From 397d06749cdacd746edab379c1dde85271ee4fd0 Mon Sep 17 00:00:00 2001 From: aireilly Date: Mon, 28 Nov 2022 14:36:45 +0000 Subject: [PATCH] updates for telcodocs-469 Updated based on @Missxiaoguo's suggestions updates changes for Angie --- .../ztp-example-hub-template-functions.adoc | 37 ++++++ ...lan-with-hub-cluster-templates-in-pgt.adoc | 74 +++++++++++ ...ztp-preparing-the-hub-cluster-for-ztp.adoc | 7 +- ...in-pgt-crs-with-hub-cluster-templates.adoc | 122 ++++++++++++++++++ ...configmap-changes-to-existing-pgt-crs.adoc | 75 +++++++++++ modules/ztp-using-hub-cluster-templates.adoc | 48 +++++++ .../ztp-advanced-policy-config.adoc | 15 +++ .../ztp-talm-updating-managed-policies.adoc | 4 +- 8 files changed, 379 insertions(+), 3 deletions(-) create mode 100644 modules/ztp-example-hub-template-functions.adoc create mode 100644 modules/ztp-managing-sriov-vlan-with-hub-cluster-templates-in-pgt.adoc create mode 100644 modules/ztp-specifying-nics-in-pgt-crs-with-hub-cluster-templates.adoc create mode 100644 modules/ztp-syncing-new-configmap-changes-to-existing-pgt-crs.adoc create mode 100644 modules/ztp-using-hub-cluster-templates.adoc diff --git a/modules/ztp-example-hub-template-functions.adoc b/modules/ztp-example-hub-template-functions.adoc new file mode 100644 index 0000000000..8023dacf7d --- /dev/null +++ b/modules/ztp-example-hub-template-functions.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc + +:_content-type: REFERENCE +[id="ztp-example-hub-template-functions_{context}"] += Example hub templates + +The following code examples are valid hub templates. Each of these templates return values from the `ConfigMap` CR with the name `test-config` in the `default` namespace. + +* Returns the value with the key `common-key`: ++ +[source,yaml] +---- +{{hub fromConfigMap "default" "test-config" "common-key" hub}} +---- + +* Returns a string by using the concatenated value of the `.ManagedClusterName` field and the string `-name`: ++ +[source,yaml] +---- +{{hub fromConfigMap "default" "test-config" (printf "%s-name" .ManagedClusterName) hub}} +---- + +* Casts and returns a boolean value from the concatenated value of the `.ManagedClusterName` field and the string `-name`: ++ +[source,yaml] +---- +{{hub fromConfigMap "default" "test-config" (printf "%s-name" .ManagedClusterName) | toBool hub}} +---- + +* Casts and returns an integer value from the concatenated value of the `.ManagedClusterName` field and the string `-name`: ++ +[source,yaml] +---- +{{hub (printf "%s-name" .ManagedClusterName) | fromConfigMap "default" "test-config" | toInt hub}} +---- diff --git a/modules/ztp-managing-sriov-vlan-with-hub-cluster-templates-in-pgt.adoc b/modules/ztp-managing-sriov-vlan-with-hub-cluster-templates-in-pgt.adoc new file mode 100644 index 0000000000..617c66c38f --- /dev/null +++ b/modules/ztp-managing-sriov-vlan-with-hub-cluster-templates-in-pgt.adoc @@ -0,0 +1,74 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc + +:_content-type: PROCEDURE +[id="ztp-managing-sriov-vlan-with-hub-cluster-templates-in-pgt_{context}"] += Specifying VLAN IDs in group PolicyGenTemplate CRs with hub cluster templates + +You can manage VLAN IDs for managed clusters in a single `ConfigMap` CR and use hub cluster templates to populate the VLAN IDs in the generated polices that get applied to the clusters. + +The following example shows how you how manage VLAN IDs in single `ConfigMap` CR and apply them in individual cluster polices by using a single `PolicyGenTemplate` group CR. + +[NOTE] +==== +When using the `fromConfigmap` function, the `printf` variable is only available for the template resource `data` key fields. +You cannot use it with `name` and `namespace` fields. +==== + +.Prerequisites + +* You have installed the OpenShift CLI (`oc`). + +* You have logged in to the hub cluster as a user with `cluster-admin` privileges. + +* You have created a Git repository where you manage your custom site configuration data. +The repository must be accessible from the hub cluster and be defined as a source repository for the Argo CD application. + +.Procedure + +. Create a `ConfigMap` CR that describes the VLAN IDs for a group of cluster hosts. For example: ++ +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: site-data + namespace: ztp-group + annotations: + argocd.argoproj.io/sync-options: Replace=true <1> +data: + site-1-vlan: "101" + site-2-vlan: "234" +---- +<1> The `argocd.argoproj.io/sync-options` annotation is required only if the `ConfigMap` is larger than 1 MiB in size. ++ +[NOTE] +==== +The `ConfigMap` must be in the same namespace with the policy that has the hub template substitution. +==== + +. Commit the `ConfigMap` CR in Git, and then push to the Git repository being monitored by the Argo CD application. + +. Create a group PGT CR that uses a hub template to pull the required VLAN IDs from the `ConfigMap` object. For example, add the following YAML snippet to the group PGT CR: ++ +[source,yaml] +---- +- fileName: SriovNetwork.yaml + policyName: "config-policy" + metadata: + name: "sriov-nw-du-mh" + annotations: + ran.openshift.io/ztp-deploy-wave: "10" + spec: + resourceName: du_mh + vlan: '{{hub fromConfigMap "" "site-data" (printf "%s-vlan" .ManagedClusterName) | toInt hub}}' +---- + +. Commit the group `PolicyGenTemplate` CR in Git, and then push to the Git repository being monitored by the Argo CD application. ++ +[NOTE] +==== +Subsequent changes to the referenced `ConfigMap` CR are not automatically synced to the applied policies. You need to manually sync the new `ConfigMap` changes to update existing PolicyGenTemplate CRs. See "Syncing new ConfigMap changes to existing PolicyGenTemplate CRs". +==== diff --git a/modules/ztp-preparing-the-hub-cluster-for-ztp.adoc b/modules/ztp-preparing-the-hub-cluster-for-ztp.adoc index c3541724e3..fc9fa7d1e9 100644 --- a/modules/ztp-preparing-the-hub-cluster-for-ztp.adoc +++ b/modules/ztp-preparing-the-hub-cluster-for-ztp.adoc @@ -6,7 +6,12 @@ [id="ztp-configuring-hub-cluster-with-argocd_{context}"] = Configuring the hub cluster with ArgoCD -You can configure your hub cluster with a set of ArgoCD applications that generate the required installation and policy custom resources (CR) for each site based on a zero touch provisioning (ZTP) GitOps flow. +You can configure the hub cluster with a set of ArgoCD applications that generate the required installation and policy custom resources (CRs) for each site with GitOps zero touch provisioning (ZTP). + +[NOTE] +==== +{rh-rhacm-first} uses `SiteConfig` CRs to generate the Day 1 managed cluster installation CRs for ArgoCD. Each ArgoCD application can manage a maximum of 300 `SiteConfig` CRs. +==== .Prerequisites diff --git a/modules/ztp-specifying-nics-in-pgt-crs-with-hub-cluster-templates.adoc b/modules/ztp-specifying-nics-in-pgt-crs-with-hub-cluster-templates.adoc new file mode 100644 index 0000000000..02ae92fd09 --- /dev/null +++ b/modules/ztp-specifying-nics-in-pgt-crs-with-hub-cluster-templates.adoc @@ -0,0 +1,122 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc + +:_content-type: PROCEDURE +[id="ztp-specifying-nics-in-pgt-crs-with-hub-cluster-templates_{context}"] += Specifying host NICs in site PolicyGenTemplate CRs with hub cluster templates + +You can manage host NICs in a single `ConfigMap` CR and use hub cluster templates to populate the custom NIC values in the generated polices that get applied to the cluster hosts. +Using hub cluster templates in site `PolicyGenTemplate` (PGT) CRs means that you do not need to create multiple single site PGT CRs for each site. + +The following example shows you how to use a single `ConfigMap` CR to manage cluster host NICs and apply them to the cluster as polices by using a single `PolicyGenTemplate` site CR. + +[NOTE] +==== +When you use the `fromConfigmap` function, the `printf` variable is only available for the template resource `data` key fields. You cannot use it with `name` and `namespace` fields. +==== + +.Prerequisites + +* You have installed the OpenShift CLI (`oc`). + +* You have logged in to the hub cluster as a user with `cluster-admin` privileges. + +* You have created a Git repository where you manage your custom site configuration data. +The repository must be accessible from the hub cluster and be defined as a source repository for the GitOps ZTP ArgoCD application. + +.Procedure + +. Create a `ConfigMap` resource that describes the NICs for a group of hosts. For example: ++ +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: sriovdata + namespace: ztp-site + annotations: + argocd.argoproj.io/sync-options: Replace=true <1> +data: + example-sno-du_fh-numVfs: "8" + example-sno-du_fh-pf: ens1f0 + example-sno-du_fh-priority: "10" + example-sno-du_fh-vlan: "140" + example-sno-du_mh-numVfs: "8" + example-sno-du_mh-pf: ens3f0 + example-sno-du_mh-priority: "10" + example-sno-du_mh-vlan: "150" +---- +<1> The `argocd.argoproj.io/sync-options` annotation is required only if the `ConfigMap` is larger than 1 MiB in size. ++ +[NOTE] +==== +The `ConfigMap` must be in the same namespace with the policy that has the hub template substitution. +==== + +. Commit the `ConfigMap` CR in Git, and then push to the Git repository being monitored by the Argo CD application. + +. Create a site PGT CR that uses templates to pull the required data from the `ConfigMap` object. For example: ++ +[source,yaml] +---- +apiVersion: ran.openshift.io/v1 +kind: PolicyGenTemplate +metadata: + name: "site" + namespace: "ztp-site" +spec: + remediationAction: inform + bindingRules: + group-du-sno: "" + mcp: "master" + sourceFiles: + - fileName: SriovNetwork.yaml + policyName: "config-policy" + metadata: + name: "sriov-nw-du-fh" + spec: + resourceName: du_fh + vlan: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_fh-vlan" .ManagedClusterName) | toInt hub}}' + - fileName: SriovNetworkNodePolicy.yaml + policyName: "config-policy" + metadata: + name: "sriov-nnp-du-fh" + spec: + deviceType: netdevice + isRdma: true + nicSelector: + pfNames: + - '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_fh-pf" .ManagedClusterName) | autoindent hub}}' + numVfs: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_fh-numVfs" .ManagedClusterName) | toInt hub}}' + priority: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_fh-priority" .ManagedClusterName) | toInt hub}}' + resourceName: du_fh + - fileName: SriovNetwork.yaml + policyName: "config-policy" + metadata: + name: "sriov-nw-du-mh" + spec: + resourceName: du_mh + vlan: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_mh-vlan" .ManagedClusterName) | toInt hub}}' + - fileName: SriovNetworkNodePolicy.yaml + policyName: "config-policy" + metadata: + name: "sriov-nnp-du-mh" + spec: + deviceType: vfio-pci + isRdma: false + nicSelector: + pfNames: + - '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_mh-pf" .ManagedClusterName) hub}}' + numVfs: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_mh-numVfs" .ManagedClusterName) | toInt hub}}' + priority: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_mh-priority" .ManagedClusterName) | toInt hub}}' + resourceName: du_mh +---- + +. Commit the site `PolicyGenTemplate` CR in Git and push to the Git repository that is monitored by the ArgoCD application. ++ +[NOTE] +==== +Subsequent changes to the referenced `ConfigMap` CR are not automatically synced to the applied policies. You need to manually sync the new `ConfigMap` changes to update existing PolicyGenTemplate CRs. See "Syncing new ConfigMap changes to existing PolicyGenTemplate CRs". +==== diff --git a/modules/ztp-syncing-new-configmap-changes-to-existing-pgt-crs.adoc b/modules/ztp-syncing-new-configmap-changes-to-existing-pgt-crs.adoc new file mode 100644 index 0000000000..de2dc4b977 --- /dev/null +++ b/modules/ztp-syncing-new-configmap-changes-to-existing-pgt-crs.adoc @@ -0,0 +1,75 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc + +:_content-type: PROCEDURE +[id="ztp-syncing-new-configmap-changes-to-existing-pgt-crs_{context}"] += Syncing new ConfigMap changes to existing PolicyGenTemplate CRs + +.Prerequisites + +* You have installed the OpenShift CLI (`oc`). + +* You have logged in to the hub cluster as a user with `cluster-admin` privileges. + +* You have created a `PolicyGenTemplate` CR that pulls information from a `ConfigMap` CR using hub cluster templates. + +.Procedure + +. Update the contents of your `ConfigMap` CR, and apply the changes in the hub cluster. + +. To sync the contents of the updated `ConfigMap` CR to the deployed policy, do either of the following: + +.. Option 1: Delete the existing policy. ArgoCD uses the `PolicyGenTemplate` CR to immediately recreate the deleted policy. For example, run the following command: ++ +[source,terminal] +---- +$ oc delete policy -n +---- + +.. Option 2: Apply a special annotation `policy.open-cluster-management.io/trigger-update` to the policy with a different value every time when you update the `ConfigMap`. For example: ++ +[source,terminal] +---- +$ oc annotate policy -n policy.open-cluster-management.io/trigger-update="1" +---- ++ +[NOTE] +==== +You must apply the updated policy for the changes to take effect. For more information, see link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.6/html-single/governance/index#special-annotation-processing[Special annotation for reprocessing]. +==== + +. Optional: If it exists, delete the `ClusterGroupUpdate` CR that contains the policy. For example: ++ +[source,terminal] +---- +$ oc delete clustergroupupgrade -n +---- + +.. Create a new `ClusterGroupUpdate` CR that includes the policy to apply with the updated `ConfigMap` changes. For example, add the following YAML to the file `cgr-example.yaml`: ++ +[source,yaml] +---- +apiVersion: ran.openshift.io/v1alpha1 +kind: ClusterGroupUpgrade +metadata: + name: + namespace: +spec: + managedPolicies: + - + enable: true + clusters: + - + - + remediationStrategy: + maxConcurrency: 2 + timeout: 240 +---- + +.. Apply the updated policy: ++ +[source,terminal] +---- +$ oc apply -f cgr-example.yaml +---- diff --git a/modules/ztp-using-hub-cluster-templates.adoc b/modules/ztp-using-hub-cluster-templates.adoc new file mode 100644 index 0000000000..8c065475c5 --- /dev/null +++ b/modules/ztp-using-hub-cluster-templates.adoc @@ -0,0 +1,48 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc + +:_content-type: CONCEPT +[id="ztp-using-hub-cluster-templates_{context}"] += Using hub templates in PolicyGenTemplate CRs + +{cgu-operator-full} supports partial {rh-rhacm-first} hub cluster template functions in configuration policies used with GitOps ZTP. + +Hub-side cluster templates allow you to define configuration policies that can be dynamically customized to the target clusters. +This reduces the need to create separate policies for many clusters with similiar configurations but with different values. + +[IMPORTANT] +==== +Policy templates are restricted to the same namespace as the namespace where the policy is defined. +This means that you must create the objects referenced in the hub template in the same namespace where the policy is created. +==== + +The following supported hub template functions are available for use in GitOps ZTP with {cgu-operator}: + +* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.6/html-single/governance/index#fromConfigmap-func[`fromConfigmap`] returns the value of the provided data key in the named `ConfigMap` resource. ++ +[NOTE] +==== +There is a link:https://kubernetes.io/docs/concepts/configuration/configmap/#motivation[1 MiB size limit] for `ConfigMap` CRs. +The effective size for `ConfigMap` CRs is further limited by the `last-applied-configuration` annotation. +To avoid the `last-applied-configuration` limitation, add the following annotation to the template `ConfigMap`: + +[source,yaml] +---- +argocd.argoproj.io/sync-options: Replace=true +---- +==== + +* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.6/html-single/governance/index#base64enc-func[`base64enc`] returns the base64-encoded value of the input string + +* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.6/html-single/governance/index#base64dec-func[`base64dec`] returns the decoded value of the base64-encoded input string + +* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.6/html-single/governance/index#indent-function[`indent`] returns the input string with added indent spaces + +* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.6/html-single/governance/index#autoindent-function[`autoindent`] returns the input string with added indent spaces based on the spacing used in the parent template + +* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.6/html-single/governance/index#toInt-function[`toInt`] casts and returns the integer value of the input value + +* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.6/html-single/governance/index#toBool-function[`toBool`] converts the input string into a boolean value, and returns the boolean + +Various link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.6/html-single/governance/index#open-source-community-functions[Open source community functions] are also available for use with GitOps ZTP. diff --git a/scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc b/scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc index c44ed01999..dddf975e82 100644 --- a/scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc +++ b/scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc @@ -67,3 +67,18 @@ include::modules/ztp-configuring-hwevents-using-pgt.adoc[leveloffset=+1] .Additional resources * For more information about how to create the username, password, and host IP address for the BMC secret, see xref:../../monitoring/using-rfhe.adoc#nw-rfhe-creating-hardware-event_using-rfhe[Creating the bare-metal event and Secret CRs]. + +include::modules/ztp-using-hub-cluster-templates.adoc[leveloffset=+1] + +[role="_additional-resources"] +.Additional resources + +* link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/{rh-rhacm-version}/html-single/governance/index#hub-templates[{rh-rhacm} support for hub cluster templates in configuration policies] + +include::modules/ztp-example-hub-template-functions.adoc[leveloffset=+2] + +include::modules/ztp-specifying-nics-in-pgt-crs-with-hub-cluster-templates.adoc[leveloffset=+2] + +include::modules/ztp-managing-sriov-vlan-with-hub-cluster-templates-in-pgt.adoc[leveloffset=+2] + +include::modules/ztp-syncing-new-configmap-changes-to-existing-pgt-crs.adoc[leveloffset=+2] diff --git a/scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc b/scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc index 5d83e69004..e627522eb1 100644 --- a/scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc +++ b/scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc @@ -28,14 +28,14 @@ include::modules/cnf-topology-aware-lifecycle-manager-preparing-for-updates.adoc * For more information about how to prepare the disconnected environment and mirroring the desired image repository, see xref:../../scalability_and_performance/ztp_far_edge/ztp-preparing-the-hub-cluster.adoc#ztp-preparing-the-hub-cluster[Preparing the disconnected environment]. -* For more information about update channels and releases, see xref:../../updating/understanding-upgrade-channels-release.adoc[Understanding upgrade channels and releases]. +* For more information about update channels and releases, see xref:../../updating/understanding-upgrade-channels-release.adoc#understanding-upgrade-channels-releases[Understanding upgrade channels and releases]. include::modules/cnf-topology-aware-lifecycle-manager-platform-update.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources -* For more information about mirroring the images in a disconnected environment, see xref:../../scalability_and_performance/ztp_far_edge/ztp-preparing-the-hub-cluster.adoc#ztp-acm-adding-images-to-mirror-registry_ztp-preparing-the-hub-cluster[Preparing the disconnected environment] +* For more information about mirroring the images in a disconnected environment, see xref:../../scalability_and_performance/ztp_far_edge/ztp-preparing-the-hub-cluster.adoc#ztp-acm-adding-images-to-mirror-registry_ztp-preparing-the-hub-cluster[Preparing the disconnected environment]. include::modules/cnf-topology-aware-lifecycle-manager-operator-update.adoc[leveloffset=+2]