Chapter 2. Preparing the hub cluster for GitOps ZTP

Procedure

1. Log in to the mirror host.

2. Obtain the RHCOS ISO and RootFS images from mirror.openshift.com, for example:

   1. Export the required image names and OpenShift Container Platform version as environment variables:

      $ export ISO_IMAGE_NAME=<iso_image_name> 

      1

      Copy to Clipboard Toggle word wrap

      $ export ROOTFS_IMAGE_NAME=<rootfs_image_name> 

      1

      Copy to Clipboard Toggle word wrap

      $ export OCP_VERSION=<ocp_version> 

      1

      Copy to Clipboard Toggle word wrap

      1

      ISO image name, for example, rhcos-4.19.1-x86_64-live.x86_64.iso

      1

      RootFS image name, for example, rhcos-4.19.1-x86_64-live-rootfs.x86_64.img

      1

      OpenShift Container Platform version, for example, 4.19.1

   2. Download the required images:

      $ sudo wget https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/4.19/${OCP_VERSION}/${ISO_IMAGE_NAME} -O /var/www/html/${ISO_IMAGE_NAME}

      Copy to Clipboard Toggle word wrap

      $ sudo wget https://mirror.openshift.com/pub/openshift-v4/dependencies/rhcos/4.19/${OCP_VERSION}/${ROOTFS_IMAGE_NAME} -O /var/www/html/${ROOTFS_IMAGE_NAME}

      Copy to Clipboard Toggle word wrap

Procedure

1. Enable the Provisioning resource to watch all namespaces and configure mirrors for disconnected environments. For more information, see Enabling the central infrastructure management service.

2. Open the AgentServiceConfig CR to update the spec.osImages field by running the following command:

   $ oc edit AgentServiceConfig

   Copy to Clipboard Toggle word wrap

3. Update the spec.osImages field in the AgentServiceConfig CR:

   apiVersion: agent-install.openshift.io/v1beta1
   kind: AgentServiceConfig
   metadata:
    name: agent
   spec:
   # ...
     osImages:
       - cpuArchitecture: x86_64
         openshiftVersion: "4.19"
         rootFSUrl: https://<host>/<path>/rhcos-live-rootfs.x86_64.img
         url: https://<host>/<path>/rhcos-live.x86_64.iso

   Copy to Clipboard Toggle word wrap

   where:

   <host>

   Specifies the fully qualified domain name (FQDN) for the target mirror registry HTTP server.

   <path>

   Specifies the path to the image on the target mirror registry.

4. Save and quit the editor to apply the changes.

Procedure

