Chapter 22. Clusters at the network far edge

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

      $ export ROOTFS_IMAGE_NAME=<rootfs_image_name> 

      1

      $ export OCP_VERSION=<ocp_version> 

      1

      1

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

      1

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

      1

      OpenShift Container Platform version, for example, 4.11.1

   2. Download the required images:

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

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

Procedure

1. Update the

   AgentServiceConfig

   CR by running the following command:

   $ oc edit AgentServiceConfig

2. Add the following entry to the

   items.spec.osImages

   field in the CR:

   - cpuArchitecture: x86_64
       openshiftVersion: "4.11"
       rootFSUrl: https://<host>/<path>/rhcos-live-rootfs.x86_64.img
       url: https://<mirror-registry>/<path>/rhcos-live.x86_64.iso

   where:

   <host>

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

   <path>

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

   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: assisted-installer
     labels:
       app: assisted-service
   data:
     ca-bundle.crt: <certificate> 

   1

   
     registries.conf: |  

   2

   
       unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
   
       [[registry]]
         location = <mirror_registry_url>  

   3

   
         insecure = false
         mirror-by-digest-only = true

   1

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

   2

   The configuration for the mirror registry.

   3

   The URL of the mirror registry.

   This updates

   mirrorRegistryRef

   in the

   AgentServiceConfig

   custom resource, as shown below:

   Example output

   apiVersion: agent-install.openshift.io/v1beta1
   kind: AgentServiceConfig
   metadata:
     name: agent
   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'
     osImages:
       - openshiftVersion: <ocp_version>
         rootfs: <rootfs_url> 

   1

   
         url: <iso_url> 

   2

   1 2

   Must match the URLs of the HTTPD server.

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

        PolicyGenTemplate

        CRs, respectively.

2. To install the ZTP GitOps plugin you must patch the ArgoCD instance in the hub cluster by using the patch file previously extracted into the

   out/argocd/deployment/

   directory. Run the following command:

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

3. Apply the pipeline configuration to your hub cluster by using the following command:

   $ oc apply -k out/argocd/deployment

Procedure

1. Create a directory structure with separate paths for the

   SiteConfig

   and

   PolicyGenTemplate

   CRs.

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.11

   $ mkdir -p ./out

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

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

     PolicyGenTemplate

     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

     PolicyGenTemplate

     files that represent the recommended configuration.

1. A Discovery image ISO file is generated and booted on the target host.
2. When the ISO file successfully boots on the target host it reports the host hardware information to RHACM.
3. After all hosts are discovered, OpenShift Container Platform is installed.
4. When OpenShift Container Platform finishes installing, the hub installs the

   klusterlet

   service on the target cluster.
5. The requested add-on services are installed on the target cluster.

Procedure

1. Create a YAML secret file containing credentials for the host Baseboard Management Controller (BMC) and a pull secret required for installing OpenShift and all add-on cluster Operators:

   1. Save the following YAML as the file

      example-sno-secret.yaml

      :

      apiVersion: v1
      kind: Secret
      metadata:
        name: example-sno-bmc-secret
        namespace: example-sno 

      1

      
      data: 

      2

      
        password: <base64_password>
        username: <base64_username>
      type: Opaque
      ---
      apiVersion: v1
      kind: Secret
      metadata:
        name: pull-secret
        namespace: example-sno  

      3

      
      data:
        .dockerconfigjson: <pull_secret> 

      4

      
      type: kubernetes.io/dockerconfigjson

      1

      Must match the namespace configured in the related SiteConfig CR

      2

      Base64-encoded values for password and username

      3

      Must match the namespace configured in the related SiteConfig CR

      4

      Base64-encoded pull secret

2. Add the relative path to

   example-sno-secret.yaml

   to the

   kustomization.yaml

   file that you use to install the cluster.

Procedure

1. Create the required managed cluster secrets on the hub cluster. These resources must be in a namespace with a name matching the cluster name. For example, in

   out/argocd/example/siteconfig/example-sno.yaml

   , the cluster name and namespace is

   example-sno

   .

   1. Export the cluster namespace by running the following command:

      $ export CLUSTERNS=example-sno

   2. Create the namespace:

      $ oc create namespace $CLUSTERNS

2. Create pull secret and BMC

   Secret

   CRs for the managed cluster. The pull secret must contain all the credentials necessary for installing OpenShift Container Platform and all required Operators. See "Creating the managed bare-metal host secrets" for more information.
   Note

   The secrets are referenced from the

   SiteConfig

   custom resource (CR) by name. The namespace must match the

   SiteConfig

   namespace.

