Install a component

Some backend modules are optional: the platform works without them, and the installer can leave them out. One that is not running can be installed later from the Lifecycle Manager, at a version from the release feed. Installing needs lifecycle/install at the platform root, which Platform Owner and Platform Contributor hold.

An install only brings in something that does not run yet. To change the version of a component that is installed, use a rollout — see Upgrade the platform.

What can be installed

The install dialog checks the component first and lists what stands in the way under This component cannot be installed yet. A component can be installed when:

• it is a backend module — the platform API, the operator, the portal and the CRD bundle cannot;
• it is not running already;
• the release feed carries a release of it on this platform's channel, pinned by digest, and describes how it is installed;
• it needs neither a service account of its own nor domains of its own — such modules are installed with the installer;
• every value it needs that the platform cannot generate is entered in the dialog.

When the install starts, it checks as well that:

• the components it depends on are installed;
• its custom resource definitions are established in the cluster — if not, roll out the CRD bundle first;
• no rollout is executing — installs and rollouts do not run at the same time;
• the Lifecycle module can create the module's sign-in client in the identity provider, with every role the module needs. On a platform the installer built this is in place.

Install

1. Open Settings → Lifecycle Manager. On the Components tab, a component that is not running shows Not installed under Health and an Install button.
2. Choose Install. The dialog Install <component> opens.
3. Pick the Version; the newest release is preselected.
4. Fill in any values the module asks for. They are secrets, written into the module's secrets; a value you enter replaces one the module's secret already holds.
5. Choose Install.

Important

Until the install succeeds, the values you entered are also stored, unencrypted, with the install in the Lifecycle module's database, so that a failed install can be resumed. An install that fails and is never resumed keeps them there.

Warning

If the module's identity is not yet registered with the platform API, the install restarts the platform API, and requests in flight can fail for a few seconds.

Follow the install

The progress dialog opens by itself, and the component's row shows Installing… while it runs. The install goes through these steps, in order:

1. Preflight checks — everything under What can be installed.
2. Provision Keycloak client — the module's sign-in client in the identity provider.
3. Provision secrets — the module's secrets. A value you entered in the dialog is written; any other value that already exists is kept.
4. Apply module resources — the module's configuration, Service and Deployment.
5. Update kernel allowlist — lets the platform API accept the module's identity.
6. Wait for module readiness — until the Deployment is available.
7. Finalize — records the component in the Lifecycle Manager's inventory.

The install is also recorded as an operation. When it has succeeded, the component appears with its version and health like any other.

When an install fails

A failed step stops the install and shows its reason; what was already applied stays in place. The row then shows Install failed — details. Fix the cause, open the details and choose Resume: the install carries on from the step that failed. A component cannot be installed again while an install of it is pending, running or failed.

Repair a running component

A repair runs the same steps against a component that is already running, to bring its identity client, secrets and resources in line with the install description the release feed carries for it, without changing its version — the image it runs stays the same. It needs lifecycle/install, and there is no button for it; use the API, for example with stsh api:

stsh api POST /lifecycle/components/<component>/repair
stsh api GET /lifecycle/installs

Resume a failed repair like an install: stsh api POST /lifecycle/installs/<install-id>/resume.