https://issues.redhat.com/browse/ACM-25181 #8339
Conversation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: jc-berger The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
gitops/gitops_manage_addon.adoc
Outdated
| * <<Prerequisites, Prerequisites>> | ||
| * <<configure-gitops-addon, Configuring GitOps add-on settings>> | ||
| * <<skip-gitops-addon, Skipping the GitOps add-on enhancement>> | ||
| * << skip-enforcements-argocd, Skipping enforcements by customizing the _ArgoCD_ custom resource>> |
There was a problem hiding this comment.
I didn't catch this error until the preview in Github. I'll fix its rendering when addressing other feedback. thanks!
mikeshng
left a comment
mikeshng
left a comment
There was a problem hiding this comment.
There is a big uninstall/delete/cleanup change. I will comment in Slack.
| [#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: |
There was a problem hiding this comment.
Why do we have Advanced coded here?
There was a problem hiding this comment.
missing comma spacing issue.
| [#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: |
There was a problem hiding this comment.
| 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: | |
| 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 | ||
|
|
||
| * {acm-short} hub cluster installed |
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.
|
|
||
| * {acm-short} hub cluster installed | ||
| * Managed clusters registered with {acm-short} | ||
| * OpenShift GitOps operator installed on the hub cluster |
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.
| oc edit subscription gitops-operator -n openshift-gitops-operator | ||
| ---- | ||
|
|
||
| . Add the following environment variables under `spec.config.env`: |
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)
| [#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` |
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 |
There was a problem hiding this comment.
The controller .... creates (add the s to make subject/predicate agree,
| The `GitOpsCluster` controller performs the following operations: | ||
|
|
||
| * Create and automated PKI management | ||
| * Creates `ArgoCD` cluster secrets configured for agent mode |
There was a problem hiding this comment.
They are for Argo CD to understand what clusters are imported.
Argo CD by default does not understand ACM's ManagedClusters.
This progress is equivalent of: importing all the ACM's ManagedClusters (selected by the Placement) into Argo CD.
|
|
||
| * Create and automated PKI management | ||
| * Creates `ArgoCD` cluster secrets configured for agent mode | ||
| * Deploys the Argo CD Agent on each selected managed cluster |
There was a problem hiding this comment.
Sometimes Argo CD is coded, see above examples, and sometimes not.
| To create a `GitOpsCluster` resource with the `ArgoCD` agent, complete the following steps: | ||
|
|
||
| . Create a `GitOpsCluster resource with the `ArgoCD` agent enabled by inputting the following YAML sample: |
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.
| [#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]. |
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?
| [#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. |
There was a problem hiding this comment.
Same with the GitOps name throughout, see where the conref needs to be used.
| * <<additional-resources, Additional resources>> | ||
| [#prerequisites] | ||
| == Prerequisites |
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.
Register your
Install OCP GitOps operator
etc...
| [#create-gitopscluster-resource] | ||
| == Creating a `GitOpsCluster` resource | ||
|
|
||
| Instead of using an `ArgoCD` agent, you can install a `GitOpsCluster` resource. After you install a `GitOpsCluster` resource, its controller automatically creates the following resources for each managed cluster selected by the `Placement` policy: |
There was a problem hiding this comment.
same with possessive. I usually just say "the"
|
|
||
| Instead of using an `ArgoCD` agent, you can install a `GitOpsCluster` resource. After you install a `GitOpsCluster` resource, its controller automatically creates the following resources for each managed cluster selected by the `Placement` policy: | ||
|
|
||
| * `AddOnDeploymentConfig` in the managed cluster namespace |
There was a problem hiding this comment.
| * `AddOnDeploymentConfig` in the managed cluster namespace | |
| * `AddOnDeploymentConfig` resource in the managed cluster namespace |
| Instead of using an `ArgoCD` agent, you can install a `GitOpsCluster` resource. After you install a `GitOpsCluster` resource, its controller automatically creates the following resources for each managed cluster selected by the `Placement` policy: | ||
|
|
||
| * `AddOnDeploymentConfig` in the managed cluster namespace | ||
| * `ManagedClusterAddOn` in the managed cluster namespace |
There was a problem hiding this comment.
| * `ManagedClusterAddOn` in the managed cluster namespace | |
| * `ManagedClusterAddOn` resource in the managed cluster namespace |
| To create a `GitOpsCluster` resource, complete the following steps: | ||
|
|
||
| . On your hub cluster, create a `GitOpsCluster` resource to enable the {gitops} add-on: |
| oc get gitopscluster gitops-clusters -n openshift-gitops -o yaml | ||
| ---- | ||
|
|
||
| . Verify that the GitOps add-on controller is working by running the following command: |
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).
| [#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]. |
There was a problem hiding this comment.
same with "learning" but you are sending them to a task to "complete"
| @@ -0,0 +1,244 @@ | |||
| [#manage-gitops-addon] | |||
| [#manage-gitops-addon] | ||
| = Managing the {gitops} add-on | ||
|
|
||
| The {gitops-short} add-on automates the deployment and lifecycle management of the managed clusters. Based on your architecture and connectivity requirements, decide if you want to deploy the GitOps add-on with the `ArgoCD` agent component. |
There was a problem hiding this comment.
I am left hanging here a little.
If I do, do I follow this process. If I don't is there another topic I should see or do I just skip this topic? Or in this process, do I have to decide? That last line is a bit confusing.
|
|
||
| The {gitops-short} add-on automates the deployment and lifecycle management of the managed clusters. Based on your architecture and connectivity requirements, decide if you want to deploy the GitOps add-on with the `ArgoCD` agent component. | ||
|
|
||
| *Important:* If you enable the {gitops-short} add-on using the `GitOpsCluster` custom resource, then the `GitOpsCluster` disables the `Push Model` for all applications. |
There was a problem hiding this comment.
add-on using
add-on by using?
add-on that is using?
|
|
||
| When you enable the {gitops-short} add-on, you have the following deployment modes: | ||
|
|
||
| * `Basic` mode: Deploys the {gitops-short} operator and the `ArgoCD` instance on managed clusters through the `GitOpsCluster` custom resource. |
| * <<Additional-resources, Additional resources>> | ||
| [#prerequisites] | ||
| == Prerequisites |
There was a problem hiding this comment.
This seems more like the intro to the topic and the types of modes, which would not be prereqs. If they are this all needs to be written as:
You need to choose your mode, etc....
|
|
||
| * xref:../gitops/gitops_addon_with_argocd.adoc#enable-gitops-addon-with-argocd[Enabling {gitops} add-on with _ArgoCD_ agent] | ||
| * xref:../gitops/gitops_addon_without_argocd.adoc#enable-gitops-addon-without-argocd[Enabling {gitops} add-on without the _ArgoCD_ agent] | ||
There was a problem hiding this comment.
there have been a number of spacing issues. Please scan all these docs for extra spacing, as I may not identify and call out each one.
|
|
||
| The {gitops-short} add-on supports various configuration options to customize the deployment according to your requirements. | ||
|
|
||
| The {gitops-short} add-on supports the following configuration options in the `gitopsAddon` spec: |
There was a problem hiding this comment.
| The {gitops-short} add-on supports the following configuration options in the `gitopsAddon` spec: | |
| The {gitops-short} add-on supports the following configuration options in the `gitopsAddon` specification: |
| * `gitOpsOperatorNamespace`: Namespace where the GitOps operator is deployed. The default is `openshift-gitops-operator`. | ||
| * `gitOpsNamespace`: Namespace where `ArgoCD` instance is deployed. The default is`openshift-gitops`. | ||
| * `reconcileScope`: Control `ArgoCD` reconciliation scope that includes `All-Namespaces` or `Single-Namespace`. The default: `Single-Namespaces`. | ||
| * `overrideExistingConfigs`: Override existing `AddOnDeploymentConfig` values with new values from GitOpsCluster spec. Must be set to `true` when performing any uninstall operation. The default is `false`. |
There was a problem hiding this comment.
please find all instances of "spec" and change to "specification"
| * `enabled`: Enable or disable the agent. The default `false`. | ||
| * `propagateHubCA`: Propagate hub certified authority (CA) certificate to managed clusters. The default is `true`. | ||
| * `image`: Custom agent container image | ||
| * `serverAddress`: Override `ArgoCD` server address. |
There was a problem hiding this comment.
Override ArgoCD the(?) server address.
|
|
||
| * `enabled`: Enable or disable the agent. The default `false`. | ||
| * `propagateHubCA`: Propagate hub certified authority (CA) certificate to managed clusters. The default is `true`. | ||
| * `image`: Custom agent container image |
There was a problem hiding this comment.
line 58 missing a period like the other lines/make a complete sentence to be parallel?
| To configure the {gitops-short} add-on setting, complete the following steps: | ||
|
|
||
| . Customize your container images for the {gitops-short} components by applying the following YAML: |
There was a problem hiding this comment.
applying the entire YAML? What is significant about the YAML?
suggest adding something like:
...applying the following YAML with the gitopsAddon images and cluster details (or something like this...you need to know what the user specifically needs from this YAML to write a line introducing it. Imagine this is being read from a screen reader and the user cannot see the YAML, give them some info about it upfront. You don't need to mention all of it, but why is it important.
| redisImage: "registry.redhat.io/rhel8/redis-6@sha256:..." | ||
| ---- | ||
|
|
||
| . Customize the namespaces where you deploy the the {gitops-short}components by applying the following YAML: |
There was a problem hiding this comment.
space issue
Same feedback on YAML
| gitOpsNamespace: openshift-gitops | ||
| ---- | ||
|
|
||
| . Specify if the `ArgoCD` agent can reconcile application in all namespaces or only in its namespace by applying the following YAML: |
| ---- | ||
|
|
||
| [#uninstall-gitops-addon] | ||
| == Uninstalling the {gitops-short} add-on |
There was a problem hiding this comment.
Skipping and uninstalling need to be their own files. We are trying better to modularize. Some of these files are too long anyway. Let's move Skipping to one file and Uninstall to another.
| ---- | ||
| + | ||
| <1> `All-Namespaces`: The `ArgoCD` instance that can reconcile applications in all namespaces. | ||
| <2> `Single-Namespace`: The `ArgoCD` instance that can only reconcile applications in its own namespace. |
There was a problem hiding this comment.
We are not creating any new call-out, remember, but put this in the previous steps. All new content we are trying to create to more easily convert. These would have to be undone.
| gitops-addon.open-cluster-management.io/skip: "true" | ||
| ---- | ||
|
|
||
| . Optional: Override the existing configuration values that the `GitOpsCluster` maintains in the `AddOnDeploymentConfig` spec by applying the following yaml: |
There was a problem hiding this comment.
I believe we bold optional, please see the special tagging topic in the internal doc or the rest of the doc for examples.
| oc edit argocd openshift-gitops -n openshift-gitops | ||
| ---- | ||
|
|
||
| . Add the skip annotation and your custom configuration by applying the following YAML: |
There was a problem hiding this comment.
In all of your YAML intros, you can be a bit more specific. Here the annotation is true. They are not just adding it.
| oc edit argocd openshift-gitops -n openshift-gitops | ||
| ---- | ||
|
|
||
| . Add the skip annotation and your custom configuration by applying the following YAML: |
There was a problem hiding this comment.
| . Add the skip annotation and your custom configuration by applying the following YAML: | |
| . Add the `gitops-addon.open-cluster-management.io/skip` annotation and set to `true`, as displayed in the following YAML: |
| @@ -0,0 +1,181 @@ | |||
| [#enable-gitops-addon-with-argocd] | |||
| = Enabling {gitops} add-on with _ArgoCD_ agent | |||
There was a problem hiding this comment.
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:
- Create the YAML file with the ___ specifications. (or resource, or label, or annotation--depends on what it actually is)
- Apply the YAML file with the following command:
oc apply(check for sure)
- There are a few space issues, I may not have caught all of them.
- One file needs to be broken out into three
- Remove callouts because we cannot create those anymore, unfortunately. We all agreed to move forward with more conversion friendly content as much as we can.
Couple other smaller things.
| ---- | ||
|
|
||
| . Verify that the `ManagedClusterAddOn` resources are removed from managed cluster namespaces by running the following command: : | ||
| + |
There was a problem hiding this comment.
press enter behind command to get rid of incorrect format, and there is an extra colon here.
swopebe
left a comment
swopebe
left a comment
There was a problem hiding this comment.
See comments, let me know if you need anything in the process of refining.
| For other Application and GitOps topics, see link:../applications/app_management_overview.adoc#managing-applications[Managing applications]. | ||
| - You can manage the {gitops} add-on to help you automate the deployment and lifecycle management of your managed clusters. For more information, see xref:../gitops/gitops_manage_addon.adoc#manage-gitops-addon[Managing the {gitops} add-on] | ||
| - You can choose to enable the {gitops-short} add-on with or without the `ArgoCD` agent. For more information see xref:../gitops/gitops_addon_with_argocd.adoc#enable-gitops-addon-with-argocd[Enabling {gitops} add-on with _ArgoCD_ agent] and xref:../gitops/gitops_addon_without_argocd.adoc#enable-gitops-addon-without-argocd[Enabling {gitops} add-on without the _ArgoCD_ agent]. |
There was a problem hiding this comment.
This is a great entry, but I feel we are missing the benefit of the Argo CD agent here. I think tell the user the benefit of each of those choices.
mikeshng
left a comment
mikeshng
left a comment
There was a problem hiding this comment.
Great job!
I think some where in this doc, we have have a link to the OpenShift GitOps doc. and just say something like to learn more about OpenShift GitOps Argo CD Agent see the OpenShift GitOps doc.
| [#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: |
There was a problem hiding this comment.
| 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: | |
| Enable the {gitops-short} add-on for `Advanced` pull model with the `ArgoCD` agent to get detailed statuses on the health of your Application. To enable a GitOps add-on with the `ArgoCD` agent, complete the following sections: |
| The `GitOpsCluster` controller performs the following operations: | ||
|
|
||
| * Create and automated PKI management | ||
| * Creates `ArgoCD` cluster secrets configured for agent mode |
There was a problem hiding this comment.
They are for Argo CD to understand what clusters are imported.
Argo CD by default does not understand ACM's ManagedClusters.
This progress is equivalent of: importing all the ACM's ManagedClusters (selected by the Placement) into Argo CD.
| * Creates `ArgoCD` cluster secrets configured for agent mode | ||
| * Deploys the Argo CD Agent on each selected managed cluster | ||
| To create a `GitOpsCluster` resource with the `ArgoCD` agent, complete the following steps: |
There was a problem hiding this comment.
| To create a `GitOpsCluster` resource with the `ArgoCD` agent, complete the following steps: | |
| To enable the advanced pull model Argo CD Agent architecture, complete the following steps: |
Does that sound better? Or remove the whole line because the next line's context sounds good to me but this current one repeats it.
| enabled: true | ||
| argoCDAgent: | ||
| enabled: true | ||
| propagateHubCA: true |
There was a problem hiding this comment.
| propagateHubCA: true |
Let's not show this field that is default to true all the time and doesn't need to be manually set and the user will rarely ever use to set it to false.
| [#verify-installation] | ||
| == Verifying the installation | ||
|
|
||
| After the `ArgoCD` agent is successfully deployed, verify the `Pull Model` workflow is completed by creating an application on the hub cluster and confirming it works on the managed cluster. |
There was a problem hiding this comment.
| After the `ArgoCD` agent is successfully deployed, verify the `Pull Model` workflow is completed by creating an application on the hub cluster and confirming it works on the managed cluster. | |
| 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. |
I like your idea of advanced pull model vs basic pull model so I am stealing that usage here.
| * `enabled`: Enable or disable the agent. The default `false`. | ||
| * `propagateHubCA`: Propagate hub certified authority (CA) certificate to managed clusters. The default is `true`. | ||
| * `image`: Custom agent container image | ||
| * `serverAddress`: Override `ArgoCD` server address. |
There was a problem hiding this comment.
| * `serverAddress`: Override `ArgoCD` server address. | |
| * `serverAddress`: Override `ArgoCD` Agent principal server address. |
| * `propagateHubCA`: Propagate hub certified authority (CA) certificate to managed clusters. The default is `true`. | ||
| * `image`: Custom agent container image | ||
| * `serverAddress`: Override `ArgoCD` server address. | ||
| * `serverPort`: Override `ArgoCD` server port. |
There was a problem hiding this comment.
| * `serverPort`: Override `ArgoCD` server port. | |
| * `serverPort`: Override `ArgoCD` Agent principal server port. |
| * `serverAddress`: Override `ArgoCD` server address. | ||
| * `serverPort`: Override `ArgoCD` server port. | ||
| * `mode`: Agent operation mode. The default is `managed`. | ||
| * `uninstall`: Uninstall only the agent while keeping the GitOps add-on. |
There was a problem hiding this comment.
| * `uninstall`: Uninstall only the agent while keeping the GitOps add-on. |
|
|
||
| To completely uninstall the GitOps add-on, including its operator and the `GitOpsCluster` resource, complete the following steps: | ||
|
|
||
| . Set the `uninstall` flag in the `GitOpsCluster` and wait for uninstallation to complete. |
There was a problem hiding this comment.
| . Set the `uninstall` flag in the `GitOpsCluster` and wait for uninstallation to complete. |
|
|
||
| . Set the `uninstall` flag in the `GitOpsCluster` and wait for uninstallation to complete. | ||
| . Delete the `GitOpsCluster` resource by running the following command: | ||
|
|
There was a problem hiding this comment.
Add:
Delete the ManagedClusterAddon resource by running the following command:
oc -n <managed_cluster_namespace> delete managedclusteraddon gitops-addon
3 participants
See Jira: https://issues.redhat.com/browse/ACM-25181
Checklist consulted.