Skip to content

README.md

Latest commit

 

History

History
113 lines (82 loc) · 4.36 KB

README.md

File metadata and controls

113 lines (82 loc) · 4.36 KB

FrameWorks GitOps

Release manifests, cluster configuration, and infrastructure secrets for the FrameWorks platform. Consumed by the FrameWorks CLI for deployments.

Architecture manifests are plaintext — anyone can see exactly how FrameWorks is deployed. Server IPs and credentials are SOPS-encrypted with age.

Structure

.
├── releases/                          # Release manifests (CI-generated, one per version tag)
│   ├── v0.1.0-rc1.yaml
│   └── ...
├── channels/                          # Channel pointers
│   ├── stable.yaml                    # Latest production-ready release
│   └── rc.yaml                        # Latest release candidate
├── clusters/                          # Cluster configuration
│   └── production/
│       ├── cluster.yaml               # Architecture manifest (plaintext)
│       ├── edge.yaml                  # Edge node topology (plaintext)
│       └── hosts.enc.yaml             # Host IPs + SSH targets (SOPS-encrypted)
├── config/
│   └── production.env                 # Non-secret operator config (plaintext)
├── secrets/
│   └── production.env                 # Credentials (SOPS-encrypted)
└── .sops.yaml                         # SOPS encryption configuration

Cluster Manifests

clusters/production/cluster.yaml is the full deployment topology: every service, database, message broker, and cache — how they're connected, what hosts they run on, and how they're configured. This is published in plaintext for full transparency.

What's not in the plaintext manifest:

  • Server IP addresses → hosts.enc.yaml (SOPS-encrypted)
  • SSH credentials → hosts.enc.yaml (SOPS-encrypted)
  • Non-secret operator config → config/production.env (plaintext)
  • API keys, passwords, tokens → secrets/production.env (SOPS-encrypted)

Decrypting

# View host IPs
sops -d clusters/production/hosts.enc.yaml

# View secrets
sops -d secrets/production.env

Requires the age private key at ~/.config/sops/age/keys.txt (or set SOPS_AGE_KEY_FILE).

Editing encrypted env files

Do not edit secrets/*.env directly and do not use ad hoc decrypt/edit/encrypt commands.

Use the repo script:

scripts/sops-env.sh delete secrets/production.env KEY1 KEY2
scripts/sops-env.sh set secrets/production.env KEY value
scripts/sops-env.sh insert-after secrets/production.env AFTER_KEY NEW_KEY value
scripts/sops-env.sh insert-before secrets/production.env BEFORE_KEY NEW_KEY value

Provisioning

# From local checkout
frameworks cluster provision --manifest clusters/production/cluster.yaml --age-key ~/.config/sops/age/keys.txt

# From GitHub (fetches manifest + encrypted files, decrypts automatically)
frameworks cluster provision --repo org/gitops --age-key ~/.config/sops/age/keys.txt

Shared operator config is loaded from env_files in cluster.yaml, currently:

env_files:
  - ../../config/production.env
  - ../../secrets/production.env

Release Manifests

Automatically generated by CI when a version tag is pushed to the monorepo. Each manifest contains:

  • Platform version, git commit SHA, timestamp
  • Docker image references with SHA256 digests
  • Native binary download references
  • Tested infrastructure versions

Channels

  • stable — Latest production-ready release. Production clusters track this.
  • rc — Release candidate. Staging clusters track this.

Release Flow

  1. Tag: Create vX.Y.Z (GA) or vX.Y.Z-rcN (RC) in the monorepo.
  2. Build: CI builds all services, pushes images, compiles native binaries.
  3. Manifest: CI generates releases/<tag>.yaml and pushes here.
  4. Channel: RC tags update channels/rc.yaml. GA tags update channels/stable.yaml.
  5. Deploy: The CLI reads the manifest to pull images by digest and download binaries.

Secrets Management

Secrets are encrypted at rest using SOPS with age keys. SOPS encrypts values while leaving keys/structure visible — this is by design for transparency.

Pre-commit hooks prevent:

  • Committing unencrypted secret files
  • Leaking IP addresses into plaintext manifests
  • Accidentally committing age private keys

See docs/key-rotation.md for rotation procedures.