Chapter 16. Image-based installation for single-node OpenShift

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.

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

   Important

   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.

Procedure

1. Create a live installation ISO and embed your single-node OpenShift seed image URL and other installation artifacts:

   1. Create a working directory by running the following:

      $ mkdir ibi-iso-workdir 1

      1

      Replace ibi-iso-workdir with the name of your working directory.

   2. Optional. Create an installation configuration template to use as a reference when configuring the ImageBasedInstallationConfig resource:

      $ openshift-install image-based create image-config-template --dir ibi-iso-workdir 1

      1

      If you do not specify a working directory, the command uses the current directory.

      Example output

      INFO Image-Config-Template created in: ibi-iso-workdir

      The command creates the image-based-installation-config.yaml installation configuration template in your target directory:

      #
      # Note: This is a sample ImageBasedInstallationConfig file showing
      # which fields are available to aid you in creating your
      # own image-based-installation-config.yaml file.
      #
      apiVersion: v1beta1
      kind: ImageBasedInstallationConfig
      metadata:
        name: example-image-based-installation-config
      # The following fields are required
      seedImage: quay.io/openshift-kni/seed-image:4.17.0
      seedVersion: 4.17.0
      installationDisk: /dev/vda
      pullSecret: '<your_pull_secret>'
      # networkConfig is optional and contains the network configuration for the host in NMState format.
      # See https://nmstate.io/examples.html for examples.
      # networkConfig:
      #   interfaces:
      #     - name: eth0
      #       type: ethernet
      #       state: up
      #       mac-address: 00:00:00:00:00:00
      #       ipv4:
      #         enabled: true
      #         address:
      #           - ip: 192.168.122.2
      #             prefix-length: 23
      #         dhcp: false

   3. Edit your installation configuration file:

      Example image-based-installation-config.yaml file

      apiVersion: v1beta1
      kind: ImageBasedInstallationConfig
      metadata:
        name: example-image-based-installation-config
      seedImage: quay.io/repo-id/seed:latest
      seedVersion: "4.17.0"
      extraPartitionStart: "-240G"
      installationDisk: /dev/disk/by-id/wwn-0x62c...
      sshKey: 'ssh-ed25519 AAAA...'
      pullSecret: '{"auths": ...}'
      networkConfig:
          interfaces:
            - name: ens1f0
              type: ethernet
              state: up
              ipv4:
                enabled: true
                dhcp: false
                auto-dns: false
                address:
                  - ip: 10.6.85.8
                    prefix-length: 24
              ipv6:
                enabled: false
          dns-resolver:
            config:
              server:
                - 10.6.73.2
                - 10.6.73.4
          routes:
            config:
            - destination: 0.0.0.0/0
              metric: 150
              next-hop-address: 10.6.85.254
              next-hop-interface: ens1f0

   4. Create the live installation ISO by running the following command:

      $ openshift-install image-based create image --dir ibi-iso-workdir

      Example output

      INFO Consuming Image-based Installation ISO Config from target directory
      INFO Creating Image-based Installation ISO with embedded ignition

Verification

1. Login to the target host.

2. View the system logs by running the following command:

   $ journalctl -b

   Example output

   Aug 13 17:01:44 10.46.26.129 install-rhcos-and-restore-seed.sh[2876]: time="2024-08-13T17:01:44Z" level=info msg="All the precaching threads have finished."
   Aug 13 17:01:44 10.46.26.129 install-rhcos-and-restore-seed.sh[2876]: time="2024-08-13T17:01:44Z" level=info msg="Total Images: 125"
   Aug 13 17:01:44 10.46.26.129 install-rhcos-and-restore-seed.sh[2876]: time="2024-08-13T17:01:44Z" level=info msg="Images Pulled Successfully: 125"
   Aug 13 17:01:44 10.46.26.129 install-rhcos-and-restore-seed.sh[2876]: time="2024-08-13T17:01:44Z" level=info msg="Images Failed to Pull: 0"
   Aug 13 17:01:44 10.46.26.129 install-rhcos-and-restore-seed.sh[2876]: time="2024-08-13T17:01:44Z" level=info msg="Completed executing pre-caching"
   Aug 13 17:01:44 10.46.26.129 install-rhcos-and-restore-seed.sh[2876]: time="2024-08-13T17:01:44Z" level=info msg="Pre-cached images successfully."
   Aug 13 17:01:44 10.46.26.129 install-rhcos-and-restore-seed.sh[2876]: time="2024-08-13 17:01:44" level=info msg="Skipping shutdown"
   Aug 13 17:01:44 10.46.26.129 install-rhcos-and-restore-seed.sh[2876]: time="2024-08-13 17:01:44" level=info msg="IBI preparation process finished successfully!"
   Aug 13 17:01:44 10.46.26.129 systemd[1]: var-lib-containers-storage-overlay.mount: Deactivated successfully.
   Aug 13 17:01:44 10.46.26.129 systemd[1]: Finished SNO Image-based Installation.
   Aug 13 17:01:44 10.46.26.129 systemd[1]: Reached target Multi-User System.
   Aug 13 17:01:44 10.46.26.129 systemd[1]: Reached target Graphical Interface.

