# `mgf-cloud` — cloud-resource interface for the Magogi Foundation

[![Registry](https://img.shields.io/badge/registry-Codeberg-blue)](https://codeberg.org/magogi-admin/mgf-cloud)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://codeberg.org/magogi-admin/mgf-cloud)

> **Shape:** Federation sibling of [`mgf-common`](https://codeberg.org/magogi-admin/mgf-common)
> under the `mgf.*` namespace. The single interface the federation uses to
> **create and manage cloud VMs and storage** — Infomaniak Public Cloud
> (OpenStack) today, AWS-ready by design. Ships a CLI (`mgf-cloud`) and a local
> web GUI (`mgf-cloud web`).
>
> **Owner/consumer:** [`mgf-fed`](https://codeberg.org/magogi-admin/mgf-fed)
> (the federation orchestrator) is the sole consumer + the owner of the resources
> mgf-cloud provisions. mgf-cloud is the *mechanism*; mgf-fed decides *what*.

## What this provides

| Area | What |
|---|---|
| **Compute** | VM lifecycle — create / list / show / delete / reboot / resize / snapshot / console; images, flavours, keypairs |
| **Block storage** | volumes — create / attach / detach / delete / snapshot |
| **Object storage** | Swift containers + objects (S3-compatible optional, `[s3]`) |
| **Networking** | floating IPs, security groups + rules |
| **Bootstrap** | cloud-init / user-data at create time **+** SSH remote-exec / file-push (`[remote]`) to stand a host up |
| **Providers** | one `CloudProvider` interface; `[infomaniak]` (OpenStack) now, an AWS stub for later |
| **Surfaces** | the `mgf-cloud` CLI (+ `--json` / `--dry-run` / `--yes`) and a local single-user web GUI (`[web]`) |

**Stateless** by design — the cloud is the source of truth; federation resources
are tagged `mgf:owner`. Importing `mgf.cloud` pulls **no** provider SDK; adapters
load lazily, each behind its own extra, so the core stays light and importable.

## Status

🚧 **In active construction (0.1.x).** The full surface has shipped: the
provider-agnostic abstraction + resource models, the **Infomaniak (OpenStack)
adapter** (compute / block / object / network), the **`mgf-cloud` CLI**, the
layered **`clouds.yaml`/`OS_*` config**, **cost** estimation, the **local web
GUI**, and the **SSH `remote`/`bootstrap`** layer — each heavy dependency behind
its own extra so the core stays light. The 0.x window applies — pin tightly:
`mgf-cloud = ">=0.1,<0.2"`.

## Install

```bash
pip install mgf-cloud                 # core: abstraction + CLI (fake provider)
pip install 'mgf-cloud[infomaniak]'   # + the Infomaniak (OpenStack) provider
pip install 'mgf-cloud[web]'          # + the local web GUI
pip install 'mgf-cloud[remote]'       # + SSH bootstrap (paramiko)
pip install 'mgf-cloud[s3]'           # + S3-compatible object storage (boto3)
```

`mgf-*` siblings resolve from the Codeberg registry (PKG-06), not pypi.org.

## Credentials (Infomaniak)

Infomaniak Public Cloud is standard OpenStack. Generate an **Application
Credential** (Public Cloud Horizon → Identity → Application Credentials) and
download the project `clouds.yaml` (API Access). mgf-cloud reads `clouds.yaml` /
the `OS_*` environment. **Never commit credentials** — keep them under
`my_stuff/` (gitignored per AG-18). See
[`docs/design/DESIGN.md`](docs/design/DESIGN.md) for the full credential model.

## Quick start

```bash
mgf-cloud version
mgf-cloud vm create web-prod --flavor a2-ram2-disk20 --image "Ubuntu 24.04 LTS" --dry-run
mgf-cloud vm list --json
mgf-cloud cost                    # current run-rate + accrued estimate
mgf-cloud web                     # local single-user GUI ([web] extra)
```

## Documentation

- [`docs/design/DESIGN.md`](docs/design/DESIGN.md) — architecture + the design decisions.
- [`docs/inprogress/mgf-cloud-progress.md`](docs/inprogress/mgf-cloud-progress.md) — the 7-pass build tracker.
- [`SCOPE.md`](SCOPE.md) · [`DEPS.md`](DEPS.md) · [`PUBLIC_API.md`](PUBLIC_API.md) · [`CHANGELOG.md`](CHANGELOG.md).

For the federation-wide engineering standards see
[`mgf-standard/docs/standards/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/);
this sibling inherits them by reference.

> **Conformance: L2** per [`mgf-standard/docs/standards/`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/).
> Per-rule audit ledger: [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md).
> Every applicable MUST is met on the surface mgf-cloud owns; the two open items
> (PKG-01, WF-11) are fleet-infra deferrals tracked at mgf-standard, not owned
> defects. L3 distance: a full per-MUST file:line depth audit + the perf-baseline
> family.

## Cross-references

- **Feedback / sharp edges** — open an entry in this repo's [`FEEDBACK.md`](FEEDBACK.md),
  or in [`mgf-common/FEEDBACK.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/FEEDBACK.md)
  with a `[mgf-cloud]` prefix.
- **Federation contract** — [`FEDERATION.md`](FEDERATION.md) (pointer to the canonical copy).
