Skip to main content

The validate, plan, apply cycle

Available

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

Everything you deploy goes through the desired state: the set of manifests applied to your tenant. This guide shows the day-to-day work cycle and the reflexes that avoid unpleasant surprises.

Prerequisites​

  • A session on the tenant (sng tenant use); sng config show displays the current cluster and tenant.
  • Your manifests in a folder, preferably one file per resource.

1. Write​

Start from a template rather than a blank page:

sng template gen App api
sng template gen SSMSecret db-password

Or retrieve what exists: sng pull exports the entire current desired state as files.

A file can contain several manifests separated by ---. The accepted kinds are listed in the manifest reference. Never specify a tenant: it is deduced from your session.

2. Validate​

sng validate .
validate OK — 4 document(s)

validate sends the manifests to the API, which applies exactly the checks of apply: kind schema, cross-field rules, allowed domains, reserved names. Nothing is written. Put it in a pre-commit hook or in the CI on every branch.

3. Preview​

sng plan .
ACTION     KIND       NAME         KEY
create     SSMSecret  db-password  …
update     App        api          …
unchanged  App        web          …

plan compares with the current content of the desired state. An unexpected update often signals that a colleague modified the resource since your last pull.

plan does not see deletions

A manifest present in the desired state but absent from your folder does not appear: apply never erases anything on its own. To delete, use sng kind delete.

4. Apply​

sng apply .
apply acme — 4 object(s)

The platform applies your changes in less than a minute. Follow progress with the kind's command:

sng app describe api
sng secret describe db-password

For the other kinds, the command that reads the state is listed in sng kind get. sng kind get KIND NAME shows the stored manifest, not its state.

5. Delete​

sng kind delete App api

Deletion removes the manifest from the desired state; the platform then removes what it described, in less than a minute, according to the kind's deletion policy. In a script: -y.

6. Read back the actual state​

sng kind list App                # what is declared
sng kind get App api             # a stored manifest
sng app describe api        # its actual state
sng pull ./etat-actuel      # everything, as files

Comparing sng pull with your git repository is the safest way to detect drift between what you believe you applied and what actually is.

Reflexes​

  • A plan before each apply outside the CI.
  • Small files: one manifest per file, named <kind>-<name>.yml or organized the way sng pull does it (<Kind>/<name>.yml). sng kind edit can only modify one document.
  • No secret value in a manifest: declare an SSMSecret and reference it (Secrets).
  • Read the status before reapplying in a loop: the reason is almost always there.

If it doesn't work​

What you seeWhat to do
validation failed (N issue(s))Fix each error: line displayed above
invalid manifest …The message names the field; see the kind's page in the manifest reference
conflictA name or host is already taken, or the resource is being deleted: rename or wait
The resource stays in ProgressingRead its reason (sng app describe) and the conditions index

Other messages: CLI errors.

Going further​

  • An apply is all or nothing: if it is interrupted (network outage, Ctrl-C), none of your manifests is taken into account. Run it again.
  • The platform keeps the history of what you apply: you can freeze what is running or go back to a previous version (Environments and restore).
  • The API additionally exposes a mechanism of deployments and versioned releases (/v1/deployments, /v1/releases), with no CLI command for now. It is described in the API reference.

See also​