3. Create a

   SiteConfig

   CR for your cluster in your local clone of the Git repository:

   1. Choose the appropriate example for your CR from the

      out/argocd/example/siteconfig/

      folder. The folder includes example files for single node, three-node, and standard clusters:

      • example-sno.yaml

      • example-3node.yaml

      • example-standard.yaml

   2. Change the cluster and host details in the example file to match the type of cluster you want. For example:

      Example single-node OpenShift cluster SiteConfig CR

      apiVersion: ran.openshift.io/v1
      kind: SiteConfig
      metadata:
        name: "<site_name>"
        namespace: "<site_name>"
      spec:
        baseDomain: "example.com"
        pullSecretRef:
          name: "assisted-deployment-pull-secret" 

      1

      
        clusterImageSetNameRef: "openshift-4.11" 

      2

      
        sshPublicKey: "ssh-rsa AAAA..." 

      3

      
        clusters:
        - clusterName: "<site_name>"
          networkType: "OVNKubernetes"
          clusterLabels: 

      4

      
            common: true
            group-du-sno: ""
            sites : "<site_name>"
          clusterNetwork:
            - cidr: 1001:1::/48
              hostPrefix: 64
          machineNetwork:
            - cidr: 1111:2222:3333:4444::/64
          serviceNetwork:
            - 1001:2::/112
          additionalNTPSources:
            - 1111:2222:3333:4444::2
          #crTemplates:
          #  KlusterletAddonConfig: "KlusterletAddonConfigOverride.yaml" 

      5

      
          nodes:
            - hostName: "example-node.example.com" 

      6

      
              role: "master"
              bmcAddress: idrac-virtualmedia://<out_of_band_ip>/<system_id>/ 

      7

      
              bmcCredentialsName:
                name: "bmh-secret" 

      8

      
              bootMACAddress: "AA:BB:CC:DD:EE:11"
              bootMode: "UEFI" 

      9

      
              rootDeviceHints:
                wwn: "0x11111000000asd123"
              cpuset: "0-1,52-53"  

      10

      
              nodeNetwork: 

      11

      
                interfaces:
                  - name: eno1
                    macAddress: "AA:BB:CC:DD:EE:11"
                config:
                  interfaces:
                    - name: eno1
                      type: ethernet
                      state: up
                      ipv4:
                        enabled: false
                      ipv6: 

      12

      
                        enabled: true
                        address:
                        - ip: 1111:2222:3333:4444::aaaa:1
                          prefix-length: 64
                  dns-resolver:
                    config:
                      search:
                      - example.com
                      server:
                      - 1111:2222:3333:4444::2
                  routes:
                    config:
                    - destination: ::/0
                      next-hop-interface: eno1
                      next-hop-address: 1111:2222:3333:4444::1
                      table-id: 254

      1

      Create the assisted-deployment-pull-secret CR with the same namespace as the SiteConfig CR.

      2

      clusterImageSetNameRef defines an image set available on the hub cluster. To see the list of supported versions on your hub cluster, run oc get clusterimagesets.

      3

      Configure the SSH public key used to access the cluster.

      4

      Cluster labels must correspond to the bindingRules field in the PolicyGenTemplate CRs that you define. For example, policygentemplates/common-ranGen.yaml applies to all clusters with common: true set, policygentemplates/group-du-sno-ranGen.yaml applies to all clusters with group-du-sno: "" set.

      5

      Optional. The CR specifed under KlusterletAddonConfig is used to override the default KlusterletAddonConfig that is created for the cluster.

      6

      For single-node deployments, define a single host. For three-node deployments, define three hosts. For standard deployments, define three hosts with role: master and two or more hosts defined with role: worker.

      7

      BMC address that you use to access the host. Applies to all cluster types.

      8

      Name of the bmh-secret CR that you separately create with the host BMC credentials. When creating the bmh-secret CR, use the same namespace as the SiteConfig CR that provisions the host.

      9

      Configures the boot mode for the host. The default value is UEFI. Use UEFISecureBoot to enable secure boot on the host.

      10

      cpuset must match the value set in the cluster PerformanceProfile CR spec.cpu.reserved field for workload partitioning.

      11

      Specifies the network settings for the node.

      12

      Configures the IPv6 address for the host. For single-node OpenShift clusters with static IP addresses, the node-specific API and Ingress IPs should be the same.

      Note

      For more information about BMC addressing, see the "Additional resources" section.

   3. You can inspect the default set of extra-manifest

      MachineConfig

      CRs in

      out/argocd/extra-manifest

      . It is automatically applied to the cluster when it is installed.
   4. Optional: To provision additional install-time manifests on the provisioned cluster, create a directory in your Git repository, for example,

      sno-extra-manifest/

      , and add your custom manifest CRs to this directory. If your

      SiteConfig.yaml

      refers to this directory in the

      extraManifestPath

      field, any CRs in this referenced directory are appended to the default set of extra manifests.
4. Add the

   SiteConfig

   CR to the

   kustomization.yaml

   file in the

   generators

   section, similar to the example shown in

   out/argocd/example/siteconfig/kustomization.yaml

   .

5. Commit the

   SiteConfig

   CR and associated

   kustomization.yaml

   changes in your Git repository and push the changes.

   The ArgoCD pipeline detects the changes and begins the managed cluster deployment.

1. The Assisted Service Operator installs OpenShift Container Platform on the cluster. You can monitor the progress of cluster installation from the RHACM dashboard or from the command line by running the following commands:

   1. Export the cluster name:

      $ export CLUSTER=<clusterName>

   2. Query the

      AgentClusterInstall

      CR for the managed cluster:

      $ oc get agentclusterinstall -n $CLUSTER $CLUSTER -o jsonpath='{.status.conditions[?(@.type=="Completed")]}' | jq

   3. Get the installation events for the cluster:

      $ curl -sk $(oc get agentclusterinstall -n $CLUSTER $CLUSTER -o jsonpath='{.status.debugInfo.eventsURL}')  | jq '.[-2,-1]'

