Metadata-Version: 2.4
Name: mgf-cloud
Version: 0.1.0
Summary: Cloud-resource interface for the Magogi Foundation — create + manage VMs and storage (Infomaniak Public Cloud first; AWS-ready). Ships a CLI + a local web GUI. Sibling of mgf-common under the mgf.* namespace.
Project-URL: Homepage, https://codeberg.org/magogi-admin/mgf-cloud
Project-URL: Issues, https://codeberg.org/magogi-admin/mgf-cloud/issues
Project-URL: Changelog, https://codeberg.org/magogi-admin/mgf-cloud/src/branch/main/CHANGELOG.md
Author: Bassam Alsanie, mgf-cloud contributors
License: MIT
License-File: LICENSE
Keywords: cloud,infomaniak,infrastructure,object-storage,openstack,vm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mgf-common<0.47,>=0.46
Requires-Dist: pydantic-settings<3,>=2.2
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyyaml<8,>=6.0
Provides-Extra: aws
Requires-Dist: boto3<2,>=1.34; extra == 'aws'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: import-linter>=2.0; extra == 'dev'
Requires-Dist: mgf-standard<0.2,>=0.1.6; extra == 'dev'
Requires-Dist: mgf-test-supervisor<0.2,>=0.1.3; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout<3,>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml<8,>=6.0; extra == 'dev'
Provides-Extra: infomaniak
Requires-Dist: openstacksdk<5,>=4; extra == 'infomaniak'
Provides-Extra: remote
Requires-Dist: paramiko<4,>=3; extra == 'remote'
Provides-Extra: s3
Requires-Dist: boto3<2,>=1.34; extra == 's3'
Provides-Extra: standards
Requires-Dist: mgf-common[standards]<0.47,>=0.46; extra == 'standards'
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: jinja2<4,>=3.1; extra == 'web'
Requires-Dist: mgf-fastapi<0.7,>=0.6; extra == 'web'
Requires-Dist: python-multipart>=0.0.9; extra == 'web'
Requires-Dist: uvicorn>=0.30; extra == 'web'
Description-Content-Type: text/markdown

# `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.0).** Built over **7 passes** — tracked in
[`docs/inprogress/mgf-cloud-progress.md`](docs/inprogress/mgf-cloud-progress.md).
Pass 1 (this) is the conformant scaffold + design docs; the core abstraction, the
Infomaniak adapter, the CLI, and the web GUI land in Passes 2–5. The 0.x window
applies — pin tightly: `mgf-cloud = ">=0.1.0,<0.2"`.

## Install

```bash
pip install mgf-cloud                 # core: abstraction + CLI skeleton
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 (CLI surface lands in Pass 4)

```bash
mgf-cloud version
# coming in Pass 4:
mgf-cloud vm create web-prod --flavor a2-ram2-disk20 --image "Ubuntu 24.04 LTS" --dry-run
mgf-cloud vm list --json
mgf-cloud web                     # local single-user GUI (Pass 5)
```

## 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: L1** 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).
> L1 is the default for a new sibling; the full per-MUST evidence audit completes
> in Pass 7 once the surface is final.

## 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).
