Chapter 2. SiteConfig

Set an environment variable that matches the namespace of the MultiClusterHub operator by running the following command:

export MCH_NAMESPACE=<namespace>

Set the enabled field to true in the siteconfig entry of spec.overrides.components in the Multiclusterhub resource by running the following command:

oc patch multiclusterhubs.operator.open-cluster-management.io multiclusterhub -n ${MCH_NAMESPACE} --type json --patch '[{"op": "add", "path":"/spec/overrides/components/-", "value": {"name":"siteconfig","enabled": true}}]'

Verify that the SiteConfig operator is enabled by running the following command on the hub cluster:

oc -n ${MCH_NAMESPACE} get po | grep siteconfig

See the following example output:

siteconfig-controller-manager-6fdd86cc64-sdg87                    2/2     Running   0             43s

Optional: Verify that you have the default installation templates by running the following command on the hub cluster:

oc -n ${MCH_NAMESPACE} get cm

See the following list of templates in the output example:

NAME                                DATA   AGE
ai-cluster-templates-v1             5      97s
ai-node-templates-v1                2      97s
...
ibi-cluster-templates-v1            3      97s
ibi-node-templates-v1               3      97s
...

Create a YAML file for the target namespace. See the following example file that is named clusterinstance-namespace.yaml:

apiVersion: v1
kind: Namespace
metadata:
  name: example-sno

Apply your file to create the resource. Run the following command on the hub cluster:

oc apply -f clusterinstance-namespace.yaml

Create a YAML file to pull images. See the following example of a file that is named pull-secret.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: pull-secret
  namespace: example-sno 1
data:
  .dockerconfigjson: <encoded_docker_configuration> 2
type: kubernetes.io/dockerconfigjson

Apply the file to create the resource. Run the following command on the hub cluster:

oc apply -f pull-secret.yaml

Create a YAML file for the BMC secret. See the following sample file that is named example-bmc-secret.yaml:

apiVersion: v1
data:
  password: <password>
  username: <username>
kind: Secret
metadata:
  name: example-bmh-secret
  namespace: "example-sno" 1
type: Opaque

Apply the file to create the resource. Run the following command on the hub cluster:

oc apply -f example-bmc-secret.yaml

Create a YAML file for an extra manifest ConfigMap object, for example named enable-crun.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: enable-crun
  namespace: example-sno 1
data:
  enable-crun-master.yaml: |
    apiVersion: machineconfiguration.openshift.io/v1
    kind: ContainerRuntimeConfig
    metadata:
      name: enable-crun-master
    spec:
      machineConfigPoolSelector:
        matchLabels:
          pools.operator.machineconfiguration.openshift.io/master: ""
      containerRuntimeConfig:
        defaultRuntime: crun
  enable-crun-worker.yaml: |
    apiVersion: machineconfiguration.openshift.io/v1
    kind: ContainerRuntimeConfig
    metadata:
      name: enable-crun-worker
    spec:
      machineConfigPoolSelector:
        matchLabels:
          pools.operator.machineconfiguration.openshift.io/worker: ""
      containerRuntimeConfig:
        defaultRuntime: crun

Create the resource by running the following command on the hub cluster:

oc apply -f enable-crun.yaml

In the example-sno namespace, create the ClusterInstance custom resource that is named clusterinstance-ibi.yaml in the following example:

apiVersion: siteconfig.open-cluster-management.io/v1alpha1
kind: ClusterInstance
metadata:
  name: "example-clusterinstance"
  namespace: "example-sno" 1
spec:
  holdInstallation: false
  extraManifestsRefs: 2
    - name: extra-machine-configs
    - name: enable-crun
  pullSecretRef:
    name: "pull-secret" 3
  [...]
  clusterName: "example-sno" 4
  [...]
  clusterImageSetNameRef: "img4.17-x86-64"
  [...]
  templateRefs: 5
    - name: ibi-cluster-templates-v1
      namespace: rhacm
  [...]
  nodes:
      [...]
      bmcCredentialsName: 6
        name: "example-bmh-secret"
      [...]
      templateRefs: 7
        - name: ibi-node-templates-v1
          namespace: rhacm
      [...]

Apply the file and create the resource by running the following command:

oc apply -f clusterinstance-ibi.yaml

After you create the custom resource, the SiteConfig operator starts reconciling the ClusterInstance custom resource, then validates and renders the installation manifests.

The SiteConfig operator continues to monitor for changes in the ClusterDeployment custom resources to update the cluster installation progress of the corresponding ClusterInstance custom resource.

Monitor the process by running the following command:

oc get clusterinstance <cluster_name> -n <target_namespace> -o yaml

See the following example output from the status.conditions section for successful manifest generation:

message: Applied site config manifests
reason: Completed
status: "True"
type: RenderedTemplatesApplied

Check the manifests that SiteConfig operator rendered by running the following command:

oc get clusterinstance <cluster_name> -n <target_namespace> -o jsonpath='{.status.manifestsRendered}'

Delete the ClusterInstance custom resource by running the following command:

oc delete clusterinstance <cluster_name> -n <target_namespace>

Verify that the deletion was successful by running the following command:

oc get clusterinstance <cluster_name> -n <target_namespace>

Create a YAML file named my-custom-secret.yaml that contains the cluster-level template in a ConfigMap object:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-custom-secret
  namespace: rhacm
data:
  MySecret: |-
    apiVersion: v1
    kind: Secret
    metadata:
      name: "{{ .Spec.ClusterName }}-my-custom-secret-key"
      namespace: "clusters"
      annotations:
        siteconfig.open-cluster-management.io/sync-wave: "1" 1
    type: Opaque
    data:
      key: <key>

Apply the custom template on the hub cluster by running the following command:

oc apply -f my-custom-secret.yaml

Reference your template in the ClusterInstance custom resource named clusterinstance-my-custom-secret.yaml:

spec:
    ...
  templateRefs:
    - name: ai-cluster-templates-v1.yaml
      namespace: rhacm
    - name: my-custom-secret.yaml
      namespace: rhacm
    ...

Apply the ClusterInstance custom resource by running the following command:

oc apply -f clusterinstance-my-custom-secret.yaml

Create a YAML file named idms-configmap.yaml for your ImageDigestMirrorSet object that contains your mirror registry locations:

kind: ConfigMap
apiVersion: v1
metadata:
  name: "idms-configmap"
  namespace: "example-sno"
data:
  99-example-idms.yaml: |
    apiVersion: config.openshift.io/v1
    kind: ImageDigestMirrorSet
    metadata:
      name: example-idms
    spec:
      imageDigestMirrors:
      - mirrors:
        - mirror.registry.example.com/image-repo/image
        source: registry.example.com/image-repo/image

Create the resource by running the following command on the hub cluster:

oc apply -f idms-configmap.yaml

Reference your ImageDigestMirrorSet object in the ClusterInstance custom resource:

apiVersion: siteconfig.open-cluster-management.io/v1alpha1
kind: ClusterInstance
metadata:
  name: "example-sno"
  namespace: "example-sno"
spec:
  ...
  extraManifestsRefs:
    - name: idms-configmap
...