diff --git a/_attributes/common-attributes.adoc b/_attributes/common-attributes.adoc index 3f5bd349a3c9..1d6f40a4684f 100644 --- a/_attributes/common-attributes.adoc +++ b/_attributes/common-attributes.adoc @@ -236,6 +236,8 @@ endif::[] :rh-dev-hub: Red Hat Developer Hub //IBU :lcao: Lifecycle Agent +//SiteConfig Operator +:sco: SiteConfig Operator diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 0f97cf0f22c1..16ae414fb5cf 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -3194,6 +3194,43 @@ Topics: # File: telco-core-ref-design-components # - Name: Core reference design configuration CRs # File: telco-core-ref-crs +- Name: Installing single-node OpenShift clusters with the SiteConfig Operator + Dir: installing_with_siteconfig_operator + Distros: openshift-origin,openshift-enterprise + Topics: + - Name: Understanding the SiteConfig Operator + File: cnf-understanding-siteconfig-operator +--- +Name: Reference design specifications +Dir: telco_ref_design_specs +Distros: openshift-telco +Topics: +- Name: Telco reference design specifications + File: telco-ref-design-specs-overview +- Name: Telco RAN DU reference design specification + Dir: ran + Topics: + - Name: Telco RAN DU reference design overview + File: telco-ran-ref-design-spec + - Name: Telco RAN DU use model overview + File: telco-ran-du-overview + - Name: RAN DU reference design components + File: telco-ran-ref-du-components + - Name: RAN DU reference design configuration CRs + File: telco-ran-ref-du-crs + - Name: Telco RAN DU software specifications + File: telco-ran-ref-software-artifacts +- Name: Telco core reference design specification + Dir: core + Topics: + - Name: Telco core reference design overview + File: telco-core-rds-overview + - Name: Telco core use model overview + File: telco-core-rds-use-cases + - Name: Core reference design components + File: telco-core-ref-design-components + - Name: Core reference design configuration CRs + File: telco-core-ref-crs --- Name: Specialized hardware and driver enablement Dir: hardware_enablement diff --git a/edge_computing/installing_with_siteconfig_operator/_attributes b/edge_computing/installing_with_siteconfig_operator/_attributes new file mode 120000 index 000000000000..20cc1dcb77bf --- /dev/null +++ b/edge_computing/installing_with_siteconfig_operator/_attributes @@ -0,0 +1 @@ +../../_attributes/ \ No newline at end of file diff --git a/edge_computing/installing_with_siteconfig_operator/cnf-understanding-siteconfig-operator.adoc b/edge_computing/installing_with_siteconfig_operator/cnf-understanding-siteconfig-operator.adoc new file mode 100644 index 000000000000..379ba6672892 --- /dev/null +++ b/edge_computing/installing_with_siteconfig_operator/cnf-understanding-siteconfig-operator.adoc @@ -0,0 +1,62 @@ +:_mod-docs-content-type: ASSEMBLY +[id="cnf-understanding-siteconfig-operator"] += Understanding the {sco} +include::_attributes/common-attributes.adoc[] +:context: siteconfig-operator + +toc::[] + +With the {sco}, you can deploy clusters with all available installation methods. +The {sco} introduces a unified `ClusterInstance` API, which is derived from the `SiteConfig` API from the SiteConfig Generator kustomize plugin. +For example, the `ClusterInstance` API decouples parameters that define a cluster from the manner in which the cluster is deployed. +This separation removes certain limitations that are presented by the `SiteConfig` kustomize plugin in the current xref:../../edge_computing/ztp-deploying-far-edge-sites.adoc#ztp-deploying-far-edge-sites[{ztp-first} flow], such as agent cluster installations and scalability constraints posed by ArgoCD. +Using the unified `ClusterInstance` API, the {sco} offers the following improvements: + +Isolation:: Separates cluster definition from the installation method. The `ClusterInstance` CR captures the cluster definition, while cluster templates capture the cluster architecture and installation methods. +Unification:: The {sco} unifies both Git and non-Git workflows. Users can apply the `ClusterInstance` CR directly on the hub cluster or synchronize them through a GitOps solution, like ArgoCD. +Consistency:: Maintains a consistent API across all installation methods, whether using the Assisted Installer, the Image Based Install Operator, or any other custom template-based approach. +Scalability:: Achieves greater scalability per cluster than the `SiteConfig` kustomize plugin. +Flexibility:: Provides users with more power to deploy and install clusters by using custom cluster templates. +Troubleshooting:: Offers insightful information regarding cluster deployment status and rendered manifests, significantly enhancing the troubleshooting experience. + +[role="_additional-resources"] +.Additional resources + +* https://access.redhat.com/articles/7075493[Image-based installations for {sno}] + +* xref:../../installing/installing_on_prem_assisted/installing-on-prem-assisted.adoc#installing-on-prem-assisted[Installing an on-premise cluster using the {ai-full}] + +include::modules/cnf-understanding-siteconfig-operator-flow.adoc[leveloffset=+1] + +include::modules/cnf-clusterinstance-cr-reference.adoc[leveloffset=+1] + +include::modules/cnf-clusterinstance-cr-spec-config-parameters.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* xref:../../installing/installing_bare_metal_ipi/ipi-install-installation-workflow.adoc#bmc-addressing_ipi-install-installation-workflow[BMC addressing] + +include::modules/cnf-cluster-instance-cr-conditions-reference.adoc[leveloffset=+2] + +include::modules/cnf-understanding-cluster-templates.adoc[leveloffset=+1] + +include::modules/cnf-creating-custom-cluster-templates.adoc[leveloffset=+2] + +include::modules/cnf-deploying-siteconfig-operator.adoc[leveloffset=+1] + +include::modules/cnf-installing-clusters.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +[role="_additional-resources"] +.Additional resources + +* https://access.redhat.com/articles/7075493[Image-based installations for {sno}] + +* xref:../../installing/installing_on_prem_assisted/installing-on-prem-assisted.adoc#installing-on-prem-assisted[Installing an on-premise cluster using the {ai-full}] + +* xref::../../edge_computing/installing_with_siteconfig_operator/cnf-understanding-siteconfig-operator#cnf-clusterinstance-conditions-reference_siteconfig-operator[ClusterInstance CR conditions] + +include::modules/cnf-deprovisioning-clusters.adoc[leveloffset=+1] \ No newline at end of file diff --git a/edge_computing/installing_with_siteconfig_operator/images b/edge_computing/installing_with_siteconfig_operator/images new file mode 120000 index 000000000000..847b03ed0541 --- /dev/null +++ b/edge_computing/installing_with_siteconfig_operator/images @@ -0,0 +1 @@ +../../images/ \ No newline at end of file diff --git a/edge_computing/installing_with_siteconfig_operator/modules b/edge_computing/installing_with_siteconfig_operator/modules new file mode 120000 index 000000000000..36719b9de743 --- /dev/null +++ b/edge_computing/installing_with_siteconfig_operator/modules @@ -0,0 +1 @@ +../../modules/ \ No newline at end of file diff --git a/edge_computing/installing_with_siteconfig_operator/snippets b/edge_computing/installing_with_siteconfig_operator/snippets new file mode 120000 index 000000000000..5a3f5add140e --- /dev/null +++ b/edge_computing/installing_with_siteconfig_operator/snippets @@ -0,0 +1 @@ +../../snippets/ \ No newline at end of file diff --git a/images/siteconfig-operator-flow.png b/images/siteconfig-operator-flow.png new file mode 100644 index 000000000000..d6ddc72d20d8 Binary files /dev/null and b/images/siteconfig-operator-flow.png differ diff --git a/modules/cnf-cluster-instance-cr-conditions-reference.adoc b/modules/cnf-cluster-instance-cr-conditions-reference.adoc new file mode 100644 index 000000000000..4006b3acddc9 --- /dev/null +++ b/modules/cnf-cluster-instance-cr-conditions-reference.adoc @@ -0,0 +1,57 @@ +// Module included in the following assemblies: +// +// * edge_computing/installing_with_siteconfig_operator/cnf-understanding-siteconfig-operator.adoc + +:_mod-docs-content-type: REFERENCE +[id="cnf-clusterinstance-conditions-reference_{context}"] += ClusterInstance CR conditions + +The {sco} sets the status conditions in the `ClusterInstance` CR that you can use for monitoring and troubleshooting throughout the process. +While creating and validating the resources that are required for provisioning, you can encounter the following status conditions: + +.ClusterInstance CR status conditions +[cols="2", options="header"] +|==== + +|Condition +|Description + +|`ClusterInstanceValidated` +|Indicates that the {sco} validated the `ClusterInstance` `spec` fields and verified that the required artifacts, such as secrets and extra manifest `ConfigMaps` objects are present. + +|`RenderedTemplates` +|Indicates that {sco} successfully validated the referenced Golang cluster templates. + +|`RenderedTemplatesValidated` +|Indicates that the {sco} rendered the installation manifests and the dry run was successful. + +|`RenderedTemplatesApplied` +|Indicates that the {sco} created the installation manifests and the underlying Operators consumed them. + +|`Provisioned` +|Indicates that the underlying Operators are provisioning the clusters. + +|==== + +After starting the provisioning of a cluster, you can encounter the following deployment status conditions: + +.Cluster deployment status conditions +[cols="2", options="header"] +|==== + +|Condition +|Description + +|`ClusterInstallRequirementsMet` +|Indicates that the installation can start. + +|`ClusterInstallCompleted` +|Indicates that the cluster installation was successful. + +|`ClusterInstallFailed` +|Indicates that the cluster installation failed. + +|`ClusterInstallStopped` +|Indicates that the cluster installation stopped. + +|==== \ No newline at end of file diff --git a/modules/cnf-clusterinstance-cr-reference.adoc b/modules/cnf-clusterinstance-cr-reference.adoc new file mode 100644 index 000000000000..4c414f287f40 --- /dev/null +++ b/modules/cnf-clusterinstance-cr-reference.adoc @@ -0,0 +1,13 @@ + +// Module included in the following assemblies: +// +// * edge_computing/installing_with_siteconfig_operator/cnf-understanding-siteconfig-operator.adoc + +:_mod-docs-content-type: REFERENCE +[id="cnf-clusterinstance-CR-reference_{context}"] += Reference ClusterInstance CR + +The following example shows a `ClusterInstance` CR using the default Assisted Installer templates: + +include::snippets/cnf-clusterinstance-cr.adoc[] + diff --git a/modules/cnf-clusterinstance-cr-spec-config-parameters.adoc b/modules/cnf-clusterinstance-cr-spec-config-parameters.adoc new file mode 100644 index 000000000000..5e7ad0f65b53 --- /dev/null +++ b/modules/cnf-clusterinstance-cr-spec-config-parameters.adoc @@ -0,0 +1,226 @@ +// Module included in the following assemblies: +// +// * edge_computing/installing_with_siteconfig_operator/cnf-understanding-siteconfig-operator.adoc + +:_mod-docs-content-type: REFERENCE +[id="cnf-clusterinstance-config-reference_{context}"] += ClusterInstance CR configuration parameters + +You can specify the installation configurations by using following fields in the `ClusterInstance` CR: + +.ClusterInstance CR spec configuration parameters +[cols="3", options="header"] +|==== +|Field +|Required +|Description + +|`additionalNTPSources` +|No +a|Specify the NTP sources that needs to be added to all cluster hosts. +They are added to any NTP sources that were configured through other means. + +|`baseDomain` +|Yes +|Specify the base domain used for the deployed cluster. + +|`caBundleRef` +|No +|Reference the `ConfigMap` object that contains the new bundle of trusted certificates for the host. The `tls-ca-bundle.pem` entry in the `ConfigMap` object is written to `/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem`. + +|`clusterLabels` +|No +a|Configure cluster labels to correspond to the binding rules in the `PolicyGenerator` or `PolicyGenTemplate` CRs that you define. +`PolicyGenerator` CRs use the `policyDefaults.placement.labelSelector` field. +`PolicyGenTemplate` CRs use the `bindingRules` field. + +|`clusterName` +|Yes +|Specify name of the cluster. + +|`clusterNetwork` +|No +|Specify the list of the IP address pools for pods. + +|`clusterType` +|No +a|Specify the cluster type. +The following values are supported: + +`SNO`:: {sno} +`HighlyAvailable`:: Multi-node OpenShift +//check the official name for MNO + +|`cpuPartitioningMode` +|No +a|Determine clusters to be set up for CPU workload partitioning at install time. +Configure workload partitioning by setting the value for `cpuPartitioningMode` to `AllNodes`. +To complete the configuration, specify the `isolated` and `reserved` CPUs in the `PerformanceProfile` CR. +The default value is `None`. + +|`diskEncryption` +|No +|Enable or disable disk encryption for cluster + +|`extraAnnotations` +|No +|Specify additional cluster-level annotations to be applied to the rendered templates. + +|`extraManifestsRefs` +|No +|Specify the list of the `ConfigMap` object references that contain additional manifests to be applied to the cluster. + +|`holdInstallation` +|No +a|Set to `true` to prevent installation when using the Assisted Installer. +You can complete the inspection and validation steps, but after the `RequirementsMet` condition becomes `true`, the installation does not begin until the `holdInstallation` field is set to `false`. + +|`ignitionConfigOverride` +|No +|Specify the user overrides for the initial Ignition configuration. + +|`installConfigOverrides` +|No +|Define install configuration parameters. + +|`machineNetwork` +|No +|Specify the list of the IP address pools for machines. + +|`networkType` +|No +|Specify the Container Network Interface (CNI) plugin to install. The default value is `OpenShiftSDN` for IPv4, and `OVNKubernetes` for IPv6 or {sno} clusters. + +|`proxy` +|No +|Define the proxy settings used for the install configuration of the cluster. + +|`pullSecretRef` +|Yes +a|Configure the `pull-secret` CR for pulling images. +When creating the `pull-secret` CR, use the same namespace as the `ClusterInstance` CR that provisions the host. +//is it a CR? Isn't it an object where the kind is Secret? + +|`serviceNetwork` +|No +|Specify the list of the IP address pools for services. + +|`sshPublicKey` +|No +a|Specify the public Secure Shell (SSH) key to provide access to instances. +This key is added to the host to allow SSH access. + +|`suppressedManifests` +|No +|Specify a list of cluster-level manifests to exclude from the template rendering process. + +|`nodes` +|Yes +|Specify the configuration parameters for each node. + +|`templateRefs` +|Yes +a|Specify the list of the references to cluster-level templates. +A cluster-level template consists of a `ConfigMap` object, in which the keys of the data field represent the kind of the installation manifests. +Cluster-level templates are instantiated once per cluster in the `ClusterInstance` CR. +|==== + +.ClusterInstance CR spec.nodes configuration parameters +[cols="3", options="header"] +|==== + +|Field +|Required +|Description + +|`automatedCleaningMode` +|No +a|Set the value to `metadata` to enable the removal of the disk's partitioning table only, without fully wiping the disk. +The default value is `disabled`. + +|`bmcAddress` +|Yes +a|BMC address that you use to access the host. +Applies to all cluster types. +For more information about BMC addressing, see the "Additional resources" section. +[NOTE] +==== +In far edge Telco use cases, only virtual media is supported for use with {ztp}. +==== + +|`bmcCredentialsName` +|Yes +a|Configure 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 `ClusterInstance` CR that provisions the host. + +|`bootMACAddress` +|Yes +a|Specify the MAC address that PXE boots. +It is required for `libvirt` VMs driven by virtual BMC. + +|`bootMode` +|No +a|Set the boot mode for the host to `UEFI`. +The default value is `UEFI`. +Use `UEFISecureBoot` to enable secure boot on the host. +The following values are supported: + +* `UEFI` +* `UEFISecureBoot` +* `legacy` + +|`extraAnnotations` +|No +|Specify additional node-level annotations to be applied to the rendered templates. + +|`hostName` +|Yes +|Define the host name. + +|`installerArgs` +|No +|Specify the user overrides for the host's CoreOS installer arguments. + +|`ignitionConfigOverride` +|No +a|Specify the user overrides for the initial Ignition configuration. +Use this field to assign partitions for persistent storage. +Adjust disk ID and size to the specific hardware. + +|`ironicInspect` +|No +|Specify if automatic introspection runs during registration of the bare metal host. + +|`nodeLabels` +|No +a|Specify custom roles for your nodes in your managed clusters. +These are additional roles are not used by any {product-title} components, only by the user. +When you add a custom role, it can be associated with a custom machine config pool that references a specific configuration for that role. +Adding custom labels or roles during installation makes the deployment process more effective and prevents the need for additional reboots after the installation is complete. + +|`nodeNetwork` +|No +|Configure the network settings for the node. + +|`role` +|No +|Configure the role of the node, such as `master` or `worker`. + +|`rootDeviceHints` +|No +a|Specify the device for deployment. +Identifiers that are stable across reboots are recommended. +For example, `wwn: ` or `deviceName: /dev/disk/by-path/`. `` values are preferred. +For a detailed list of stable identifiers, see the "About root device hints" section. +You can also specify the name, model, size, or vendor of the device. + +|`suppressedManifests` +|No +|Specify a list of node-level manifests to exclude from the template rendering process. + +|`templateRefs` +|Yes +|Specify the list of the references to node-level templates. +A node-level template consists of a `ConfigMap` object, in which the keys of the data field represent the kind of the installation manifests. +Node-level templates are instantiated once for each node in the `ClusterInstance` CR. +|==== diff --git a/modules/cnf-creating-custom-cluster-templates.adoc b/modules/cnf-creating-custom-cluster-templates.adoc new file mode 100644 index 000000000000..046fc75ad62e --- /dev/null +++ b/modules/cnf-creating-custom-cluster-templates.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// Epic CNF-9657 (TELCODOCS-1540) (4.16) +// * edge_computing/cnf-understanding-siteconfig-operator.adoc + +:_mod-docs-content-type: CONCEPT +[id="cnf-creating-custom-cluster-templates_{context}"] += Creating custom cluster templates with the {sco} + +Create user-defined templates with the {sco}. +This example shows how you can create a template for etcd encryption. + +.Prerequisites +// Any? + +.Procedure + +. Create a YAML file, named `example-etcdencryptionsecret-cluster-template.yaml`, that contains the cluster-level template in a `ConfigMap` object: ++ +-- +include::snippets/siteconfig-etcdencryptionsecret-cluster-level.adoc[] +-- + +. Create the template on the hub cluster by running the following commands: ++ +[source,terminal] +---- +$ oc apply -f example-etcdencryptionsecret-cluster-template.yaml +---- + +. Reference your template in the `ClusterInstance` CR, named for example `clusterinstance-etcd.yaml`: ++ +[source,yaml] +---- +spec: + [...] + templateRefs: + - name: ai-cluster-templates-v1.yaml + namespace: siteconfig-operator + - name: example-etcdencryptionsecret-cluster-template.yaml + namespace: siteconfig-operator +---- + +. Create the `ClusterInstance` CR by running the following command: ++ +[source,terminal] +---- +$ oc apply -f clusterinstance-etcd.yaml +---- \ No newline at end of file diff --git a/modules/cnf-deploying-siteconfig-operator.adoc b/modules/cnf-deploying-siteconfig-operator.adoc new file mode 100644 index 000000000000..1379099b7c06 --- /dev/null +++ b/modules/cnf-deploying-siteconfig-operator.adoc @@ -0,0 +1,71 @@ +// Module included in the following assemblies: +// Epic CNF-9657 (TELCODOCS-1540) (4.16) +// * edge_computing/cnf-understanding-siteconfig-operator.adoc + +:_mod-docs-content-type: CONCEPT +[id="cnf-deploying-siteconfig-operator_{context}"] += Deploying the {sco} + +Deploy the {sco} on your hub cluster. + +.Prerequisites + +* You have logged in to the hub cluster as a user with cluster-admin privileges. +* You have installed the Make tool. +// What flavour of Make and min version? +//Anything else? + +.Procedure + +. Clone the {sco} Git repository by running the following command: ++ +[source,terminal] +---- +$ git clone git@github.com:stolostron/siteconfig.git +---- + +. Change to the `siteconfig` directory by running the following command: ++ +[source,terminal] +---- +$ cd siteconfig +---- + +. Define the `KUBECONFIG` file path for your hub cluster by running the following command: ++ +[source,terminal] +---- +$ export KUBECONFIG= +---- + +. Deploy the {sco} by running the following command: ++ +[source,terminal] +---- +$ make install deploy CONTAINER_TOOL=podman IMG=quay.io/acm-d/siteconfig:latest +---- + +.Verification + +. Confirm that the {sco} is running by running the following command: ++ +-- +[source,terminal] +---- +$ oc get pod -n siteconfig-operator +---- + +.Example output +[source,terminal] +---- +NAME READY STATUS RESTARTS AGE +siteconfig-controller-manager 2/2 Running 0 3h37m +---- +-- + +. Collect logs by running the following command: ++ +[source,terminal] +---- +$ oc logs -n siteconfig-operator --selector app.kubernetes.io/name=siteconfig-controller -c manager --follow --tail=-1 +---- \ No newline at end of file diff --git a/modules/cnf-deprovisioning-clusters.adoc b/modules/cnf-deprovisioning-clusters.adoc new file mode 100644 index 000000000000..eb516703956c --- /dev/null +++ b/modules/cnf-deprovisioning-clusters.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// Epic CNF-9657 (TELCODOCS-1540) (4.16) +// * edge_computing/cnf-understanding-siteconfig-operator.adoc + +:_mod-docs-content-type: CONCEPT +[id="cnf-deprovisioning-clusters_{context}"] += Deprovisioning {sno} clusters with the {sco} + +Delete your clusters with the {sco}. + +.Prerequisites + +* You have deployed your clusters with the {sco} by using the default cluster templates. + +.Procedure + +* Delete the `ClusterInstance` CR by running the following command: ++ +[source,terminal] +---- +$ oc delete clusterinstance -n +---- + +.Verification + +* Verify that the deletion was successful by running the following command: ++ +-- +[source,terminal] +---- +$ oc get clusterinstance -n +---- + +.Example output +[source,terminal] +---- +Error from server (NotFound): clusterinstances.siteconfig.open-cluster-management.io "" not found +---- +-- \ No newline at end of file diff --git a/modules/cnf-installing-clusters.adoc b/modules/cnf-installing-clusters.adoc new file mode 100644 index 000000000000..4530408bcc0e --- /dev/null +++ b/modules/cnf-installing-clusters.adoc @@ -0,0 +1,235 @@ +// Module included in the following assemblies: +// Epic CNF-9657 (TELCODOCS-1540) (4.16) +// * edge_computing/cnf-understanding-siteconfig-operator.adoc + +:_mod-docs-content-type: CONCEPT +[id="cnf-installing-clusters_{context}"] += Installing {sno} clusters with the {sco} + +Install your clusters with the {sco} by using the default cluster templates. +This example procedure uses the cluster templates for Image Based Install Operator. + +.Prerequisites + +* You have logged in to the hub cluster as a user with cluster-admin privileges. +* If using {ztp}, you have configured your {ztp} environment. +* You have the default cluster templates. +* You have installed and configured the underlying Operator of your choice. For more information, see "Image-based installations for {sno}" or "Installing an on-premise cluster using the {ai-full}" sections. + +.Procedure + +. Create your cluster and node templates for the Image-based Install Operator by running the following commands: ++ +-- +[source,terminal] +---- +$ oc apply -f ibi-cluster-templates-v1.yaml +---- + +[source,terminal] +---- +$ oc apply -f ibi-node-templates-v1.yaml +---- +-- + +. Create a YAML file, for example named `clusterinstance-namespace.yaml`, for the target namespace: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Namespace +metadata: + name: example-sno +---- + +.. Create the resource by running the following command on the hub cluster: ++ +[source,terminal] +---- +$ oc apply -f clusterinstance-namespace.yaml +---- + ++ +[IMPORTANT] +==== +The target namespace must be used when creating the pull secret, the BMC secret, extra manifest `ConfigMap` objects, and the `ClusterInstance` CR. +==== + +. Create a YAML file for pulling images, for example named `pull-secret.yaml`: ++ +-- +[source,yaml] +---- +apiVersion: v1 +kind: Secret +metadata: + name: pull-secret + namespace: example-sno <1> +data: + .dockerconfigjson: <2> +type: kubernetes.io/dockerconfigjson +---- +<1> The `namespace` value must match the target namespace. +<2> Specify the base64-encoded configuration file as the value. +-- + +.. Create the resource by running the following command on the hub cluster: ++ +[source,terminal] +---- +$ oc apply -f pull-secret.yaml +---- + +. Create a YAML file for the BMC secret, for example named `example-bmc-secret.yaml`: ++ +-- +[source,yaml] +---- +apiVersion: v1 +data: + password: + username: +kind: Secret +metadata: + name: example-bmh-secret + namespace: "example-sno" <1> +type: Opaque +---- +<1> The `namespace` value must match the target namespace. +-- + +.. Create the resource by running the following command on the hub cluster: ++ +[source,terminal] +---- +$ oc apply -f example-bmc-secret.yaml +---- + +. Create a YAML file for an extra manifest `ConfigMap` object, for example named `enable-crun.yaml`: ++ +-- +[source,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 +---- +<1> The `namespace` value must match the target namespace. +-- + +.. Create the resource by running the following command on the hub cluster: ++ +[source,terminal] +---- +$ oc apply -f enable-crun.yaml +---- + +. In the `example-sno` namespace, create the `ClusterInstance` CR, named for example `clusterinstance-ibi.yaml`, and reference your templates and supporting manifests: ++ +-- +[source,yaml] +---- +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> + [...] + templateRefs: <4> + - name: ibi-cluster-templates-v1 + namespace: siteconfig-operator + [...] + nodes: + [...] + bmcCredentialsName: <5> + name: "example-bmh-secret" + [...] + templateRefs: <6> + - name: ibi-node-templates-v1 + namespace: siteconfig-operator + [...] +---- +<1> The `namespace` in the `ClusterInstance` CR must match the target namespace that you defined. +<2> Reference the `name` of one or more extra manifests `ConfigMap` objects. +<3> Reference the `name` of your pull secret. +<4> Reference the `name` of the cluster-level templates under the `spec.templateRefs` field. The `namespace` must match the namespace where the Operator is installed. +<5> Reference the `name` of the BMC secret. +<6> Reference the `name` of the node-level templates under the `spec.nodes.templateRefs` field. The `namespace` must match the namespace where the Operator is installed. +-- + +.. Create the resource by running the following command: ++ +[source,terminal] +---- +$ oc apply -f clusterinstance-ibi.yaml +---- + + ++ +After creating the CR, the {sco} starts reconciling the `ClusterInstance` CR, then validates and renders the installation manifests. +The {sco} continues to monitor for changes in the `ClusterDeployment` CRs to update the cluster installation progress of the corresponding `ClusterInstance` CR. + + +.Verification + +. Monitor the process by running the following command: ++ +-- +[source,terminal] +---- +$ oc get clusterinstance -n -o yaml +---- + +.Example output from status.conditions section for successful manifest generation +[source,terminal] +---- +message: Applied site config manifests +reason: Completed +status: "True" +type: RenderedTemplatesApplied +---- + +For more information about status conditions, see "ClusterInstance CR conditions". +-- + +. Check the manifests that {sco} rendered by running the following command: ++ +[source,terminal] +---- +$ oc get clusterinstance -n -o jsonpath='{.status.manifestsRendered}' +---- + ++ +include::snippets/cnf-cluster-instance-cr-manifestrendered.adoc[] \ No newline at end of file diff --git a/modules/cnf-understanding-cluster-templates.adoc b/modules/cnf-understanding-cluster-templates.adoc new file mode 100644 index 000000000000..a6a5e9113ae8 --- /dev/null +++ b/modules/cnf-understanding-cluster-templates.adoc @@ -0,0 +1,110 @@ +// Module included in the following assemblies: +// Epic CNF-9657 (TELCODOCS-1540) (4.16) +// * edge_computing/cnf-understanding-siteconfig-operator.adoc + +:_mod-docs-content-type: CONCEPT +[id="cnf-understanding-cluster-templates_{context}"] += Understanding cluster templates + +Cluster templates are data-driven templates used to generate the set of installation artifacts. +These templates follow the Golang text/template format and they are instantiated by using data from the `ClusterInstance` CR. +This enables dynamic creation of installation manifests for each target cluster that has similar configurations but with different values. +You can also create multiple sets based on the different installation methods or cluster topologies. + +There are two types of cluster templates: + +* Cluster-level templates that must reference only cluster-specific fields. +* Node-level templates that can reference both cluster-specific and node-specific fields. + +You can customize the templated fields as the {sco} supports all link:https://masterminds.github.io/sprig/[sprig library functions]. +Additionally, it provides a new function that you can use while creating your custom manifests: + +`toYaml`:: The `toYaml` function encodes an item into a YAML string. If the item cannot be converted to YAML the function returns an empty string. + +.Using .toYaml in the ClusterInstance.Spec.Proxy field +[source,yaml] +---- +[...] +{{ if .Spec.Proxy }} + proxy: +{{ .Spec.Proxy | toYaml | indent 4 }} +{{ end }} +[...] +---- + +The {sco} provides the following default, validated, immutable set of templates in the same namespace in which the Operator is installed: + +.Default set of templates +[cols=3*, width="95%", options="header"] +|==== + +|Installation method +|Template type +|Template content + +.2+|Assisted Installer +a|Cluster-level templates + +(`ai-cluster-templates-v1.yaml`) +a|`AgentClusterInstall` + +`ClusterDeployment` + +`InfraEnv` + +`KlusterletAddonConfig` + +`ManagedCluster` + + +a|Node-level templates + +(`ai-node-templates-v1.yaml`) +a|`BareMetalHost` + +`NMStateConfig` + + +.2+|Image-based Install Operator +a|Cluster-level templates + +(`ibi-cluster-templates-v1.yaml`) +a|`ClusterDeployment` + +`KlusterletAddonConfig` + +`ManagedCluster` + + +a|Node-level templates + +(`ibi-node-templates-v1.yaml`) +a|`BareMetalHost` + +`ImageClusterInstall` + +`NetworkConfigMap` + +|==== + +[id="cnf-special-template-variable_{context}"] +== Special templates variables + +The {sco} provides a set of special template variables that you can use in your templates. + +`CurrentNode`:: The {sco} explicitly controls the iteration of the node objects and exposes this variable to access all the content for the current node being handled in templating. +`InstallConfigOverrides`:: This variable contains the merged `networkType`, `cpuPartitioningMode` and `installConfigOverrides` content. +`ControlPlaneAgents`:: This variable is automatically derived from the `ClusterInstance` node objects. It consists of the number of control plane agents. +`WorkerAgents`:: This variable is automatically derived from the `ClusterInstance` node objects. It consists of the number of worker agents. + +You can create a custom templated field by capitalizing the field name in the text template. +The `ClusterInstance` `spec` fields must be referenced with the `.Spec` prefix, except for `spec.nodes` fields for which you can use the `.SpecialVars.CurrentNode` special template variable. +Special variable fields must be referenced with the `.SpecialVars` prefix. +For example, if you want to specify the `name` and `namespace` for your current node by using the `CurrentNode` special template variable, use the field names in the following form: + +[source,yaml] +---- +name: "{{ .SpecialVars.CurrentNode.HostName }}" +namespace: "{{ .Spec.ClusterName }}" +---- + +[id="cnf-sync-wave-annotation_{context}"] +== Controlling the manifest order with the `siteconfig.open-cluster-management.io/sync-wave` annotation + +You can control the order in which manifests are created, updated, and deleted by using the `siteconfig.open-cluster-management.io/sync-wave` annotation. +The annotation takes an integer as a value and that integer constitutes as a wave. +You can add one or several manifests to a single wave. +If not specified for a resource, the annotation takes the default value of `0`. + +The {sco} reconciles the manifests in ascending order when creating or updating resources and it deletes resources in descending order. + +In the following example, if the {sco} creates or updated the manifests, the `AgentClusterInstall` and `ClusterDeployment` CRs are reconciled in the first wave, while `KlusterletAddonConfig` and `ManagedCluster` CRs are reconciled in the third wave. +If the {sco} deletes the resources, `KlusterletAddonConfig` and `ManagedCluster` CRs are the first to be deleted, while the `AgentClusterInstall` and `ClusterDeployment` CRs are the last. + +include::snippets/siteconfig-ai-cluster-templates-v1.adoc[] \ No newline at end of file diff --git a/modules/cnf-understanding-siteconfig-operator-flow.adoc b/modules/cnf-understanding-siteconfig-operator-flow.adoc new file mode 100644 index 000000000000..377d005ef08e --- /dev/null +++ b/modules/cnf-understanding-siteconfig-operator-flow.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// Epic CNF-9657 (TELCODOCS-1540) (4.16) +// * edge_computing/cnf-understanding-siteconfig-operator.adoc + +:_mod-docs-content-type: CONCEPT +[id="cnf-understanding-siteconfig-operator-flow_{context}"] += Understanding the {sco} flow + +The {sco} dynamically generates installation manifests based on user-defined cluster templates that are instantiated from the data in the `ClusterInstance` CR. +You can source the `ClusterInstance` CR from your Git repository through ArgoCD, or you can manually create it on the hub cluster directly or through external tools and workflows. + +As shown in Figure 1., the process involves the following steps: + +. Create one or more sets of cluster templates on the hub cluster. +. Create a `ClusterInstance` CR that references those cluster templates and supporting manifests. +. After the resources are created, the {sco} reconciles the `ClusterInstance` CR by populating the templated fields that are referenced in the CR. +. The {sco} validates and renders the installation manifests, then the Operator performs a dry run. +. If the dry run is successful, the manifests are created, then the underlying Operators consume and process the manifests. +. The installation begins. +. The {sco} continuously monitors for changes in the associated `ClusterDeployment` resource and updates the `ClusterInstance` CR's `status` field accordingly. + +.{sco} flow +image::siteconfig-operator-flow.png[{sco} flow] \ No newline at end of file diff --git a/snippets/cnf-cluster-instance-cr-manifestrendered.adoc b/snippets/cnf-cluster-instance-cr-manifestrendered.adoc new file mode 100644 index 000000000000..c46b510bcb37 --- /dev/null +++ b/snippets/cnf-cluster-instance-cr-manifestrendered.adoc @@ -0,0 +1,47 @@ +.Example manifestsRendered list +[source,yaml] +---- +status: + manifestsRendered: + - apiGroup: extensions.hive.openshift.io/v1beta1 + kind: ImageClusterInstall + lastAppliedTime: "2024-07-01T09:00:55Z" + name: example-cluster + namespace: example-cluster + status: rendered + syncWave: 1 + - apiGroup: metal3.io/v1alpha1 + kind: BareMetalHost + lastAppliedTime: "2024-07-01T09:00:55Z" + name: example-cluster.example.redhat.com + namespace: example-cluster + status: rendered + syncWave: 1 + - apiGroup: hive.openshift.io/v1 + kind: ClusterDeployment + lastAppliedTime: "2024-07-01T09:00:55Z" + name: example-cluster + namespace: example-cluster + status: rendered + syncWave: 1 + - apiGroup: v1 + kind: NetworkConfigMap + lastAppliedTime: "2024-07-01T09:00:55Z" + name: example-cluster.example.redhat.com + namespace: example-cluster + status: rendered + syncWave: 1 + - apiGroup: agent.open-cluster-management.io/v1 + kind: KlusterletAddonConfig + lastAppliedTime: "2024-07-01T09:00:55Z" + name: example-cluster + namespace: example-cluster + status: rendered + syncWave: 2 + - apiGroup: cluster.open-cluster-management.io/v1 + kind: ManagedCluster + lastAppliedTime: "2024-07-01T09:00:55Z" + name: example-cluster + status: rendered + syncWave: 2 +---- \ No newline at end of file diff --git a/snippets/cnf-clusterinstance-cr.adoc b/snippets/cnf-clusterinstance-cr.adoc new file mode 100644 index 000000000000..ac74a410d3cc --- /dev/null +++ b/snippets/cnf-clusterinstance-cr.adoc @@ -0,0 +1,56 @@ +.Reference ClusterInstance CR +[source,yaml] +---- +apiVersion: siteconfig.open-cluster-management.io/v1alpha1 +kind: ClusterInstance +metadata: + name: example-cluster + namespace: example-cluster +spec: + additionalNTPSources: + - + baseDomain: + clusterImageSetNameRef: + clusterLabels: + common: "true" + sites: example-cluster + clusterName: example-cluster + clusterNetwork: + - cidr: + hostPrefix: + cpuPartitioningMode: None + extraAnnotations: + ClusterDeployment: + myTestAnnotation: success + holdInstallation: false + installConfigOverrides: '' + machineNetwork: + - cidr: + networkType: OVNKubernetes + nodes: + - automatedCleaningMode: disabled + bmcAddress: + bmcCredentialsName: + name: + bootMACAddress: + bootMode: UEFI + hostName: example-cluster.example.redhat.com + ironicInspect: "" + nodeNetwork: + config: + + interfaces: + + role: master + templateRefs: + - name: ai-node-templates-v1 + namespace: siteconfig-operator + pullSecretRef: + name: pull-secret + serviceNetwork: + - cidr: + sshPublicKey: + templateRefs: + - name: ai-cluster-templates-v1 + namespace: siteconfig-operator +---- \ No newline at end of file diff --git a/snippets/siteconfig-ai-cluster-templates-v1.adoc b/snippets/siteconfig-ai-cluster-templates-v1.adoc new file mode 100644 index 000000000000..57d0396f1c86 --- /dev/null +++ b/snippets/siteconfig-ai-cluster-templates-v1.adoc @@ -0,0 +1,30 @@ +.Example node-level template for Assisted Installer +[source,yaml] +---- +apiVersion: v1 +data: + AgentClusterInstall: |- + [...] + siteconfig.open-cluster-management.io/sync-wave: "1" + [...] + ClusterDeployment: |- + [...] + siteconfig.open-cluster-management.io/sync-wave: "1" + [...] + InfraEnv: |- + [...] + siteconfig.open-cluster-management.io/sync-wave: "2" + [...] + KlusterletAddonConfig: |- + [...] + siteconfig.open-cluster-management.io/sync-wave: "3" + [...] + ManagedCluster: |- + [...] + siteconfig.open-cluster-management.io/sync-wave: "3" + [...] +kind: ConfigMap +metadata: + name: assisted-installer-templates + namespace: example-namespace +---- \ No newline at end of file diff --git a/snippets/siteconfig-etcdencryptionsecret-cluster-level.adoc b/snippets/siteconfig-etcdencryptionsecret-cluster-level.adoc new file mode 100644 index 000000000000..bf51fda59f9c --- /dev/null +++ b/snippets/siteconfig-etcdencryptionsecret-cluster-level.adoc @@ -0,0 +1,21 @@ +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: example-etcdencryptionsecret-cluster-template + namespace: siteconfig-operator +data: + EtcdEncryptionSecret: |- + apiVersion: v1 + kind: Secret + metadata: + name: "{{ .Site.ClusterName }}-etcd-encryption-key" + namespace: "clusters" + annotations: + siteconfig.open-cluster-management.io/sync-wave: "1" <1> + type: Opaque + data: + key: +---- +<1> The `siteconfig.open-cluster-management.io/sync-wave` annotation controls in which order manifests are created, updated, or deleted. \ No newline at end of file