Procedure

1. Check that the installation CRs were created by using the following command:

   $ oc get AgentClusterInstall -n <cluster_name>

   If no object is returned, use the following steps to troubleshoot the ArgoCD pipeline flow from

   SiteConfig

   files to the installation CRs.

2. Verify that the

   ManagedCluster

   CR was generated using the

   SiteConfig

   CR on the hub cluster:

   $ oc get managedcluster

3. If the

   ManagedCluster

   is missing, check if the

   clusters

   application failed to synchronize the files from the Git repository to the hub cluster:

   $ oc describe -n openshift-gitops application clusters

   1. Check for the

      Status.Conditions

      field to view the error logs for the managed cluster. For example, setting an invalid value for

      extraManifestPath:

      in the

      SiteConfig

      CR raises the following error:

      Status:
        Conditions:
          Last Transition Time:  2021-11-26T17:21:39Z
          Message:               rpc error: code = Unknown desc = `kustomize build /tmp/https___git.com/ran-sites/siteconfigs/ --enable-alpha-plugins` failed exit status 1: 2021/11/26 17:21:40 Error could not create extra-manifest ranSite1.extra-manifest3 stat extra-manifest3: no such file or directory 2021/11/26 17:21:40 Error: could not build the entire SiteConfig defined by /tmp/kust-plugin-config-913473579: stat extra-manifest3: no such file or directory Error: failure in plugin configured via /tmp/kust-plugin-config-913473579; exit status 1: exit status 1
          Type:  ComparisonError

   2. Check the

      Status.Sync

      field. If there are log errors, the

      Status.Sync

      field could indicate an

      Unknown

      error:

      Status:
        Sync:
          Compared To:
            Destination:
              Namespace:  clusters-sub
              Server:     https://kubernetes.default.svc
            Source:
              Path:             sites-config
              Repo URL:         https://git.com/ran-sites/siteconfigs/.git
              Target Revision:  master
          Status:               Unknown

Procedure

1. Disable TLS in the

   Provisioning

   resource by running the following command:

   $ oc patch provisioning provisioning-configuration --type merge -p '{"spec":{"disableVirtualMediaTLS": true}}'

2. Continue the steps to deploy your single-node OpenShift cluster.

Procedure

1. Remove a site and the associated CRs by removing the associated

   SiteConfig

   and

   PolicyGenTemplate

   files from the

   kustomization.yaml

   file.

   When you run the ZTP pipeline again, the generated CRs are removed.

2. Optional: If you want to permanently remove a site, you should also remove the

   SiteConfig

   and site-specific

   PolicyGenTemplate

   files from the Git repository.
3. Optional: If you want to remove a site temporarily, for example when redeploying a site, you can leave the

   SiteConfig

   and site-specific

   PolicyGenTemplate

   CRs in the Git repository.

Procedure

1. Remove the affected

   PolicyGenTemplate

   files from the Git repository, commit and push to the remote repository.
2. Wait for the changes to synchronize through the application and the affected policies to be removed from the hub cluster.

3. Add the updated

   PolicyGenTemplate

   files back to the Git repository, and then commit and push to the remote repository.
   Note

   Removing zero touch provisioning (ZTP) policies from the Git repository, and as a result also removing them from the hub cluster, does not affect the configuration of the managed cluster. The policy and CRs managed by that policy remains in place on the managed cluster.

4. Optional: As an alternative, after making changes to

   PolicyGenTemplate

   CRs that result in obsolete policies, you can remove these policies from the hub cluster manually. You can delete policies from the RHACM console using the Governance tab or by running the following command:

   $ oc delete policy -n <namespace> <policy_name>

Procedure

1. Detach all clusters from Red Hat Advanced Cluster Management (RHACM) on the hub cluster.

2. Delete the

   kustomization.yaml

   file in the

   deployment

   directory using the following command:

   $ oc delete -k out/argocd/deployment

3. Commit and push your changes to the site repository.

Procedure

1. Create a

   PolicyGenTemplate

   CR for site-specific configuration CRs.
   1. Choose the appropriate example for your CR from the

      out/argocd/example/policygentemplates

      folder, for example,

      example-sno-site.yaml

      or

      example-multinode-site.yaml

      .

   2. Change the

      bindingRules

      field in the example file to match the site-specific label included in the

      SiteConfig

      CR. In the example

      SiteConfig

      file, the site-specific label is

      sites: example-sno

      .
      Note

      Ensure that the labels defined in your

      PolicyGenTemplate

      bindingRules

      field correspond to the labels that are defined in the related managed clusters

      SiteConfig

      CR.

   3. Change the content in the example file to match the desired configuration.

2. Optional: Create a

   PolicyGenTemplate

   CR for any common configuration CRs that apply to the entire fleet of clusters.
   1. Select the appropriate example for your CR from the

      out/argocd/example/policygentemplates

      folder, for example,

      common-ranGen.yaml

      .
   2. Change the content in the example file to match the desired configuration.

