← Back to PortfolioMK
How-to

Task 3.2: Install the control plane

A full task module: prerequisites, warnings, numbered steps, verification, and what to do if verification fails.

Purpose

This task installs the Orchestrator control plane on a single host and brings it to a running state. At the end of this task, the control plane accepts API requests and is ready to enroll worker nodes.

Worker enrollment is Task 3.3. High-availability control planes are Task 3.5. Do not begin either until this task is verified.

Estimated time: 25 minutes.

Prerequisites

Confirm all 8 items before you begin. A missing item found partway through requires the procedure to be started again.

# Item How to confirm
1 Host running RHEL 9.2+, Ubuntu 22.04+, or Debian 12+ cat /etc/os-release
2 8 CPU cores, 16 GB RAM, 200 GB free on /var nproc, free -g, df -h /var
3 Root or full sudo privilege sudo -v returns without error
4 PostgreSQL 15+ reachable, with an empty database psql -h <db-host> -U <user> -l
5 TLS certificate and private key for the control-plane hostname Files present and readable
6 DNS A record for the control-plane hostname resolving to this host dig +short <hostname>
7 Inbound TCP 8443 permitted from the worker subnets Firewall rule confirmed with its owner; tested end to end in Task 3.3
8 Outbound HTTPS to the package repository curl -sI https://repo.orchestrator.io

The certificate at item 5 must carry the hostname from item 6 in its subject alternative name field. A mismatch is not detected until verification check 2. Correcting the mismatch then means repeating step 6 with the right certificate and restarting the service.

Advisory notices for this task

Each notice in this section is repeated, unchanged, before the step it governs.

CAUTION

The package does not start the service when it is installed. Do not start the service before step 9. A service started without a complete configuration writes a partial state file. The procedure must then be started again from step 4.

WARNING

The private key installed at step 6 grants the identity of the control plane. A key readable by other accounts permits impersonation of the control plane to every worker node.

WARNING

Step 7 initializes the database schema and erases all data in the target database. Confirm the database is empty before you run step 7. Data erased at this step is not recoverable.

Procedure

Install the package

  1. Log in to the control-plane host as a user with sudo privilege.

  2. Download the repository setup script:

    curl -fsSLo /tmp/orchestrator-setup.sh https://repo.orchestrator.io/setup.sh

NOTE

The setup script adds the Orchestrator package repository and its signing key. It changes nothing else. If your security policy requires review of scripts run as root, read the script before step 3.

  1. Run the setup script:

    sudo bash /tmp/orchestrator-setup.sh

CAUTION

The package does not start the service when it is installed. Do not start the service before step 9. A service started without a complete configuration writes a partial state file. The procedure must then be started again from step 4.

NOTE

On RHEL, the command for step 4 is sudo dnf install -y orchestrator-control-plane-4.6.0. The remaining steps do not differ.

  1. Install the control-plane package:

    sudo apt-get install -y orchestrator-control-plane=4.6.0

  2. Confirm the installed version:

    orchestrator-ctl --version

    The output reads orchestrator-ctl 4.6.0. If the output shows a different version, do not continue. Uninstall the package, then repeat step 4.

Install the certificate

WARNING

The private key installed at step 6 grants the identity of the control plane. A key readable by other accounts permits impersonation of the control plane to every worker node.

  1. Copy the certificate and the private key into the configuration directory:

    sudo install -o orchestrator -g orchestrator -m 0644 \
  <cert-path> /etc/orchestrator/tls/server.crt
sudo install -o orchestrator -g orchestrator -m 0600 \
  <key-path> /etc/orchestrator/tls/server.key

    The mode on the key is 0600. Do not widen the mode. If a later step reports that the key is unreadable, correct the owner, not the mode.

Initialize the database

WARNING

Step 7 initializes the database schema and erases all data in the target database. Confirm the database is empty before you run step 7. Data erased at this step is not recoverable.

  1. Initialize the schema:

    sudo -u orchestrator orchestrator-ctl db init \
  --dsn "postgresql://<user>@<db-host>:5432/<database>"

    The command prompts for the database password. It stores the password in /etc/orchestrator/db.secret with mode 0600. It then prints the name of the target database. Read the printed name before you confirm.

    Expected output ends with schema initialized: 52 tables.

Configure and start

  1. Write the configuration file:

    sudo -u orchestrator tee /etc/orchestrator/control-plane.yaml <<'EOF'
listen: 0.0.0.0:8443
hostname: <control-plane-hostname>
tls:
  certificate: /etc/orchestrator/tls/server.crt
  key: /etc/orchestrator/tls/server.key
database:
  dsn: postgresql://<user>@<db-host>:5432/<database>
  password_file: /etc/orchestrator/db.secret
EOF

    Substitute every value in angle brackets. The hostname value must match the subject alternative name in the certificate from step 6. The password is not written into this file; the service reads it from password_file.

  2. Start the service:

    sudo systemctl enable --now orchestrator-control-plane

  3. Wait 30 seconds for the service to complete its first-run checks.

Verification

Perform all 3 checks. The task is complete only when all 3 pass.

Check 1: the service is running.

systemctl is-active orchestrator-control-plane

Expected result: active.

Check 2: the API responds over TLS.

curl -sS https://<control-plane-hostname>:8443/healthz

Expected result: {"status":"ok","version":"4.6.0"}.

If check 2 reports a TLS error, see FI 7.2. The usual cause is a certificate that does not carry the hostname.

Check 3: the database is reachable from the service.

sudo -u orchestrator orchestrator-ctl status --verbose

Expected result: the output contains database: connected and schema_version: 46.

If verification fails

Check Symptom Go to
1 Service reports failed FI 7.1
2 TLS handshake error FI 7.2
2 Connection refused or timeout FI 7.3
3 database: unreachable FI 7.4
3 schema_version below 46 Repeat step 7 against the same database

Do not proceed to Task 3.3 while any check fails. A worker enrolled against an incompletely configured control plane holds a certificate that must be revoked by hand before the worker can be enrolled again.

Next

  • Task 3.3 enrolls worker nodes. Its first step confirms that each worker subnet reaches port 8443.
  • Task 6.1 configures the scheduled backup. Complete it within 24 hours; a control plane without a verified backup has no recovery path.
← Back to Portfolio