×

To prepare for an image-based installation for single-node OpenShift clusters, you must complete the following tasks:

  • Create a seed image by using the Lifecycle Agent.

  • Verify that all software components meet the required versions. For further information, see "Software prerequisites for an image-based installation and deployment".

Installing the Lifecycle Agent

Use the Lifecycle Agent to generate a seed image from a seed cluster. You can install the Lifecycle Agent using the OpenShift CLI (oc) or the web console.

Installing the Lifecycle Agent by using the CLI

You can use the OpenShift CLI (oc) to install the Lifecycle Agent.

Prerequisites
  • You have installed the OpenShift CLI (oc).

  • You have logged in as a user with cluster-admin privileges.

Procedure
  1. Create a Namespace object YAML file for the Lifecycle Agent:

    apiVersion: v1
    kind: Namespace
    metadata:
      name: openshift-lifecycle-agent
      annotations:
        workload.openshift.io/allowed: management
    1. Create the Namespace CR by running the following command:

      $ oc create -f <namespace_filename>.yaml
  2. Create an OperatorGroup object YAML file for the Lifecycle Agent:

    apiVersion: operators.coreos.com/v1
    kind: OperatorGroup
    metadata:
      name: openshift-lifecycle-agent
      namespace: openshift-lifecycle-agent
    spec:
      targetNamespaces:
      - openshift-lifecycle-agent
    1. Create the OperatorGroup CR by running the following command:

      $ oc create -f <operatorgroup_filename>.yaml
  3. Create a Subscription CR for the Lifecycle Agent:

    apiVersion: operators.coreos.com/v1
    kind: Subscription
    metadata:
      name: openshift-lifecycle-agent-subscription
      namespace: openshift-lifecycle-agent
    spec:
      channel: "stable"
      name: lifecycle-agent
      source: redhat-operators
      sourceNamespace: openshift-marketplace
    1. Create the Subscription CR by running the following command:

      $ oc create -f <subscription_filename>.yaml
Verification
  1. To verify that the installation succeeded, inspect the CSV resource by running the following command:

    $ oc get csv -n openshift-lifecycle-agent
    Example output
    NAME                              DISPLAY                     VERSION               REPLACES                           PHASE
    lifecycle-agent.v4.0           Openshift Lifecycle Agent   4.0                Succeeded
  2. Verify that the Lifecycle Agent is up and running by running the following command:

    $ oc get deploy -n openshift-lifecycle-agent
    Example output
    NAME                                 READY   UP-TO-DATE   AVAILABLE   AGE
    lifecycle-agent-controller-manager   1/1     1            1           14s

Installing the Lifecycle Agent by using the web console

You can use the OKD web console to install the Lifecycle Agent.

Prerequisites
  • You have logged in as a user with cluster-admin privileges.

Procedure
  1. In the OKD web console, navigate to OperatorsOperatorHub.

  2. Search for the Lifecycle Agent from the list of available Operators, and then click Install.

  3. On the Install Operator page, under A specific namespace on the cluster select openshift-lifecycle-agent.

  4. Click Install.

Verification
  1. To confirm that the installation is successful:

    1. Click OperatorsInstalled Operators.

    2. Ensure that the Lifecycle Agent is listed in the openshift-lifecycle-agent project with a Status of InstallSucceeded.

      During installation an Operator might display a Failed status. If the installation later succeeds with an InstallSucceeded message, you can ignore the Failed message.

If the Operator is not installed successfully:

  1. Click OperatorsInstalled Operators, and inspect the Operator Subscriptions and Install Plans tabs for any failure or errors under Status.

  2. Click WorkloadsPods, and check the logs for pods in the openshift-lifecycle-agent project.

Configuring a shared container partition between ostree stateroots

You must complete this procedure at installation time.

Apply a MachineConfig to the seed cluster to create a separate partition and share the /var/lib/containers partition between the two ostree stateroots that will be used during the preinstall process.