3. Optional: Create a

   PolicyGenTemplate

   CR for any group configuration CRs that apply to the certain groups of clusters in the fleet.

   Ensure that the content of the overlaid spec files matches your desired end state. As a reference, the out/source-crs directory contains the full list of source-crs available to be included and overlaid by your PolicyGenTemplate templates.

   Note

   Depending on the specific requirements of your clusters, you might need more than a single group policy per cluster type, especially considering that the example group policies each have a single PerformancePolicy.yaml file that can only be shared across a set of clusters if those clusters consist of identical hardware configurations.

   1. Select the appropriate example for your CR from the

      out/argocd/example/policygentemplates

      folder, for example,

      group-du-sno-ranGen.yaml

      .
   2. Change the content in the example file to match the desired configuration.
4. Optional. Create a validator inform policy

   PolicyGenTemplate

   CR to signal when the ZTP installation and configuration of the deployed cluster is complete. For more information, see "Creating a validator inform policy".

5. Define all the policy namespaces in a YAML file similar to the example

   out/argocd/example/policygentemplates/ns.yaml

   file.
   Important

   Do not include the

   Namespace

   CR in the same file with the

   PolicyGenTemplate

   CR.

6. Add the

   PolicyGenTemplate

   CRs and

   Namespace

   CR to the

   kustomization.yaml

   file in the generators section, similar to the example shown in

   out/argocd/example/policygentemplates/kustomization.yaml

   .

7. Commit the

   PolicyGenTemplate

   CRs,

   Namespace

   CR, and associated

   kustomization.yaml

   file in your Git repository and push the changes.

   The ArgoCD pipeline detects the changes and begins the managed cluster deployment. You can push the changes to the

   SiteConfig

   CR and the

   PolicyGenTemplate

   CR simultaneously.

Procedure

1. The Topology Aware Lifecycle Manager (TALM) applies the configuration policies that are bound to the cluster.

   After the cluster installation is complete and the cluster becomes

   Ready

   , a

   ClusterGroupUpgrade

   CR corresponding to this cluster, with a list of ordered policies defined by the

   ran.openshift.io/ztp-deploy-wave annotations

   , is automatically created by the TALM. The cluster’s policies are applied in the order listed in

   ClusterGroupUpgrade

   CR.

   You can monitor the high-level progress of configuration policy reconciliation by using the following commands:

   $ export CLUSTER=<clusterName>

   $ oc get clustergroupupgrades -n ztp-install $CLUSTER -o jsonpath='{.status.conditions[-1:]}' | jq

   Example output

   {
     "lastTransitionTime": "2022-11-09T07:28:09Z",
     "message": "The ClusterGroupUpgrade CR has upgrade policies that are still non compliant",
     "reason": "UpgradeNotCompleted",
     "status": "False",
     "type": "Ready"
   }

2. You can monitor the detailed cluster policy compliance status by using the RHACM dashboard or the command line.

   1. To check policy compliance by using

      oc

      , run the following command:

      $ oc get policies -n $CLUSTER

      Example output

      NAME                                                     REMEDIATION ACTION   COMPLIANCE STATE   AGE
      ztp-common.common-config-policy                          inform               Compliant          3h42m
      ztp-common.common-subscriptions-policy                   inform               NonCompliant       3h42m
      ztp-group.group-du-sno-config-policy                     inform               NonCompliant       3h42m
      ztp-group.group-du-sno-validator-du-policy               inform               NonCompliant       3h42m
      ztp-install.example1-common-config-policy-pjz9s          enforce              Compliant          167m
      ztp-install.example1-common-subscriptions-policy-zzd9k   enforce              NonCompliant       164m
      ztp-site.example1-config-policy                          inform               NonCompliant       3h42m
      ztp-site.example1-perf-policy                            inform               NonCompliant       3h42m

   2. To check policy status from the RHACM web console, perform the following actions:

      1. Click Governance Find policies.
      2. Click on a cluster policy to check it’s status.

Procedure

1. To display detailed information about the policies, run the following command:

   $ oc describe -n openshift-gitops application policies

2. Check for

   Status: Conditions:

   to show the error logs. For example, setting an invalid

   sourceFile→fileName:

   generates the error shown below:

   Status:
     Conditions:
       Last Transition Time:  2021-11-26T17:21:39Z
       Message:               rpc error: code = Unknown desc = `kustomize build /tmp/https___git.com/ran-sites/policies/ --enable-alpha-plugins` failed exit status 1: 2021/11/26 17:21:40 Error could not find test.yaml under source-crs/: no such file or directory Error: failure in plugin configured via /tmp/kust-plugin-config-52463179; exit status 1: exit status 1
       Type:  ComparisonError

3. Check for

   Status: Sync:

   . If there are log errors at

   Status: Conditions:

   , the

   Status: Sync:

   shows

   Unknown

   or

   Error

   :

   Status:
     Sync:
       Compared To:
         Destination:
           Namespace:  policies-sub
           Server:     https://kubernetes.default.svc
         Source:
           Path:             policies
           Repo URL:         https://git.com/ran-sites/policies/.git
           Target Revision:  master
       Status:               Error