1. Create a ConfigMap containing the mirror registry config:

   apiVersion: v1
   kind: ConfigMap
   metadata:
     name: assisted-installer-mirror-config
     namespace: multicluster-engine 

   1

   
     labels:
       app: assisted-service
   data:
     ca-bundle.crt: | 

   2

   
       -----BEGIN CERTIFICATE-----
       <certificate_contents>
       -----END CERTIFICATE-----
   
     registries.conf: | 

   3

   
       unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
   
       [[registry]]
          prefix = ""
          location = "quay.io/example-repository" 

   4

   
          mirror-by-digest-only = true
   
          [[registry.mirror]]
          location = "mirror1.registry.corp.com:5000/example-repository" 

   5

   Copy to Clipboard Toggle word wrap

   1

   The ConfigMap namespace must be set to multicluster-engine.

   2

   The mirror registry’s certificate that is used when creating the mirror registry.

   3

   The configuration file for the mirror registry. The mirror registry configuration adds mirror information to the /etc/containers/registries.conf file in the discovery image. The mirror information is stored in the imageContentSources section of the install-config.yaml file when the information is passed to the installation program. The Assisted Service pod that runs on the hub cluster fetches the container images from the configured mirror registry.

   4

   The URL of the mirror registry. You must use the URL from the imageContentSources section by running the oc adm release mirror command when you configure the mirror registry. For more information, see the Mirroring the OpenShift Container Platform image repository section.

   5

   The registries defined in the registries.conf file must be scoped by repository, not by registry. In this example, both the quay.io/example-repository and the mirror1.registry.corp.com:5000/example-repository repositories are scoped by the example-repository repository.

   This updates mirrorRegistryRef in the AgentServiceConfig custom resource, as shown below:

   Example output

   apiVersion: agent-install.openshift.io/v1beta1
   kind: AgentServiceConfig
   metadata:
     name: agent
     namespace: multicluster-engine 

   1

   
   spec:
     databaseStorage:
       volumeName: <db_pv_name>
       accessModes:
       - ReadWriteOnce
       resources:
         requests:
           storage: <db_storage_size>
     filesystemStorage:
       volumeName: <fs_pv_name>
       accessModes:
       - ReadWriteOnce
       resources:
         requests:
           storage: <fs_storage_size>
     mirrorRegistryRef:
       name: assisted-installer-mirror-config 

   2

   
     osImages:
       - openshiftVersion: <ocp_version> 

   3

   
         url: <iso_url> 

   4

   Copy to Clipboard Toggle word wrap

   1

   Set the AgentServiceConfig namespace to multicluster-engine to match the ConfigMap namespace.

   2

   Set mirrorRegistryRef.name to match the definition specified in the related ConfigMap CR.

   3

   Set the OpenShift Container Platform version to either the x.y or x.y.z format.

   4

   Set the URL for the ISO hosted on the httpd server.

Procedure

1. Update the AgentServiceConfig custom resource (CR) by running the following command:

   $ oc edit AgentServiceConfig agent

   Copy to Clipboard Toggle word wrap

2. Add the unauthenticatedRegistries field in the CR:

   apiVersion: agent-install.openshift.io/v1beta1
   kind: AgentServiceConfig
   metadata:
     name: agent
   spec:
     unauthenticatedRegistries:
     - example.registry.com
     - example.registry2.com
     ...

   Copy to Clipboard Toggle word wrap

   Unauthenticated registries are listed under spec.unauthenticatedRegistries in the AgentServiceConfig resource. Any registry on this list is not required to have an entry in the pull secret used for the spoke cluster installation. assisted-service validates the pull secret by making sure it contains the authentication information for every image registry used for installation.

1. Open a debug shell prompt to the hub cluster:

   $ oc debug node/<node_name>

   Copy to Clipboard Toggle word wrap

2. Test access to the unauthenticated registry by running the following command:

   sh-4.4# podman login -u kubeadmin -p $(oc whoami -t) <unauthenticated_registry>

   Copy to Clipboard Toggle word wrap

   where:

   <unauthenticated_registry>

   Is the new registry, for example, unauthenticated-image-registry.openshift-image-registry.svc:5000.

   Example output

   Login Succeeded!

   Copy to Clipboard Toggle word wrap

Procedure

1. Prepare the ArgoCD pipeline configuration:

   1. Create a Git repository with the directory structure similar to the example directory. For more information, see "Preparing the GitOps ZTP site configuration repository".

   2. Configure access to the repository using the ArgoCD UI. Under Settings configure the following:

      • Repositories - Add the connection information. The URL must end in .git, for example, https://repo.example.com/repo.git and credentials.
      • Certificates - Add the public certificate for the repository, if needed.

   3. Modify the two ArgoCD applications, out/argocd/deployment/clusters-app.yaml and out/argocd/deployment/policies-app.yaml, based on your Git repository:

      • Update the URL to point to the Git repository. The URL ends with .git, for example, https://repo.example.com/repo.git.
      • The targetRevision indicates which Git repository branch to monitor.
      • path specifies the path to the SiteConfig and PolicyGenerator or PolicyGentemplate CRs, respectively.

