lifecycle-agent

Lifecycle Agent Operator

Overview

The Lifecycle Agent (LCA) Operator provides local, on-cluster lifecycle management for Single Node OpenShift (SNO) clusters. It performs image-based upgrades by pivoting between OSTree stateroots, enabling fast, reliable major-version upgrades with automatic rollback on failure. A seed image captured from a reference SNO is used to build the target stateroot, and OADP/Velero backup-restore preserves application and platform state across the upgrade.

Key Features

• Image-based upgrades via OSTree stateroot pivoting
• Seed image generation from a running SNO cluster
• OADP-based backup/restore of cluster and application state
• IP configuration management during upgrades
• Automatic rollback on upgrade failure or timeout
• Container image pre-caching to reduce upgrade downtime

Custom Resource Definitions

All CRDs are cluster-scoped singletons under lca.openshift.io/v1:

Upgrade Lifecycle

The ImageBasedUpgrade controller implements a stage-based state machine:

Idle → Prep → Upgrade → Rollback

• Idle — Default state; cleanup of previous upgrade artifacts
• Prep — Pulls the seed image, sets up a new OSTree stateroot, and optionally pre-caches container images
• Upgrade — Takes OADP backups, pivots to the new stateroot, restores backups, and reconfigures the cluster
• Rollback — Reverts to the previous stateroot if the upgrade fails or is manually triggered

Getting Started

Prerequisites

• Go 1.24+
• Access to an OpenShift SNO cluster
• oc or kubectl configured with cluster-admin privileges

Build

make build       # Build the operator binary (bin/manager)
make cli-build   # Build the on-node CLI binary (bin/lca-cli)

Deploy

make install deploy IMG=<image>   # Install CRDs and deploy the operator
make bundle-run                   # Deploy via OLM

Test & Lint

make unittest    # Run unit tests with coverage
make ci-job      # Full CI pipeline (generate, fmt, vet, lint, test)

Documentation

• Image-Based Upgrade
• Seed Image Generation
• Backup/Restore with OADP
• Post-Pivot Configuration
• Troubleshooting
• Examples
• Must-Gather

Contributing

See DEVELOPING.md for development setup, testing, and contribution guidelines.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.