diff --git a/content/patterns/rhoso-gitops/_index.adoc b/content/patterns/rhoso-gitops/_index.adoc index 9817e8e08..deec77f6a 100644 --- a/content/patterns/rhoso-gitops/_index.adoc +++ b/content/patterns/rhoso-gitops/_index.adoc @@ -27,10 +27,3 @@ include::modules/comm-attributes.adoc[] include::modules/rhoso-gitops/rhoso-gitops-about.adoc[leveloffset=+1] include::modules/rhoso-gitops/rhoso-gitops-architecture.adoc[leveloffset=+1] - -[id="next-steps_rhoso-gitops-index"] -== Next steps - -* link:getting-started[Deploy the pattern] -* link:cluster-sizing[Review cluster sizing requirements] -* link:configuration[Configure upstream pins and overrides] diff --git a/content/patterns/rhoso-gitops/cluster-sizing.adoc b/content/patterns/rhoso-gitops/cluster-sizing.adoc index fe3e9ac0b..5a9d7a68e 100644 --- a/content/patterns/rhoso-gitops/cluster-sizing.adoc +++ b/content/patterns/rhoso-gitops/cluster-sizing.adoc @@ -10,25 +10,26 @@ aliases: /rhoso-gitops/cluster-sizing/ include::modules/comm-attributes.adoc[] include::modules/rhoso-gitops/metadata-rhoso-gitops.adoc[] -include::modules/cluster-sizing-template.adoc[] +[id="rhoso-gitops-cluster-requirements"] +== Cluster requirements + +{rh-rhoso-short} requires baremetal infrastructure for both the {rh-ocp} cluster +and the compute nodes. Cloud-based instance types (AWS, GCP, Azure) are not +supported. + +For detailed hardware, software, and network requirements, see +link:https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/planning_your_deployment/assembly_infrastructure-and-system-requirements[Infrastructure and system requirements] +in the {rh-rhoso} _Planning your deployment_ guide. [id="rhoso-gitops-dataplane-hosts"] == Data plane host requirements -The preceding hub cluster sizing tables cover the {rh-ocp} nodes that host the -{rh-rhoso-short} control plane. -A full {rh-rhoso-short} deployment also -requires separate {rhel-short} hosts for the data plane (compute nodes running -data plane elements). +In addition to the {rh-ocp} cluster that hosts the {rh-rhoso-short} control +plane, a full {rh-rhoso-short} deployment requires separate {rhel-short} hosts +for the data plane (compute nodes running data plane elements). Plan additional {rhel-short} capacity beyond the OpenShift worker sizing in `pattern-metadata.yaml`. For Operator stages, sync order, and version pins, see the pattern repository link:https://github.com/validatedpatterns-sandbox/rhoso-gitops/blob/main/VERSIONS.md[VERSIONS.md] file. - -[id="next-steps_rhoso-gitops-cluster-sizing"] -== Next steps - -* link:../getting-started/[Deploy the pattern] -* link:../configuration/[Configure upstream pins and overrides] diff --git a/content/patterns/rhoso-gitops/configuration.adoc b/content/patterns/rhoso-gitops/configuration.adoc index e24d606fd..e5a28a8de 100644 --- a/content/patterns/rhoso-gitops/configuration.adoc +++ b/content/patterns/rhoso-gitops/configuration.adoc @@ -10,9 +10,3 @@ aliases: /rhoso-gitops/configuration/ include::modules/comm-attributes.adoc[] include::modules/rhoso-gitops/rhoso-gitops-configuration.adoc[leveloffset=+1] - -[id="next-steps_rhoso-gitops-configuration"] -== Next steps - -* link:../getting-started/[Deploy the pattern] -* link:../troubleshooting/[Troubleshoot the pattern] diff --git a/content/patterns/rhoso-gitops/getting-started.adoc b/content/patterns/rhoso-gitops/getting-started.adoc index 9e27f0fa3..98ccfc17d 100644 --- a/content/patterns/rhoso-gitops/getting-started.adoc +++ b/content/patterns/rhoso-gitops/getting-started.adoc @@ -10,10 +10,3 @@ aliases: /rhoso-gitops/getting-started/ include::modules/comm-attributes.adoc[] include::modules/rhoso-gitops/rhoso-gitops-deploying.adoc[leveloffset=+1] - -[id="next-steps_rhoso-gitops-getting-started"] -== Next steps - -* link:../configuration/[Configure the pattern] -* link:../cluster-sizing/[Review cluster sizing] -* link:../troubleshooting/[Troubleshoot the pattern] diff --git a/content/patterns/rhoso-gitops/troubleshooting.adoc b/content/patterns/rhoso-gitops/troubleshooting.adoc index 6789b2106..c85da986d 100644 --- a/content/patterns/rhoso-gitops/troubleshooting.adoc +++ b/content/patterns/rhoso-gitops/troubleshooting.adoc @@ -53,22 +53,22 @@ The pattern uses two Argo CD namespaces. List applications in each namespace: $ oc get applications -n vp-gitops ---- -. List applications in `openshift-gitops`: +. List applications in `rhoso-gitops-standalone`: + [source,terminal] ---- -$ oc get applications -n openshift-gitops +$ oc get applications -n rhoso-gitops-standalone ---- . Inspect a child application that is out of sync or unhealthy: + [source,terminal] ---- -$ oc describe application -n openshift-gitops +$ oc describe application -n rhoso-gitops-standalone ---- -Use the Argo CD UI in the `openshift-gitops` namespace to review sync waves, -resource health, and diff details for upstream overlays. +Use the Argo CD UI in the `rhoso-gitops-standalone` namespace to review +application status, resource health, and diff details for upstream overlays. [id="rhoso-gitops-check-pods"] == Checking pod status @@ -103,13 +103,8 @@ The following known issues can affect pattern deployment: link:https://github.com/openstack-k8s-operators/gitops[openstack-k8s-operators/gitops]. * *Operator install delays*: Infrastructure Operators in `operator-dependencies` subscribe from the cluster catalog; allow time for OLM to resolve - `ClusterServiceVersions` (CSVs) before later sync waves run. + `ClusterServiceVersions` (CSVs). Other applications retry automatically + until their dependencies are satisfied. For community support, open an issue in the link:https://github.com/validatedpatterns-sandbox/rhoso-gitops/issues[pattern repository]. - -[id="next-steps_rhoso-gitops-troubleshooting"] -== Next steps - -* link:../getting-started/[Deploy the pattern] -* link:../configuration/[Configure the pattern] diff --git a/modules/rhoso-gitops/rhoso-gitops-about.adoc b/modules/rhoso-gitops/rhoso-gitops-about.adoc index 8aadf3c77..d712aa187 100644 --- a/modules/rhoso-gitops/rhoso-gitops-about.adoc +++ b/modules/rhoso-gitops/rhoso-gitops-about.adoc @@ -52,7 +52,7 @@ fan-out. | Yes | {solution-name-upstream} clustergroup (`values-standalone.yaml`), *rhoso-gitops* meta-chart, and child {rh-rhoso-short} Applications in - `openshift-gitops` + `rhoso-gitops-standalone` | Managed clusters | None diff --git a/modules/rhoso-gitops/rhoso-gitops-architecture.adoc b/modules/rhoso-gitops/rhoso-gitops-architecture.adoc index 81ee4e9dc..37b381bc9 100644 --- a/modules/rhoso-gitops/rhoso-gitops-architecture.adoc +++ b/modules/rhoso-gitops/rhoso-gitops-architecture.adoc @@ -7,7 +7,7 @@ The {rhoso-gitops-pattern} delivers {rh-rhoso-short} configuration through Argo CD Applications that the *rhoso-gitops* meta-chart creates. Use this overview to understand GitOps delivery, the dual Argo CD namespaces, infrastructure topology, -and sync-wave order before you deploy or customize the pattern. +and deployment convergence before you deploy or customize the pattern. [id="rhoso-gitops-gitops-delivery"] == GitOps delivery flow @@ -23,18 +23,18 @@ The delivery path is: . The {validated-patterns-op} reconciles the pattern clustergroup . The parent *rhoso-gitops* Application runs in `vp-gitops` ({solution-name-upstream} GitOps) -. The meta-chart renders child Applications in `openshift-gitops` - ({gitops-title}) -. The child apps sync upstream `example/*` overlays in order (Operators, - networks, control plane, data plane) +. The meta-chart renders child Applications in `rhoso-gitops-standalone` + (dedicated Argo CD instance) +. The child apps sync upstream `example/*` overlays (Operators, + networks, control plane, data plane) and converge through retry policies -.GitOps application delivery and sync-wave ordering -image::rhoso-gitops/rhoso-gitops-applications.svg[{rhoso-gitops-pattern} GitOps application delivery,700] +.GitOps application delivery +image::rhoso-gitops/rhoso-gitops-applications.png[{rhoso-gitops-pattern} GitOps application delivery] The diagram shows the parent Application in `vp-gitops`, child Applications in -`openshift-gitops`, and the upstream Kustomize overlays they sync. Sync-wave -annotations order deployment from infrastructure Operators through the data -plane. +`rhoso-gitops-standalone`, and the upstream Kustomize overlays they sync. +All child Applications deploy at sync-wave 0 and converge eventually through +retry policies. [id="rhoso-gitops-dual-argocd"] == Dual Argo CD namespaces @@ -43,8 +43,9 @@ The pattern uses two Argo CD namespaces: * The {validated-patterns-op} deploys the parent *rhoso-gitops* Application into *`vp-gitops`* ({solution-name-upstream} GitOps). -* The meta-chart creates child {rh-rhoso-short} Applications in - *`openshift-gitops`* ({gitops-title} Operator), per the chart defaults. +* Child {rh-rhoso-short} Applications are created in *`rhoso-gitops-standalone`*, + a dedicated Argo CD instance managed by the pattern (see `applicationNamespace` + in the chart). [id="rhoso-gitops-infrastructure-topology"] == Infrastructure topology @@ -57,51 +58,25 @@ The preceding GitOps flow describes *how* GitOps delivers configuration. The following diagram and list describe *what* gets deployed: .{rh-rhoso-short} infrastructure topology -image::rhoso-gitops/rhoso-gitops-infrastructure.svg[{rhoso-gitops-pattern} infrastructure topology,700] +image::rhoso-gitops/rhoso-gitops-infrastructure.png[{rhoso-gitops-pattern} infrastructure topology] * *OpenShift cluster*: Control-plane nodes run OpenStack Operators and `OpenStackControlPlane` services. * *Data plane hosts*: One or more {rhel-short} compute nodes run {rh-rhoso-short} data plane elements and connect to the control plane. -[id="rhoso-gitops-sync-waves"] -== Application sync order +[id="rhoso-gitops-deployment-convergence"] +== Deployment convergence -Child Applications deploy in sync-wave order when Argo CD reconciles the parent -*rhoso-gitops* Application: +All child Applications deploy at sync-wave `0` (the default) when Argo CD +reconciles the parent *rhoso-gitops* Application. Argo CD launches every child +simultaneously; each retries (per `syncPolicy.retry`) until its upstream +dependencies are satisfied and converges eventually. -[cols="2,3,1",options="header"] -|=== -| Application | Purpose | Sync wave - -| `operator-dependencies` -| Infrastructure Operators (cert-manager, MetalLB, nmstate, observability) -| `-20` - -| `openstack-operator` -| OpenStack Operator subscription -| `-20` - -| `openstack-operator-cr` -| Main `OpenStack` custom resource -| `-15` - -| `openstack-secrets` -| Secure-backend sync (disabled by default) -| `-10` - -| `openstack-networks` -| Network configuration -| `0` - -| `openstack-controlplane` -| `OpenStackControlPlane` -| `10` - -| `openstack-dataplane` -| Data plane -| `20` -|=== +For the full list of child applications, their upstream paths, and links to the +corresponding {rh-rhoso} product documentation, see +xref:rhoso-gitops-configuration[Configuration] > +xref:rhoso-gitops-upstream-applications[Upstream applications]. After you change overrides, confirm child apps in the Argo CD UI or with -`oc get applications -n openshift-gitops`. +`oc get applications -n rhoso-gitops-standalone`. diff --git a/modules/rhoso-gitops/rhoso-gitops-configuration.adoc b/modules/rhoso-gitops/rhoso-gitops-configuration.adoc index 32263837b..9af92c230 100644 --- a/modules/rhoso-gitops/rhoso-gitops-configuration.adoc +++ b/modules/rhoso-gitops/rhoso-gitops-configuration.adoc @@ -46,54 +46,78 @@ To change upstream Git content (revision, paths, enable or disable apps), edit sync reconcile, per `global.options.syncPolicy` in `values-global.yaml`). [id="rhoso-gitops-upstream-applications"] -== Upstream applications (default `v0.1.0`) +== Upstream applications Child Argo CD Applications sync from link:https://github.com/openstack-k8s-operators/gitops[openstack-k8s-operators/gitops] at the revision pinned in `overrides/values-rhoso-gitops.yaml`. +[IMPORTANT] +==== +The `example/` overlays shipped in the upstream repository are *reference samples +only*. They will not produce a working deployment on your infrastructure. +To deploy {rh-rhoso-short}, point each application at your own Git overlay +(see xref:rhoso-gitops-repoint-overlay[Pointing an application to your Git overlay]). +==== + .Default upstream applications -[cols="2,2,1",options="header"] +[cols="2,3,2,3",options="header"] |=== -| Argo CD application | Upstream path | Enabled +| Application | Purpose | Upstream path | {rh-rhoso} docs | `operator-dependencies` -| `example/dependencies` -| Yes +| Infrastructure Operators (cert-manager, MetalLB, nmstate, observability) +| link:https://github.com/openstack-k8s-operators/gitops/tree/main/example/dependencies[`example/dependencies`] +| link:https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/planning_your_deployment/assembly_infrastructure-and-system-requirements#ref_RHOCP-software-requirements_planning[Planning your deployment 3.1.3] | `openstack-operator` -| `example/openstack-operator` -| Yes +| OpenStack Operator subscription +| link:https://github.com/openstack-k8s-operators/gitops/tree/main/example/openstack-operator[`example/openstack-operator`] +| link:https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/deploying_red_hat_openstack_services_on_openshift/assembly_installing-and-preparing-the-openstack-operator[Deploying RHOSO ch. 1] | `openstack-operator-cr` -| `example/openstack-operator-cr` -| Yes +| Main `OpenStack` custom resource +| link:https://github.com/openstack-k8s-operators/gitops/tree/main/example/openstack-operator-cr[`example/openstack-operator-cr`] +| link:https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/deploying_red_hat_openstack_services_on_openshift/assembly_installing-and-preparing-the-openstack-operator[Deploying RHOSO ch. 1] | `openstack-secrets` +| Secure-backend sync (disabled by default) | not configured (`path: TODO`) -| No +| link:https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/deploying_red_hat_openstack_services_on_openshift/assembly_preparing-rhocp-for-rhoso#proc_providing-secure-access-to-the-RHOSO-services_preparing[Deploying RHOSO ch. 2.3] | `openstack-networks` -| `example/openstack-networks` -| Yes +| Network configuration +| link:https://github.com/openstack-k8s-operators/gitops/tree/main/example/openstack-networks[`example/openstack-networks`] +| link:https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/deploying_red_hat_openstack_services_on_openshift/assembly_preparing-rhoso-networks_preparing[Deploying RHOSO ch. 3] | `openstack-controlplane` -| `example/openstack-controlplane` -| Yes +| `OpenStackControlPlane` +| link:https://github.com/openstack-k8s-operators/gitops/tree/main/example/openstack-controlplane[`example/openstack-controlplane`] +| link:https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/deploying_red_hat_openstack_services_on_openshift/assembly_creating-the-control-plane[Deploying RHOSO ch. 4] | `openstack-dataplane` -| `example/openstack-dataplane` -| Yes +| Data plane +| link:https://github.com/openstack-k8s-operators/gitops/tree/main/example/openstack-dataplane[`example/openstack-dataplane`] +| link:https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/deploying_red_hat_openstack_services_on_openshift/assembly_creating-the-data-plane[Deploying RHOSO ch. 5] |=== -For product, framework, upstream Git, and Operator versions, see the pattern -repository -link:https://github.com/validatedpatterns-sandbox/rhoso-gitops/blob/main/VERSIONS.md[VERSIONS.md] -file. +All applications are enabled by default (except `openstack-secrets`) and use +automated sync with a retry policy to handle transient failures during +deployment convergence. [id="rhoso-gitops-pin-revision"] == Pinning a different upstream revision +Child applications use *automated sync* by default: Argo CD reconciles them +whenever the upstream Git repository changes. If `targetRevision` points to a +branch name like `main` or `HEAD`, any push to that branch triggers an automatic +deployment, which can cause unexpected changes in production. + +[IMPORTANT] +==== +Always pin `targetRevision` to a *tag* or *commit hash* for stability. +==== + In `overrides/values-rhoso-gitops.yaml`, set `targetRevision` for each application that you want to pin: @@ -101,14 +125,29 @@ application that you want to pin: ---- applications: openstack-operator: - targetRevision: "v0.2.0" + targetRevision: "v0.2.0" # tag — recommended openstack-controlplane: - targetRevision: "v0.2.0" + targetRevision: "abc123def456" # commit hash — also safe ---- Apply the same key under every application you want on that revision, or only the entries that you want to change; unspecified keys keep chart defaults. +[id="rhoso-gitops-disable-automated-sync"] +== Disabling automated sync for an application + +To switch a specific application to manual sync, override its `syncPolicy` +without the `automated` key: + +[source,yaml] +---- +applications: + openstack-dataplane: + syncPolicy: + syncOptions: + - Prune=true +---- + [id="rhoso-gitops-disable-stage"] == Disabling a deployment stage @@ -121,6 +160,31 @@ applications: enabled: false ---- +[id="rhoso-gitops-custom-retry"] +== Setting a custom retry policy + +To override the default retry policy for an application: + +[source,yaml] +---- +applications: + openstack-controlplane: + syncPolicy: + automated: + prune: true + selfHeal: true + retry: + limit: 20 + backoff: + duration: "10s" + factor: 2 + maxDuration: "5m" +---- + +Refer to the Argo CD +link:https://argo-cd.readthedocs.io/en/stable/user-guide/auto_sync/#automatic-sync-semantics[automatic sync documentation] +for available retry options. + [id="rhoso-gitops-repoint-overlay"] == Pointing an application to your Git overlay @@ -162,15 +226,34 @@ README. {hashicorp-vault-short}). The bootstrap credential must not live in Git. Complete the following steps: -. Create the `openstack` namespace (or the namespace your overlay specifies). -. Create the Kubernetes `Secret` out of band (`oc create secret generic ...`). -. Add a Kustomize overlay in *your* Git repository for secret wiring (non-sensitive - manifests only). -. Enable and configure `applications.openstack-secrets` in - `overrides/values-rhoso-gitops.yaml` (`enabled: true`, `repoURL`, `path`, - `targetRevision`, optional `kustomize` patches). -. Install the secrets Operator through `operator-dependencies` by using - `kustomize.components` URLs from the upstream secrets components. +. Configure the secret wiring *before* deploying the pattern: +.. Add a Kustomize overlay in *your* Git repository for secret wiring (non-sensitive + manifests only). +.. Enable and configure `applications.openstack-secrets` in + `overrides/values-rhoso-gitops.yaml` (`enabled: true`, `repoURL`, `path`, + `targetRevision`, optional `kustomize` patches). +.. Install the secrets Operator through `operator-dependencies` by using + `kustomize.components` URLs from the upstream secrets components. +. While the pattern is deploying, *wait* for the `openstack` namespace to appear + (it is created by an earlier Argo CD application), then inject the bootstrap + `Secret` out of band in a separate terminal (`oc create secret generic ...`). + If you are working remotely, use `tmux` or `screen` so you can monitor the + deployment and inject the secret in parallel. ++ +[IMPORTANT] +==== +Do *not* create the `openstack` namespace manually. Argo CD creates it during +deployment, and a pre-existing namespace causes ownership conflicts. Instead, +poll for the namespace and inject the secret as soon as it appears: + +[source,terminal] +---- +$ while ! oc get namespace openstack &>/dev/null; do sleep 10; done +$ oc create secret generic \ + --from-literal== \ + -n openstack --dry-run=client -o yaml | oc apply -f - +---- +==== For standalone Helm usage and advanced chart examples, see the upstream link:https://github.com/openstack-k8s-operators/gitops/tree/main/charts/rhoso-apps[rhoso-apps chart]. diff --git a/modules/rhoso-gitops/rhoso-gitops-deploying.adoc b/modules/rhoso-gitops/rhoso-gitops-deploying.adoc index 8faf0f4a2..8f39d8985 100644 --- a/modules/rhoso-gitops/rhoso-gitops-deploying.adoc +++ b/modules/rhoso-gitops/rhoso-gitops-deploying.adoc @@ -91,11 +91,11 @@ $ ./pattern.sh make install $ oc get applications -n vp-gitops ---- -. List Argo CD applications in `openshift-gitops`: +. List Argo CD applications in `rhoso-gitops-standalone`: + [source,terminal] ---- -$ oc get applications -n openshift-gitops +$ oc get applications -n rhoso-gitops-standalone ---- . After install, run the pattern health check: diff --git a/static/images/rhoso-gitops/rhoso-gitops-applications.png b/static/images/rhoso-gitops/rhoso-gitops-applications.png new file mode 100644 index 000000000..d800e9aef Binary files /dev/null and b/static/images/rhoso-gitops/rhoso-gitops-applications.png differ diff --git a/static/images/rhoso-gitops/rhoso-gitops-applications.svg b/static/images/rhoso-gitops/rhoso-gitops-applications.svg deleted file mode 100644 index 633860e1f..000000000 --- a/static/images/rhoso-gitops/rhoso-gitops-applications.svg +++ /dev/null @@ -1,242 +0,0 @@ - - - - - - - - - - - - -Validated Pattern: rhoso-​gitopsWave -20: operator-​dependenciesInfra + VSO/ESOWave -20: openstack-​operatorOpenStack operatorWave -15: openstack-​operator-​crMain OpenStack CRWave -10: openstack-​secretsSecure backend syncWave 0: openstack-​networksNetworksWave 10: openstack-​controlplaneOpenStackControlPlaneWave 20: openstack-​dataplaneData planeOpenShift Cluster (OCP)Red Hat OpenStack Services on OpenShift - - creates - - creates - - syncWave 20 - - syncWave 20 - - syncWave 15 - - syncWave 10 - - syncWave 0 - - syncWave 10 - - deploys to \ No newline at end of file diff --git a/static/images/rhoso-gitops/rhoso-gitops-infrastructure.png b/static/images/rhoso-gitops/rhoso-gitops-infrastructure.png new file mode 100644 index 000000000..e0c8f3cd5 Binary files /dev/null and b/static/images/rhoso-gitops/rhoso-gitops-infrastructure.png differ diff --git a/static/images/rhoso-gitops/rhoso-gitops-infrastructure.svg b/static/images/rhoso-gitops/rhoso-gitops-infrastructure.svg deleted file mode 100644 index 323addd9a..000000000 --- a/static/images/rhoso-gitops/rhoso-gitops-infrastructure.svg +++ /dev/null @@ -1,252 +0,0 @@ - - - - - - - - - - - - -OpenShift Cluster (OCP)Control Plane Nodes (3 masters)master-1master-2master-3RHOSO Control PlaneOpenStack OperatorsOpenStackControlPlane ServicesData Plane Hosts (N compute nodes)Compute NodeRHELRHOSO Data Plane Elements (nova-​compute, etc.) - - contains - - includes - - includes - - includes - - contains - - manages - - hosts - - contains - - runs - - supports - - controlsCompute NodeCompute nodes \ No newline at end of file