Skip to content

Commit f141823

Browse files
jab-rhjab-rh
authored
Merge pull request #53209 from aireilly/telcodocs-469
TELCODOCS-469 - Document GitOps ZTP specifics of hub-side CR templating
2 parents e532fb2 + 588795e commit f141823

8 files changed

+379
-3
lines changed

‎modules/ztp-example-hub-template-functions.adoc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc
4+
5+
:_content-type: REFERENCE
6+
[id="ztp-example-hub-template-functions_{context}"]
7+
= Example hub templates
8+
9+
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.
10+
11+
* Returns the value with the key `common-key`:
12+
+
13+
[source,yaml]
14+
----
15+
{{hub fromConfigMap "default" "test-config" "common-key" hub}}
16+
----
17+
18+
* Returns a string by using the concatenated value of the `.ManagedClusterName` field and the string `-name`:
19+
+
20+
[source,yaml]
21+
----
22+
{{hub fromConfigMap "default" "test-config" (printf "%s-name" .ManagedClusterName) hub}}
23+
----
24+
25+
* Casts and returns a boolean value from the concatenated value of the `.ManagedClusterName` field and the string `-name`:
26+
+
27+
[source,yaml]
28+
----
29+
{{hub fromConfigMap "default" "test-config" (printf "%s-name" .ManagedClusterName) | toBool hub}}
30+
----
31+
32+
* Casts and returns an integer value from the concatenated value of the `.ManagedClusterName` field and the string `-name`:
33+
+
34+
[source,yaml]
35+
----
36+
{{hub (printf "%s-name" .ManagedClusterName) | fromConfigMap "default" "test-config" | toInt hub}}
37+
----

‎modules/ztp-managing-sriov-vlan-with-hub-cluster-templates-in-pgt.adoc

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="ztp-managing-sriov-vlan-with-hub-cluster-templates-in-pgt_{context}"]
7+
= Specifying VLAN IDs in group PolicyGenTemplate CRs with hub cluster templates
8+
9+
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.
10+
11+
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.
12+
13+
[NOTE]
14+
====
15+
When using the `fromConfigmap` function, the `printf` variable is only available for the template resource `data` key fields.
16+
You cannot use it with `name` and `namespace` fields.
17+
====
18+
19+
.Prerequisites
20+
21+
* You have installed the OpenShift CLI (`oc`).
22+
23+
* You have logged in to the hub cluster as a user with `cluster-admin` privileges.
24+
25+
* You have created a Git repository where you manage your custom site configuration data.
26+
The repository must be accessible from the hub cluster and be defined as a source repository for the Argo CD application.
27+
28+
.Procedure
29+
30+
. Create a `ConfigMap` CR that describes the VLAN IDs for a group of cluster hosts. For example:
31+
+
32+
[source,yaml]
33+
----
34+
apiVersion: v1
35+
kind: ConfigMap
36+
metadata:
37+
name: site-data
38+
namespace: ztp-group
39+
annotations:
40+
argocd.argoproj.io/sync-options: Replace=true <1>
41+
data:
42+
site-1-vlan: "101"
43+
site-2-vlan: "234"
44+
----
45+
<1> The `argocd.argoproj.io/sync-options` annotation is required only if the `ConfigMap` is larger than 1 MiB in size.
46+
+
47+
[NOTE]
48+
====
49+
The `ConfigMap` must be in the same namespace with the policy that has the hub template substitution.
50+
====
51+
52+
. Commit the `ConfigMap` CR in Git, and then push to the Git repository being monitored by the Argo CD application.
53+
54+
. 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:
55+
+
56+
[source,yaml]
57+
----
58+
- fileName: SriovNetwork.yaml
59+
policyName: "config-policy"
60+
metadata:
61+
name: "sriov-nw-du-mh"
62+
annotations:
63+
ran.openshift.io/ztp-deploy-wave: "10"
64+
spec:
65+
resourceName: du_mh
66+
vlan: '{{hub fromConfigMap "" "site-data" (printf "%s-vlan" .ManagedClusterName) | toInt hub}}'
67+
----
68+
69+
. Commit the group `PolicyGenTemplate` CR in Git, and then push to the Git repository being monitored by the Argo CD application.
70+
+
71+
[NOTE]
72+
====
73+
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".
74+
====

‎modules/ztp-preparing-the-hub-cluster-for-ztp.adoc

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,12 @@
66
[id="ztp-configuring-hub-cluster-with-argocd_{context}"]
77
= Configuring the hub cluster with ArgoCD
88

