Coriolis STACKIT Installer
Last updated on
Overview
Section titled “Overview”The Coriolis STACKIT Installer deploys and maintains a Cloudbase Coriolis appliance on STACKIT. For deployment, a single Go binary validates the OVA and target placement, prepares a reusable STACKIT image, provisions the runtime infrastructure, and bootstraps access without Terraform, the STACKIT CLI, a serial console, or manual Web Console steps.
This asset covers appliance deployment, repeatable provisioning, status checks, and approved in-place service updates with mandatory volume snapshots. Maintenance uses the existing VM through STACKIT Server Agent and Run Command, without manual SSH or console login. Cloudbase Coriolis provides the actual migration and disaster recovery capabilities used after the appliance is ready.
Cloudbase Coriolis Review the migration, replication, and disaster recovery capabilities of the deployed product. Open pageWhat the installer automates
Section titled “What the installer automates”- OVA inspection and placement validation: Reads OVF metadata, calculates the OVA SHA-256, and rejects incompatible disk sizing, availability zones, or machine types before image upload.
- Image normalization: Streams the VMDK to a temporary STACKIT helper VM, converts it through RAW to QCOW2, installs the STACKIT Server Agent offline, and imports a reusable image.
- Image reuse and sharing: Discovers normalized images by OVA hash, resumes interrupted imports, and supports project-specific, organization-wide, or central image-project sharing.
- STACKIT infrastructure: Creates or reuses the network, security group, appliance VM, public IP, DNS record, and supporting resources from declarative YAML settings.
- Bootstrap and exposure: Configures the hostname and appliance administrator password through Run Command, then provides direct HTTPS with ACME DNS-01 or optional TLS termination through a STACKIT Application Load Balancer.
- Repeatable execution: Reuses matching infrastructure, generated credentials, and current certificates on subsequent runs and returns a structured JSON result for downstream automation.
- Status and version discovery: Reports the installed release, container health, storage usage, active executions, and enabled schedules. Discovers published releases and checks the availability of required component images for newer targets in the same release stream.
- Approved service updates: Requires an explicit plan approval and an exclusive maintenance window. Stops appliance services and the VM, creates cold snapshots of every attached volume, restarts the same VM, and launches the service update. A persistent status file supports monitoring and independent checks of the target release, data inventory, configuration, and TLS.
Inputs and outputs
Section titled “Inputs and outputs”Typical deployment inputs are:
- a STACKIT service-account key and target project ID;
- the target STACKIT region;
- a supported Cloudbase Coriolis OVA;
- a YAML configuration based on the repository example.
The successful deployment result contains the resolved image, network, server, security group, public IP, and login details as JSON. When configured to print a generated appliance password, route stdout directly into a protected secret store instead of retaining it in terminal or build logs.
Maintenance reuses the project, region, and credentials from the configuration and selects an existing appliance by server ID; no OVA is required. Status checks, version discovery, and update planning return JSON. Keep the update status file on protected, persistent storage until the attempt has been fully reviewed.
Recommended workflow
Section titled “Recommended workflow”For a new deployment:
- Build the binary with
make check, or use a suitable prebuilt binary when one is available. - Copy the example YAML, add project-specific values, and protect the service-account key and any fixed password.
- Run
--dry-runto validate configuration, OVA metadata, sizing, and the resolved deployment plan without cloud changes. - Run
--check-cloudto validate authentication, placement, and optional DNS or load-balancer access, then verify quotas separately. - Run the deployment, store its JSON result securely, and repeat the same command to confirm that resources are reused.
Maintain an existing appliance
Section titled “Maintain an existing appliance”| Command | Purpose |
|---|---|
status | Inspect the installed release and appliance health without changing configuration |
versions | List published releases and eligible update targets |
update | Print a plan; execute it only with explicit approval and --apply |
update-status | Monitor the launched updater and verify its result |
Use the existing deployment configuration and select the appliance explicitly:
CONFIG="config.local.yaml"SERVER_ID="<appliance-server-id>"
bin/coriolis-stackit status --config "$CONFIG" --server-id "$SERVER_ID"bin/coriolis-stackit versions --config "$CONFIG" --server-id "$SERVER_ID"bin/coriolis-stackit update --config "$CONFIG" \ --server-id "$SERVER_ID" --latest-compatible--latest-compatible selects the newest eligible target in the installed YYMM release stream;
it does not mean the newest release across all streams. Alternatively, plan with an explicit
numeric --target-version. The literal value latest is not supported. Review the release
notes, the plan’s numeric target_version, its snapshot volumes, and its approval value.
A failed version query does not mean the appliance is up to date.
Before execution, reserve a maintenance window with downtime. Let all tenant executions finish, disable every transfer schedule, and prevent users, automation, and workers from submitting new work. The appliance and package manager must be ready, and inspected filesystems must be below 80% usage.
Execute the reviewed numeric target with a new persistent status file for each attempt:
TARGET_VERSION="<numeric-target-from-plan>"STATE_FILE="<new-persistent-status-file.json>"
bin/coriolis-stackit update --config "$CONFIG" \ --server-id "$SERVER_ID" --target-version "$TARGET_VERSION" \ --apply --approve-plan "<approval-from-reviewed-plan>" \ --confirm-server-id "$SERVER_ID" --state-file "$STATE_FILE"
bin/coriolis-stackit update-status --config "$CONFIG" \ --server-id "$SERVER_ID" --state-file "$STATE_FILE"Without --apply, planning does not stop services, create snapshots, or perform an update.
Execution creates new native STACKIT snapshots of every attached volume, including the boot
volume, while the VM is stopped. The VM restarts only after all snapshots are available.
Snapshots are mandatory and retained; the VM and its boot volume are not replaced.
Keep the CLI connected until update --apply returns. A successful return confirms that the
updater was launched, not that the update finished. Repeat update-status with the same file
until stage: verified, then perform a representative functional test before resuming normal
use. Failed verification requires investigation; do not blindly repeat --apply or remove a
maintenance lock.
Prerequisites
Section titled “Prerequisites”- Operator workstation: Requires the installer binary, read access to the OVA, outbound HTTPS to STACKIT APIs, and temporary outbound TCP/22 to the helper VM during a new image import. Building from source requires Go 1.25 or newer.
- Service-account permissions: Automatic Run Command activation requires the
Project Editorrole. The selected workflow also needs read and write access to its IaaS, Server Agent, DNS, and optional load-balancer and certificate resources. - Quota and connectivity: The first import temporarily uses a helper VM, two data volumes, a public IP, a security group, and a key pair in addition to the final image and appliance resources.
- OVA format: The OVA must be TAR-based and contain exactly one OVF and one referenced virtual disk. The current installer supports one appliance disk.
- Storage performance: The documented default uses
storage_premium_perf12for appliance and normalization volumes because conversion, image upload, migration, and backup paths create sustained I/O load. - Maintenance access: Existing appliances require a working Server Agent and an already enabled Run Command service. Updates additionally require server stop/start and volume snapshot permissions, snapshot quota, and access to the release notes and required images. Maintenance does not require the original OVA.
Security and operational boundaries
Section titled “Security and operational boundaries”- The appliance security group opens only TCP/443 by default. The STACKIT Server Agent uses an outbound management channel and does not need an ingress rule.
- A new OVA import temporarily permits TCP/22 to the helper VM from
0.0.0.0/0. Access requires a one-time key and a host key pinned through Server Agent. Rerun or clean up promptly after a failed import because helper resources may remain for recovery. - Direct TLS keeps the private key on the appliance. The optional Application Load Balancer covers only the HTTPS web path and does not proxy every Coriolis migration or worker connection.
- Existing servers, failed VMs, security-group rules, and licensed appliance state are never deleted or replaced implicitly.
- Update snapshots cover the appliance volumes, not external databases, workers, or remote source and target systems. Keep an independent backup and a tested recovery plan for production use.
- There is no automatic rollback. Retain the status file and snapshots for recovery; do not treat running containers or a reachable web interface alone as functional acceptance.
Limitations
Section titled “Limitations”- Service updates support only newer numeric releases in the installed YYMM stream, not cross-stream upgrades, downgrades, or reinstalls. Technical eligibility does not replace confirming the supported upgrade path with Cloudbase.
- A service update does not necessarily include every operating-system change in a newer OVA. The installer does not migrate licenses, projects, endpoints, transfer state, or application data to a different appliance.
- A new OVA creates a new normalized image but never replaces an existing stateful server automatically.
--check-cloudvalidates access and placement but does not reserve resources or replace a full quota check.- Adopting an existing server can change its hostname, administrator password, or TLS configuration when the corresponding management features are enabled. Back up a licensed production appliance before first adoption.
References
Section titled “References”Asset historyActive 2 of the last 12 weeksLWUpdatedNo updates · 1 bar = 1 week i
- LWLukas WeberrußHead of STACKIT Cloud Migration Framework · STACKITOwner
Lukas WeberrußHead of STACKIT Cloud Migration Framework · STACKITOwnerActive 12 of the last 12 weeks · 58 updateswww.linkedin.com/in/lukas-weberruß-a360b081