4. When Red Hat Advanced Cluster Management (RHACM) recognizes that policies apply to a

   ManagedCluster

   object, the policy CR objects are applied to the cluster namespace. Check to see if the policies were copied to the cluster namespace:

   $ oc get policy -n $CLUSTER

   Example output:

   NAME                                         REMEDIATION ACTION   COMPLIANCE STATE   AGE
   ztp-common.common-config-policy              inform               Compliant          13d
   ztp-common.common-subscriptions-policy       inform               Compliant          13d
   ztp-group.group-du-sno-config-policy         inform               Compliant          13d
   Ztp-group.group-du-sno-validator-du-policy   inform               Compliant          13d
   ztp-site.example-sno-config-policy           inform               Compliant          13d

   RHACM copies all applicable policies into the cluster namespace. The copied policy names have the format:

   <policyGenTemplate.Namespace>.<policyGenTemplate.Name>-<policyName>

   .

5. Check the placement rule for any policies not copied to the cluster namespace. The

   matchSelector

   in the

   PlacementRule

   for those policies should match labels on the

   ManagedCluster

   object:

   $ oc get placementrule -n $NS

6. Note the

   PlacementRule

   name appropriate for the missing policy, common, group, or site, using the following command:

   $ oc get placementrule -n $NS <placementRuleName> -o yaml

   • The status-decisions should include your cluster name.
   • The key-value pair of the

     matchSelector

     in the spec must match the labels on your managed cluster.

7. Check the labels on the

   ManagedCluster

   object using the following command:

   $ oc get ManagedCluster $CLUSTER -o jsonpath='{.metadata.labels}' | jq

8. Check to see which policies are compliant using the following command:

   $ oc get policy -n $CLUSTER

   If the

   Namespace

   ,

   OperatorGroup

   , and

   Subscription

   policies are compliant but the Operator configuration policies are not, it is likely that the Operators did not install on the managed cluster. This causes the Operator configuration policies to fail to apply because the CRD is not yet applied to the spoke.

Procedure

1. A

   ClusterGroupUpgrade

   CR is generated in the namespace

   ztp-install

   by the Topology Aware Lifecycle Manager after the managed cluster becomes

   Ready

   :

   $ export CLUSTER=<clusterName>

   $ oc get clustergroupupgrades -n ztp-install $CLUSTER

2. If there are unexpected issues and the policies fail to become complaint within the configured timeout (the default is 4 hours), the status of the

   ClusterGroupUpgrade

   CR shows

   UpgradeTimedOut

   :

   $ oc get clustergroupupgrades -n ztp-install $CLUSTER -o jsonpath='{.status.conditions[?(@.type=="Ready")]}'

3. A

   ClusterGroupUpgrade

   CR in the

   UpgradeTimedOut

   state automatically restarts its policy reconciliation every hour. If you have changed your policies, you can start a retry immediately by deleting the existing

   ClusterGroupUpgrade

   CR. This triggers the automatic creation of a new

   ClusterGroupUpgrade

   CR that begins reconciling the policies immediately:

   $ oc delete clustergroupupgrades -n ztp-install $CLUSTER

Procedure

1. Remove the content that you no longer need from the affected CRs. In this example, the

   disableDrain: false

   line was removed from the

   SriovOperatorConfig

   CR.

   Example CR

   apiVersion: sriovnetwork.openshift.io/v1
   kind: SriovOperatorConfig
   metadata:
     name: default
     namespace: openshift-sriov-network-operator
   spec:
     configDaemonNodeSelector:
       "node-role.kubernetes.io/$mcp": ""
     disableDrain: true
     enableInjector: true
     enableOperatorWebhook: true

2. Change the

   complianceType

   of the affected policies to

   mustonlyhave

   in the

   group-du-sno-ranGen.yaml

   file.

   Example YAML

   # ...
   - fileName: SriovOperatorConfig.yaml
     policyName: "config-policy"
     complianceType: mustonlyhave
   # ...

3. Create a

   ClusterGroupUpdates

   CR and specify the clusters that must receive the CR changes::

   Example ClusterGroupUpdates CR

   apiVersion: ran.openshift.io/v1alpha1
   kind: ClusterGroupUpgrade
   metadata:
     name: cgu-remove
     namespace: default
   spec:
     managedPolicies:
       - ztp-group.group-du-sno-config-policy
     enable: false
     clusters:
     - spoke1
     - spoke2
     remediationStrategy:
       maxConcurrency: 2
       timeout: 240
     batchTimeoutAction:

4. Create the

   ClusterGroupUpgrade

   CR by running the following command:

   $ oc create -f cgu-remove.yaml

5. When you are ready to apply the changes, for example, during an appropriate maintenance window, change the value of the

   spec.enable

   field to

   true

   by running the following command:

   $ oc --namespace=default patch clustergroupupgrade.ran.openshift.io/cgu-remove \
   --patch '{"spec":{"enable":true}}' --type=merge

Verification