9-
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.
9+
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).
10+
11+
[NOTE]
12+
====
13+
{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.
14+
====
1015

1116
.Prerequisites
1217

‎modules/ztp-specifying-nics-in-pgt-crs-with-hub-cluster-templates.adoc

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="ztp-specifying-nics-in-pgt-crs-with-hub-cluster-templates_{context}"]
7+
= Specifying host NICs in site PolicyGenTemplate CRs with hub cluster templates
8+
9+
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.
10+
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.
11+
12+
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.
13+
14+
[NOTE]
15+
====
16+
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.
17+
====
18+
19+
.Prerequisites
20+
21+
* You have installed the OpenShift CLI (`oc`).
22+
23+
* You have logged in to the hub cluster as a user with `cluster-admin` privileges.
24+
25+
* You have created a Git repository where you manage your custom site configuration data.
26+
The repository must be accessible from the hub cluster and be defined as a source repository for the GitOps ZTP ArgoCD application.
27+
28+
.Procedure
29+
30+
. Create a `ConfigMap` resource that describes the NICs for a group of hosts. For example:
31+
+
32+
[source,yaml]
33+
----
34+
apiVersion: v1
35+
kind: ConfigMap
36+
metadata:
37+
name: sriovdata
38+
namespace: ztp-site
39+
annotations:
40+
argocd.argoproj.io/sync-options: Replace=true <1>
41+
data:
42+
example-sno-du_fh-numVfs: "8"
43+
example-sno-du_fh-pf: ens1f0
44+
example-sno-du_fh-priority: "10"
45+
example-sno-du_fh-vlan: "140"
46+
example-sno-du_mh-numVfs: "8"
47+
example-sno-du_mh-pf: ens3f0
48+
example-sno-du_mh-priority: "10"
49+
example-sno-du_mh-vlan: "150"
50+
----
51+
<1> The `argocd.argoproj.io/sync-options` annotation is required only if the `ConfigMap` is larger than 1 MiB in size.
52+
+
53+
[NOTE]
54+
====
55+
The `ConfigMap` must be in the same namespace with the policy that has the hub template substitution.
56+
====
57+
58+
. Commit the `ConfigMap` CR in Git, and then push to the Git repository being monitored by the Argo CD application.
59+
60+
. Create a site PGT CR that uses templates to pull the required data from the `ConfigMap` object. For example:
61+
+
62+
[source,yaml]
63+
----
64+
apiVersion: ran.openshift.io/v1
65+
kind: PolicyGenTemplate
66+
metadata:
67+
name: "site"
68+
namespace: "ztp-site"
69+
spec:
70+
remediationAction: inform
71+
bindingRules:
72+
group-du-sno: ""
73+
mcp: "master"
74+
sourceFiles:
75+
- fileName: SriovNetwork.yaml
76+
policyName: "config-policy"
77+
metadata:
78+
name: "sriov-nw-du-fh"
79+
spec:
80+
resourceName: du_fh
81+
vlan: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_fh-vlan" .ManagedClusterName) | toInt hub}}'
82+
- fileName: SriovNetworkNodePolicy.yaml
83+
policyName: "config-policy"
84+
metadata:
85+
name: "sriov-nnp-du-fh"
86+
spec:
87+
deviceType: netdevice
88+
isRdma: true
89+
nicSelector:
90+
pfNames:
91+
- '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_fh-pf" .ManagedClusterName) | autoindent hub}}'
92+
numVfs: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_fh-numVfs" .ManagedClusterName) | toInt hub}}'
93+
priority: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_fh-priority" .ManagedClusterName) | toInt hub}}'
94+
resourceName: du_fh
95+
- fileName: SriovNetwork.yaml
96+
policyName: "config-policy"
97+
metadata:
98+
name: "sriov-nw-du-mh"
99+
spec:
100+
resourceName: du_mh
101+
vlan: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_mh-vlan" .ManagedClusterName) | toInt hub}}'
102+
- fileName: SriovNetworkNodePolicy.yaml
103+
policyName: "config-policy"
104+
metadata:
105+
name: "sriov-nnp-du-mh"
106+
spec:
107+
deviceType: vfio-pci
108+
isRdma: false
109+
nicSelector:
110+
pfNames:
111+
- '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_mh-pf" .ManagedClusterName) hub}}'
112+
numVfs: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_mh-numVfs" .ManagedClusterName) | toInt hub}}'
113+
priority: '{{hub fromConfigMap "ztp-site" "sriovdata" (printf "%s-du_mh-priority" .ManagedClusterName) | toInt hub}}'
114+
resourceName: du_mh
115+
----
116+
117+
. Commit the site `PolicyGenTemplate` CR in Git and push to the Git repository that is monitored by the ArgoCD application.
118+
+
119+
[NOTE]
120+
====
121+
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".
122+
====

