Skip to content

Commit b75cc73

Browse files
jab-rhjab-rh
authored
Merge pull request openshift#63133 from slovern/TELCODOCS-1214
TELCODOCS-1214 - CNF-7365 GitOps ZTP independence from deployed clust…
2 parents cc48cd8 + dcec2dd commit b75cc73

5 files changed

+188
-14
lines changed

‎modules/ztp-customizing-the-install-extra-manifests.adoc

+31-7
Original file line numberDiff line numberDiff line change
@@ -16,29 +16,53 @@ You can define a set of extra manifests for inclusion in the installation phase
1616

1717
. Create a set of extra manifest CRs that the {ztp} pipeline uses to customize the cluster installs.
1818

19-
. In your custom `/siteconfig` directory, create an `/extra-manifest` folder for your extra manifests. The following example illustrates a sample `/siteconfig` with `/extra-manifest` folder:
19+
. In your custom `/siteconfig` directory, create a subdirectory `/custom-manifest` for your extra manifests. The following example illustrates a sample `/siteconfig` with `/custom-manifest` folder:
2020
+
2121
[source,text]
2222
----
2323
siteconfig
2424
├── site1-sno-du.yaml
2525
├── site2-standard-du.yaml
26-
└── extra-manifest
26+
├── extra-manifest/
27+
└── custom-manifest
2728
└── 01-example-machine-config.yaml
2829
----
30+
+
31+
[NOTE]
32+
====
33+
The subdirectory names `/custom-manifest` and `/extra-manifest` used throughout are example names only. There is no requirement to use these names and no restriction on how you name these subdirectories.
34+
In this example `/extra-manifest` refers to the Git subdirectory that stores the contents of `/extra-manifest` from the `ztp-site-generate` container.
35+
====
2936

30-
. Add your custom extra manifest CRs to the `siteconfig/extra-manifest` directory.
37+
. Add your custom extra manifest CRs to the `siteconfig/custom-manifest` directory.
3138

32-
. In your `SiteConfig` CR, enter the directory name in the `extraManifestPath` field, for example:
39+
. In your `SiteConfig` CR, enter the directory name in the `extraManifests.searchPaths` field, for example:
3340
+
3441
[source,yaml]
3542
----
3643
clusters:
3744
- clusterName: "example-sno"
3845
networkType: "OVNKubernetes"
39-
extraManifestPath: extra-manifest
46+
extraManifests:
47+
searchPaths:
48+
- extra-manifest/ <1>
49+
- custom-manifest/ <2>
4050
----
51+
<1> Folder for manifests copied from the `ztp-site-generate` container.
52+
<2> Folder for custom manifests.
53+
54+
. Save the `SiteConfig`, `/extra-manifest`, and `/custom-manifest` CRs, and push them to the site configuration repo.
55+
56+
During cluster provisioning, the {ztp} pipeline appends the CRs in the `/custom-manifest` directory to the default set of extra manifests stored in `extra-manifest/`.
57+
58+
[NOTE]
59+
====
60+
As of version 4.14 `extraManifestPath` is subject to a deprecation warning.
61+
62+
While `extraManifestPath` is still supported, we recommend that you use `extraManifests.searchPaths`.
63+
If you define `extraManifests.searchPaths` in the `SiteConfig` file, the {ztp} pipeline does not fetch manifests from the `ztp-site-generate` container during site installation.
4164
42-
. Save the `SiteConfig` CRs and `/extra-manifest` CRs and push them to the site configuration repo.
65+
If you define both `extraManifestPath` and `extraManifests.searchPaths` in the `Siteconfig` CR, the setting defined for `extraManifests.searchPaths` takes precedence.
4366
44-
The {ztp} pipeline appends the CRs in the `/extra-manifest` directory to the default set of extra manifests during cluster provisioning.
67+
It is strongly recommended that you extract the contents of `/extra-manifest` from the `ztp-site-generate` container and push it to the GIT repository.
68+
====

‎modules/ztp-generating-install-and-config-crs-manually.adoc

+7
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,13 @@ $ mkdir -p ./site-install
6464
----
6565
include::snippets/ztp_example-sno.yaml[]
6666
----
67+
+
68+
[NOTE]
69+
====
70+
Once you have extracted reference CR configuration files from the `out/extra-manifest` directory of the `ztp-site-generate` container, you can use `extraManifests.searchPaths` to include the path to the git directory containing those files.
71+
This allows the {ztp} pipeline to apply those CR files during cluster installation.
72+
If you configure a `searchPaths` directory, the {ztp} pipeline does not fetch manifests from the `ztp-site-generate` container during site installation.
73+
====
6774

6875
. Generate the Day 0 installation CRs by processing the modified `SiteConfig` CR `site-1-sno.yaml` by running the following command:
6976
+

