Operate
Operating Koios Automation Platform means maintaining a reconciled, observable platform and
checking that its services can perform useful work. The gateway operator reconciles
KoiosPlatform and its shared services; the controller, EDA and hub operators reconcile their
respective child resources.
Change supported settings in KoiosPlatform, or use the product UI/API for application objects.
Do not edit generated Deployments, container configuration files or service registrations by hand:
reconciliation can replace them. See Configure the platform and the
KoiosPlatform reference.
Components and workloads
The following map uses the default names observed on the test platform on 2026-11-18. <p> is the
KoiosPlatform name. The controller, EDA and hub resource names default to <p>-controller,
<p>-eda and <p>-hub; spec.controller.name, spec.eda.name and spec.hub.name can select
other names, including adopted resources. Read their actual names from status.controller,
status.eda and status.hub before constructing workload names.
Component |
Default workloads |
Responsibility / checks |
|---|---|---|
Platform gateway and proxy |
Deployment |
Shared UI/API entry point, authentication and routing; |
Automation controller |
Deployments |
Controller API/UI backend, scheduling and control tasks. Job execution can use separate container group pods or external execution nodes. |
Event-Driven Ansible |
Deployments |
API, background work, activation management and event streams. Rulebook activations have their own runtime pods/history. |
Automation hub |
Deployments |
Metadata/API, artifact delivery, imports/background work, web service and the hub’s own Redis/Valkey. |
Managed PostgreSQL |
StatefulSet |
Shared database service, with component-specific databases/users. The major-version suffix can change; use |
Gateway Redis/Valkey |
StatefulSet |
Gateway cache/messaging. Cluster mode has a different topology; inspect |
Disabled optional components and external databases/Redis change this map. A ready gateway does not establish the health of controller jobs, activations or content imports.
Operator deployments
The installer and OLM bundles name the operator Deployments:
koios-gateway-operator-controller-managerkoios-controller-operator-controller-managerkoios-eda-operator-controller-managerkoios-hub-operator-controller-manager
These names come from the installation package’s component prefixes, not from <p>. For
example, naming a platform production does not rename the gateway operator to
production-gateway-operator-controller-manager.
Discover the operator namespace for your installation: normally openshift-operators for
cluster-scoped OpenShift OLM, operators for cluster-scoped Kubernetes OLM, or the platform
namespace for a namespaced install. The documented Kustomize package deploys them in koios.
One operator deployment can manage several platforms; filter diagnostics for the affected name
and namespace. See installation methods.
Status
Use Check platform health for bounded kubectl commands and service endpoints.
The operator reports the last reconciliation and component resource names in KoiosPlatform.status.
Condition |
Interpretation |
|---|---|
Successful |
|
Failure |
|
Running |
A reconciliation lifecycle condition, not a standalone readiness check. It was |
DeprecatedFields |
Warns that deprecated CR fields are in use; migrate them to the fields named in the message. |
Status also includes version, URL, gatewayImage, component names, databaseVersions and
redisMode. adminUser and adminPasswordSecret identify the administrator and its Secret;
they do not contain the password. Inspect only needed fields rather than dumping configuration.
Upgrades
The canonical installation and upgrade guidance is under Install and upgrade and Upgrading and reissued releases. Back up before changing release and read its release notes.
With OLM, apply the new release’s catalog and Subscription for the chosen scope/channel from an authorized installer checkout. Check the new operator CSVs and follow any manual approval policy configured for that installation.
With Kustomize, apply the new release’s operator package from its installer tag.
Verify the expected operator/platform version,
Successful=True,Failure=False, ready workloads and service checks. Version alone is not a functional acceptance test.
A release reissued with the same number needs the extra procedure in the reissued-release guide; a same-number reinstall cannot be inferred from a version string. This page does not duplicate its catalog/CSV recovery commands.
Backup and restore
Use Backup and restore for the canonical procedure and confidentiality requirements. After a restore, follow the restored-platform runbook before enabling integrations, activations and schedules that could affect the original platform.
Daily operation
Need |
Canonical guide |
|---|---|
Platform/resource health |
|
Workload/operator output |
|
External controller log aggregation |
|
Metrics and scraping |
|
Job history/activity retention |
|
Capacity, resources and scaling |
|
Controller diagnosis |
|
Activation diagnosis |
|
Import/download diagnosis |
Idle mode
Idle mode intentionally scales platform components down while preserving their configuration/data. Account for it when interpreting successful reconciliation, missing running pods and unavailable HTTP endpoints. Resume through the CR as described there, not by manually scaling Deployments.
Deleting a platform
Deletion is different from a restart, idle mode or upgrade. Check backups and retained data first. Use the intended namespace and context for the CR deletion:
kubectl --context '<context>' -n '<platform-namespace>' delete koiosplatform '<platform-name>'
The operator removes the platform and its components. It retains, without a platform owner, the managed PostgreSQL and hub content volumes and the component Secrets needed to reuse the data, including encryption keys and database connections. Creating a platform with the same name in the same namespace can reuse those retained resources; preserve the matching database and keys together. With external databases, the operator does not delete your databases or supplied connection Secrets.
Removing the platform completely is a separate data-destruction operation. Inventory the retained volumes/Secrets and verify backups before planning it; do not use namespace or PVC deletion as a routine troubleshooting step. See Backup and restore.