1. Check the status of the policies by running the following command:

   $ oc get <kind> <changed_cr_name>

   Example output

   NAMESPACE   NAME                                                   REMEDIATION ACTION   COMPLIANCE STATE   AGE
   default     cgu-ztp-group.group-du-sno-config-policy               enforce                                 17m
   default     ztp-group.group-du-sno-config-policy                   inform               NonCompliant       15h

   When the

   COMPLIANCE STATE

   of the policy is

   Compliant

   , it means that the CR is updated and the unwanted content is removed.

2. Check that the policies are removed from the targeted clusters by running the following command on the managed clusters:

   $ oc get <kind> <changed_cr_name>

   If there are no results, the CR is removed from the managed cluster.

Procedure

1. Create an output folder by running the following command:

   $ mkdir -p ./out

2. Export the

   argocd

   directory from the

   ztp-site-generate

   container image:

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

   The

   ./out

   directory has the reference

   PolicyGenTemplate

   and

   SiteConfig

   CRs in the

   out/argocd/example/

   folder.

   Example output

   out
    └── argocd
         └── example
              ├── policygentemplates
              │     ├── common-ranGen.yaml
              │     ├── example-sno-site.yaml
              │     ├── group-du-sno-ranGen.yaml
              │     ├── group-du-sno-validator-ranGen.yaml
              │     ├── kustomization.yaml
              │     └── ns.yaml
              └── siteconfig
                     ├── example-sno.yaml
                     ├── KlusterletAddonConfigOverride.yaml
                     └── kustomization.yaml

3. Create an output folder for the site installation CRs:

   $ mkdir -p ./site-install

4. Modify the example

   SiteConfig

   CR for the cluster type that you want to install. Copy

   example-sno.yaml

   to

   site-1-sno.yaml

   and modify the CR to match the details of the site and bare-metal host that you want to install, for example:

   Example single-node OpenShift cluster SiteConfig CR

   apiVersion: ran.openshift.io/v1
   kind: SiteConfig
   metadata:
     name: "<site_name>"
     namespace: "<site_name>"
   spec:
     baseDomain: "example.com"
     pullSecretRef:
       name: "assisted-deployment-pull-secret" 

   1

   
     clusterImageSetNameRef: "openshift-4.11" 

   2

   
     sshPublicKey: "ssh-rsa AAAA..." 

   3

   
     clusters:
     - clusterName: "<site_name>"
       networkType: "OVNKubernetes"
       clusterLabels: 

   4

   
         common: true
         group-du-sno: ""
         sites : "<site_name>"
       clusterNetwork:
         - cidr: 1001:1::/48
           hostPrefix: 64
       machineNetwork:
         - cidr: 1111:2222:3333:4444::/64
       serviceNetwork:
         - 1001:2::/112
       additionalNTPSources:
         - 1111:2222:3333:4444::2
       #crTemplates:
       #  KlusterletAddonConfig: "KlusterletAddonConfigOverride.yaml" 

   5

   
       nodes:
         - hostName: "example-node.example.com" 

   6

   
           role: "master"
           bmcAddress: idrac-virtualmedia://<out_of_band_ip>/<system_id>/ 

   7

   
           bmcCredentialsName:
             name: "bmh-secret" 

   8

   
           bootMACAddress: "AA:BB:CC:DD:EE:11"
           bootMode: "UEFI" 

   9

   
           rootDeviceHints:
             wwn: "0x11111000000asd123"
           cpuset: "0-1,52-53"  

   10

   
           nodeNetwork: 

   11

   
             interfaces:
               - name: eno1
                 macAddress: "AA:BB:CC:DD:EE:11"
             config:
               interfaces:
                 - name: eno1
                   type: ethernet
                   state: up
                   ipv4:
                     enabled: false
                   ipv6: 

   12

   
                     enabled: true
                     address:
                     - ip: 1111:2222:3333:4444::aaaa:1
                       prefix-length: 64
               dns-resolver:
                 config:
                   search:
                   - example.com
                   server:
                   - 1111:2222:3333:4444::2
               routes:
                 config:
                 - destination: ::/0
                   next-hop-interface: eno1
                   next-hop-address: 1111:2222:3333:4444::1
                   table-id: 254

   1

   Create the assisted-deployment-pull-secret CR with the same namespace as the SiteConfig CR.

   2

   clusterImageSetNameRef defines an image set available on the hub cluster. To see the list of supported versions on your hub cluster, run oc get clusterimagesets.

   3

   Configure the SSH public key used to access the cluster.

   4

   Cluster labels must correspond to the bindingRules field in the PolicyGenTemplate CRs that you define. For example, policygentemplates/common-ranGen.yaml applies to all clusters with common: true set, policygentemplates/group-du-sno-ranGen.yaml applies to all clusters with group-du-sno: "" set.

   5

   Optional. The CR specifed under KlusterletAddonConfig is used to override the default KlusterletAddonConfig that is created for the cluster.

   6

   For single-node deployments, define a single host. For three-node deployments, define three hosts. For standard deployments, define three hosts with role: master and two or more hosts defined with role: worker.

   7

   BMC address that you use to access the host. Applies to all cluster types.

   8

   Name of the bmh-secret CR that you separately create with the host BMC credentials. When creating the bmh-secret CR, use the same namespace as the SiteConfig CR that provisions the host.

   9

   Configures the boot mode for the host. The default value is UEFI. Use UEFISecureBoot to enable secure boot on the host.

   10

   cpuset must match the value set in the cluster PerformanceProfile CR spec.cpu.reserved field for workload partitioning.

   11

   Specifies the network settings for the node.

   12

   Configures the IPv6 address for the host. For single-node OpenShift clusters with static IP addresses, the node-specific API and Ingress IPs should be the same.