‎modules/ztp-preparing-the-ztp-git-repository-ver-ind.adoc

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * scalability_and_performance/ztp_far_edge/ztp-preparing-the-hub-cluster.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="ztp-preparing-the-ztp-git-repository-ver-ind_{context}"]
7+
= Preparing the {ztp} site configuration repository for version independence
8+
9+
You can use {ztp} to manage source custom resources (CRs) for managed clusters that are running different versions of {product-title}.
10+
This means that the version of {product-title} running on the hub cluster can be independent of the version running on the managed clusters.
11+
12+
.Procedure
13+
14+
. Create a directory structure with separate paths for the `SiteConfig` and `PolicyGenTemplate` CRs.
15+
16+
. Within the `PolicyGenTemplate` directory, create a directory for each {product-title} version you want to make available.
17+
For each version, create the following resources:
18+
* `kustomization.yaml` file that explicitly includes the files in that directory
19+
* `source-crs` directory to contain reference CR configuration files from the `ztp-site-generate` container
20+
21+
. In the `/siteconfig` directory, create a subdirectory for each {product-title} version you want to make available. For each version, create at least one directory for reference CRs to be copied from the container. There is no restriction on the naming of directories or on the number of reference directories. If you want to work with custom CRs, you must create a separate directory for those.
22+
+
23+
The following example describes a structure using custom CRs for different versions of {product-title}:
24+
+
25+
[source,text]
26+
----
27+
├── policygentemplates
28+
│ ├── kustomization.yaml <1>
29+
│ ├── version_4.13 <2>
30+
│ │ ├── common-ranGen.yaml
31+
│ │ ├── group-du-sno-ranGen.yaml
32+
│ │ ├── group-du-sno-validator-ranGen.yaml
33+
│ │ ├── helix56-v413.yaml
34+
│ │ ├── kustomization.yaml <3>
35+
│ │ ├── ns.yaml
36+
│ │ └── source-crs/ <4>
37+
│ └── version_4.14 <2>
38+
│ ├── common-ranGen.yaml
39+
│ ├── group-du-sno-ranGen.yaml
40+
│ ├── group-du-sno-validator-ranGen.yaml
41+
│ ├── helix56-v414.yaml
42+
│ ├── kustomization.yaml <3>
43+
│ ├── ns.yaml
44+
│ └── source-crs/ <4>
45+
└── siteconfig
46+
├── kustomization.yaml
47+
├── version_4.13
48+
│ ├── helix56-v413.yaml
49+
│ ├── kustomization.yaml
50+
│ ├── extra-manifest/ <5>
51+
│ └── custom-manifest/ <6>
52+
└── version_4.14
53+
├── helix57-v414.yaml
54+
├── kustomization.yaml
55+
├── extra-manifest/ <5>
56+
└── custom-manifest/ <6>
57+
58+
----
59+
<1> Create a top-level `kustomization` yaml file.
60+
<2> Create the version-specific directories within the custom `/policygentemplates` directory.
61+
<3> Create a `kustomization.yaml` file for each version.
62+
<4> Create a `source-crs` directory for each version to contain reference CRs from the `ztp-site-generate` container.
63+
<5> Create a directory within the custom `/siteconfig` directory to contain extra manifests from the `ztp-site-generate` container.
64+
<6> Create a folder to hold custom CRs.
65+
+
66+
[NOTE]
67+
====
68+
In the previous example, each version subdirectory in the custom `/siteconfig` directory contains two further subdirectories, one containing the reference manifests copied from the container, the other for custom manifests that you provide.
69+
The names assigned to those directories are examples.
70+
If you use custom CRs, the last directory listed under `extraManifests.searchPaths` in the `SiteConfig` CR must be the directory containing custom CRs.
71+
====
72+
73+
. Edit the `SiteConfig` CR to include the search paths of any directories you have created.
74+
The first directory that is listed under `extraManifests.searchPaths` must be the directory containing the reference manifests.
75+
Consider the order in which the directories are listed.
76+
In cases where directories contain files with the same name, the file in the final directory takes precedence.
77+
+
78+
.Example SiteConfig CR
79+
+
80+
[source,yaml]
81+
----
82+
extraManifests:
83+
searchPaths:
84+
- extra-manifest/ <1>
85+
- custom-manifest/ <2>
86+
----
87+
<1> The directory containing the reference manifests must be listed first under `extraManifests.searchPaths`.
88+
<2> If you are using custom CRs, the last directory listed under `extraManifests.searchPaths` in the `SiteConfig` CR must be the directory containing those custom CRs.
89+
90+
. Edit the top-level `kustomization.yaml` file to control which {product-title} versions are active. The following is an example of a `kustomization.yaml` file at the top level:
91+
+
92+
[source,yaml]
93+
----
94+
resources:
95+
- version_4.13 <1>
96+
#- version_4.14 <2>
97+
----
98+
<1> Activate version 4.13.
99+
<2> Use comments to deactivate a version.

‎modules/ztp-preparing-the-ztp-git-repository.adoc

+49-7
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ Before you can use the {ztp-first} pipeline, you need to prepare the Git reposit
1717
.Procedure
1818

1919
. Create a directory structure with separate paths for the `SiteConfig` and `PolicyGenTemplate` CRs.
20+
+
21+
[NOTE]
22+
====
23+
Keep `SiteConfig` and `PolicyGenTemplate` CRs in separate directories.
24+
Both the `SiteConfig` and `PolicyGenTemplate` directories must contain a `kustomization.yaml` file that explicitly includes the files in that directory.
25+
====
2026

