https://issues.redhat.com/browse/ACM-25181 #8339
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,180 @@ | ||
| [#enable-gitops-addon-with-argocd] | ||
| = Enabling {gitops} add-on with _ArgoCD_ agent | ||
|
|
||
| Enable the {gitops-short} add-on for `Advanced` pull model with the `ArgoCD` agent to get detailed statuses on the health of your hub clusters, and to simplify your cluster management processes. To enable a GitOps add-on with the `ArgoCD` agent, complete the following sections: | ||
|
|
||
| * <<prerequisites, Prerequisites>> | ||
| * <<enable-argocd-agent, Enabling the _ArgoCD_ agent>> | ||
| * <<verify-installation, Verifying the installation>> | ||
| * <<additional-resources, Additional resources>> | ||
|
|
||
| [#prerequisites] | ||
| == Prerequisites | ||
|
|
||
| * {acm-short} hub cluster installed | ||
|
Contributor
There was a problem hiding this comment. Throughout the doc, these are complete sentences. We would be changing that with this prereq list. Usually: You need x or You have X. |
||
| * Managed clusters registered with {acm-short} | ||
| * OpenShift GitOps operator installed on the hub cluster | ||
|
Contributor
There was a problem hiding this comment. I think this is conref-ed in our docs--please check; please check on all product names internally and check the guidance if we don't have anything for this. Check all OCP and GitOps instances for conref and naming. |
||
| * A `Placement` resource to select target managed clusters | ||
| * `ManagedClusterSet` bound to the target namespace | ||
| * OpenShift GitOps operator subscription configured with the `ArgoCD` agent environment | ||
| * The `ArgoCD` custom resource configured for the `Agent` mode | ||
|
|
||
| [#configure-subscriptions-resources] | ||
| == Configuring subscriptions and resources | ||
|
|
||
| To enable the `ArgoCD` agent, you must configure the {gitops-short} operator subscription and the `ArgoCD` custom resource. To configure the necessary subscriptions and resources, complete the following steps: | ||
|
|
||
|
|
||
| . On the hub cluster only, modify the OpenShift GitOps operator subscription to include the required environment variables: | ||
|
|
||
| + | ||
| [source,bash] | ||
| ---- | ||
| oc edit subscription gitops-operator -n openshift-gitops-operator | ||
| ---- | ||
|
|
||
| . Add the following environment variables under `spec.config.env`: | ||
|
Contributor
There was a problem hiding this comment. please never use under, this can alienate a nonsighted user. We go over this in our internal doc very clearly: https://stolostron.github.io/rhacm-docs/accessibility Further we have this on the checklist: https://stolostron.github.io/rhacm-docs/checklist (directional language) |
||
|
|
||
| + | ||
| [source,yaml] | ||
| ---- | ||
| spec: | ||
| config: | ||
| env: | ||
| - name: ARGOCD_CLUSTER_CONFIG_NAMESPACES | ||
| value: openshift-gitops | ||
| - name: ARGOCD_PRINCIPAL_TLS_SERVER_ALLOW_GENERATE | ||
| value: "false" | ||
| - name: ARGOCD_PRINCIPAL_REDIS_SERVER_ADDRESS | ||
| value: openshift-gitops-redis:6379 | ||
| ---- | ||
|
|
||
| . Replace the existing `ArgoCD` custom resource with the compatible `Agent` mode configuration: | ||
|
|
||
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: argoproj.io/v1beta1 | ||
| kind: ArgoCD | ||
| metadata: | ||
| name: openshift-gitops | ||
| namespace: openshift-gitops | ||
| spec: | ||
| controller: | ||
| enabled: false | ||
| argoCDAgent: | ||
| principal: | ||
| allowedNamespaces: | ||
| - '*' | ||
| auth: mtls:CN=system:open-cluster-management:cluster:([^:]+):addon:gitops-addon:agent:gitops-addon-agent | ||
| enabled: true | ||
| ---- | ||
|
|
||
| * *Note:* On the hub cluster only, this configuration disables the traditional `ArgoCD` controller and enables the agent principal with mutual TLS authentication. | ||
|
|
||
| [#enable-argocd-agent] | ||
| == Enabling _ArgoCD_ agent | ||
|
|
||
| Create a `GitOpsCluster` resource to manage the `ArgoCD` agent add-on deployment. its controller automatically creates the following resources for each managed cluster selected by the `Placement` | ||
|
Contributor
There was a problem hiding this comment. Remove the possessive here and rewrite that line; see the IBM style guide about possessive. "its" is also not capitalized, but is a start a new sentence, I think? |
||
|
|
||
| The `GitOpsCluster` controller performs the following operations: | ||
|
|
||
| * Create and automated PKI management | ||
|
Contributor
There was a problem hiding this comment. The controller .... creates (add the s to make subject/predicate agree, |
||
| * Creates `ArgoCD` cluster secrets configured for agent mode | ||
|
Contributor
There was a problem hiding this comment. They are for Argo CD to understand what clusters are imported. |
||
| * Deploys the Argo CD Agent on each selected managed cluster | ||
|
Contributor
There was a problem hiding this comment. Sometimes Argo CD is coded, see above examples, and sometimes not. |
||
|
|
||
| To enable the advanced pull model Argo CD Agent architecture, complete the following steps: | ||
|
|
||
| . Create a `GitOpsCluster resource with the `ArgoCD` agent enabled by inputting the following YAML sample: | ||
|
Contributor
There was a problem hiding this comment. inputting? We normally keep it simple: Add the following YAML to create ___ Create ___ by adding the following YAML. Are they adding the entire sample and what from it matters to the user. We don't want to just give them a big sample and not explain it. |
||
|
|
||
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: apps.open-cluster-management.io/v1beta1 | ||
| kind: GitOpsCluster | ||
| metadata: | ||
| name: gitops-agent-clusters | ||
| namespace: openshift-gitops | ||
| spec: | ||
| argoServer: | ||
| argoNamespace: openshift-gitops | ||
| placementRef: | ||
| kind: Placement | ||
| apiVersion: cluster.open-cluster-management.io/v1beta1 | ||
| name: production-clusters | ||
| namespace: openshift-gitops | ||
| gitopsAddon: | ||
| enabled: true | ||
| argoCDAgent: | ||
| enabled: true | ||
| ---- | ||
|
|
||
| [#verify-installation] | ||
| == Verifying the installation | ||
|
|
||
| After the `ArgoCD` agent is successfully deployed, verify the advanced `Pull Model` workflow is completed by creating an application on the hub cluster and confirming it works on the managed cluster. | ||
|
|
||
| To verify the necessary installations and resources for successful deployment, complete the following steps: | ||
|
|
||
| . Check the `GitOpsCluster` status for specific `Agent` conditions by running the following command: | ||
|
|
||
| + | ||
| [source,bash] | ||
| ---- | ||
| oc get gitopscluster gitops-agent-clusters -n openshift-gitops -o jsonpath='{.status.conditions}' | jq | ||
| ---- | ||
|
|
||
| . Confirm that you see the following condition types in the status: | ||
|
|
||
| + | ||
| * `ArgoCDAgentPrereqsReady` - Agent prerequisites are set up | ||
| * `CertificatesReady` - TLS certificates are signed | ||
| * `ManifestWorksApplied` - CA certificates propagated to managed clusters | ||
|
Contributor
There was a problem hiding this comment.
Sorry, we added new conditions. Please see above for the full list. |
||
|
|
||
| . On the hub cluster, create an `ArgoCD` application resource in the managed cluster namespace by inputting the following YAML file: | ||
|
|
||
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: argoproj.io/v1alpha1 | ||
| kind: Application | ||
| metadata: | ||
| name: guestbook | ||
| namespace: <managed cluster name> | ||
| spec: | ||
| project: default | ||
| source: | ||
| repoURL: https://github.com/argoproj/argocd-example-apps.git | ||
| targetRevision: HEAD | ||
| path: guestbook | ||
| destination: | ||
| server: https://<principal-external-ip:port>?agentName=<managed cluster name> | ||
| namespace: guestbook | ||
| syncPolicy: | ||
| automated: | ||
| prune: true | ||
| selfHeal: true | ||
| ---- | ||
|
|
||
| . On the managed cluster, verify that the application resources are deployed by running the following command: | ||
|
|
||
| + | ||
| [source,bash] | ||
| ---- | ||
| oc get all -n guestbook | ||
| ---- | ||
|
|
||
| . On the hub cluster, verify the application status is reflected back to you by running the following command: | ||
|
|
||
| + | ||
| [source,bash] | ||
| ---- | ||
| oc get application guestbook -n <managed cluster name> | ||
| ---- | ||
|
|
||
| . Confirm that the status shows `Synced` when the application is successfully deployed. | ||
|
|
||
| [#additional-resources] | ||
| == Additional resources | ||
|
|
||
| Continue learning about the {gitops-short} add-on by completing xref:../gitops/gitops_manage_addon.adoc#manage-gitops-addon[Managing the {gitops} add-on]. | ||
|
Contributor
There was a problem hiding this comment. I would take out learning here since they are heading to a task and not a concept and you are telling them to "complete" something? |
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| [#enable-gitops-addon-without-argocd] | ||
| = Enabling {gitops} add-on without the _ArgoCD_ agent | ||
|
|
||
| The `Basic` pull model does not include the `ArgoCD` agent, so it gives you a simpler setup for your hub cluster management and only gives you the necessary statuses of the health of your hub clusters. | ||
|
Contributor
There was a problem hiding this comment. Same with the GitOps name throughout, see where the conref needs to be used. |
||
|
|
||
| To enable a GitOps add-on without the `ArgoCD` agent, complete the following sections: | ||
|
|
||
| * <<prerequisites, Prerequisites>> | ||
| * <<create-gitopscluster-resource, Creating a _GitOpsCluster_ resource>> | ||
| * <<verify-installation, Verifying the installation>> | ||
| * <<additional-resources, Additional resources>> | ||
|
|
||
| [#prerequisites] | ||
| == Prerequisites | ||
|
Contributor
There was a problem hiding this comment. Same feedback. You tell them to "complete" this section in the line before, so I would go with different language, but either way these are complete sentences in most of the books. Ensure you have an {acm-short} hub cluster installed. |
||
|
|
||
| * {acm-short} hub cluster installed | ||
| * Managed clusters registered with {acm-short} | ||
| * OpenShift GitOps operator installed on the hub cluster | ||
| * A `Placement` resource to select target managed clusters | ||
| * `ManagedClusterSet` bound to the target namespace | ||
|
|
||
| [#create-gitopscluster-resource] | ||
| == Creating a `GitOpsCluster` resource | ||
|
|
||
| To enable basic pull model, create a `GitOpsCluster` resource, its controller automatically creates the following resources for each managed cluster selected by the `Placement` policy: | ||
|
|
||
| * `AddOnDeploymentConfig` resource in the managed cluster namespace | ||
| * `ManagedClusterAddOn` resource in the managed cluster namespace | ||
|
|
||
| The {gitops} add-on deploys to each selected managed cluster and installs the following resources: | ||
|
|
||
| * OpenShift GitOps operator in the `openshift-gitops-operator` namespace | ||
| * ArgoCD instance in the `openshift-gitops` namespace | ||
|
|
||
| To create a `GitOpsCluster` resource, complete the following steps: | ||
|
|
||
| . On your hub cluster, create a `GitOpsCluster` resource to enable the {gitops} add-on: | ||
|
|
||
|
|
||
| + | ||
| [source,yaml] | ||
| ---- | ||
| apiVersion: apps.open-cluster-management.io/v1beta1 | ||
| kind: GitOpsCluster | ||
| metadata: | ||
| name: gitops-clusters | ||
| namespace: openshift-gitops | ||
| spec: | ||
| argoServer: | ||
| argoNamespace: openshift-gitops | ||
| placementRef: | ||
| kind: Placement | ||
| apiVersion: cluster.open-cluster-management.io/v1beta1 | ||
| name: all-openshift-clusters | ||
| namespace: openshift-gitops | ||
| gitopsAddon: | ||
| enabled: true | ||
| ---- | ||
|
|
||
| [#verify-installation] | ||
| == Verifying the installation | ||
|
|
||
| To verify the necessary installations and resources for successful deployment, complete the following steps: | ||
|
|
||
| . Verify that the `GitOpsCluster` resource has a status for successful deployment by running the following command: | ||
|
|
||
| + | ||
| [source,bash] | ||
| ---- | ||
| oc get gitopscluster gitops-clusters -n openshift-gitops -o yaml | ||
| ---- | ||
|
|
||
| . Verify that the GitOps add-on controller is working by running the following command: | ||
|
Contributor
There was a problem hiding this comment. This command and the following commands are meant to run on the managed cluster (where the addon is installed). |
||
|
|
||
| + | ||
| [source,bash] | ||
| ---- | ||
| oc get pods -n open-cluster-management-agent-addon | ||
| ---- | ||
|
|
||
| . Verify the OpenShift GitOps operator is working by running the following command: | ||
|
|
||
| + | ||
| [source,bash] | ||
| ---- | ||
| oc get pods -n openshift-gitops-operator | ||
| ---- | ||
|
|
||
| . Verify the Argo CD instance is working by running the following command: | ||
|
|
||
| + | ||
| [source,bash] | ||
| ---- | ||
| oc get pods -n openshift-gitops | ||
| ---- | ||
|
|
||
| [#additional-resources] | ||
| == Additional resources | ||
|
|
||
| Continue learning about the {gitops-short} add-on by completing xref:../gitops/gitops_manage_addon.adoc#manage-gitops-addon[Managing the {gitops} add-on]. | ||
|
Contributor
There was a problem hiding this comment. same with "learning" but you are sending them to a task to "complete" |
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Feedback for the entire collection here:
This was a lot, great job. I think it's getting close to done.
Themes:
The YAML additions are missing details or specifics.
All of them are also missing the step to apply the command. I have shown this previously, but there are also examples in the doc if you need to see what I mean. We give them a sample to add, explain it a bit, then give them the command to apply.
Usually something like:
oc apply(check for sure)Couple other smaller things.