2. To install the GitOps ZTP plugin, patch the ArgoCD instance in the hub cluster with the relevant multicluster engine (MCE) subscription image. Customize the patch file that you previously extracted into the out/argocd/deployment/ directory for your environment.

   1. Select the multicluster-operators-subscription image that matches your RHACM version.

      • For RHACM 2.8 and 2.9, use the registry.redhat.io/rhacm2/multicluster-operators-subscription-rhel8:v<rhacm_version> image.
      • For RHACM 2.10 and later, use the registry.redhat.io/rhacm2/multicluster-operators-subscription-rhel9:v<rhacm_version> image.
      Important

      The version of the multicluster-operators-subscription image must match the RHACM version. Beginning with the MCE 2.10 release, RHEL 9 is the base image for multicluster-operators-subscription images.

      Click [Expand for Operator list] in the "Platform Aligned Operators" table in OpenShift Operator Life Cycles to view the complete supported Operators matrix for OpenShift Container Platform.

   2. Modify the out/argocd/deployment/argocd-openshift-gitops-patch.json file with the multicluster-operators-subscription image that matches your RHACM version:

      {
        "args": [
          "-c",
          "mkdir -p /.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator && cp /policy-generator/PolicyGenerator-not-fips-compliant /.config/kustomize/plugin/policy.open-cluster-management.io/v1/policygenerator/PolicyGenerator" 

      1

      
        ],
        "command": [
          "/bin/bash"
        ],
        "image": "registry.redhat.io/rhacm2/multicluster-operators-subscription-rhel9:v2.10", 

      2

      3

      
        "name": "policy-generator-install",
        "imagePullPolicy": "Always",
        "volumeMounts": [
          {
            "mountPath": "/.config",
            "name": "kustomize"
          }
        ]
      }

      Copy to Clipboard Toggle word wrap

      1

      Optional: For RHEL 9 images, copy the required universal executable in the /policy-generator/PolicyGenerator-not-fips-compliant folder for the ArgoCD version.

      2

      Match the multicluster-operators-subscription image to the RHACM version.

      3

      In disconnected environments, replace the URL for the multicluster-operators-subscription image with the disconnected registry equivalent for your environment.

   3. Patch the ArgoCD instance. Run the following command:

      $ oc patch argocd openshift-gitops \
      -n openshift-gitops --type=merge \
      --patch-file out/argocd/deployment/argocd-openshift-gitops-patch.json

      Copy to Clipboard Toggle word wrap

3. In RHACM 2.7 and later, the multicluster engine enables the cluster-proxy-addon feature by default. Apply the following patch to disable the cluster-proxy-addon feature and remove the relevant hub cluster and managed pods that are responsible for this add-on. Run the following command:

   $ oc patch multiclusterengines.multicluster.openshift.io multiclusterengine --type=merge --patch-file out/argocd/deployment/disable-cluster-proxy-addon.json

   Copy to Clipboard Toggle word wrap

4. Apply the pipeline configuration to your hub cluster by running the following command:

   $ oc apply -k out/argocd/deployment

   Copy to Clipboard Toggle word wrap

5. Optional: If you have existing ArgoCD applications, verify that the PrunePropagationPolicy=background policy is set in the Application resource by running the following command:

   $ oc -n openshift-gitops get applications.argoproj.io  \
   clusters -o jsonpath='{.spec.syncPolicy.syncOptions}' |jq

   Copy to Clipboard Toggle word wrap

   Example output for an existing policy

   [
     "CreateNamespace=true",
     "PrunePropagationPolicy=background",
     "RespectIgnoreDifferences=true"
   ]

   Copy to Clipboard Toggle word wrap

   1. If the spec.syncPolicy.syncOption field does not contain a PrunePropagationPolicy parameter or PrunePropagationPolicy is set to the foreground value, set the policy to background in the Application resource. See the following example:

      kind: Application
      spec:
        syncPolicy:
          syncOptions:
          - PrunePropagationPolicy=background

      Copy to Clipboard Toggle word wrap

   Setting the background deletion policy ensures that the ManagedCluster CR and all its associated resources are deleted.

Procedure