2127
. Export the `argocd` directory from the `ztp-site-generate` container image using the following commands:
2228
+
@@ -35,14 +41,51 @@ $ mkdir -p ./out
3541
$ podman run --log-driver=none --rm registry.redhat.io/openshift4/ztp-site-generate-rhel8:v{product-version} extract /home/ztp --tar | tar x -C ./out
3642
----
3743

44+
3845
. Check that the `out` directory contains the following subdirectories:
3946
+
4047
* `out/extra-manifest` contains the source CR files that `SiteConfig` uses to generate extra manifest `configMap`.
4148
* `out/source-crs` contains the source CR files that `PolicyGenTemplate` uses to generate the {rh-rhacm-first} policies.
4249
* `out/argocd/deployment` contains patches and YAML files to apply on the hub cluster for use in the next step of this procedure.
4350
* `out/argocd/example` contains the examples for `SiteConfig` and `PolicyGenTemplate` files that represent the recommended configuration.
4451

45-
The directory structure under `out/argocd/example` serves as a reference for the structure and content of your Git repository. The example includes `SiteConfig` and `PolicyGenTemplate` reference CRs for single-node, three-node, and standard clusters. Remove references to cluster types that you are not using. The following example describes a set of CRs for a network of single-node clusters:
52+
53+
. Copy the `out/source-crs` folder and contents to the `PolicyGentemplate` directory.
54+
55+
. The out/extra-manifests directory contains the reference manifests for a RAN DU cluster.
56+
Copy the `out/extra-manifests` directory into the `SiteConfig` folder.
57+
This directory should contain CRs from the `ztp-site-generate` container only.
58+
Do not add custom CRs here.
59+
If you want to work with custom CRs you must create another directory for that content.
60+
+
61+
[NOTE]
62+
====
63+
Here is an example of the directory structure:
64+
source,text]
65+
----
66+
example
67+
├── policygentemplates
68+
│ ├── kustomization.yaml
69+
│ └── source-crs/
70+
└── siteconfig
71+
├── extra-manifests
72+
└── kustomization.yaml
73+
----
74+
====
75+
76+
. Commit the directory structure and the `kustomization.yaml` files and push to your Git repository.
77+
The initial push to Git should include the `kustomization.yaml` files.
78+
79+
You can use the directory structure under `out/argocd/example` as a reference for the structure and content of your Git repository.
80+
That structure includes `SiteConfig` and `PolicyGenTemplate` reference CRs for single-node, three-node, and standard clusters.
81+
Remove references to cluster types that you are not using.
82+
83+
For all cluster types, you must:
84+
85+
* Add the `source-crs` subdirectory to the `policygentemplate` directory.
86+
* Add the `extra-manifests` directory to the `siteconfig` directory.
87+
88+
The following example describes a set of CRs for a network of single-node clusters:
4689
4790
[source,text]
4891
----
@@ -53,15 +96,14 @@ example
5396
│ ├── group-du-sno-ranGen.yaml
5497
│ ├── group-du-sno-validator-ranGen.yaml
5598
│ ├── kustomization.yaml
99+
│ ├── source-crs/
56100
│ └── ns.yaml
57101
└── siteconfig
58102
├── example-sno.yaml
103+
├── extra-manifests/ <1>
104+
├── custom-manifests/ <2>
59105
├── KlusterletAddonConfigOverride.yaml
60106
└── kustomization.yaml
61107
----
62-
63-
Keep `SiteConfig` and `PolicyGenTemplate` CRs in separate directories. Both the `SiteConfig` and `PolicyGenTemplate` directories must contain a `kustomization.yaml` file that explicitly includes the files in that directory.
64-
65-
This directory structure and the `kustomization.yaml` files must be committed and pushed to your Git repository. The initial push to Git should include the `kustomization.yaml` files. The `SiteConfig` (`example-sno.yaml`) and `PolicyGenTemplate` (`common-ranGen.yaml`, `group-du-sno*.yaml`, and `example-sno-site.yaml`) files can be omitted and pushed at a later time as required when deploying a site.
66-
67-
The `KlusterletAddonConfigOverride.yaml` file is only required if one or more `SiteConfig` CRs which make reference to it are committed and pushed to Git. See `example-sno.yaml` for an example of how this is used.
108+
<1> Contains reference manifests from the `ztp-container`.
109+
<2> Contains custom manifests.

‎scalability_and_performance/ztp_far_edge/ztp-preparing-the-hub-cluster.adoc

+2
Original file line numberDiff line numberDiff line change
@@ -51,3 +51,5 @@ include::modules/ztp-configuring-the-hub-cluster-to-use-unauthenticated-registri
5151
include::modules/ztp-preparing-the-hub-cluster-for-ztp.adoc[leveloffset=+1]
5252

5353
include::modules/ztp-preparing-the-ztp-git-repository.adoc[leveloffset=+1]
54+
55+
include::modules/ztp-preparing-the-ztp-git-repository-ver-ind.adoc[leveloffset=+2]

0 commit comments

Comments
 (0)