exoscale-connector 0.2.0__tar.gz

exoscale_connector-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        # Lower and upper bounds of the supported range (requires-python >=3.9).
+        python-version: ["3.9", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev dependencies
+        run: pip install -e '.[dev]'
+      - name: Lint
+        run: ruff check src tests
+      - name: Type-check
+        run: mypy src
+      - name: Unit tests
+        run: pytest tests/unit -q
+      # Integration tiers (tests/integration) need live tenant credentials and
+      # are deliberately NOT run in CI — see docs/live-test-plan.md.

exoscale_connector-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,51 @@
+name: Release
+
+# Publishes to PyPI on version tags (v0.2.0, v1.0.0, ...).
+#
+# INERT UNTIL CONFIGURED: this uses PyPI "trusted publishing" (no API token in
+# the repo). Before the first release, register this repository + workflow as a
+# trusted publisher for the 'exoscale-connector' project on pypi.org, and create
+# the 'pypi' environment in the GitHub repo settings.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Run the full check suite before building
+        run: |
+          pip install -e '.[dev]'
+          ruff check src tests
+          mypy src
+          pytest tests/unit -q
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      # Pinned to a commit SHA: this third-party action receives the OIDC
+      # token that authorizes publishing; a floating branch ref would let a
+      # compromised upstream publish on our behalf. Bump deliberately.
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # release/v1 as of 2026-02-18

exoscale_connector-0.2.0/.gitignore

@@ -0,0 +1,81 @@
+# Python build / cache
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Local virtualenvs
+.venv/
+venv/
+env/
+
+# Test / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Secrets & credentials — NEVER commit
+# App reads credentials from environment variables only; injected at runtime.
+.env
+.env.*
+*.env
+secrets.json
+secrets.yaml
+secrets.yml
+credentials
+credentials.json
+*.token
+*.secret
+
+# Exoscale / cloud credentials
+# EXOSCALE_API_KEY / EXOSCALE_API_SECRET must come from the environment, not files.
+exoscale.toml
+.exoscale/
+# Object Storage (SOS) uses boto3 — keep AWS-style shared creds out of the repo
+.aws/
+.boto
+
+# Keys & certificates
+*.pem
+*.key
+*.p12
+*.pfx
+*.crt
+*.cer
+# SSH keypairs (the ssh-key asset type can generate ephemeral ed25519 keys)
+id_rsa
+id_rsa.pub
+id_ed25519
+id_ed25519.pub
+id_dsa
+*.ppk
+
+# Kubernetes — SKS generate_kubeconfig() output must never be committed
+*.kubeconfig
+kubeconfig
+.kube/
+
+# Terraform / IaC state & vars (this connector is built for IaC pipelines)
+*.tfvars
+*.tfstate
+*.tfstate.*
+.terraform/
+
+# IDE / editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

exoscale_connector-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raphael Lang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

exoscale_connector-0.2.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: exoscale-connector
+Version: 0.2.0
+Summary: A clean, typed, reusable Python connector for the Exoscale APIv2 — no CLI tool required.
+Author: Raphael Lang
+License: MIT
+License-File: LICENSE
+Keywords: api,cloud,connector,exoscale,iac
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: cryptography>=40; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: responses>=0.24; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Provides-Extra: sos
+Requires-Dist: boto3>=1.28; extra == 'sos'
+Description-Content-Type: text/markdown
+
+# exoscale-connector
+
+A clean, typed, reusable Python connector for the **Exoscale APIv2**. It talks to
+the HTTP API directly — **no `exo` CLI and no Ansible required** — so it can be
+dropped into any project that needs to read or manage Exoscale resources
+programmatically.
+
+- **Typed** — every request/response is a [pydantic](https://docs.pydantic.dev) v2
+  model, so you get validation and editor autocompletion.
+- **One module per asset type** — `security-group`, `instance`, `elastic-ip`,
+  `dns`, `dbaas`, `sks`, … each with a small, uniform client.
+- **Library + CLI** — import it, or use the per-asset command-line tools
+  (also namespaced under one `exoscale-connector` binary, with `--output table`).
+- **Built for automation** — idempotent `ensure()` (get-or-create by name),
+  `wait_for_state` polling, and label-filtered listing make provisioning
+  scripts re-runnable by construction.
+- **Self-contained** — runtime deps are just `requests` + `pydantic`; copy the
+  package into another repo and it keeps working.
+- **Secret-safe** — credentials come only from the environment; nothing is
+  hardcoded or read from disk, and credentials are masked in `repr()`/log
+  output.
+
+## Relationship to the official Exoscale SDK
+
+Exoscale publishes an official, actively maintained Python SDK —
+[`python-exoscale`](https://github.com/exoscale/python-exoscale) (the `exoscale`
+package on PyPI); if you want the vendor-supported, batteries-included bindings,
+use that. This connector is a smaller, opinionated alternative built for one
+goal — a **drop-in, IaC-ready APIv2 client that is as easy to use as possible**:
+where the official SDK splits into a high-level interface that grew up around the
+now-retired APIv1 and a lower-level, OpenAPI-generated `exoscale.api.v2.Client`,
+this project gives *every* asset type the same uniform, pydantic-typed client
+plus a matching per-asset CLI, talks only to APIv2, reads credentials only from
+the environment, polls async operations to completion, backs every asset type
+with a live test that has run end-to-end against a real account, depends on just
+`requests` + `pydantic`, and can be vendored by copying one folder.
+
+## Install
+
+```bash
+pip install -e ".[dev]"          # from this folder, for development
+# or, once published / vendored:
+pip install exoscale-connector
+```
+
+Object Storage (S3-compatible) support pulls in `boto3`:
+
+```bash
+pip install "exoscale-connector[sos]"
+```
+
+## Quickstart (library)
+
+```python
+from exoscale_connector import ExoscaleClient
+from exoscale_connector.resources.security_group import (
+    SecurityGroupClient, SecurityGroupRule,
+)
+
+# Credentials from EXOSCALE_API_KEY / EXOSCALE_API_SECRET in the environment.
+client = ExoscaleClient.from_env(zone="de-fra-1")
+sg = SecurityGroupClient(client)
+
+for group in sg.list():
+    print(group.id, group.name)
+
+group = sg.create({"name": "web", "description": "public web tier"})
+sg.add_rule(group.id, SecurityGroupRule(
+    flow_direction="ingress", protocol="tcp",
+    start_port=443, end_port=443, network="0.0.0.0/0",
+))
+```
+
+## Quickstart (CLI)
+
+```bash
+export EXOSCALE_API_KEY=... EXOSCALE_API_SECRET=... EXOSCALE_ZONE=de-fra-1
+
+exoscale-security-group list
+exoscale-security-group get --id <uuid>
+exoscale-security-group create --json '{"name": "web"}'
+exoscale-security-group delete --id <uuid>
+```
+
+> In practice, inject the credentials with your secret-management tooling rather
+> than exporting them by hand. The connector only reads environment variables, so
+> any injector works (HashiCorp Vault, Infisical, Doppler, …), e.g.
+> `<vault-cli> run -- exoscale-security-group list`.
+
+## Documentation
+
+- **[User / operator guide](docs/user-guide.md)** — installing, authenticating,
+  zones, and the common commands shared by every asset type.
+- **[Asset type reference](docs/asset-types/README.md)** — one page per asset
+  type with model schema, CLI subcommands, library snippets, gotchas, and a
+  runnable end-to-end example backed by a passing live test.
+- **[IAM policy cookbook](docs/iam-policy-cookbook.md)** — helper constructors
+  and copy-paste recipes for IAM role policies (the one area with real depth).
+- **[Developer guide](docs/developer-guide.md)** — architecture, how to add a
+  new asset type, and the testing strategy.
+- **[Live test plan](docs/live-test-plan.md)** — tiered per-asset live-test
+  design (safety rails, naming prefix, cleanup invariants, cost model).
+- **[Live test results](docs/live-test-results.md)** — run log of every live
+  test executed against a real Exoscale tenant, plus the bugs each tier
+  surfaced and how they were fixed.
+
+Every asset type the connector supports has a live test that has actually run
+end-to-end against a real account; the gotchas in the asset-type pages are
+empirical, not theoretical.
+
+## Maintenance & support
+
+This is a personal project, maintained on a **best-effort, occasional basis** —
+not full-time and not on a fixed schedule. It's shared because it may be useful
+to others, not as a supported product. Issues and pull requests are welcome and
+will be looked at when time allows, but there is **no guaranteed response time or
+release cadence**. The API surface it tracks can drift; if you depend on it,
+pin a version and don't hesitate to fork and adapt it — that's encouraged.
+
+## License
+
+Released under the [MIT License](LICENSE) — free to use, modify, and
+redistribute, including commercially. Provided **as-is, without warranty of any
+kind**; use entirely at your own risk. The only condition is that the copyright
+and permission notice are kept in copies.

exoscale_connector-0.2.0/README.md

@@ -0,0 +1,125 @@
+# exoscale-connector
+
+A clean, typed, reusable Python connector for the **Exoscale APIv2**. It talks to
+the HTTP API directly — **no `exo` CLI and no Ansible required** — so it can be
+dropped into any project that needs to read or manage Exoscale resources
+programmatically.
+
+- **Typed** — every request/response is a [pydantic](https://docs.pydantic.dev) v2
+  model, so you get validation and editor autocompletion.
+- **One module per asset type** — `security-group`, `instance`, `elastic-ip`,
+  `dns`, `dbaas`, `sks`, … each with a small, uniform client.
+- **Library + CLI** — import it, or use the per-asset command-line tools
+  (also namespaced under one `exoscale-connector` binary, with `--output table`).
+- **Built for automation** — idempotent `ensure()` (get-or-create by name),
+  `wait_for_state` polling, and label-filtered listing make provisioning
+  scripts re-runnable by construction.
+- **Self-contained** — runtime deps are just `requests` + `pydantic`; copy the
+  package into another repo and it keeps working.
+- **Secret-safe** — credentials come only from the environment; nothing is
+  hardcoded or read from disk, and credentials are masked in `repr()`/log
+  output.
+
+## Relationship to the official Exoscale SDK
+
+Exoscale publishes an official, actively maintained Python SDK —
+[`python-exoscale`](https://github.com/exoscale/python-exoscale) (the `exoscale`
+package on PyPI); if you want the vendor-supported, batteries-included bindings,
+use that. This connector is a smaller, opinionated alternative built for one
+goal — a **drop-in, IaC-ready APIv2 client that is as easy to use as possible**:
+where the official SDK splits into a high-level interface that grew up around the
+now-retired APIv1 and a lower-level, OpenAPI-generated `exoscale.api.v2.Client`,
+this project gives *every* asset type the same uniform, pydantic-typed client
+plus a matching per-asset CLI, talks only to APIv2, reads credentials only from
+the environment, polls async operations to completion, backs every asset type
+with a live test that has run end-to-end against a real account, depends on just
+`requests` + `pydantic`, and can be vendored by copying one folder.
+
+## Install
+
+```bash
+pip install -e ".[dev]"          # from this folder, for development
+# or, once published / vendored:
+pip install exoscale-connector
+```
+
+Object Storage (S3-compatible) support pulls in `boto3`:
+
+```bash
+pip install "exoscale-connector[sos]"
+```
+
+## Quickstart (library)
+
+```python
+from exoscale_connector import ExoscaleClient
+from exoscale_connector.resources.security_group import (
+    SecurityGroupClient, SecurityGroupRule,
+)
+
+# Credentials from EXOSCALE_API_KEY / EXOSCALE_API_SECRET in the environment.
+client = ExoscaleClient.from_env(zone="de-fra-1")
+sg = SecurityGroupClient(client)
+
+for group in sg.list():
+    print(group.id, group.name)
+
+group = sg.create({"name": "web", "description": "public web tier"})
+sg.add_rule(group.id, SecurityGroupRule(
+    flow_direction="ingress", protocol="tcp",
+    start_port=443, end_port=443, network="0.0.0.0/0",
+))
+```
+
+## Quickstart (CLI)
+
+```bash
+export EXOSCALE_API_KEY=... EXOSCALE_API_SECRET=... EXOSCALE_ZONE=de-fra-1
+
+exoscale-security-group list
+exoscale-security-group get --id <uuid>
+exoscale-security-group create --json '{"name": "web"}'
+exoscale-security-group delete --id <uuid>
+```
+
+> In practice, inject the credentials with your secret-management tooling rather
+> than exporting them by hand. The connector only reads environment variables, so
+> any injector works (HashiCorp Vault, Infisical, Doppler, …), e.g.
+> `<vault-cli> run -- exoscale-security-group list`.
+
+## Documentation
+
+- **[User / operator guide](docs/user-guide.md)** — installing, authenticating,
+  zones, and the common commands shared by every asset type.
+- **[Asset type reference](docs/asset-types/README.md)** — one page per asset
+  type with model schema, CLI subcommands, library snippets, gotchas, and a
+  runnable end-to-end example backed by a passing live test.
+- **[IAM policy cookbook](docs/iam-policy-cookbook.md)** — helper constructors
+  and copy-paste recipes for IAM role policies (the one area with real depth).
+- **[Developer guide](docs/developer-guide.md)** — architecture, how to add a
+  new asset type, and the testing strategy.
+- **[Live test plan](docs/live-test-plan.md)** — tiered per-asset live-test
+  design (safety rails, naming prefix, cleanup invariants, cost model).
+- **[Live test results](docs/live-test-results.md)** — run log of every live
+  test executed against a real Exoscale tenant, plus the bugs each tier
+  surfaced and how they were fixed.
+
+Every asset type the connector supports has a live test that has actually run
+end-to-end against a real account; the gotchas in the asset-type pages are
+empirical, not theoretical.
+
+## Maintenance & support
+
+This is a personal project, maintained on a **best-effort, occasional basis** —
+not full-time and not on a fixed schedule. It's shared because it may be useful
+to others, not as a supported product. Issues and pull requests are welcome and
+will be looked at when time allows, but there is **no guaranteed response time or
+release cadence**. The API surface it tracks can drift; if you depend on it,
+pin a version and don't hesitate to fork and adapt it — that's encouraged.
+
+## License
+
+Released under the [MIT License](LICENSE) — free to use, modify, and
+redistribute, including commercially. Provided **as-is, without warranty of any
+kind**; use entirely at your own risk. The only condition is that the copyright
+and permission notice are kept in copies.

exoscale_connector-0.2.0/docs/asset-types/README.md

@@ -0,0 +1,72 @@
+# Asset type reference
+
+One page per asset type the connector supports. Every page has the same six
+sections — **Overview**, **Model**, **CLI**, **Library**, **Gotchas**,
+**End-to-end example** — and is backed by a passing
+[live test](../live-test-plan.md).
+
+If something on a page contradicts the live behaviour, the live test is the
+source of truth — open an issue and the page will be corrected.
+
+## Capability matrix
+
+| Asset type | CLI binary | Live-tested | Tier |
+|---|---|---|---|
+| [security-group (+rules)](security-group.md) | `exoscale-security-group` | ✅ | 1 |
+| [private-network](private-network.md) | `exoscale-private-network` | ✅ | 1 |
+| [anti-affinity-group](anti-affinity-group.md) | `exoscale-anti-affinity-group` | ✅ | 1 |
+| [ssh-key](ssh-key.md) | `exoscale-ssh-key` | ✅ | 1 |
+| [iam-role](iam-role.md) | `exoscale-iam-role` | ✅ | 1 |
+| [iam-user](iam-user.md) | `exoscale-iam-user` | read-only | — |
+| [api-key](api-key.md) | `exoscale-api-key` | ✅ (gated) | 1 (opt-in, `EXOSCALE_TEST_TIER_1_API_KEY=1`) |
+| [dns (domain + records)](dns.md) | `exoscale-dns` | ✅ | 1 |
+| [elastic-ip](elastic-ip.md) | `exoscale-elastic-ip` | ✅ | 2 |
+| [object-storage bucket](object-storage.md) | `exoscale-bucket` | ✅ | 2 |
+| [block-volume](block-volume.md) | `exoscale-block-volume` | ✅ create/snapshot/delete (Tier 2); attach/detach (Tier 3); resize endpoint+method verified, size-change assertion self-skips on tenant quota | 2/3 |
+| [block-volume-snapshot](block-volume-snapshot.md) | `exoscale-block-volume-snapshot` | ✅ | 2 |
+| [instance (+lifecycle)](instance.md) | `exoscale-instance` | ✅ | 3 |
+| [instance-pool (+scale)](instance-pool.md) | `exoscale-instance-pool` | ✅ | 3 |
+| [snapshot (compute)](snapshot.md) | `exoscale-snapshot` | ✅ create/list/get/export/delete | 3 |
+| [load-balancer (+services)](load-balancer.md) | `exoscale-load-balancer` | ✅ | 4 |
+| [dbaas](dbaas.md) | `exoscale-dbaas` | ✅ | 4 |
+| [sks (cluster + nodepool)](sks.md) | `exoscale-sks` | ✅ | 4 |
+| [zone](zone.md) | `exoscale-zone` | pending (smoke test added) | 0 |
+| [template](template.md) | `exoscale-template` | pending (smoke test added) | 0 |
+| [instance-type](instance-type.md) | `exoscale-instance-type` | pending (smoke test added) | 0 |
+
+Instance scale, reverse DNS, SOS objects, DBaaS users/update, and `ensure()`
+were all live-verified in the 2026-06-10 extensions validation run (see
+[live-test-results.md](../live-test-results.md)). Three spec-vs-reality
+divergences were found and fixed during that run.
+
+## Page template
+
+```
+# <asset-type>
+Overview — one paragraph.
+## Model
+Field table from the pydantic model.
+## CLI
+Every subcommand with a copy-pasteable example invocation.
+## Library
+Python snippet for each operation.
+## Gotchas
+Caveats verified by the live test (e.g. unit-of-measure quirks,
+required-but-undocumented fields, quota constraints).
+## End-to-end example
+The full lifecycle distilled from the corresponding live test.
+```
+
+## Conventions used on every page
+
+- **Authentication** is always env-based: `EXOSCALE_API_KEY` /
+  `EXOSCALE_API_SECRET` / `EXOSCALE_ZONE`. Inject with your secret manager
+  (HashiCorp Vault, Infisical, Doppler, …); the connector reads only env vars.
+- **JSON output** from CLIs goes to stdout; errors to stderr; exit 0 on
+  success, 1 on API/connector error, 2 on argparse error.
+- **All resources** are pydantic v2 models with snake_case attributes that
+  auto-map to the API's kebab-case JSON keys (e.g. `flow_direction` ↔
+  `flow-direction`). Unknown server fields pass through (`extra="allow"`),
+  so the connector keeps working when the API adds fields ahead of the model.
+- **Async operations** are awaited by default — pass `wait=False` to return
+  the operation object without polling.

exoscale_connector-0.2.0/docs/asset-types/anti-affinity-group.md

@@ -0,0 +1,65 @@
+# anti-affinity-group
+
+A scheduling hint telling Exoscale's placement engine that the instances
+assigned to this group should be spread across distinct physical hosts. Used
+to maximise availability for replica sets (e.g. a 3-node etcd cluster, or an
+HA database).
+
+## Model
+
+```python
+class AntiAffinityGroup(ExoscaleModel):
+    id: Optional[str]
+    name: Optional[str]
+    description: Optional[str]
+    instances: Optional[List[Reference]]   # members; populated on detail responses
+```
+
+## CLI
+
+```bash
+exoscale-anti-affinity-group list
+exoscale-anti-affinity-group get --id <uuid>
+exoscale-anti-affinity-group find --name <name>
+exoscale-anti-affinity-group create --json '{"name": "etcd-aag", "description": "etcd replica anti-affinity"}'
+exoscale-anti-affinity-group delete --id <uuid>
+```
+
+## Library
+
+```python
+from exoscale_connector import ExoscaleClient
+from exoscale_connector.resources.anti_affinity_group import AntiAffinityGroupClient
+
+aag = AntiAffinityGroupClient(ExoscaleClient.from_env(zone="de-fra-1"))
+
+group = aag.create({"name": "etcd-aag", "description": "etcd anti-affinity"})
+fetched = aag.get(group.id)
+aag.delete(group.id)
+```
+
+## Gotchas
+
+- **No `update` endpoint.** The API does not support modifying an AAG in
+  place — `update()` is intentionally not exposed on this client. To change
+  anything, delete and recreate.
+- **Members are read-only here.** Instances are assigned via the
+  *instance* create/update endpoint by including the AAG id in the
+  instance's `anti-affinity-groups` array.
+
+## End-to-end example
+
+Distilled from
+[`tests/integration/test_tier_1.py::test_anti_affinity_group_lifecycle`](../../tests/integration/test_tier_1.py):
+
+```python
+from exoscale_connector import ExoscaleClient
+from exoscale_connector.resources.anti_affinity_group import AntiAffinityGroupClient
+
+aag = AntiAffinityGroupClient(ExoscaleClient.from_env(zone="de-fra-1"))
+
+group = aag.create({"name": "etcd-aag", "description": "tier-1 smoke"})
+assert aag.get(group.id).name == "etcd-aag"
+assert aag.find_by_name("etcd-aag").id == group.id
+aag.delete(group.id)
+```

exoscale_connector-0.2.0/docs/asset-types/api-key.md

@@ -0,0 +1,88 @@
+# api-key
+
+A scoped credential bound to an IAM role at creation time. The role
+determines what the key can do; the key's name/identifier on the wire is
+its **key id** (an API-generated string), and the **secret is returned
+exactly once** on the create response — there is no way to re-fetch it.
+
+## Model
+
+```python
+class ApiKey(ExoscaleModel):
+    key: Optional[str]        # API key id (the public part, used in URL paths)
+    name: Optional[str]
+    role_id: Optional[str]    # bound role's id
+    role: Optional[Reference]
+    secret: Optional[str]     # PRESENT ONLY ON CREATE — never returned later
+```
+
+## CLI
+
+```bash
+exoscale-api-key list
+exoscale-api-key get --id <key-id>
+exoscale-api-key find --name <name>
+exoscale-api-key create --json '{"name": "ci-bot", "role-id": "<role-uuid>"}'
+exoscale-api-key delete --id <key-id>
+```
+
+## Library
+
+```python
+from exoscale_connector import ExoscaleClient
+from exoscale_connector.resources.api_key import ApiKeyClient
+
+keys = ApiKeyClient(ExoscaleClient.from_env(zone="de-fra-1"))
+
+created = keys.create({"name": "ci-bot", "role-id": "<role-uuid>"})
+# Capture the secret IMMEDIATELY — it is not retrievable later.
+secret = created.secret
+key_id = created.key
+
+# Listing / fetching never returns the secret.
+for existing in keys.list():
+    print(existing.key, existing.name)
+
+keys.delete(key_id)
+```
+
+## Gotchas
+
+- **`secret` is one-shot.** The first response after `create` is the only
+  time the secret is visible. Persist it to a vault immediately; never log it.
+  As a guard, `repr()` of an `ApiKey` masks the secret — but it is still
+  present in `model_dump()` and in the CLI's `create` JSON output (that is
+  your one chance to capture it).
+- **`id_field = "key"`** — the path token is the `key` field, not a uuid in
+  `id`. `keys.get("EXO...")` calls `GET /api-key/EXO...`.
+- **`update` not exposed.** The API does not allow rotating a key in place —
+  delete and create a new one.
+- **Tier 1 live test for create is gated separately** (off by default) so
+  the standard Tier 1 run never produces a stray secret-bearing response.
+  Enable with `EXOSCALE_TEST_TIER_1_API_KEY=1`.
+
+## End-to-end example
+
+```python
+from exoscale_connector import ExoscaleClient
+from exoscale_connector.resources.api_key import ApiKeyClient
+from exoscale_connector.resources.iam_role import IAMPolicy, IAMRole, IAMRoleClient
+
+client = ExoscaleClient.from_env(zone="de-fra-1")
+roles = IAMRoleClient(client)
+keys = ApiKeyClient(client)
+
+# Bind to a minimal role created just for this key.
+role = roles.create(IAMRole(
+    name="ci-bot-role",
+    policy=IAMPolicy(default_service_strategy="deny", services={}),
+))
+
+created = keys.create({"name": "ci-bot", "role-id": role.id})
+assert created.secret, "secret must be returned exactly once"
+# Hand `created.key` / `created.secret` to your vault here.
+
+# Teardown
+keys.delete(created.key)
+roles.delete(role.id)
+```