Ai-OPs
ai-ops.com
Docs
/
Upgrading
/

Upgrading to v1.2.0

Upgrading to v1.2.0

Koios v1.2.0 supports a direct upgrade from v1.1.x, v1.0.x, and v0.10.x. Database migrations run automatically the first time the new container starts, and Koios saves a copy of the configuration database before running them. Before you begin, follow the general update procedure to pull the new image and restart the service.

Before You Upgrade

Review each of these against your system. Every one of them changes behavior on first boot:

  1. Models with duplicate input binding order will stop. Two input bindings on the same model can no longer share a binding order. Binding order is not editable on the Bindings page — Koios assigns it from the model file — so renumbering means exporting the model's bindings to CSV, giving each input a distinct order, and importing the file back. See Model Configuration Errors.
  2. Renamed built-in roles do not receive new permissions. If you renamed a role such as Engineer or Administrator, the upgrade skips it and prints a warning naming the permission instead. Grant Component Stacks, the Audit Trail view and export permissions, and web interface certificate management by hand. See Roles & Permissions.
  3. Modbus TCP reads get larger. A hidden cap previously limited every read to 50 registers. Max Registers Per Read (1–125, default 125) is now the only limit. Lower it to the device's published limit if the device rejects large blocks. See Device Parameters.
  4. Integrations may break. Events can no longer be created or edited through the API, the root-event grouping header is gone, and a few filter and sort fields that never worked were removed. Review any integration that writes or groups events. See API Clients.
  5. The component environment list page is gone. Environments are opened and managed from the workspace, and environment bulk actions no longer exist. See Component Environments.
  6. Logic that reads an OPC-UA tag's error code — an expression, a component, an integration, or a mapping that writes it to a device output — sees 107 for data the server reports bad and 105 for an empty value, where it saw 106. See OPC-UA read status and quality.
  7. Device passwords logged at Debug should be changed. Before 1.2, a device running with Debug logging could write its password to the device log. Change any device password that was in use while Debug logging was on. From 1.2, credentials are masked in logs. See Logs.
  8. The built-in HTTPS certificate is replaced. Koios generates one for your installation on its first start. Browsers that stored an exception for the old one ask once more, and an Admin Console that monitors the instance needs you to sign in to it again, as step 6 under After Upgrading describes. See Certificates.
  9. Going back to v1.1 or v1.0 needs a restore. From v1.2.5, once v1.2 has started on the database an older version refuses to start on it. To go back, restore the copy of the database saved before the upgrade. See Downgrade to a Previous Version.

From v1.1.x

This is a drop-in upgrade. No volume or configuration changes are needed:

  1. Pull the new image and restart the service, following Updating Koios.
  2. Migrations run automatically on first boot.
  3. Confirm the new version under System > Overview.

Your existing devices, tags, models, bindings, and component environments carry forward.

From v1.0.x

Also a drop-in upgrade — the seven volume mounts are unchanged. Follow the same three steps as v1.1.x. Nothing introduced between v1.0.x and v1.2.0 requires a service file change.

From v0.10.x

A v0.10.x upgrade needs the same one-time change introduced in v1.0.0: the koios_secrets volume must be mounted so runtime secrets are generated and preserved across restarts. Complete the v1.0.0 migration steps to add the seventh volume mount to your service file, then proceed with the standard update. Your existing credentials are detected and preserved.

No New Volumes

Component stacks — the isolated package sets introduced in this release — are stored alongside your other uploaded files on the existing media volume. Upgrading needs no service file change and no eighth mount.

After Upgrading

  1. Confirm the version under System > Overview.
  2. Check System > Service Status to verify every service is running.
  3. Check your renamed roles for the new permissions listed above.
  4. Confirm any model that was stopped by a duplicate binding order is running again.
  5. If you are upgrading from v1.0.x or v1.1.x, open Components > Libraries. The Core Library now ships as version 1.0.0, without the release-candidate tag it carried before, and the new version is added alongside the one you are running rather than replacing it. Your environments keep running the version they already use until you activate the new one. The components are identical, so activating it is safe and the preview shown before you confirm reports no component changes. Installs coming from v0.10.x, and new installs, start on 1.0.0 with nothing to do. See Component Libraries.
  6. If the instance is connected to the Admin Console, open its connection settings there and sign in to it again. The instance now has a certificate of its own, and the console trusts only the one it pinned. See Managing Instances.
  7. Review the v1.2 release notes for new features.

What's Next

Updating KoiosUpgrading to v1.1.0