1. Create a directory structure with separate paths for the SiteConfig and PolicyGenerator or PolicyGentemplate CRs.

   Note

   Keep SiteConfig and PolicyGenerator or PolicyGentemplate CRs in separate directories. Both the SiteConfig and PolicyGenerator or PolicyGentemplate directories must contain a kustomization.yaml file that explicitly includes the files in that directory.

2. Export the argocd directory from the ztp-site-generate container image using the following commands:

   $ podman pull registry.redhat.io/openshift4/ztp-site-generate-rhel8:v4.19

   Copy to Clipboard Toggle word wrap

   $ mkdir -p ./out

   Copy to Clipboard Toggle word wrap

   $ podman run --log-driver=none --rm registry.redhat.io/openshift4/ztp-site-generate-rhel8:v4.19 extract /home/ztp --tar | tar x -C ./out

   Copy to Clipboard Toggle word wrap

3. Check that the out directory contains the following subdirectories:

   • out/extra-manifest contains the source CR files that SiteConfig uses to generate extra manifest configMap.
   • out/source-crs contains the source CR files that PolicyGenerator uses to generate the Red Hat Advanced Cluster Management (RHACM) policies.
   • out/argocd/deployment contains patches and YAML files to apply on the hub cluster for use in the next step of this procedure.
   • out/argocd/example contains the examples for SiteConfig and PolicyGenerator or PolicyGentemplate files that represent the recommended configuration.
4. Copy the out/source-crs folder and contents to the PolicyGenerator or PolicyGentemplate directory.

5. The out/extra-manifests directory contains the reference manifests for a RAN DU cluster. Copy the out/extra-manifests directory into the SiteConfig folder. This directory should contain CRs from the ztp-site-generate container only. Do not add user-provided CRs here. If you want to work with user-provided CRs you must create another directory for that content. For example:

   example/
     ├── acmpolicygenerator
     │   ├── kustomization.yaml
     │   └── source-crs/
     ├── policygentemplates 

   1

   
     │   ├── kustomization.yaml
     │   └── source-crs/
     └── siteconfig
           ├── extra-manifests
           └── kustomization.yaml

   Copy to Clipboard Toggle word wrap

   1

   Using PolicyGenTemplate CRs to manage and deploy policies to manage clusters will be deprecated in a future OpenShift Container Platform release. Equivalent and improved functionality is available by using Red Hat Advanced Cluster Management (RHACM) and PolicyGenerator CRs.

6. Commit the directory structure and the kustomization.yaml files and push to your Git repository. The initial push to Git should include the kustomization.yaml files.

Procedure

1. Create a directory structure with separate paths for the SiteConfig and PolicyGenerator CRs.

2. Within the PolicyGenerator directory, create a directory for each OpenShift Container Platform version you want to make available. For each version, create the following resources:

   • kustomization.yaml file that explicitly includes the files in that directory

   • source-crs directory to contain reference CR configuration files from the ztp-site-generate container

     If you want to work with user-provided CRs, you must create a separate directory for them.

