17. Backup and Restore

Koios Automation Platform is backed up and restored through the Koios operator, with two resources in the namespace of the platform:

  • a KoiosPlatformBackup captures the databases of every component (platform gateway, automation controller and, when they are enabled, Event-Driven Ansible and automation hub), the content files of automation hub, the secrets that encrypt them, and the KoiosPlatform specification;

  • a KoiosPlatformRestore creates a new KoiosPlatform from a backup. It never changes the platform the backup was taken from, so you can restore next to it and compare.

The fields of both resources are listed in KoiosPlatformBackup and KoiosPlatformRestore. On OpenShift, you can also create them from the installed operator in the web console.

Note

Backup and restore also cover external PostgreSQL databases: the operator dumps and restores them the same way. A restore keeps the database mode of the backed-up platform. To restore a platform with external databases, give the destination its own Secrets in spec_overrides (database.database_secret, controller.database_secret and, when they are enabled, eda.database_secret, eda.event_stream.database_secret and hub.database_secret), different from each other and from the original ones, pointing to databases you have created and left empty. To restore into a PostgreSQL managed by the operator instead, set spec_overrides.database.managed: true.

17.1. Backing up

Create the backup in the namespace of the platform, naming the KoiosPlatform to back up:

kubectl apply -n koios -f - <<'EOF'
apiVersion: platform.koioss.com/v1alpha1
kind: KoiosPlatformBackup
metadata:
  name: koios-backup-2026-11-05
spec:
  deployment_name: koios
EOF

The operator creates one persistent volume claim per component, unless you name existing ones in spec.<component>.backup_pvc, and checks every file it writes (its SHA-256 is kept in the status). A small platform takes a minute or two. When the backup is complete, its status says so and records where the files are:

kubectl get koiosplatformbackup koios-backup-2026-11-05 -n koios \
  -o jsonpath='{.status.backupComplete} {.status.backupDirectory}{"\n"}'

By default, deleting the KoiosPlatformBackup keeps the files. Set clean_backup_on_delete: true to remove them, and the claims the backup created, along with it.

Copy the backup somewhere off the cluster as well: a volume in the same cluster does not protect you against the loss of the cluster.

Warning

A backup contains the databases and the Secrets of each component: the keys that encrypt the credentials stored in the databases, the secret keys, the administrator passwords and the certificate authority and signing key of receptor. Anyone who can read the backup can read every credential stored in the platform and act as its administrator. Restrict access to the backup volumes and to their copies, and encrypt the copies you keep off the cluster.

17.2. Restoring

Create a KoiosPlatformRestore that names the backup and the new platform. The destination KoiosPlatform must not exist yet. The new platform takes the backed-up specification; use spec_overrides to change part of it. When you restore next to the original, give the copy its own address, so that both do not claim the same host:

kubectl apply -n koios -f - <<'EOF'
apiVersion: platform.koioss.com/v1alpha1
kind: KoiosPlatformRestore
metadata:
  name: koios-restore-2026-11-05
spec:
  backup_name: koios-backup-2026-11-05
  deployment_name: koios-restored
  spec_overrides:
    hostname: koios-restored.example.com
EOF

The operator creates the new platform held, restores each database into it (with the files of automation hub), and then lets it start. The restore is complete when its Complete column is true; its status lists the restored components:

kubectl get koiosplatformrestore koios-restore-2026-11-05 -n koios
kubectl get koiosplatformrestore koios-restore-2026-11-05 -n koios \
  -o jsonpath='{.status.restoredComponents}{"\n"}'

The restored platform becomes available service by service. Its gateway starts without the service nodes copied from the original, so it sends no requests to the original services, and each service is registered, with new service keys, as it comes up. Until then, requests to that service fail (for example with 503).

Warning

A restored platform is a copy of the original, including what points outside it. When the original keeps running, check before you use the copy:

  • its address: change hostname (or route_host) with spec_overrides;

  • an external Redis: give the copy its own with spec_overrides, as two platforms must not share one;

  • credentials and integrations that point to the original platform, such as the credential an Event-Driven Ansible activation uses to launch jobs: update them before you enable activations and schedules in the copy;

  • trust between the two: the copy signs the tokens its gateway passes to its services with the same keys and issuer as the original, so both platforms trust the same tokens. Treat the copy as part of the security boundary of the original.

A restore resumes where it stopped: components already recorded as restored in its status are skipped. But if it fails after restoring a component’s database and before recording that component (for example, while it extracts the files of automation hub), retrying fails, because that database is no longer empty. Start again with a new destination.

To restore from files that are no longer tied to a KoiosPlatformBackup (for example, after copying them into a new cluster), use backup_dir and spec.<component>.backup_pvc instead of backup_name.