Procedure
  • Apply a MachineConfig to create a separate partition:

    apiVersion: machineconfiguration.openshift.io/v1
    kind: MachineConfig
    metadata:
      labels:
        machineconfiguration.openshift.io/role: master
      name: 98-var-lib-containers-partitioned
    spec:
      config:
        ignition:
          version: 3.2.0
        storage:
          disks:
            - device: /dev/disk/by-path/pci-<root_disk> (1)
              partitions:
                - label: varlibcontainers
                  startMiB: <start_of_partition> (2)
                  sizeMiB: <partition_size> (3)
          filesystems:
            - device: /dev/disk/by-partlabel/varlibcontainers
              format: xfs
              mountOptions:
                - defaults
                - prjquota
              path: /var/lib/containers
              wipeFilesystem: true
        systemd:
          units:
            - contents: |-
                # Generated by Butane
                [Unit]
                Before=local-fs.target
                Requires=systemd-fsck@dev-disk-by\x2dpartlabel-varlibcontainers.service
                After=systemd-fsck@dev-disk-by\x2dpartlabel-varlibcontainers.service
    
                [Mount]
                Where=/var/lib/containers
                What=/dev/disk/by-partlabel/varlibcontainers
                Type=xfs
                Options=defaults,prjquota
    
                [Install]
                RequiredBy=local-fs.target
              enabled: true
              name: var-lib-containers.mount
    1 Specify the root disk.
    2 Specify the start of the partition in MiB. If the value is too small, the installation will fail.
    3 Specify a minimum size for the partition of 500 GB to ensure adequate disk space for precached images. If the value is too small, the deployments after installation will fail.

Seed image configuration

You can create a seed image from a single-node OpenShift cluster with the same hardware as your bare-metal host, and with a similar target cluster configuration. However, the seed image generated from the seed cluster cannot contain any cluster-specific configuration.

The following table lists the components, resources, and configurations that you must and must not include in your seed image:

Table 1. Seed image configuration
Cluster configuration Include in seed image

Performance profile

Yes

MachineConfig resources for the target cluster

Yes

IP version [1]

Yes

Set of Day 2 Operators, including the Lifecycle Agent and the OADP Operator

Yes

Disconnected registry configuration [2]

Yes

Valid proxy configuration [3]

Yes

FIPS configuration

Yes

Dedicated partition on the primary disk for container storage that matches the size of the target clusters

Yes

Local volumes

  • StorageClass used in LocalVolume for LSO

  • LocalVolume for LSO

  • LVMCluster CR for LVMS

No

  1. Dual-stack networking is not supported in this release.

  2. If the seed cluster is installed in a disconnected environment, the target clusters must also be installed in a disconnected environment.

  3. The proxy configuration on the seed and target clusters does not have to match.

Seed image configuration using the RAN DU profile

The following table lists the components, resources, and configurations that you must and must not include in the seed image when using the RAN DU profile:

Table 2. Seed image configuration with RAN DU profile
Resource Include in seed image

All extra manifests that are applied as part of Day 0 installation

Yes

All Day 2 Operator subscriptions

Yes

ClusterLogging.yaml

Yes

DisableOLMPprof.yaml

Yes

TunedPerformancePatch.yaml

Yes

PerformanceProfile.yaml

Yes

SriovOperatorConfig.yaml

Yes

DisableSnoNetworkDiag.yaml

Yes

StorageClass.yaml

No, if it is used in StorageLV.yaml

StorageLV.yaml

No

StorageLVMCluster.yaml

No

Table 3. Seed image configuration with RAN DU profile for extra manifests
Resource Apply as extra manifest

ClusterLogForwarder.yaml

Yes

ReduceMonitoringFootprint.yaml

Yes

SriovFecClusterConfig.yaml

Yes

PtpOperatorConfigForEvent.yaml

Yes

DefaultCatsrc.yaml

Yes

PtpConfig.yaml

If the interfaces of the target cluster are common with the seed cluster, you can include them in the seed image. Otherwise, apply it as extra manifests.

SriovNetwork.yaml SriovNetworkNodePolicy.yaml

If the configuration, including namespaces, is exactly the same on both the seed and target cluster, you can include them in the seed image. Otherwise, apply them as extra manifests.

Generating a seed image with the Lifecycle Agent

Use the Lifecycle Agent to generate the seed image with the SeedGenerator CR. The Operator checks for required system configurations, performs any necessary system cleanup before generating the seed image, and launches the image generation. The seed image generation includes the following tasks:

  • Stopping cluster Operators

  • Preparing the seed image configuration

  • Generating and pushing the seed image to the image repository specified in the SeedGenerator CR

  • Restoring cluster Operators

  • Expiring seed cluster certificates

  • Generating new certificates for the seed cluster

  • Restoring and updating the SeedGenerator CR on the seed cluster