3. In the /siteconfig directory, create a subdirectory for each OpenShift Container Platform version you want to make available. For each version, create at least one directory for reference CRs to be copied from the container. There is no restriction on the naming of directories or on the number of reference directories. If you want to work with custom manifests, you must create a separate directory for them.

   The following example describes a structure using user-provided manifests and CRs for different versions of OpenShift Container Platform:

   ├── acmpolicygenerator
   │   ├── kustomization.yaml 

   1

   
   │   ├── version_4.13 

   2

   
   │   │   ├── common-ranGen.yaml
   │   │   ├── group-du-sno-ranGen.yaml
   │   │   ├── group-du-sno-validator-ranGen.yaml
   │   │   ├── helix56-v413.yaml
   │   │   ├── kustomization.yaml 

   3

   
   │   │   ├── ns.yaml
   │   │   └── source-crs/ 

   4

   
   │   │      └── reference-crs/ 

   5

   
   │   │      └── custom-crs/ 

   6

   
   │   └── version_4.14 

   7

   
   │       ├── common-ranGen.yaml
   │       ├── group-du-sno-ranGen.yaml
   │       ├── group-du-sno-validator-ranGen.yaml
   │       ├── helix56-v414.yaml
   │       ├── kustomization.yaml 

   8

   
   │       ├── ns.yaml
   │       └── source-crs/ 

   9

   
   │         └── reference-crs/ 

   10

   
   │         └── custom-crs/ 

   11

   
   └── siteconfig
       ├── kustomization.yaml
       ├── version_4.13
       │   ├── helix56-v413.yaml
       │   ├── kustomization.yaml
       │   ├── extra-manifest/ 

   12

   
       │   └── custom-manifest/ 

   13

   
       └── version_4.14
           ├── helix57-v414.yaml
           ├── kustomization.yaml
           ├── extra-manifest/ 

   14

   
           └── custom-manifest/ 

   15

   Copy to Clipboard Toggle word wrap

   1

   Create a top-level kustomization YAML file.

   2 7

   Create the version-specific directories within the custom /acmpolicygenerator directory.

   3 8

   Create a kustomization.yaml file for each version.

   4 9

   Create a source-crs directory for each version to contain reference CRs from the ztp-site-generate container.

   5 10

   Create the reference-crs directory for policy CRs that are extracted from the ZTP container.

   6 11

   Optional: Create a custom-crs directory for user-provided CRs.

   12 14

   Create a directory within the custom /siteconfig directory to contain extra manifests from the ztp-site-generate container.

   13 15

   Create a folder to hold user-provided manifests.

   Note

   In the previous example, each version subdirectory in the custom /siteconfig directory contains two further subdirectories, one containing the reference manifests copied from the container, the other for custom manifests that you provide. The names assigned to those directories are examples. If you use user-provided CRs, the last directory listed under extraManifests.searchPaths in the SiteConfig CR must be the directory containing user-provided CRs.

4. Edit the SiteConfig CR to include the search paths of any directories you have created. The first directory that is listed under extraManifests.searchPaths must be the directory containing the reference manifests. Consider the order in which the directories are listed. In cases where directories contain files with the same name, the file in the final directory takes precedence.

   Example SiteConfig CR

   extraManifests:
       searchPaths:
       - extra-manifest/ 

   1

   
       - custom-manifest/ 

   2

   Copy to Clipboard Toggle word wrap

   1

   The directory containing the reference manifests must be listed first under extraManifests.searchPaths.

   2

   If you are using user-provided CRs, the last directory listed under extraManifests.searchPaths in the SiteConfig CR must be the directory containing those user-provided CRs.

5. Edit the top-level kustomization.yaml file to control which OpenShift Container Platform versions are active. The following is an example of a kustomization.yaml file at the top level:

   resources:
   - version_4.13 

   1

   
   #- version_4.14 

   2

   Copy to Clipboard Toggle word wrap

   1

   Activate version 4.13.

   2

   Use comments to deactivate a version.

Procedure