‎modules/ztp-syncing-new-configmap-changes-to-existing-pgt-crs.adoc

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="ztp-syncing-new-configmap-changes-to-existing-pgt-crs_{context}"]
7+
= Syncing new ConfigMap changes to existing PolicyGenTemplate CRs
8+
9+
.Prerequisites
10+
11+
* You have installed the OpenShift CLI (`oc`).
12+
13+
* You have logged in to the hub cluster as a user with `cluster-admin` privileges.
14+
15+
* You have created a `PolicyGenTemplate` CR that pulls information from a `ConfigMap` CR using hub cluster templates.
16+
17+
.Procedure
18+
19+
. Update the contents of your `ConfigMap` CR, and apply the changes in the hub cluster.
20+
21+
. To sync the contents of the updated `ConfigMap` CR to the deployed policy, do either of the following:
22+
23+
.. Option 1: Delete the existing policy. ArgoCD uses the `PolicyGenTemplate` CR to immediately recreate the deleted policy. For example, run the following command:
24+
+
25+
[source,terminal]
26+
----
27+
$ oc delete policy <policy_name> -n <policy_namespace>
28+
----
29+
30+
.. 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:
31+
+
32+
[source,terminal]
33+
----
34+
$ oc annotate policy <policy_name> -n <policy_namespace> policy.open-cluster-management.io/trigger-update="1"
35+
----
36+
+
37+
[NOTE]
38+
====
39+
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].
40+
====
41+
42+
. Optional: If it exists, delete the `ClusterGroupUpdate` CR that contains the policy. For example:
43+
+
44+
[source,terminal]
45+
----
46+
$ oc delete clustergroupupgrade <cgu_name> -n <cgu_namespace>
47+
----
48+
49+
.. 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`:
50+
+
51+
[source,yaml]
52+
----
53+
apiVersion: ran.openshift.io/v1alpha1
54+
kind: ClusterGroupUpgrade
55+
metadata:
56+
name: <cgr_name>
57+
namespace: <policy_namespace>
58+
spec:
59+
managedPolicies:
60+
- <managed_policy>
61+
enable: true
62+
clusters:
63+
- <managed_cluster_1>
64+
- <managed_cluster_2>
65+
remediationStrategy:
66+
maxConcurrency: 2
67+
timeout: 240
68+
----
69+
70+
.. Apply the updated policy:
71+
+
72+
[source,terminal]
73+
----
74+
$ oc apply -f cgr-example.yaml
75+
----

‎modules/ztp-using-hub-cluster-templates.adoc

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="ztp-using-hub-cluster-templates_{context}"]
7+
= Using hub templates in PolicyGenTemplate CRs
8+
9+
{cgu-operator-full} supports partial {rh-rhacm-first} hub cluster template functions in configuration policies used with GitOps ZTP.
10+
11+
Hub-side cluster templates allow you to define configuration policies that can be dynamically customized to the target clusters.
12+
This reduces the need to create separate policies for many clusters with similiar configurations but with different values.
13+
14+
[IMPORTANT]
15+
====
16+
Policy templates are restricted to the same namespace as the namespace where the policy is defined.
17+
This means that you must create the objects referenced in the hub template in the same namespace where the policy is created.
18+
====
19+
20+
The following supported hub template functions are available for use in GitOps ZTP with {cgu-operator}:
21+
22+
* 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.
23+
+
24+
[NOTE]
25+
====
26+
There is a link:https://kubernetes.io/docs/concepts/configuration/configmap/#motivation[1 MiB size limit] for `ConfigMap` CRs.
27+
The effective size for `ConfigMap` CRs is further limited by the `last-applied-configuration` annotation.
28+
To avoid the `last-applied-configuration` limitation, add the following annotation to the template `ConfigMap`:
29+
30+
[source,yaml]
31+
----
32+
argocd.argoproj.io/sync-options: Replace=true
33+
----
34+
====
35+
36+
* 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
37+
38+
* 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
39+
40+
* 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
41+
42+
* 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
43+
44+
* 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
45+
46+
* 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
47+
48+
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.

‎scalability_and_performance/ztp_far_edge/ztp-advanced-policy-config.adoc

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,3 +67,18 @@ include::modules/ztp-configuring-hwevents-using-pgt.adoc[leveloffset=+1]
6767
.Additional resources
6868

6969
* 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].
70+
71+
include::modules/ztp-using-hub-cluster-templates.adoc[leveloffset=+1]
72+
73+
[role="_additional-resources"]
74+
.Additional resources
75+
76+
* 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]
77+
78+
include::modules/ztp-example-hub-template-functions.adoc[leveloffset=+2]
79+
80+
include::modules/ztp-specifying-nics-in-pgt-crs-with-hub-cluster-templates.adoc[leveloffset=+2]
81+
82+
include::modules/ztp-managing-sriov-vlan-with-hub-cluster-templates-in-pgt.adoc[leveloffset=+2]
83+
84+
include::modules/ztp-syncing-new-configmap-changes-to-existing-pgt-crs.adoc[leveloffset=+2]

0 commit comments

Comments
 (0)