shc deploy
shc deploy
Section titled “shc deploy”deploy the deployments declared in one or more .shc.yaml deployfiles
Synopsis
Section titled “Synopsis”Deploy from a .shc.yaml deployfile: a declarative manifest naming the
app, what it exposes, the --var wiring and the environments a
stack deploys to. A deployfile is to shc what a helmfile is to helm.
The verb is install-or-update: a (stack, environment) that does not exist yet is installed from the app directory, one that does is updated with the declared hosts re-asserted. Running it repeatedly is the normal case: the pipeline that runs it is the reconciler.
The file is the deployment’s whole desired state. An update converges to
it: every route and port, integration, --var override, operator label,
where and prefer the file does not name is removed, a hand-added one
included, and a file with no expose: means no routes and no ports. The
routes an app declares behind a host (x-shc-path) come with that host.
A file names one source: app: for an app directory in this checkout
(an app repo deploying what it just built), catalog: for a catalogue
app, optionally with repo: and version: (an estate deploying something
it does not build), or git: for a git remote, its url, the ref it
renders and the path that holds the app (an estate deploying an app from
its own repo). A deployment that records another source is repointed onto
the file’s before its update. An estate file can also name its
tenant:, wire the deployment to its neighbours with integrate: (a map of
consumer plug to provider), and set the SSO gate with gated:.
expose: takes the --expose grammar, routes and ports alike. Each hostname
is written for prod and fans out per environment on the convention the
GitLab CI generator uses: app.example.com is app.dev.example.com in dev,
inside the environment’s DNS base, placed the same way in test or any
other environment, domain:
key, and a file carrying one is refused. The DNS zone the first hostname
lives in gives the environment’s DNS base, dev.example.com in dev and
example.com in prod: the longest zone of the daemon’s public DNS
connections, or the hostname’s registrable domain when no connection
holds it or no daemon is asked, and the plan says which. The deployment
records that base, and its hosts directly under it that share one address
publish one wildcard and one claim. ${VAR} references in the file resolve
from --env-file, the process environment and --set, in that order of
increasing precedence; an undefined variable is refused rather than
rendered as an empty value.
vars: is a tree, as an app’s vars.yaml is: postgres: {image: {tag: 16}}
sets what --var postgres.image.tag=16 sets. A key with a dot in it is
refused. A list is one var holding its JSON: roleKeys: [eng, ops] sets
what --var 'roleKeys=["eng","ops"]' sets.
storage: sizes the volumes, one entry per volume: pgdata-1: 20Gi, or
pgdata-1: hcloud:20Gi to name the backend too. Each renders one
--storage, as on shc install. --storage on the command line adds to them,
and for a volume both name the flag wins. An update sizes the volume as
shc update --storage does and keeps the backend its install chose.
scale: maps service or group names to --scale values, as strings or
integer counts. Every deploy passes them to install or update. A name
removed from the map keeps its stored scale.
quota: maps a service to its cpu: and memory: quota, as
--cpu-quota and --memory-quota take them: web: {cpu: "0.5", memory: 512M}.
Every deploy passes them to install or update, so they land in the
deployment’s resource overrides. A service or axis removed from the map
keeps its stored quota.
addons: lists the vApp add-ons the deployment carries, otpmanager or
[email protected], on a catalog: file. After the deployment has
deployed, each is installed into it in file order, as
shc install <catalog>/<add-on> --into <stack>, and one already there
is updated to its version, or the catalogue’s newest when the file pins
none. The plan prints each add-on’s step after its deployment’s.
An environment block may carry app:, vars:, scale:, quota:, integrate:
and connections: of its own. Its app replaces the file’s for that
environment, and the others merge key by key over the file’s, the
environment’s entry winning, so a review deployment can be a thinner
app, seeded, and only staging and prod bind a CDN bucket. An
environment adds or replaces an entry and never removes one: a plug
only some environments bind is named in their blocks alone. Nothing
else differs per environment: stack: and tenant: are the
deployment’s identity.
--dry-run is the plan and changes nothing. For each deployment it prints install, no changes, or the update’s changes against what runs: the app digest it would move to, vars by key (a secret’s value never shown), integrations, routes with the app’s own paths, ports, where and prefer, labels and volume sizes, removals first. It exits 0 when nothing would change and 3 when something would. With no cluster named it needs no daemon and prints the resolved argv and variables instead, so a deployfile is reviewable from a laptop. Logged in to a cluster, given a socket, or run on a cluster node, it asks that daemon, and fails when it cannot.
An app: directory on this machine goes to a daemon on another machine as an upload, which the cluster keeps by its digest. A catalog: app travels by name.
Several deployfiles deploy as a set: -f repeated, or -f a directory, which reads every *.shc.yaml directly inside it. Deployments start at once, except that one whose integrate: names another deployment of the set (same tenant and environment) waits until that one has deployed. A deployment whose provider failed never starts, and the first failure stops every deployment not yet started unless --keep-going is given. Integrate edges that form a cycle, and two files naming one deployment, are refused before anything deploys.
shc deploy -f <file.shc.yaml|directory> -e <environment> [flags]Examples
Section titled “Examples” shc deploy -f deploy/ioverse.shc.yaml -e dev shc deploy -f deploy/ioverse.shc.yaml -e review --slug feat-login-42 shc deploy -f deploy/ -e prod # every *.shc.yaml in deploy/, as one set shc deploy -f deploy/postgres.shc.yaml -f deploy/gitea.shc.yaml -f deploy/wiki.shc.yaml -e prod # gitea integrates postgres, so it waits for it; wiki starts at once shc deploy -f deploy/ioverse.shc.yaml -e dev --dry-run # the plan, touches nothing shc deploy -f deploy/ioverse.shc.yaml -e dev --env-file .env --set CI_COMMIT_SHORT_SHA=abc1234Options
Section titled “Options” --dry-run print the plan, what each deployment's install or update would change, and change nothing; exits 3 when something would change --env-file stringArray file of KEY=VALUE interpolation values (repeatable; the process environment and --set beat it) -e, --environment string environment to deploy (must be declared in the deployfile) -f, --file stringArray deployfile, or a directory of *.shc.yaml deployfiles (repeatable); deployments start at once, except one whose integrate: names another deployment in the set, which waits for it -h, --help help for deploy --keep-going after a failure, still start every deployment that does not wait on a failed one (still exits non-zero) --set stringArray interpolation value (KEY=VALUE); beats both --env-file and the environment --slug string review-app slug; the review host is <slug>.review.<host>, and a slug past 56 bytes is cut to fit an environment name, the same for every deployfile --storage stringArray volume storage, repeatable, as on shc install: <backend>, <volume>=<size> or <volume>=<backend>:<size>; a volume named here outranks the deployfile's storage: entry for it; an update sizes the volume and keeps the backend its install choseOptions inherited from parent commands
Section titled “Options inherited from parent commands” --config stringArray extra YAML config file to layer on top of auto-discovered config; repeatable, later files win -d, --debug enable debug mode (default: $SHC_DEBUG) --exclude string comma-separated dotted paths to drop --fields string comma-separated columns/keys to show (and their order) --filter string comma-separated dotted paths to keep (drops everything else) -o, --output string output format: tty|text|json|yaml (default: $SHC_OUTPUT) -s, --stack string stack name (default: $SHC_STACK) -t, --tenant string tenant name (default: $SHC_TENANT) -v, --verbose verbose output (default: $SHC_VERBOSE)SEE ALSO
Section titled “SEE ALSO”- shc - Selfhosted Cloud CLI