Common conventions

Available

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

All StackNGO manifests follow the same conventions. Knowing them saves you from rereading every reference page for the same concepts.

Shape of a manifest

apiVersion: <groupe>/v1alpha1   # e.g. deploy.stackngo.io/v1alpha1
kind: <Kind>                    # e.g. App
metadata:
  name: <nom>                   # unique per kind in your tenant; the only metadata field
spec: {}                        # what you want
status: {}                      # what the platform observes; not writable

• metadata.name: a lowercase DNS label (a-z, 0-9, -), at most 63 characters. Some kinds are stricter (24 characters for App, OCI component name for RegistryRepository): the kind's page says so.
• metadata only holds name: no tenant (inferred from your session), no labels, no annotations. sng apply rejects any other key with metadata : seul name est permis (<clé> refusé). A manifest from before this rule reads back without these keys (sng kind get, sng pull): re-apply it as read back.
• status: written by the platform. If it is present in your file (for example after a sng kind get), it is ignored when applying.

Multiple documents per file

A file can contain several manifests separated by ---. sng apply also accepts a directory: it reads every .yml and .yaml file.

Status, conditions, and reasons

The status of a resource almost always contains:

Field	Meaning
observedGeneration	The version of the spec the platform has processed. If it is lower than metadata.generation, your latest change has not been taken into account yet.
conditions[]	A list of named states, each with type, status (True/False/Unknown), reason (a CamelCase word), message (a sentence), and lastTransitionTime.

The most common condition types:

Type	True means	False means
Ready	The resource does what you asked for	Something is missing or failing: read reason and message
Progressing	A convergence is in progress (deployment, image pull)	Nothing in progress
Degraded	One part works, another does not	—
Accepted	The manifest passed admission (quotas, consistency)	Rejected: reason says why
Synced	The external state (provider, registry, DNS) matches the spec	Out of sync

The reason is stable and documented: each reference page lists those of its kind, and the conditions index gathers them all.

sng app describe web       # state of an App
sng secret describe db     # state of a secret
sng kind get App web            # saved manifest, then its state as comments

Deletion policies

Several kinds have a spec.deletionPolicy field that says what happens to external objects when you delete the manifest:

Value	Effect
Block	Deletion waits until the resource is no longer used (images in a repository, members in a group, users holding a role…): the status says what remains. As soon as you have emptied it, it completes on its own and the external object is deleted.
Orphan	The manifest disappears; the external object is left in place.
Delete	The external object is deleted along with the manifest.

When a kind does not have this field, its reference page describes the behavior (for example, the volumes of an App always survive its deletion).

A resource being deleted stays visible for a few moments while cleanup finishes. It then disappears on its own.

Immutability

Some fields can no longer change after creation (for example spec.domain of a DNSZone). Changing an immutable field is rejected at apply time, with a message that names it. You must delete and recreate the resource.

Validation rules

Two levels of validation apply, both before the manifest enters the desired state:

1. Per field: type, bounds (minimum, maxLength), pattern (pattern), enumeration. These rules appear in the Validation column of the fields tables.
2. Cross-field: rules that tie several fields together ("schedule is required if kind: cronjob", "a CNAME has only one target"). They are listed in plain language under each fields table, in the Cross-field validation rules section.

A rejected manifest is not applied at all, not even partially.

Compatibility

All kinds are at v1alpha1. The compatibility policy describes what can change and how changes are announced.