1. Create a policy to add the cluster.open-cluster-management.io/backup=cluster-activation label to all BareMetalHost resources that have the infraenvs.agent-install.openshift.io label. Save the policy as BareMetalHostBackupPolicy.yaml.

   The following example adds the cluster.open-cluster-management.io/backup label to all BareMetalHost resources that have the infraenvs.agent-install.openshift.io label:

   Example Policy

   apiVersion: policy.open-cluster-management.io/v1
   kind: Policy
   metadata:
     name: bmh-cluster-activation-label
     annotations:
       policy.open-cluster-management.io/description: Policy used to add the cluster.open-cluster-management.io/backup=cluster-activation label to all BareMetalHost resources
   spec:
     disabled: false
     policy-templates:
       - objectDefinition:
           apiVersion: policy.open-cluster-management.io/v1
           kind: ConfigurationPolicy
           metadata:
             name: set-bmh-backup-label
           spec:
             object-templates-raw: |
               {{- /* Set cluster-activation label on all BMH resources */ -}}
               {{- $infra_label := "infraenvs.agent-install.openshift.io" }}
               {{- range $bmh := (lookup "metal3.io/v1alpha1" "BareMetalHost" "" "" $infra_label).items }}
                   - complianceType: musthave
                     objectDefinition:
                       kind: BareMetalHost
                       apiVersion: metal3.io/v1alpha1
                       metadata:
                         name: {{ $bmh.metadata.name }}
                         namespace: {{ $bmh.metadata.namespace }}
                         labels:
                           cluster.open-cluster-management.io/backup: cluster-activation 

   1

   
               {{- end }}
             remediationAction: enforce
             severity: high
   ---
   apiVersion: cluster.open-cluster-management.io/v1beta1
   kind: Placement
   metadata:
     name: bmh-cluster-activation-label-pr
   spec:
     predicates:
       - requiredClusterSelector:
           labelSelector:
             matchExpressions:
               - key: name
                 operator: In
                 values:
                   - local-cluster
   ---
   apiVersion: policy.open-cluster-management.io/v1
   kind: PlacementBinding
   metadata:
     name: bmh-cluster-activation-label-binding
   placementRef:
     name: bmh-cluster-activation-label-pr
     apiGroup: cluster.open-cluster-management.io
     kind: Placement
   subjects:
     - name: bmh-cluster-activation-label
       apiGroup: policy.open-cluster-management.io
       kind: Policy
   ---
   apiVersion: cluster.open-cluster-management.io/v1beta2
   kind: ManagedClusterSetBinding
   metadata:
     name: default
     namespace: default
   spec:
     clusterSet: default

   Copy to Clipboard Toggle word wrap

   1

   If you apply the cluster.open-cluster-management.io/backup: cluster-activation label to BareMetalHost resources, the RHACM cluster backs up those resources. You can restore the BareMetalHost resources if the active cluster becomes unavailable, when restoring the hub activation resources.

2. Apply the policy by running the following command:

   $ oc apply -f BareMetalHostBackupPolicy.yaml

   Copy to Clipboard Toggle word wrap

Verification

1. Find all BareMetalHost resources with the label infraenvs.agent-install.openshift.io by running the following command:

   $ oc get BareMetalHost -A -l infraenvs.agent-install.openshift.io

   Copy to Clipboard Toggle word wrap

   Example output

   NAMESPACE      NAME             STATE   CONSUMER   ONLINE   ERROR   AGE
   baremetal-ns   baremetal-name                      false            50s

   Copy to Clipboard Toggle word wrap

2. Verify that the policy has applied the label cluster.open-cluster-management.io/backup=cluster-activation to all these resources, by running the following command:

   $ oc get BareMetalHost -A -l infraenvs.agent-install.openshift.io,cluster.open-cluster-management.io/backup=cluster-activation

   Copy to Clipboard Toggle word wrap

   Example output

   NAMESPACE      NAME             STATE   CONSUMER   ONLINE   ERROR   AGE
   baremetal-ns   baremetal-name                      false            50s

   Copy to Clipboard Toggle word wrap

   The output must show the same list as in the previous step, which listed all BareMetalHost resources with the label infraenvs.agent-install.openshift.io. This confirms that all the BareMetalHost resources with the infraenvs.agent-install.openshift.io label also have the cluster.open-cluster-management.io/backup: cluster-activation label.

   The following example shows a BareMetalHost resource with the infraenvs.agent-install.openshift.io label. The resource must also have the cluster.open-cluster-management.io/backup: cluster-activation label, which was added by the policy created in step 1.

   apiVersion: metal3.io/v1alpha1
   kind: BareMetalHost
   metadata:
     labels:
       cluster.open-cluster-management.io/backup: cluster-activation
       infraenvs.agent-install.openshift.io: value
     name: baremetal-name
     namespace: baremetal-ns

   Copy to Clipboard Toggle word wrap