Procedure

1. Create a working directory by running the following:

   $ mkdir ibi-config-iso-workdir 1

   1

   Replace ibi-config-iso-workdir with the name of your working directory.

2. Create the installation manifest:

   1. Create a YAML file that defines the install-config manifest:

      Example install-config.yaml file

      apiVersion: v1
      metadata:
        name: sno-cluster-name
      baseDomain: host.example.com
      compute:
        - architecture: amd64
          hyperthreading: Enabled
          name: worker
          replicas: 0
      controlPlane:
        architecture: amd64
        hyperthreading: Enabled
        name: master
        replicas: 1
      networking:
        clusterNetwork:
        - cidr: 10.128.0.0/14
          hostPrefix: 23
        machineNetwork:
        - cidr: 10.6.85.0/24
        networkType: OVNKubernetes
        serviceNetwork:
        - 172.30.0.0/16
      platform:
        none: {}
      fips: false
      cpuPartitioningMode: "AllNodes"
      pullSecret: '{"auths":{"<your_pull_secret>"}}}'
      sshKey: 'ssh-rsa <your_ssh_pub_key>'

   2. Save the file in your working directory.

3. Optional. Create a configuration template in your working directory by running the following command:

   $ openshift-install image-based create config-template --dir ibi-config-iso-workdir/

   Example output

   INFO Config-Template created in: ibi-config-iso-workdir

   The command creates the image-based-config.yaml configuration template in your working directory:

   #
   # Note: This is a sample ImageBasedConfig file showing
   # which fields are available to aid you in creating your
   # own image-based-config.yaml file.
   #
   apiVersion: v1beta1
   kind: ImageBasedConfig
   metadata:
     name: example-image-based-config
   additionalNTPSources:
     - 0.rhel.pool.ntp.org
     - 1.rhel.pool.ntp.org
   hostname: change-to-hostname
   releaseRegistry: quay.io
   # networkConfig contains the network configuration for the host in NMState format.
   # See https://nmstate.io/examples.html for examples.
   networkConfig:
     interfaces:
       - name: eth0
         type: ethernet
         state: up
         #mtu: 9000 1
         mac-address: 00:00:00:00:00:00
         ipv4:
           enabled: true
           address:
             - ip: 192.168.122.2
               prefix-length: 23
           dhcp: false

   1

   If you configure a maximum transmission unit (MTU) in the seed cluster, you must apply the same MTU value in the static network configuration for the configuration ISO.

4. Edit your configuration file:

   Example image-based-config.yaml file

   #
   # Note: This is a sample ImageBasedConfig file showing
   # which fields are available to aid you in creating your
   # own image-based-config.yaml file.
   #
   apiVersion: v1beta1
   kind: ImageBasedConfig
   metadata:
     name: sno-cluster-name
   additionalNTPSources:
     - 0.rhel.pool.ntp.org
     - 1.rhel.pool.ntp.org
   hostname: host.example.com
   releaseRegistry: quay.io
   # networkConfig contains the network configuration for the host in NMState format.
   # See https://nmstate.io/examples.html for examples.
   networkConfig:
       interfaces:
         - name: ens1f0
           type: ethernet
           state: up
           ipv4:
             enabled: true
             dhcp: false
             auto-dns: false
             address:
               - ip: 10.6.85.8
                 prefix-length: 24
           ipv6:
             enabled: false
       dns-resolver:
         config:
           server:
             - 10.6.73.2
             - 10.6.73.4
       routes:
         config:
         - destination: 0.0.0.0/0
           metric: 150
           next-hop-address: 10.6.85.254
           next-hop-interface: ens1f0

5. Create the configuration ISO in your working directory by running the following command:

   $ openshift-install image-based create config-image --dir ibi-config-iso-workdir/

   Example output

   INFO Adding NMConnection file <ens1f0.nmconnection>
   INFO Consuming Install Config from target directory
   INFO Consuming Image-based Config ISO configuration from target directory
   INFO Config-Image created in: ibi-config-iso-workdir/auth

   View the output in the working directory:

   Example output

   ibi-config-iso-workdir/
   ├── auth
   │   ├── kubeadmin-password
   │   └── kubeconfig
   └── imagebasedconfig.iso

6. Attach the imagebasedconfig.iso to the preinstalled host using your preferred method and restart the host to complete the configuration process and deploy the cluster.

1. Export the kubeconfig environment variable to your kubeconfig file by running the following command:

   $ export KUBECONFIG=ibi-config-iso-workdir/auth/kubeconfig

2. Verify that the cluster is responding by running the following command:

   $ oc get nodes

   Example output

   NAME                                         STATUS   ROLES                  AGE     VERSION
   node/sno-cluster-name.host.example.com       Ready    control-plane,master   5h15m   v1.30.3