deploy

Install, upgrade or reconfigure the cluster, and take backups

You're viewing a development version of manager, the latest released version is 1.6.2

Page not available in that version

The current page deploy doesn't exist in version 1.6.2 of the documentation for this product.

We can take you to the product root for that version instead: /docs/acd/components/manager/1.6.2/

Synopsis

deploy init [prod|lab]
deploy [run] [-i <inventory>] [<ansible-playbook option>...]
deploy backup [-i <inventory>] [<ansible-playbook option>...]
deploy -h | --help

Description

deploy is on the installation ISO, at /mnt/esb3027/deploy; it is not on the PATH. Run it as root on the first server in the inventory, with the ISO mounted at /mnt/esb3027. It reaches every machine in the inventory, the first server included, over SSH.

deploy reads its configuration from /etc/acd/deploy, applies it to every machine, and installs or upgrades the cdn-platform Helm release. The first run installs; every later run re-applies the configuration and changes only what differs. Running it again is safe, including after a failed run. It is the only supported way to change what is installed.

When deploy stops on a problem it recognizes, its message starts with a code such as [ACD-TLS-HOSTNAME]. Each code is described in Installation Troubleshooting.

With -h or --help, deploy prints its usage and exits.

Commands

init

deploy init [prod|lab]

Prepares the first server. Run it once before the first deploy, and again after mounting a new ISO elsewhere. It:

Installs ansible-core from the operating system’s repositories with dnf, unless it is already installed.
Installs the Ansible collections bundled on the ISO, unless they are already installed.
Creates /etc/acd/deploy and every file in it that is missing: see Files. It never overwrites a file that exists.
Points preset.yaml at the chosen preset on the ISO.

Argument	Effect
`prod`	Uses the production preset. A new configuration gets `prod` when no preset is given.
`lab`	Uses the lab preset.
(none)	On an existing configuration, keeps the current preset and re-points `preset.yaml` at the mounted ISO.

deploy init takes no other arguments.

run

deploy [run] [-i <inventory>] [<ansible-playbook option>...]

Runs the deployment. run is the default and can be left out. Every run takes a backup before it changes anything, even with the preflight checks skipped, and stops if the backup fails. The stages of a run are described in Running deploy.

backup

deploy backup [-i <inventory>] [<ansible-playbook option>...]

Takes a backup and changes nothing. It runs only the gather-inputs and backup stages, so it also skips the preflight checks. See Files for what a backup holds.

Options

Option	Commands	Effect
`-i <inventory>`	`run`, `backup`	Uses this inventory file instead of `/etc/acd/deploy/inventory.ini`. The settings still come from `/etc/acd/deploy/group_vars/all.yaml`, which must exist.
`-h`, `--help`	all	Prints the usage and exits with status 0.
`--skip-tags preflight`	`run`	Skips the preflight checks. The run still works out every setting and takes the backup. The check of each machine’s network after it is changed cannot be skipped.
`-v`, `-vv`, `-vvv`	`run`, `backup`	More detailed output, for support.

Every other option is passed to ansible-playbook. These are rejected, because every run must start with gathering inputs and the backup:

Option	Rejected with
`--start-at-task`, or any prefix of it from `--sta`	every command
`--skip-tags` naming `always`	every command
`-t`, `--tags`, or any prefix of `--tags` from `--ta`	`deploy backup`
`--limit`	`run`: the run stops with `[ACD-PARTIAL-RUN]`, because what each machine’s firewall trusts depends on all of them

Environment

Variable	Effect
`ACD_CONFIG_DIR`	The configuration folder. Default: `/etc/acd/deploy`. Every path on this page under `/etc/acd/deploy` moves with it.

Files

Configuration

In /etc/acd/deploy, created by deploy init and edited by you:

File	Contents
`inventory.ini`	The machines and their roles. See Inventory.
`group_vars/all.yaml`	The site settings. See Site Settings.
`values.override.yaml`	Your application settings. See Application Settings.
`preset.yaml`	A link to the chosen preset on the ISO. Change it with `deploy init prod` or `deploy init lab`.
`certs/`	The TLS certificate and key. See TLS Certificates.
`maxmind/`	The MaxMind databases. See GeoIP Databases.
`README.md`	A copy of the configuration reference shipped on the ISO.

Written by a Run

In /etc/acd/deploy:

File	Contents
`deploy.log`	Every run’s output, newest last, each under a header with its start time in UTC
`values.yaml`	The Helm values the cluster received. Generated: do not edit. See Application Settings.
`decision-record.json`	What the run worked out about the cluster and each machine
`probe/<machine>.json`	Everything the run read from each machine
`support-bundle-acd.tar.gz`	Written only when the final health check fails

Backups

Each run, and each deploy backup, writes a folder on the first server, <backup_dir>/<UTC time>-cdn-platform/, readable only by root. backup_dir is a site setting and defaults to /var/lib/acd/backups. deploy never deletes a backup.

File	Contents
`<machine>.tar.gz`	That machine’s files as they were before the run: k3s configuration, unit files and token, network connection profiles, firewall, sysctl and kernel module settings, SELinux configuration, `/etc/hosts` and routing table names. The first server’s archive also holds `/etc/acd/deploy`, except `certs/`, `maxmind/` and `deploy.log`. On a running cluster, one server’s archive also holds an etcd snapshot of the cluster.
`<machine>.files.sha256`	A checksum for every file in that archive
`SHA256SUMS`	A checksum for each archive
`manifest.yaml`	The release, the machines, the run time and the etcd snapshot’s path

A backup holds configuration only, never the data stored in the cluster. See Running deploy.

Exit Status

Status	Meaning
`0`	The run, backup or initialization finished, or `-h` printed the usage
`1`	`deploy` refused to start: an unknown command or bad arguments, a rejected option, no configuration in `/etc/acd/deploy` (run `deploy init`), `ansible-core` missing, a `preset.yaml` that points at an ISO no longer mounted there, or a failed `deploy init`
other	The exit status of `ansible-playbook`: the run started and stopped on a failure. The last message names the cause, usually with an `[ACD-…]` code.

Examples

Prepare a new lab installation:

/mnt/esb3027/deploy init lab

Install, or apply a changed configuration:

/mnt/esb3027/deploy

Apply the configuration without the preflight checks:

/mnt/esb3027/deploy --skip-tags preflight

Take a backup and change nothing:

/mnt/esb3027/deploy backup