$ grep -r "ztp-deploy-wave" out/source-crs
You can provision OKD clusters at scale with Red Hat Advanced Cluster Management (RHACM) using the assisted service and the GitOps plugin policy generator with core-reduction technology enabled. The GitOps Zero Touch Provisioning (ZTP) pipeline performs the cluster installations. GitOps ZTP can be used in a disconnected environment.
Using For more information about |
GitOps Zero Touch Provisioning (ZTP) generates installation and configuration CRs from manifests stored in Git. These artifacts are applied to a centralized hub cluster where Red Hat Advanced Cluster Management (RHACM), the assisted service, and the Topology Aware Lifecycle Manager (TALM) use the CRs to install and configure the managed cluster. The configuration phase of the GitOps ZTP pipeline uses the TALM to orchestrate the application of the configuration CRs to the cluster. There are several key integration points between GitOps ZTP and the TALM.
By default, GitOps ZTP creates all policies with a remediation action of inform
. These policies cause RHACM to report on compliance status of clusters relevant to the policies but does not apply the desired configuration. During the GitOps ZTP process, after OpenShift installation, the TALM steps through the created inform
policies and enforces them on the target managed cluster(s). This applies the configuration to the managed cluster. Outside of the GitOps ZTP phase of the cluster lifecycle, this allows you to change policies without the risk of immediately rolling those changes out to affected managed clusters. You can control the timing and the set of remediated clusters by using TALM.
To automate the initial configuration of newly deployed clusters, TALM monitors the state of all ManagedCluster
CRs on the hub cluster. Any ManagedCluster
CR that does not have a ztp-done
label applied, including newly created ManagedCluster
CRs, causes the TALM to automatically create a ClusterGroupUpgrade
CR with the following characteristics:
The ClusterGroupUpgrade
CR is created and enabled in the ztp-install
namespace.
ClusterGroupUpgrade
CR has the same name as the ManagedCluster
CR.
The cluster selector includes only the cluster associated with that ManagedCluster
CR.
The set of managed policies includes all policies that RHACM has bound to the cluster at the time the ClusterGroupUpgrade
is created.
Pre-caching is disabled.
Timeout set to 4 hours (240 minutes).
The automatic creation of an enabled ClusterGroupUpgrade
ensures that initial zero-touch deployment of clusters proceeds without the need for user intervention. Additionally, the automatic creation of a ClusterGroupUpgrade
CR for any ManagedCluster
without the ztp-done
label allows a failed GitOps ZTP installation to be restarted by simply deleting the ClusterGroupUpgrade
CR for the cluster.
Each policy generated from a PolicyGenerator
or PolicyGentemplate
CR includes a ztp-deploy-wave
annotation. This annotation is based on the same annotation from each CR which is included in that policy. The wave annotation is used to order the policies in the auto-generated ClusterGroupUpgrade
CR. The wave annotation is not used other than for the auto-generated ClusterGroupUpgrade
CR.
All CRs in the same policy must have the same setting for the |
The TALM applies the configuration policies in the order specified by the wave annotations. The TALM waits for each policy to be compliant before moving to the next policy. It is important to ensure that the wave annotation for each CR takes into account any prerequisites for those CRs to be applied to the cluster. For example, an Operator must be installed before or concurrently with the configuration for the Operator. Similarly, the CatalogSource
for an Operator must be installed in a wave before or concurrently with the Operator Subscription. The default wave value for each CR takes these prerequisites into account.
Multiple CRs and policies can share the same wave number. Having fewer policies can result in faster deployments and lower CPU usage. It is a best practice to group many CRs into relatively few waves.
To check the default wave value in each source CR, run the following command against the out/source-crs
directory that is extracted from the ztp-site-generate
container image:
$ grep -r "ztp-deploy-wave" out/source-crs
The ClusterGroupUpgrade
CR is automatically created and includes directives to annotate the ManagedCluster
CR with labels at the start and end of the GitOps ZTP process.
When GitOps ZTP configuration postinstallation commences, the ManagedCluster
has the ztp-running
label applied. When all policies are remediated to the cluster and are fully compliant, these directives cause the TALM to remove the ztp-running
label and apply the ztp-done
label.
For deployments that make use of the informDuValidator
policy, the ztp-done
label is applied when the cluster is fully ready for deployment of applications. This includes all reconciliation and resulting effects of the GitOps ZTP applied configuration CRs. The ztp-done
label affects automatic ClusterGroupUpgrade
CR creation by TALM. Do not manipulate this label after the initial GitOps ZTP installation of the cluster.
The automatically created ClusterGroupUpgrade
CR has the owner reference set as the ManagedCluster
from which it was derived. This reference ensures that deleting the ManagedCluster
CR causes the instance of the ClusterGroupUpgrade
to be deleted along with any supporting resources.
Red Hat Advanced Cluster Management (RHACM) uses GitOps Zero Touch Provisioning (ZTP) to deploy single-node OKD clusters, three-node clusters, and standard clusters. You manage site configuration data as OKD custom resources (CRs) in a Git repository. GitOps ZTP uses a declarative GitOps approach for a develop once, deploy anywhere model to deploy the managed clusters.
The deployment of the clusters includes:
Installing the host operating system (RHCOS) on a blank server
Deploying OKD
Creating cluster policies and site subscriptions
Making the necessary network configurations to the server operating system
Deploying profile Operators and performing any needed software-related configuration, such as performance profile, PTP, and SR-IOV
After you apply the managed site custom resources (CRs) on the hub cluster, the following actions happen automatically:
A Discovery image ISO file is generated and booted on the target host.
When the ISO file successfully boots on the target host it reports the host hardware information to RHACM.
After all hosts are discovered, OKD is installed.
When OKD finishes installing, the hub installs the klusterlet
service on the target cluster.
The requested add-on services are installed on the target cluster.
The Discovery image ISO process is complete when the Agent
CR for the managed cluster is created on the hub cluster.
The target bare-metal host must meet the networking, firmware, and hardware requirements listed in Recommended single-node OpenShift cluster configuration for vDU application workloads. |
Add the required Secret
custom resources (CRs) for the managed bare-metal host to the hub cluster. You need a secret for the GitOps Zero Touch Provisioning (ZTP) pipeline to access the Baseboard Management Controller (BMC) and a secret for the assisted installer service to pull cluster installation images from the registry.
The secrets are referenced from the |
Create a YAML secret file containing credentials for the host Baseboard Management Controller (BMC) and a pull secret required for installing OpenShift and all add-on cluster Operators:
Save the following YAML as the file example-sno-secret.yaml
:
apiVersion: v1
kind: Secret
metadata:
name: example-sno-bmc-secret
namespace: example-sno (1)
data: (2)
password: <base64_password>
username: <base64_username>
type: Opaque
---
apiVersion: v1
kind: Secret
metadata:
name: pull-secret
namespace: example-sno (3)
data:
.dockerconfigjson: <pull_secret> (4)
type: kubernetes.io/dockerconfigjson
1 | Must match the namespace configured in the related SiteConfig CR |
2 | Base64-encoded values for password and username |
3 | Must match the namespace configured in the related SiteConfig CR |
4 | Base64-encoded pull secret |
Add the relative path to example-sno-secret.yaml
to the kustomization.yaml
file that you use to install the cluster.
The GitOps Zero Touch Provisioning (ZTP) workflow uses the Discovery ISO as part of the OKD installation process on managed bare-metal hosts. You can edit the InfraEnv
resource to specify kernel arguments for the Discovery ISO. This is useful for cluster installations with specific environmental requirements. For example, configure the rd.net.timeout.carrier
kernel argument for the Discovery ISO to facilitate static networking for the cluster or to receive a DHCP address before downloading the root file system during installation.
In OKD 4.16, you can only add kernel arguments. You can not replace or delete kernel arguments. |
You have installed the OpenShift CLI (oc).
You have logged in to the hub cluster as a user with cluster-admin privileges.
Create the InfraEnv
CR and edit the spec.kernelArguments
specification to configure kernel arguments.
Save the following YAML in an InfraEnv-example.yaml
file:
The |
apiVersion: agent-install.openshift.io/v1beta1
kind: InfraEnv
metadata:
annotations:
argocd.argoproj.io/sync-wave: "1"
name: "{{ .Cluster.ClusterName }}"
namespace: "{{ .Cluster.ClusterName }}"
spec:
clusterRef:
name: "{{ .Cluster.ClusterName }}"
namespace: "{{ .Cluster.ClusterName }}"
kernelArguments:
- operation: append (1)
value: audit=0 (2)
- operation: append
value: trace=1
sshAuthorizedKey: "{{ .Site.SshPublicKey }}"
proxy: "{{ .Cluster.ProxySettings }}"
pullSecretRef:
name: "{{ .Site.PullSecretRef.Name }}"
ignitionConfigOverride: "{{ .Cluster.IgnitionConfigOverride }}"
nmStateConfigLabelSelector:
matchLabels:
nmstate-label: "{{ .Cluster.ClusterName }}"
additionalNTPSources: "{{ .Cluster.AdditionalNTPSources }}"
1 | Specify the append operation to add a kernel argument. |
2 | Specify the kernel argument you want to configure. This example configures the audit kernel argument and the trace kernel argument. |
Commit the InfraEnv-example.yaml
CR to the same location in your Git repository that has the SiteConfig
CR and push your changes. The following example shows a sample Git repository structure:
~/example-ztp/install
└── site-install
├── siteconfig-example.yaml
├── InfraEnv-example.yaml
...
Edit the spec.clusters.crTemplates
specification in the SiteConfig
CR to reference the InfraEnv-example.yaml
CR in your Git repository:
clusters:
crTemplates:
InfraEnv: "InfraEnv-example.yaml"
When you are ready to deploy your cluster by committing and pushing the SiteConfig
CR, the build pipeline uses the custom InfraEnv-example
CR in your Git repository to configure the infrastructure environment, including the custom kernel arguments.
To verify that the kernel arguments are applied, after the Discovery image verifies that OKD is ready for installation, you can SSH to the target host before the installation process begins. At that point, you can view the kernel arguments for the Discovery ISO in the /proc/cmdline
file.
Begin an SSH session with the target host:
$ ssh -i /path/to/privatekey core@<host_name>
View the system’s kernel arguments by using the following command:
$ cat /proc/cmdline
Use the following procedure to create a SiteConfig
custom resource (CR) and related files and initiate the GitOps Zero Touch Provisioning (ZTP) cluster deployment.
You have installed the OpenShift CLI (oc
).
You have logged in to the hub cluster as a user with cluster-admin
privileges.
You configured the hub cluster for generating the required installation and policy CRs.
You created a Git repository where you manage your custom site configuration data. The repository must be accessible from the hub cluster and you must configure it as a source repository for the ArgoCD application. See "Preparing the GitOps ZTP site configuration repository" for more information.
When you create the source repository, ensure that you patch the ArgoCD application with the |
To be ready for provisioning managed clusters, you require the following for each bare-metal host:
Your network requires DNS. Managed cluster hosts should be reachable from the hub cluster. Ensure that Layer 3 connectivity exists between the hub cluster and the managed cluster host.
GitOps ZTP uses BMC username and password details to connect to the BMC during cluster installation. The GitOps ZTP plugin manages the ManagedCluster
CRs on the hub cluster based on the SiteConfig
CR in your site Git repo. You create individual BMCSecret
CRs for each host manually.
Create the required managed cluster secrets on the hub cluster. These resources must be in a namespace with a name matching the cluster name. For example, in out/argocd/example/siteconfig/example-sno.yaml
, the cluster name and namespace is example-sno
.
Export the cluster namespace by running the following command:
$ export CLUSTERNS=example-sno
Create the namespace:
$ oc create namespace $CLUSTERNS
Create pull secret and BMC Secret
CRs for the managed cluster. The pull secret must contain all the credentials necessary for installing OKD and all required Operators. See "Creating the managed bare-metal host secrets" for more information.
The secrets are referenced from the |
Create a SiteConfig
CR for your cluster in your local clone of the Git repository:
Choose the appropriate example for your CR from the out/argocd/example/siteconfig/
folder.
The folder includes example files for single node, three-node, and standard clusters:
example-sno.yaml
example-3node.yaml
example-standard.yaml
Change the cluster and host details in the example file to match the type of cluster you want. For example:
# example-node1-bmh-secret & assisted-deployment-pull-secret need to be created under same namespace example-sno
---
apiVersion: ran.openshift.io/v1
kind: SiteConfig
metadata:
name: "example-sno"
namespace: "example-sno"
spec:
baseDomain: "example.com"
pullSecretRef:
name: "assisted-deployment-pull-secret"
clusterImageSetNameRef: "openshift-4.16"
sshPublicKey: "ssh-rsa AAAA..."
clusters:
- clusterName: "example-sno"
networkType: "OVNKubernetes"
# installConfigOverrides is a generic way of passing install-config
# parameters through the siteConfig. The 'capabilities' field configures
# the composable openshift feature. In this 'capabilities' setting, we
# remove all the optional set of components.
# Notes:
# - OperatorLifecycleManager is needed for 4.15 and later
# - NodeTuning is needed for 4.13 and later, not for 4.12 and earlier
# - Ingress is needed for 4.16 and later
installConfigOverrides: |
{
"capabilities": {
"baselineCapabilitySet": "None",
"additionalEnabledCapabilities": [
"NodeTuning",
"OperatorLifecycleManager",
"Ingress"
]
}
}
# It is strongly recommended to include crun manifests as part of the additional install-time manifests for 4.13+.
# The crun manifests can be obtained from source-crs/optional-extra-manifest/ and added to the git repo ie.sno-extra-manifest.
# extraManifestPath: sno-extra-manifest
clusterLabels:
# These example cluster labels correspond to the bindingRules in the PolicyGenTemplate examples
du-profile: "latest"
# These example cluster labels correspond to the bindingRules in the PolicyGenTemplate examples in ../policygentemplates:
# ../policygentemplates/common-ranGen.yaml will apply to all clusters with 'common: true'
common: true
# ../policygentemplates/group-du-sno-ranGen.yaml will apply to all clusters with 'group-du-sno: ""'
group-du-sno: ""
# ../policygentemplates/example-sno-site.yaml will apply to all clusters with 'sites: "example-sno"'
# Normally this should match or contain the cluster name so it only applies to a single cluster
sites: "example-sno"
clusterNetwork:
- cidr: 1001:1::/48
hostPrefix: 64
machineNetwork:
- cidr: 1111:2222:3333:4444::/64
serviceNetwork:
- 1001:2::/112
additionalNTPSources:
- 1111:2222:3333:4444::2
# Initiates the cluster for workload partitioning. Setting specific reserved/isolated CPUSets is done via PolicyTemplate
# please see Workload Partitioning Feature for a complete guide.
cpuPartitioningMode: AllNodes
# Optionally; This can be used to override the KlusterletAddonConfig that is created for this cluster:
#crTemplates:
# KlusterletAddonConfig: "KlusterletAddonConfigOverride.yaml"
nodes:
- hostName: "example-node1.example.com"
role: "master"
# Optionally; This can be used to configure desired BIOS setting on a host:
#biosConfigRef:
# filePath: "example-hw.profile"
bmcAddress: "idrac-virtualmedia+https://[1111:2222:3333:4444::bbbb:1]/redfish/v1/Systems/System.Embedded.1"
bmcCredentialsName:
name: "example-node1-bmh-secret"
bootMACAddress: "AA:BB:CC:DD:EE:11"
# Use UEFISecureBoot to enable secure boot
bootMode: "UEFI"
rootDeviceHints:
deviceName: "/dev/disk/by-path/pci-0000:01:00.0-scsi-0:2:0:0"
# disk partition at `/var/lib/containers` with ignitionConfigOverride. Some values must be updated. See DiskPartitionContainer.md for more details
ignitionConfigOverride: |
{
"ignition": {
"version": "3.2.0"
},
"storage": {
"disks": [
{
"device": "/dev/disk/by-id/wwn-0x6b07b250ebb9d0002a33509f24af1f62",
"partitions": [
{
"label": "var-lib-containers",
"sizeMiB": 0,
"startMiB": 250000
}
],
"wipeTable": false
}
],
"filesystems": [
{
"device": "/dev/disk/by-partlabel/var-lib-containers",
"format": "xfs",
"mountOptions": [
"defaults",
"prjquota"
],
"path": "/var/lib/containers",
"wipeFilesystem": true
}
]
},
"systemd": {
"units": [
{
"contents": "# Generated by Butane\n[Unit]\nRequires=systemd-fsck@dev-disk-by\\x2dpartlabel-var\\x2dlib\\x2dcontainers.service\nAfter=systemd-fsck@dev-disk-by\\x2dpartlabel-var\\x2dlib\\x2dcontainers.service\n\n[Mount]\nWhere=/var/lib/containers\nWhat=/dev/disk/by-partlabel/var-lib-containers\nType=xfs\nOptions=defaults,prjquota\n\n[Install]\nRequiredBy=local-fs.target",
"enabled": true,
"name": "var-lib-containers.mount"
}
]
}
}
nodeNetwork:
interfaces:
- name: eno1
macAddress: "AA:BB:CC:DD:EE:11"
config:
interfaces:
- name: eno1
type: ethernet
state: up
ipv4:
enabled: false
ipv6:
enabled: true
address:
# For SNO sites with static IP addresses, the node-specific,
# API and Ingress IPs should all be the same and configured on
# the interface
- ip: 1111:2222:3333:4444::aaaa:1
prefix-length: 64
dns-resolver:
config:
search:
- example.com
server:
- 1111:2222:3333:4444::2
routes:
config:
- destination: ::/0
next-hop-interface: eno1
next-hop-address: 1111:2222:3333:4444::1
table-id: 254
For more information about BMC addressing, see the "Additional resources" section. The |
You can inspect the default set of extra-manifest MachineConfig
CRs in out/argocd/extra-manifest
. It is automatically applied to the cluster when it is installed.
Optional: To provision additional install-time manifests on the provisioned cluster, create a directory in your Git repository, for example, sno-extra-manifest/
, and add your custom manifest CRs to this directory. If your SiteConfig.yaml
refers to this directory in the extraManifestPath
field, any CRs in this referenced directory are appended to the default set of extra manifests.
Enabling the crun OCI container runtime
For optimal cluster performance, enable crun for master and worker nodes in single-node OpenShift, single-node OpenShift with additional worker nodes, three-node OpenShift, and standard clusters. Enable crun in a The |
Add the SiteConfig
CR to the kustomization.yaml
file in the generators
section, similar to the example shown in out/argocd/example/siteconfig/kustomization.yaml
.
Commit the SiteConfig
CR and associated kustomization.yaml
changes in your Git repository and push the changes.
The ArgoCD pipeline detects the changes and begins the managed cluster deployment.
Verify that the custom roles and labels are applied after the node is deployed:
$ oc describe node example-node.example.com
Name: example-node.example.com
Roles: control-plane,example-label,master,worker
Labels: beta.kubernetes.io/arch=amd64
beta.kubernetes.io/os=linux
custom-label/parameter1=true
kubernetes.io/arch=amd64
kubernetes.io/hostname=cnfdf03.telco5gran.eng.rdu2.redhat.com
kubernetes.io/os=linux
node-role.kubernetes.io/control-plane=
node-role.kubernetes.io/example-label= (1)
node-role.kubernetes.io/master=
node-role.kubernetes.io/worker=
node.openshift.io/os_id=rhcos
1 | The custom label is applied to the node. |
Accelerated provisioning of GitOps ZTP is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope. |
You can reduce the time taken for cluster installation by using accelerated provisioning of GitOps ZTP for single-node OpenShift. Accelerated ZTP speeds up installation by applying Day 2 manifests derived from policies at an earlier stage.
Accelerated provisioning of GitOps ZTP is supported only when installing single-node OpenShift with Assisted Installer. Otherwise this installation method will fail. |
You can activate accelerated ZTP using the spec.clusters.clusterLabels.accelerated-ztp
label, as in the following example:
SiteConfig
CR.apiVersion: ran.openshift.io/v2
kind: SiteConfig
metadata:
name: "example-sno"
namespace: "example-sno"
spec:
baseDomain: "example.com"
pullSecretRef:
name: "assisted-deployment-pull-secret"
clusterImageSetNameRef: "openshift-4.10"
sshPublicKey: "ssh-rsa AAAA..."
clusters:
# ...
clusterLabels:
common: true
group-du-sno: ""
sites : "example-sno"
accelerated-ztp: full
You can use accelerated-ztp: full
to fully automate the accelerated process.
GitOps ZTP updates the AgentClusterInstall
resource with a reference to the accelerated GitOps ZTP ConfigMap
, and includes resources extracted from policies by TALM, and accelerated ZTP job manifests.
If you use accelerated-ztp: partial
, GitOps ZTP does not include the accelerated job manifests, but includes policy-derived objects created during the cluster installation of the following kind
types:
PerformanceProfile.performance.openshift.io
Tuned.tuned.openshift.io
Namespace
CatalogSource.operators.coreos.com
ContainerRuntimeConfig.machineconfiguration.openshift.io
This partial acceleration can reduce the number of reboots done by the node when applying resources of the kind Performance Profile
, Tuned
, and ContainerRuntimeConfig
.
TALM installs the Operator subscriptions derived from policies after RHACM completes the import of the cluster, following the same flow as standard GitOps ZTP.
The benefits of accelerated ZTP increase with the scale of your deployment.
Using accelerated-ztp: full
gives more benefit on a large number of clusters.
With a smaller number of clusters, the reduction in installation time is less significant.
Full accelerated ZTP leaves behind a namespace and a completed job on the spoke that need to be manually removed.
One benefit of using accelerated-ztp: partial
is that you can override the functionality of the on-spoke job if something goes wrong with the stock implementation or if you require a custom functionality.
Accelerated ZTP uses an additional ConfigMap
to create the resources derived from policies on the spoke cluster.
The standard ConfigMap
includes manifests that the GitOps ZTP workflow uses to customize cluster installs.
TALM detects that the accelerated-ztp
label is set and then creates a second ConfigMap
.
As part of accelerated ZTP, the SiteConfig
generator adds a reference to that second ConfigMap
using the naming convention <spoke-cluster-name>-aztp
.
After TALM creates that second ConfigMap
, it finds all policies bound to the managed cluster and extracts the GitOps ZTP profile information.
TALM adds the GitOps ZTP profile information to the <spoke-cluster-name>-aztp
ConfigMap
custom resource (CR) and applies the CR to the hub cluster API.
You can enable IPsec encryption in managed single-node OpenShift clusters that you install using GitOps ZTP and Red Hat Advanced Cluster Management (RHACM). You can encrypt external traffic between pods and IPsec endpoints external to the managed cluster. All pod-to-pod network traffic between nodes on the OVN-Kubernetes cluster network is encrypted with IPsec in Transport mode.
In OKD 4.16, deploying IPsec encryption by using GitOps ZTP and RHACM is validated for single-node OpenShift clusters only. The GitOps ZTP IPsec implementation assumes you are deploying to a resource constrained platform.
As such, you install the feature with a single |
You have installed the OpenShift CLI (oc
).
You have logged in to the hub cluster as a user with cluster-admin
privileges.
You have configured RHACM and the hub cluster for generating the required installation and policy custom resources (CRs) for managed clusters.
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.
You have installed the butane
utility, version 0.20.0 or higher.
You have a PKCS#12 certificate for the IPsec endpoint and a CA cert in PEM format.
Extract the latest version of the ztp-site-generate
container source and merge it with your repository where you manage your custom site configuration data.
Configure optional-extra-manifest/ipsec/ipsec-endpoint-config.yaml
with the required values that configure IPsec in the cluster. For example:
interfaces:
- name: hosta_conn
type: ipsec
libreswan:
left: <cluster_node> (1)
leftid: '%fromcert'
leftmodecfgclient: false
leftcert: <left_cert> (2)
leftrsasigkey: '%cert'
right: <external_host> (3)
rightid: '%fromcert'
rightrsasigkey: '%cert'
rightsubnet: <external_address> (4)
ikev2: insist (5)
type: tunnel
1 | Replace <cluster_node> with the IP address or DNS hostname of the cluster node for the cluster-side IPsec tunnel. |
2 | Replace <left_cert> with the IPsec certificate nickname. |
3 | Replace <external_host> with the external host IP address or DNS hostname. |
4 | Replace <external_address> with the IP address or subnet of the external host on the other side of the IPsec tunnel. |
5 | Use the IKEv2 VPN encryption protocol only. Do not use IKEv1, which is deprecated. |
Add your ca.pem
and left_server.p12
certificates to the optional-extra-manifest/ipsec
folder.
The certificate files are required for the Network Security Services (NSS) database on each host. These files are imported as part of the Butane configuration in later steps.
left_server.p12
: The certificate bundle for the IPsec endpoints
ca.pem
: The certificate authority that you signed your certificates with
Open a shell prompt at the optional-extra-manifest/ipsec
folder of the Git repository where you maintain your custom site configuration data.
Run the optional-extra-manifest/ipsec/build.sh
script to generate the required Butane and MachineConfig
CRs files.
out
└── argocd
└── example
└── optional-extra-manifest
└── ipsec
├── 99-ipsec-master-endpoint-config.bu (1)
├── 99-ipsec-master-endpoint-config.yaml
├── 99-ipsec-worker-endpoint-config.bu
├── 99-ipsec-worker-endpoint-config.yaml
├── build.sh
├── ca.pem (2)
├── left_server.p12
├── enable-ipsec.yaml
├── ipsec-endpoint-config.yml
└── README.md
1 | The ipsec/build.sh script generates the Butane and endpoint configuration CRs. |
2 | You provide ca.pem and left_server.p12 certificate files that are relevant to your network. |
Create a custom-manifest/
folder in the repository where you manage your custom site configuration data.
Add the enable-ipsec.yaml
and 99-ipsec-*
YAML files to the directory.
For example:
siteconfig
├── site1-sno-du.yaml
├── extra-manifest/
└── custom-manifest
├── enable-ipsec.yaml
├── 99-ipsec-worker-endpoint-config.yaml
└── 99-ipsec-master-endpoint-config.yaml
In your SiteConfig
CR, add the custom-manifest/
directory to the extraManifests.searchPaths
field.
For example:
clusters:
- clusterName: "site1-sno-du"
networkType: "OVNKubernetes"
extraManifests:
searchPaths:
- extra-manifest/
- custom-manifest/
Commit the SiteConfig
CR changes and updated files in your Git repository and push the changes to provision the managed cluster and configure IPsec encryption.
The Argo CD pipeline detects the changes and begins the managed cluster deployment.
During cluster provisioning, the GitOps ZTP pipeline appends the CRs in the /custom-manifest
directory to the default set of extra manifests stored in extra-manifest/
.
To verify that the IPsec encryption is successfully applied in the managed single-node OpenShift cluster, perform the following steps:
Start a debug pod for the managed cluster by running the following command:
$ oc debug node/<node_name>
Check that the IPsec policy is applied in the cluster node:
sh-5.1# ip xfrm policy
src 172.16.123.0/24 dst 10.1.232.10/32
dir out priority 1757377 ptype main
tmpl src 10.1.28.190 dst 10.1.232.10
proto esp reqid 16393 mode tunnel
src 10.1.232.10/32 dst 172.16.123.0/24
dir fwd priority 1757377 ptype main
tmpl src 10.1.232.10 dst 10.1.28.190
proto esp reqid 16393 mode tunnel
src 10.1.232.10/32 dst 172.16.123.0/24
dir in priority 1757377 ptype main
tmpl src 10.1.232.10 dst 10.1.28.190
proto esp reqid 16393 mode tunnel
Check that the IPsec tunnel is up and connected:
sh-5.1# ip xfrm state
src 10.1.232.10 dst 10.1.28.190
proto esp spi 0xa62a05aa reqid 16393 mode tunnel
replay-window 0 flag af-unspec esn
auth-trunc hmac(sha1) 0x8c59f680c8ea1e667b665d8424e2ab749cec12dc 96
enc cbc(aes) 0x2818a489fe84929c8ab72907e9ce2f0eac6f16f2258bd22240f4087e0326badb
anti-replay esn context:
seq-hi 0x0, seq 0x0, oseq-hi 0x0, oseq 0x0
replay_window 128, bitmap-length 4
00000000 00000000 00000000 00000000
src 10.1.28.190 dst 10.1.232.10
proto esp spi 0x8e96e9f9 reqid 16393 mode tunnel
replay-window 0 flag af-unspec esn
auth-trunc hmac(sha1) 0xd960ddc0a6baaccb343396a51295e08cfd8aaddd 96
enc cbc(aes) 0x0273c02e05b4216d5e652de3fc9b3528fea94648bc2b88fa01139fdf0beb27ab
anti-replay esn context:
seq-hi 0x0, seq 0x0, oseq-hi 0x0, oseq 0x0
replay_window 128, bitmap-length 4
00000000 00000000 00000000 00000000
Ping a known IP in the external host subnet.
For example, ping an IP in the rightsubnet
range that you set in ipsec/ipsec-endpoint-config.yaml
:
sh-5.1# ping 172.16.110.8
sh-5.1# ping 172.16.110.8
PING 172.16.110.8 (172.16.110.8) 56(84) bytes of data.
64 bytes from 172.16.110.8: icmp_seq=1 ttl=64 time=153 ms
64 bytes from 172.16.110.8: icmp_seq=2 ttl=64 time=155 ms
SiteConfig CR field | Description | ||
---|---|---|---|
|
Configure workload partitioning by setting the value for
|
||
|
Set |
||
|
Configure the image set available on the hub cluster for all the clusters in the site.
To see the list of supported versions on your hub cluster, run |
||
|
Set the
|
||
|
Specifies the cluster image set used to deploy an individual cluster. If defined, it overrides the |
||
|
Configure cluster labels to correspond to the binding rules in the For example, |
||
|
Optional. Set |
||
|
For single-node deployments, define a single host.
For three-node deployments, define three hosts.
For standard deployments, define three hosts with |
||
|
Specify custom roles for your nodes in your managed clusters. These are additional roles are not used by any OKD 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. |
||
|
Optional. Uncomment and set the value to |
||
|
BMC address that you use to access the host. Applies to all cluster types. GitOps ZTP supports iPXE and virtual media booting by using Redfish or IPMI protocols. To use iPXE booting, you must use RHACM 2.8 or later. For more information about BMC addressing, see the "Additional resources" section. |
||
|
BMC address that you use to access the host. Applies to all cluster types. GitOps ZTP supports iPXE and virtual media booting by using Redfish or IPMI protocols. To use iPXE booting, you must use RHACM 2.8 or later. For more information about BMC addressing, see the "Additional resources" section.
|
||
|
Configure the |
||
|
Set the boot mode for the host to |
||
|
Specifies the device for deployment. Identifiers that are stable across reboots are recommended. For example, |
||
|
Optional. Use this field to assign partitions for persistent storage. Adjust disk ID and size to the specific hardware. |
||
|
Configure the network settings for the node. |
||
|
Configure the IPv6 address for the host. For single-node OpenShift clusters with static IP addresses, the node-specific API and Ingress IPs should be the same. |
The ArgoCD pipeline uses the SiteConfig
CR to generate the cluster configuration CRs and syncs it with the hub cluster. You can monitor the progress of the synchronization in the ArgoCD dashboard.
You have installed the OpenShift CLI (oc
).
You have logged in to the hub cluster as a user with cluster-admin
privileges.
When the synchronization is complete, the installation generally proceeds as follows:
The Assisted Service Operator installs OKD on the cluster. You can monitor the progress of cluster installation from the RHACM dashboard or from the command line by running the following commands:
Export the cluster name:
$ export CLUSTER=<clusterName>
Query the AgentClusterInstall
CR for the managed cluster:
$ oc get agentclusterinstall -n $CLUSTER $CLUSTER -o jsonpath='{.status.conditions[?(@.type=="Completed")]}' | jq
Get the installation events for the cluster:
$ curl -sk $(oc get agentclusterinstall -n $CLUSTER $CLUSTER -o jsonpath='{.status.debugInfo.eventsURL}') | jq '.[-2,-1]'
The ArgoCD pipeline uses the SiteConfig
and PolicyGenerator
or PolicyGentemplate
custom resources (CRs) to generate the cluster configuration CRs and Red Hat Advanced Cluster Management (RHACM) policies. Use the following steps to troubleshoot issues that might occur during this process.
You have installed the OpenShift CLI (oc
).
You have logged in to the hub cluster as a user with cluster-admin
privileges.
Check that the installation CRs were created by using the following command:
$ oc get AgentClusterInstall -n <cluster_name>
If no object is returned, use the following steps to troubleshoot the ArgoCD pipeline flow from SiteConfig
files to the installation CRs.
Verify that the ManagedCluster
CR was generated using the SiteConfig
CR on the hub cluster:
$ oc get managedcluster
If the ManagedCluster
is missing, check if the clusters
application failed to synchronize the files from the Git repository to the hub cluster:
$ oc describe -n openshift-gitops application clusters
Check for the Status.Conditions
field to view the error logs for the managed cluster. For example, setting an invalid value for extraManifestPath:
in the SiteConfig
CR raises the following error:
Status:
Conditions:
Last Transition Time: 2021-11-26T17:21:39Z
Message: rpc error: code = Unknown desc = `kustomize build /tmp/https___git.com/ran-sites/siteconfigs/ --enable-alpha-plugins` failed exit status 1: 2021/11/26 17:21:40 Error could not create extra-manifest ranSite1.extra-manifest3 stat extra-manifest3: no such file or directory 2021/11/26 17:21:40 Error: could not build the entire SiteConfig defined by /tmp/kust-plugin-config-913473579: stat extra-manifest3: no such file or directory Error: failure in plugin configured via /tmp/kust-plugin-config-913473579; exit status 1: exit status 1
Type: ComparisonError
Check the Status.Sync
field. If there are log errors, the Status.Sync
field could indicate an Unknown
error:
Status:
Sync:
Compared To:
Destination:
Namespace: clusters-sub
Server: https://kubernetes.default.svc
Source:
Path: sites-config
Repo URL: https://git.com/ran-sites/siteconfigs/.git
Target Revision: master
Status: Unknown
SuperMicro X11 servers do not support virtual media installations when the image is served using the https
protocol. As a result, single-node OpenShift deployments for this environment fail to boot on the target node. To avoid this issue, log in to the hub cluster and disable Transport Layer Security (TLS) in the Provisioning
resource. This ensures the image is not served with TLS even though the image address uses the https
scheme.
You have installed the OpenShift CLI (oc
).
You have logged in to the hub cluster as a user with cluster-admin
privileges.
Disable TLS in the Provisioning
resource by running the following command:
$ oc patch provisioning provisioning-configuration --type merge -p '{"spec":{"disableVirtualMediaTLS": true}}'
Continue the steps to deploy your single-node OpenShift cluster.
You can remove a managed site and the associated installation and configuration policy CRs from the GitOps Zero Touch Provisioning (ZTP) pipeline.
You have installed the OpenShift CLI (oc
).
You have logged in to the hub cluster as a user with cluster-admin
privileges.
Remove a site and the associated CRs by removing the associated SiteConfig
and PolicyGenerator
or PolicyGentemplate
files from the kustomization.yaml
file.
Add the following syncOptions
field to your SiteConfig
application.
kind: Application
spec:
syncPolicy:
syncOptions:
- PrunePropagationPolicy=background
When you run the GitOps ZTP pipeline again, the generated CRs are removed.
Optional: If you want to permanently remove a site, you should also remove the SiteConfig
and site-specific PolicyGenerator
or PolicyGentemplate
files from the Git repository.
Optional: If you want to remove a site temporarily, for example when redeploying a site, you can leave the SiteConfig
and site-specific PolicyGenerator
or PolicyGentemplate
CRs in the Git repository.
For information about removing a cluster, see Removing a cluster from management.
If a change to the PolicyGenerator
or PolicyGentemplate
configuration results in obsolete policies, for example, if you rename policies, use the following procedure to remove the obsolete policies.
You have installed the OpenShift CLI (oc
).
You have logged in to the hub cluster as a user with cluster-admin
privileges.
Remove the affected PolicyGenerator
or PolicyGentemplate
files from the Git repository, commit and push to the remote repository.
Wait for the changes to synchronize through the application and the affected policies to be removed from the hub cluster.
Add the updated PolicyGenerator
or PolicyGentemplate
files back to the Git repository, and then commit and push to the remote repository.
Removing GitOps Zero Touch Provisioning (ZTP) policies from the Git repository, and as a result also removing them from the hub cluster, does not affect the configuration of the managed cluster. The policy and CRs managed by that policy remains in place on the managed cluster. |
Optional: As an alternative, after making changes to PolicyGenerator
or PolicyGentemplate
CRs that result in obsolete policies, you can remove these policies from the hub cluster manually. You can delete policies from the RHACM console using the Governance tab or by running the following command:
$ oc delete policy -n <namespace> <policy_name>
You can remove the ArgoCD pipeline and all generated GitOps Zero Touch Provisioning (ZTP) artifacts.
You have installed the OpenShift CLI (oc
).
You have logged in to the hub cluster as a user with cluster-admin
privileges.
Detach all clusters from Red Hat Advanced Cluster Management (RHACM) on the hub cluster.
Delete the kustomization.yaml
file in the deployment
directory using the following command:
$ oc delete -k out/argocd/deployment
Commit and push your changes to the site repository.