Prerequisites
  • You have configured a shared container directory on the seed cluster.

  • You have installed the minimum version of the OADP Operator and the Lifecycle Agent on the seed cluster.

  • Ensure that persistent volumes are not configured on the seed cluster.

  • Ensure that the LocalVolume CR does not exist on the seed cluster if the Local Storage Operator is used.

  • Ensure that the LVMCluster CR does not exist on the seed cluster if LVM Storage is used.

  • Ensure that the DataProtectionApplication CR does not exist on the seed cluster if OADP is used.

Procedure
  1. Detach the cluster from the hub to delete any RHACM-specific resources from the seed cluster that must not be in the seed image:

    1. Manually detach the seed cluster by running the following command:

      $ oc delete managedcluster sno-worker-example
      1. Wait until the ManagedCluster CR is removed. After the CR is removed, create the proper SeedGenerator CR. The Lifecycle Agent cleans up the RHACM artifacts.

    2. If you are using GitOps ZTP, detach your cluster by removing the seed cluster’s SiteConfig CR from the kustomization.yaml.

      1. If you have a kustomization.yaml file that references multiple SiteConfig CRs, remove your seed cluster’s SiteConfig CR from the kustomization.yaml:

        apiVersion: kustomize.config.k8s.io/v1beta1
        kind: Kustomization
        
        generators:
        #- example-seed-sno1.yaml
        - example-target-sno2.yaml
        - example-target-sno3.yaml
      2. If you have a kustomization.yaml that references one SiteConfig CR, remove your seed cluster’s SiteConfig CR from the kustomization.yaml and add the generators: {} line:

        apiVersion: kustomize.config.k8s.io/v1beta1
        kind: Kustomization
        
        generators: {}
      3. Commit the kustomization.yaml changes in your Git repository and push the changes to your repository.

        The ArgoCD pipeline detects the changes and removes the managed cluster.

  2. Create the Secret object so that you can push the seed image to your registry.

    1. Create the authentication file by running the following commands:

      $ MY_USER=myuserid
      $ AUTHFILE=/tmp/my-auth.json
      $ podman login --authfile ${AUTHFILE} -u ${MY_USER} quay.io/${MY_USER}
      $ base64 -w 0 ${AUTHFILE} ; echo
    2. Copy the output into the seedAuth field in the Secret YAML file named seedgen in the openshift-lifecycle-agent namespace:

      apiVersion: v1
      kind: Secret
      metadata:
        name: seedgen (1)
        namespace: openshift-lifecycle-agent
      type: Opaque
      data:
        seedAuth: <encoded_AUTHFILE> (2)
      1 The Secret resource must have the name: seedgen and namespace: openshift-lifecycle-agent fields.
      2 Specifies a base64-encoded authfile for write-access to the registry for pushing the generated seed images.
    3. Apply the Secret by running the following command:

      $ oc apply -f secretseedgenerator.yaml
  3. Create the SeedGenerator CR:

    apiVersion: lca.openshift.io/v1
    kind: SeedGenerator
    metadata:
      name: seedimage (1)
    spec:
      seedImage: <seed_container_image> (2)
    1 The SeedGenerator CR must be named seedimage.
    2 Specify the container image URL, for example, quay.io/example/seed-container-image:<tag>. It is recommended to use the <seed_cluster_name>:<ocp_version> format.
  4. Generate the seed image by running the following command:

    $ oc apply -f seedgenerator.yaml

    The cluster reboots and loses API capabilities while the Lifecycle Agent generates the seed image. Applying the SeedGenerator CR stops the kubelet and the CRI-O operations, then it starts the image generation.

If you want to generate more seed images, you must provision a new seed cluster with the version that you want to generate a seed image from.

Verification
  • After the cluster recovers and it is available, you can check the status of the SeedGenerator CR by running the following command:

    $ oc get seedgenerator -o yaml
    Example output
    status:
      conditions:
      - lastTransitionTime: "2024-02-13T21:24:26Z"
        message: Seed Generation completed
        observedGeneration: 1
        reason: Completed
        status: "False"
        type: SeedGenInProgress
      - lastTransitionTime: "2024-02-13T21:24:26Z"
        message: Seed Generation completed
        observedGeneration: 1
        reason: Completed
        status: "True"
        type: SeedGenCompleted (1)
      observedGeneration: 1
    1 The seed image generation is complete.