5. Generate the day-0 installation CRs by processing the modified

   SiteConfig

   CR

   site-1-sno.yaml

   by running the following command:

   $ podman run -it --rm -v `pwd`/out/argocd/example/siteconfig:/resources:Z -v `pwd`/site-install:/output:Z,U registry.redhat.io/openshift4/ztp-site-generate-rhel8:v4.11.1 generator install site-1-sno.yaml /output

   Example output

   site-install
   └── site-1-sno
       ├── site-1_agentclusterinstall_example-sno.yaml
       ├── site-1-sno_baremetalhost_example-node1.example.com.yaml
       ├── site-1-sno_clusterdeployment_example-sno.yaml
       ├── site-1-sno_configmap_example-sno.yaml
       ├── site-1-sno_infraenv_example-sno.yaml
       ├── site-1-sno_klusterletaddonconfig_example-sno.yaml
       ├── site-1-sno_machineconfig_02-master-workload-partitioning.yaml
       ├── site-1-sno_machineconfig_predefined-extra-manifests-master.yaml
       ├── site-1-sno_machineconfig_predefined-extra-manifests-worker.yaml
       ├── site-1-sno_managedcluster_example-sno.yaml
       ├── site-1-sno_namespace_example-sno.yaml
       └── site-1-sno_nmstateconfig_example-node1.example.com.yaml

6. Optional: Generate just the day-0

   MachineConfig

   installation CRs for a particular cluster type by processing the reference

   SiteConfig

   CR with the

   -E

   option. For example, run the following commands:

   1. Create an output folder for the

      MachineConfig

      CRs:

      $ mkdir -p ./site-machineconfig

   2. Generate the

      MachineConfig

      installation CRs:

      $ podman run -it --rm -v `pwd`/out/argocd/example/siteconfig:/resources:Z -v `pwd`/site-machineconfig:/output:Z,U registry.redhat.io/openshift4/ztp-site-generate-rhel8:v4.11.1 generator install -E site-1-sno.yaml /output

      Example output

      site-machineconfig
      └── site-1-sno
          ├── site-1-sno_machineconfig_02-master-workload-partitioning.yaml
          ├── site-1-sno_machineconfig_predefined-extra-manifests-master.yaml
          └── site-1-sno_machineconfig_predefined-extra-manifests-worker.yaml

7. Generate and export the day-2 configuration CRs using the reference

   PolicyGenTemplate

   CRs from the previous step. Run the following commands:

   1. Create an output folder for the day-2 CRs:

      $ mkdir -p ./ref

   2. Generate and export the day-2 configuration CRs:

      $ podman run -it --rm -v `pwd`/out/argocd/example/policygentemplates:/resources:Z -v `pwd`/ref:/output:Z,U registry.redhat.io/openshift4/ztp-site-generate-rhel8:v4.11.1 generator config -N . /output

      The command generates example group and site-specific

      PolicyGenTemplate

      CRs for single-node OpenShift, three-node clusters, and standard clusters in the

      ./ref

      folder.

      Example output

      ref
       └── customResource
            ├── common
            ├── example-multinode-site
            ├── example-sno
            ├── group-du-3node
            ├── group-du-3node-validator
            │    └── Multiple-validatorCRs
            ├── group-du-sno
            ├── group-du-sno-validator
            ├── group-du-standard
            └── group-du-standard-validator
                 └── Multiple-validatorCRs

8. Use the generated CRs as the basis for the CRs that you use to install the cluster. You apply the installation CRs to the hub cluster as described in "Installing a single managed cluster". The configuration CRs can be applied to the cluster after cluster installation is complete.

Procedure

1. Create a YAML secret file containing credentials for the host Baseboard Management Controller (BMC) and a pull secret required for installing OpenShift and all add-on cluster Operators:

   1. Save the following YAML as the file

      example-sno-secret.yaml

      :

      apiVersion: v1
      kind: Secret
      metadata:
        name: example-sno-bmc-secret
        namespace: example-sno 

      1

      
      data: 

      2

      
        password: <base64_password>
        username: <base64_username>
      type: Opaque
      ---
      apiVersion: v1
      kind: Secret
      metadata:
        name: pull-secret
        namespace: example-sno  

      3

      
      data:
        .dockerconfigjson: <pull_secret> 

      4

      
      type: kubernetes.io/dockerconfigjson

      1

      Must match the namespace configured in the related SiteConfig CR

      2

      Base64-encoded values for password and username

      3

      Must match the namespace configured in the related SiteConfig CR

      4

      Base64-encoded pull secret

2. Add the relative path to

   example-sno-secret.yaml

   to the

   kustomization.yaml

   file that you use to install the cluster.

Procedure

