Skip to main content

Version in git

Available

Deployed and supported. The fields and commands described here are stable within version v1alpha1.

Your manifests are text: put them in git. This guide proposes an organization that works well with sng apply and a CI, without additional tooling.

Repository organization​

infra/
├── stackngo.yaml            # informational (written by sng pull)
├── App/
│   ├── api.yml
│   └── web.yml
├── SSMSecret/
│   └── db-password.yml
├── RegistryRepository/
│   └── api.yml
└── DNSRecord/
    └── api.yml

This is the layout that sng pull produces: one folder per kind, one file per resource. sng apply infra/ applies everything; sng apply infra/App/api.yml a single resource.

For several tenants or environments, one folder per target:

infra/
├── acme-dev/      …
├── acme-prod/     …
└── labs-dev/      …

and, in the CI, sng tenant use acme-prod && sng apply infra/acme-prod.

What goes in git, what does not​

In gitNot in git
Manifests (App, SSMSecret, DNSRecord, …)Secret values (sng secret set, never in a file)
Your in-house templates~/.config/stackngo/config.yaml (tokens)
The CI pipelineThe status: sng pull does not export it, and if it lingers in a file it is ignored

An SSMSecret declares a secret without its value: this is exactly what you want to version.

Minimal pipeline​

On every branch: sng validate. On the main branch: sng apply. The CI's identity comes from an OIDC trust, with no stored secret.

.gitlab-ci.yml (extrait)
validate:
  script:
    - sng sso login --oidc
    - sng tenant use acme-prod
    - sng validate infra/acme-prod
    - sng plan infra/acme-prod

deploy:
  rules: [{if: $CI_COMMIT_BRANCH == "main"}]
  script:
    - sng sso login --oidc
    - sng tenant use acme-prod
    - sng apply infra/acme-prod

Complete pipelines, with the CLI installation, are in GitLab CI and GitHub Actions.

Code review​

sng plan in the CI of a merge request shows reviewers what is going to change, with the same rendering as locally. Paste its output in the description, or make it an artifact.

Detect drift​

Someone may have applied by hand (sng app scale, sng kind edit). To find out:

sng pull /tmp/etat && diff -r /tmp/etat infra/acme/default

A scheduled job that runs this diff and fails if there is a difference is a good alarm. To bring the tenant back into compliance: sng apply infra/acme/default.

Go back​

Your repository keeps the history of what you wanted to apply. The platform keeps, on its side, the history of what was actually applied: you can freeze what is running or go back to a previous version without going through your repository, with sng env (Environments and restore).

If it doesn't work​

What you seeWhat to do
The deploy job fails on sng sso login --oidcThe CI's OIDC trust is not in place: see Deploy without a secret
The diff after sng pull shows a differenceSomeone modified a resource by hand: reapply your repository, or carry the change over into git
sng apply infra/ rejects a fileThe message names the file and the field: fix it, or remove from the folder the files that are not manifests

See also​