Install flags and steps
1. Flags
The options install.sh accepts, in the order it parses them, with the help install.sh --help prints for each. A flag the help does not describe is shown with the variable it sets.
| Flag | Description |
|---|---|
--update | same thing, named for what you meant |
--prepare-tenant | Sets GENTIAN_DIRECTION, GENTIAN_TENANT_NAME. |
--uninstall, --destroy | reverse order, destroy() each step |
--purge | the same, plus the data an uninstall keeps: OpenBao and infra volumes, and local state |
--explain | print what every step does, in order, and stop |
--status | report which steps this cluster has already satisfied |
--dry-run | run every check() and print the plan. Changes nothing: no object in the cluster, no file in the deployments checkout, no commit or push, no signing key, nothing under ~/.gentian or ~/.local/bin. Where an install would do one of those, it prints a line beginning "Would". It reads: the cluster, and the deployments repository's remote (to say whether the checkout is behind it). With --uninstall or --purge it previews the teardown the same way |
--force | apply even where check() says satisfied. The way past a step whose check tests the wrong thing, without editing code. A step needing this routinely has a check() that is asking the wrong question |
--step, --only ID[,ID...] | run only these steps (--step is a synonym) |
--from ID | start here and continue to the end |
--until ID | start at the beginning and stop after this one |
--skip ID[,ID...] | run everything except these |
--phase NAME | one phase: control-plane, secrets, platform, applications, handover — or its letter, A through E |
--layout | --layout v5 is the only layout and is now the default; the flag does nothing. |
--export-recovery-kit [PATH] | write the bootstrap material (master password, derivation salt, unseal keys, cluster identity) to an encrypted kit; default gentian-recovery-kit.age |
--recover PATH | load a kit before installing, so derived credentials reproduce their original values |
--rotate-break-glass-key | replace a break-glass signing key that is lost. The installer refuses to run when the key the deployments repository records for this cluster is not in this host's keyring; --recover puts it back. This is for when there is nothing to put back: it generates a new key, after a person has typed the old key's id at a terminal. Nothing confirms it on their behalf |
--disable-api-extensions | leave the store's extensions -- the Operations Console's service and the API-extension grant it needs -- out of the scaffold. Everything of Gentian OS stays: export, import, purge and the bundle need no extension |
--no-extra-services | leave out the store's extra services, which a cluster otherwise gets from the store's catalog: the Operations Console and the operations sync (platform tenant), the App Store app and the Aluvian Center (every other tenant, new ones included, while the cluster offers a store), and the store's vendor as every tenant's partner. Recorded on the Cluster claim (spec.catalogue. extraServices: false), so a later run keeps them out; GENTIAN_NO_EXTRA_SERVICES=0 brings them back |
--no-cluster-infra | do not issue the kernel wildcard certificate (C-03). That is all it leaves out: cert-manager, CNPG and Reloader are installed as always. The same as INSTALL_CLUSTER_INFRA=0 in the environment |
--cluster-infra | with --purge, also remove them and their CRDs: CNPG, Reloader, external-dns, cert-manager. They may serve workloads that are not Gentian's, and this discards the wildcard certificate, which Let's Encrypt rations to five per week for one set of names. It is also the ONLY thing that removes this cluster's published DNS records: without it external-dns is stopped before its sources go, so the records — and the per-hostname edge certificates that depend on them existing — survive a teardown |
--config-file PATH | override install.env |
--secrets-file | --secrets-file is no longer read. |
--no-config-files | ignore install.env entirely; take everything from the environment |
--verify-only | run post-install verification and print the summary |
--activate-admin | issue a new activation link for the cluster administrator (admin@<kernel-domain>), mailed or shown once — for a lost password when nobody can sign in to ask the director |
--validate, --check | check the step files, report which settings and credentials this configuration has, then run the pre-flight (tools, cluster reachable, Kubernetes version, operator image). Asks no question, collects no credential and runs no step's check(). Changes nothing, on the same terms as --dry-run |
-h, --help | this message |
2. Steps
The step files under scripts/steps/, in the order the installer runs them, as their header lines declare them: what each provides, which steps it requires, what it mutates, and which entries of versions.yaml it pins.
2.1 Phase A: control-plane
| Step | Provides | Requires | Mutates | Pins |
|---|---|---|---|---|
A-01-namespaces | every kernel namespace of kernel/namespaces.yaml, labeled with gentianos.io/tier and gentianos.io/function; the platform's own namespaces labeled; in each kernel namespace the NetworkPolicies of kernel/security/network-policies when KERNEL_NETWORK_POLICIES=true, and none of them otherwise | namespaces, and the NetworkPolicies labeled gentianos.io/kernel-network-policy in the kernel namespaces | ||
A-02-cert-manager | cert-manager controller and its CRDs in the edge namespace | A-01-namespaces | the edge namespace, cert-manager CRDs, cluster-scoped RBAC | cert-manager |
A-03-external-secrets | External Secrets Operator and its CRDs in the secrets namespace | A-01-namespaces | the secrets namespace, ESO CRDs, cluster-scoped RBAC | external-secrets |
A-04-crossplane | Crossplane core and its CRDs in the provisioning namespace, without the default policy that activates every provider resource type | A-01-namespaces | the provisioning namespace, Crossplane CRDs, cluster-scoped RBAC | crossplane |
A-05-envoy-gateway | Envoy Gateway controller answering for the kernel's GatewayClass name, and the Gateway API CRDs, in the edge namespace | A-01-namespaces | the edge namespace, Gateway API CRDs, cluster-scoped RBAC | envoy-gateway |
A-06-argocd | Argo CD (server, repo-server, application controller, applicationset controller), argocd-image-updater, and, for gentian-os and deployments where they authenticate, the login Argo CD reads them with until the vault supplies it, in the gitops namespace | A-01-namespaces | the gitops namespace, Argo CD CRDs, cluster-scoped RBAC, the bootstrap repo-creds Secrets (argocd-repo-creds-bootstrap-gentian-os, argocd-repo-creds-bootstrap-deployments) | argocd |
A-07-metrics-server | metrics-server in kube-system (API aggregation convention), or the platform's own | A-01-namespaces | kube-system, the metrics.k8s.io APIService | metrics-server |
A-08-prewarm | pre-pulled images on every node, and the two cold-start races burned on a throwaway pod | A-01-namespaces | transient DaemonSet/Pods only — nothing that outlives the step | |
A-09-cluster-issuers | the cluster's trust anchor as ClusterIssuers, and the internal CA gentian-ca on every cluster | A-02-cert-manager A-03-external-secrets | cluster-scoped ClusterIssuer objects; the internal CA's ServiceAccount, and the Role and RoleBinding that let cert-manager request its token, in the cert-manager namespace |
2.2 Phase B: secrets
| Step | Provides | Requires | Mutates | Pins |
|---|---|---|---|---|
B-01-bootstrap-apps | the gentian AppProject and the kernel Applications of kernel/bootstrap/chart (reloader, cnpg, kyverno, headlamp, node-apparmor Synced and Healthy; openbao and openbao-transit Synced, awaiting their init; kernel-postgres created, awaited by C-02), each in its layout namespace | A-06-argocd | the ValidatingAdmissionPolicy gentian-namespace-tier and its binding (who may set a namespace's tier, function and mac-waiver labels); a placeholder Secret openbao-transit-unseal in the seal namespace; the vault's TLS in the secrets namespace (a self-signed Issuer, the CA openbao-ca, its Issuer, the serving Certificate openbao-tls); the copy openbao-ca-bundle of that CA's certificate in the cert-manager, control and provisioning namespaces; the vault pods' tls-crt-sha256 annotation, after signaling them to load their certificate; a restart of the custodian when the CA it trusts changed; Application and AppProject objects in the gitops namespace; what they sync lands in the seal, secrets, data, admission, observability and edge namespaces | headlamp openbao reloader cnpg kyverno external-dns |
B-02-seal-init | initialized transit seal in the seal namespace, its unseal key as a Secret there, and the transit token the vault reads from the secrets namespace | B-01-bootstrap-apps | transit OpenBao data; Secrets openbao-transit-unseal (seal namespace), openbao-transit-token (seal and secrets namespaces); ~/.gentian/openbao-transit-init.json | |
B-03-vault-init | initialized, auto-unsealed vault in the secrets namespace; BAO_TOKEN for the rest of the run | B-02-seal-init | vault storage; ~/.gentian/openbao-init.json (the recovery key and root token, until the recovery kit holds them) | openbao |
B-04-vault-auth | the vault's KV mount, the crossplane-write policy, and the openbao-crossplane-token Secret in the provisioning namespace | B-03-vault-init | vault secrets engines, policies and tokens; Secret openbao-crossplane-token in the provisioning namespace | |
B-05-crossplane-providers | the activation policy naming the provider resource types the platform uses, from this checkout, and those types as established CRDs; Crossplane providers kubernetes, helm and vault with their ProviderConfigs, in the provisioning namespace; provider-helm's second ProviderConfig tenant-apps, acting as the narrow account tenant apps are installed as | B-04-vault-auth | the ManagedResourceActivationPolicy gentian-platform, Provider packages, cluster-scoped RBAC for the providers, the ServiceAccount provider-helm-tenant-apps and the Secret provider-helm-tenant-apps (a kubeconfig holding no credential) in the provisioning namespace, ProviderConfigs | |
B-06-crossplane-definitions | the XRDs and Compositions of crossplane/, established, from this checkout, until the gentian-definitions Application delivers them | B-05-crossplane-providers | CompositeResourceDefinitions and Compositions (cluster-scoped) | logForwarding monitoring |
B-07-crossplane-secrets | the derived-credential Secrets the Cluster composition reads (master password and what is derived from it), in the provisioning namespace | B-04-vault-auth | Secrets in the provisioning namespace; the vault's gentian-os/kernel/internal paths | |
B-08-seed-secrets | the kernel KV paths ESO reads — DNS provider, tunnel, mail relay, registry, the deployments repository credential | B-07-crossplane-secrets | vault KV paths under gentian-os/kernel/; the vault's PKI engine pki-internal (the internal CA, made once, and its role gentian-ca); the Secret gentian-root-ca-tls in the cert-manager namespace (that CA's certificate, no key) | |
B-09-vault-oidc-mount | the oidc auth mount in OpenBao | B-08-seed-secrets | OpenBao auth mount oidc/ | |
B-10-deployment-signing | both deployment signing keys in Argo CD's keyring, and the director's private key in the vault | B-08-seed-secrets | ConfigMap argocd-gpg-keys-cm in the gitops namespace; the vault path gentian-os/kernel/signing/director |
2.3 Phase C: platform
| Step | Provides | Requires | Mutates | Pins |
|---|---|---|---|---|
C-01-cluster-claim | the Cluster claim of clusters/<cluster>/kernel/claims/cluster.yaml applied and its composite structurally Ready — the vault's Kubernetes auth and roles, the ESO ClusterSecretStore, the kernel config; the Keycloak-dependent parts follow Keycloak (C-02) | B-06-crossplane-definitions | the Cluster claim in the provisioning namespace and everything its composition creates | |
C-02-appsets | the kernel Postgres (kernel-postgres) Synced and Healthy, the gentian-appsets Application (kernel/appsets) Synced, and its children — the system tier's data plane, Keycloak and OpenFGA in their namespaces, the claims of the deployments repository — Synced and Healthy | B-08-seed-secrets | the gentian-appsets Application and the ApplicationSets it creates in the gitops namespace; what they sync | postfix |
C-03-wildcard-cert | the cluster issuers and the wildcard certificate for *.<kernelDomain>, copied into the namespaces that terminate TLS for a kernel host | C-02-appsets | ClusterIssuers, the Certificate in cert-manager, and wildcard-tls Secrets in the edge and gitops namespaces and, where the cluster runs its own mail, the mail namespace; on this host, the kept copy of the wildcard under ~/.gentian/certs | |
C-04-credential-catalogue | CredentialRequirement catalog and its ESO satisfaction probes | C-01-cluster-claim | cluster-scoped CredentialRequirement objects, ExternalSecrets in the control namespace | |
C-05-repository-handoff | removal of each bootstrap repo-creds bridge (gentian-os, deployments) once Argo CD holds the same login from the vault | C-04-credential-catalogue | deletes the bootstrap repo-creds Secrets in the gitops namespace |
2.4 Phase D: applications
| Step | Provides | Requires | Mutates | Pins |
|---|---|---|---|---|
D-01-operator | the gentian-os operator AND the director in the control namespace, the CRDs and webhook, and the kernel Gateway the operator reconciles in the edge namespace | C-02-appsets | the gentian-os Application in the gitops namespace; the operator's and the director's Deployments, RBAC and webhook; the Gateway and its routes | |
D-02-dns-wait | id.<kernel> resolving publicly, for the OIDC discovery D-03 is the first to need | D-01-operator | nothing — waits on a condition | |
D-03-portal-login | the kernel realm with its clients and the administrator user, Argo CD and Headlamp signing in against it, the platform tenant Ready and its desktop serving platform.<kernel> | D-02-dns-wait | Keycloak realm, clients, groups and users; the realm's mail server and the keycloak-smtp-credentials Secret; Secrets in the edge and gitops namespaces; the argocd-cm, argocd-rbac-cm and argocd-tls-certs-cm ConfigMaps (Argo CD's local admin off); the argocd-initial-admin-secret (deleted); the bootstrap Applications (Headlamp's OIDC on); the gentian-portal Application | |
D-04-vault-oidc-config | OpenBao's oidc mount configured against the kernel realm, so bao login -method=oidc works | D-03-portal-login | auth/oidc/config in OpenBao | |
D-05-gateway-wait | kernel Gateway reporting Programmed, and platform.<kernel> resolving publicly | D-04-vault-oidc-config | nothing in the cluster — waits on a condition; on this host, the kept copy of the wildcard under ~/.gentian/certs |
2.5 Phase E: handover
| Step | Provides | Requires | Mutates | Pins |
|---|---|---|---|---|
E-01-tenants | nothing at install time — tenants are created after installation | D-03-portal-login | Tenant, Component and App CRs, and the finalizer of the RoleBinding gentian-tenant-apps-helm in tenant namespaces, on teardown only | |
E-02-recovery-kit | an exported recovery kit, recorded in gentian-handover | E-01-tenants | writes the kit file; records recoveryKitExported | |
E-03-revoke-bootstrap-token | an installer whose OpenBao token no longer works | E-02-recovery-kit | revokes BAO_TOKEN; deletes the local openbao-init file | |
E-04-user-tenant | on a single-tenancy cluster, the user tenant Ready and its administrator's activation link issued; nothing on a multi-tenancy cluster | E-03-revoke-bootstrap-token | an Argo CD sync request for Application tenant-user; in Keycloak, the user admin's required actions (through issue_admin_activation) | |
E-05-operator-objects | the catalog and every declared tenant synced by Argo CD -- each of its apps syncing gentianos.io objects Synced -- and each declared tenant a Tenant on the cluster | E-04-user-tenant | Argo CD sync requests for those Applications whose last sync failed |