# Public API — `mgf-cloud`

> **Master-HEAD banner:** tracks the public surface of the CURRENT main/release.
> Verify your pinned version via `mgf.cloud.__version__` (single-sourced from the
> installed package metadata, so it always equals `pyproject.toml::project.version`
> — pinned by `tests/unit/test_version_in_sync.py`). Machine-readable companion:
> [`PUBLIC_API.json`](PUBLIC_API.json), generated from `__all__` and pinned in CI.

The public surface is exactly `mgf.cloud.__all__`. Modules under a leading
underscore are private and may change without notice.

## Stability

🚧 **Experimental (AP-11).** mgf-cloud is in active construction. Every public
name is `experimental` until the surface settles; the 0.x window applies — pin
tightly (`mgf-cloud = ">=0.1,<0.2"`).

## `mgf.cloud`

| Name | Kind | Stability | Since | Notes |
|---|---|---|---|---|
| `CloudConfig` | class | experimental | 0.1.0 | a provider choice + its resolved `Credentials` |
| `CloudProvider` | Protocol | experimental | 0.1.0 | the provider-agnostic interface every adapter implements |
| `Credentials` | class | experimental | 0.1.0 | validated OpenStack auth; secrets held as `SecretStr` |
| `DEFAULT_OWNER` | `str` | experimental | 0.1.0 | default value for the owner tag (`"federation"`) |
| `OWNER_TAG` | `str` | experimental | 0.1.0 | metadata key marking a resource federation-owned |
| `Flavor` | model | experimental | 0.1.0 | compute shape (vcpus / ram / disk) |
| `FloatingIP` | model | experimental | 0.1.0 | a reserved/attached public IP |
| `Image` | model | experimental | 0.1.0 | a bootable image |
| `Keypair` | model | experimental | 0.1.0 | a registered SSH public key |
| `Network` | model | experimental | 0.1.0 | a network |
| `ObjectContainer` | model | experimental | 0.1.0 | an object-storage (Swift) container |
| `ObjectInfo` | model | experimental | 0.1.0 | one stored object's metadata |
| `SecurityGroup` | model | experimental | 0.1.0 | a security group + its rules |
| `SecurityRule` | model | experimental | 0.1.0 | one ingress/egress rule |
| `Server` | model | experimental | 0.1.0 | a virtual machine |
| `ServerSpec` | model | experimental | 0.1.0 | the desired-state input to `create_server` |
| `Volume` | model | experimental | 0.1.0 | a block-storage volume |
| `VolumeSnapshot` | model | experimental | 0.1.0 | a point-in-time volume snapshot |
| `VolumeSpec` | model | experimental | 0.1.0 | the desired-state input to `create_volume` |
| `__version__` | `str` | experimental | 0.1.0 | package version (single-sourced from metadata) |
| `available_providers` | function | experimental | 0.1.0 | the provider names `get_provider` accepts |
| `get_provider` | function | experimental | 0.1.0 | factory returning a `CloudProvider` for a name |
| `is_owned` | function | experimental | 0.1.0 | predicate: is a resource federation-owned |
| `owned_metadata` | function | experimental | 0.1.0 | build the owner-tag metadata dict |

The Infomaniak adapter (`mgf.cloud.providers.infomaniak`) and the SSH bootstrap
helpers (`mgf.cloud.remote`) are loaded behind their extras and are not part of
the top-level `__all__`; program against the `CloudProvider` Protocol instead.

## CLI — `mgf-cloud`

All commands take the common flags `--provider` (default `infomaniak`; `fake` for
a local dry test), `--clouds-yaml`, `--json`, `--dry-run`, `--yes` — placed *with*
the action (e.g. `mgf-cloud vm delete web --yes`).

| Group | Actions |
|---|---|
| `version` | — |
| `provider` | `list`, `check` |
| `vm` | `list`, `show`, `create`, `delete`, `reboot`, `resize`, `snapshot` |
| `flavor` / `image` | `list` |
| `cost` | estimate current cloud-usage cost (rate + accrued) |
| `volume` | `list`, `create`, `attach`, `detach`, `delete`, `snapshot` |
| `floating-ip` | `list`, `create`, `attach`, `detach`, `release` |
| `secgroup` | `list`, `create`, `delete` |
| `keypair` | `list`, `create`, `delete` |
| `object` | `containers`, `mkcontainer`, `rmcontainer`, `ls`, `put`, `get`, `rm` |
| `web` | launch the local web GUI (`--host`/`--port`) |
| `remote` | `exec` (run a command), `push` (upload a file) — over SSH |
| `bootstrap` | stand a host up: `--docker` (install Docker) + `--compose-dir` (deploy a compose bundle) |

Mutations require `--yes` (else a refusal is printed); `--dry-run` plans without
applying. Exit codes: **0** ok · **1** cloud error (or an untyped bug, routed to a
crash report per EH-04) · **2** refused / usage. `mgf-cloud web` serves a
localhost FastAPI console (needs the `[web]` extra). `remote` / `bootstrap` use
SSH (the `[remote]` extra; `--user`/`--port`/`--key`/`--accept-new`).