1. Create a

   ClusterImageSet

   for each specific cluster version to be deployed, for example

   clusterImageSet-4.11.yaml

   . A

   ClusterImageSet

   has the following format:

   apiVersion: hive.openshift.io/v1
   kind: ClusterImageSet
   metadata:
     name: openshift-4.11.0 

   1

   
   spec:
      releaseImage: quay.io/openshift-release-dev/ocp-release:4.11.0-x86_64 

   2

   1

   The descriptive version that you want to deploy.

   2

   Specifies the releaseImage to deploy and determines the operating system image version. The discovery ISO is based on the image version as set by releaseImage, or the latest version if the exact version is unavailable.

2. Apply the

   clusterImageSet

   CR:

   $ oc apply -f clusterImageSet-4.11.yaml

3. Create the

   Namespace

   CR in the

   cluster-namespace.yaml

   file:

   apiVersion: v1
   kind: Namespace
   metadata:
        name: <cluster_name> 

   1

   
        labels:
           name: <cluster_name> 

   2

   1 2

   The name of the managed cluster to provision.

4. Apply the

   Namespace

   CR by running the following command:

   $ oc apply -f cluster-namespace.yaml

5. Apply the generated day-0 CRs that you extracted from the

   ztp-site-generate

   container and customized to meet your requirements:

   $ oc apply -R ./site-install/site-sno-1

Procedure

1. Check the status of the managed cluster:

   $ oc get managedcluster

   True

   indicates the managed cluster is ready.

2. Check the agent status:

   $ oc get agent -n <cluster_name>

3. Use the

   describe

   command to provide an in-depth description of the agent’s condition. Statuses to be aware of include

   BackendError

   ,

   InputError

   ,

   ValidationsFailing

   ,

   InstallationFailed

   , and

   AgentIsConnected

   . These statuses are relevant to the

   Agent

   and

   AgentClusterInstall

   custom resources.

   $ oc describe agent -n <cluster_name>

4. Check the cluster provisioning status:

   $ oc get agentclusterinstall -n <cluster_name>

5. Use the

   describe

   command to provide an in-depth description of the cluster provisioning status:

   $ oc describe agentclusterinstall -n <cluster_name>

6. Check the status of the managed cluster’s add-on services:

   $ oc get managedclusteraddon -n <cluster_name>

7. Retrieve the authentication information of the

   kubeconfig

   file for the managed cluster:

   $ oc get secret -n <cluster_name> <cluster_name>-admin-kubeconfig -o jsonpath={.data.kubeconfig} | base64 -d > <directory>/<cluster_name>-kubeconfig

Procedure

1. Check the status of the managed cluster:

   $ oc get managedcluster

   Example output

   NAME            HUB ACCEPTED   MANAGED CLUSTER URLS   JOINED   AVAILABLE   AGE
   SNO-cluster     true                                   True     True      2d19h

   If the status in the

   AVAILABLE

   column is

   True

   , the managed cluster is being managed by the hub.

   If the status in the

   AVAILABLE

   column is

   Unknown

   , the managed cluster is not being managed by the hub. Use the following steps to continue checking to get more information.

2. Check the

   AgentClusterInstall

   install status:

   $ oc get clusterdeployment -n <cluster_name>

   Example output

   NAME        PLATFORM            REGION   CLUSTERTYPE   INSTALLED    INFRAID    VERSION  POWERSTATE AGE
   Sno0026    agent-baremetal                               false                          Initialized
   2d14h

   If the status in the

   INSTALLED

   column is

   false

   , the installation was unsuccessful.

3. If the installation failed, enter the following command to review the status of the

   AgentClusterInstall

   resource:

   $ oc describe agentclusterinstall -n <cluster_name> <cluster_name>

4. Resolve the errors and reset the cluster:

   1. Remove the cluster’s managed cluster resource:

      $ oc delete managedcluster <cluster_name>

   2. Remove the cluster’s namespace:

      $ oc delete namespace <cluster_name>

      This deletes all of the namespace-scoped custom resources created for this cluster. You must wait for the

      ManagedCluster

      CR deletion to complete before proceeding.

   3. Recreate the custom resources for the managed cluster.

Procedure

1. Set the UEFI/BIOS Boot Mode to

   UEFI

   .
2. In the host boot sequence order, set Hard drive first.

3. Apply the specific firmware configuration for your hardware. The following table describes a representative firmware configuration for an Intel Xeon Skylake or Intel Cascade Lake server, based on the Intel FlexRAN 4G and 5G baseband PHY reference design.

   Important

   The exact firmware configuration depends on your specific hardware and network requirements. The following sample configuration is for illustrative purposes only.

   Expand

   Table 22.6. Sample firmware configuration for an Intel Xeon Skylake or Cascade Lake server

   Firmware setting	Configuration
   CPU Power and Performance Policy	Performance
   Uncore Frequency Scaling	Disabled
   Performance P-limit	Disabled
   Enhanced Intel SpeedStep ® Tech	Enabled
   Intel Configurable TDP	Enabled
   Configurable TDP Level	Level 2
   Intel® Turbo Boost Technology	Enabled
   Energy Efficient Turbo	Disabled
   Hardware P-States	Disabled
   Package C-State	C0/C1 state
   C1E	Disabled
   Processor C6	Disabled

   Show more