cs-image-system

A plugin-based, configuration-driven system that turns one YAML tree into infrastructure-as-code for identities, storages, base images and instance images, and applies it through gates, on AWS and GCE. Its purpose is scientific compute: machine images that are correct for a given HPC model, formally released, whose users log in through Okta Privileged Access.

Where to start

• DAILY_DRIVER.md — how a person actually uses the system: what must exist first, the first run, making and changing things, what proves what, and what a failure means.
• DESCRIPTION.md — what the system is and how it works, in one read.
• GOALS.md — what it is for and the properties it keeps.
• docs/OPERATIONS.md — the operating manual: runs, the developer workflow, CI, the operator's cycles, the rules.
• docs/CONFIGURATION.md — the configuration reference: every file, every type, every field, one example each.
• docs/DESIGN.md — the design and its rationale.
• docs/PLUGINS.md — the packages, each with its own README ending in the same four sections: prerequisites, configuration, what it tests, when it fails.
• GOLDEN.md — the pinned emission every change is judged against.
• PARITY.md — how the system and its documentation can diverge, and how to check.
• BILLING_REMINDERS.md — the GCP account's cost housekeeping.
• docs/history/ — frozen records of how the system got here; nothing there describes the present.
• TODO.md and PLAN.md — the work in flight; a worksheet, not documentation.

The Justfile contract

The Justfile is the single entry point for the build lifecycle. Five names are reserved, in lifecycle order:

just alone lists every recipe, the contract first. just publish [test|pypi] builds and uploads the version in the tree (TestPyPI by default; a pushed v* tag makes CI do the same). just cli … runs the CLI against the reference configuration for the system's own live proofs; just fixture-live proves the frozen fixture against the real accounts; just public-safe is the gate that keeps secrets and people out of anything published. The cloud change cycle (cloud-*, ci-login-proof, sft-install) is a configuration repository's own business: its Justfile comes from the release (cs-image-system init-config), and a team runs those recipes from its own repository. cs-image-system bootstrap (stage 70) is the one-time initialisation of such a repository as terraform from an interview: the answers to bootstrap.yaml, the root to generated/bootstrap/, regenerated by every run and applied by the operator. The manual describes each.

Layout

packages/ holds the uv workspace: base (models, lifecycles, state), system (the CLI), hashicorp-utils (the terraform library) and one package per plugin (AWS and GCE runtimes, packer, ansible and bash modifications, Okta identity, terraform storage and instance builders, the GCP terraform pieces, the S3 state backend). tfmodules/ are the terraform modules the builders emit calls to. tests/ is the suite, with the frozen fixture configuration under tests/fixtures/config/ and the golden emission under tests/fixtures/v2_golden/. docs/examples/ holds the three starter configuration repositories the release ships and init-config writes out. The reference configuration is its own repository, cs-image-system-testconfig, which stands alone with its own Justfile and CI; it is checked out beside this one (CSIS_CONFIG_ROOT overrides) for the system's own live proofs only, and the tests never read it.

Licence

Apache-2.0 (LICENSE); every package carries the licence file and declares it in its project metadata.