diff --git a/gitops/gitops_addon_with_argocd.adoc b/gitops/gitops_addon_with_argocd.adoc new file mode 100644 index 0000000000..c07221c18b --- /dev/null +++ b/gitops/gitops_addon_with_argocd.adoc @@ -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 + +* {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 +* 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`: + ++ +[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` + +The `GitOpsCluster` controller performs the following operations: + +* Create and automated PKI management +* Creates `ArgoCD` cluster secrets configured for agent mode +* Deploys the Argo CD Agent on each selected managed cluster + +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: + ++ +[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 + +. 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: +spec: + project: default + source: + repoURL: https://github.com/argoproj/argocd-example-apps.git + targetRevision: HEAD + path: guestbook + destination: + server: https://?agentName= + 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 +---- + +. 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]. diff --git a/gitops/gitops_addon_without_argocd.adoc b/gitops/gitops_addon_without_argocd.adoc new file mode 100644 index 0000000000..d2a47d295c --- /dev/null +++ b/gitops/gitops_addon_without_argocd.adoc @@ -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. + +To enable a GitOps add-on without the `ArgoCD` agent, complete the following sections: + +* <> +* <> +* <> +* <> + +[#prerequisites] +== Prerequisites + +* {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: + ++ +[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]. diff --git a/gitops/gitops_manage_addon.adoc b/gitops/gitops_manage_addon.adoc new file mode 100644 index 0000000000..13bc672886 --- /dev/null +++ b/gitops/gitops_manage_addon.adoc @@ -0,0 +1,243 @@ +[#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. + +*Important:* If you enable the {gitops-short} add-on using the `GitOpsCluster` custom resource, then the `GitOpsCluster` disables the `Push Model` for all applications. + +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. + +* `Agent` mode: Includes all basic mode components along with the `ArgoCD` agent for enhanced pull-based architecture. + +To enable the GitOps add-on for your selected managed clusters, reference your `Placement` and use the `GitOpsCluster` custom resource as the interface for enabling. To enable and manage the GitOps add-on, complete the following sections: + +* <> +* <> +* <> +* <> +* <> +* <> + +[#prerequisites] +== Prerequisites + +If you want to enable the GitOps add-on with the `ArgoCd` agent, use the `Agent` mode. This mode extends the basic GitOps add-on with the `ArgoCD` agent component, enabling a `Pull Model` architecture. Use the `Agent` mode in environments with network restrictions, enhanced security requirements, or when you implement a `Pull Model` for application delivery. The `Advanced` pull model is powered by the `ArgoCD` agent and gives you a fully automated GitOps experience. + +If you want to enable the GitOps add-on without the `ArgoCD` agent, use the `Basic` mode. This mode enables the GitOps add-on to the managed clusters that you selected with the `Placement`. After enabling the add-on, the `Basic` mode deploys the {gitops-short} `ArgoCD` components that are suitable for the cluster workflows. + +Based on your decision, complete one of the following sections: + +* 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] + + +[#configure-gitops-addon] +== Configuring {gitops-short} add-on settings + +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` specification: + +* `enabled`: Enable or disable the GitOps add-on. The default is `false`. +* `gitOpsOperatorImage`: Custom container image for the GitOps operator. +* `gitOpsImage`: Custom container image for `ArgoCD` components. +* `redisImage`: Custom container image for `Redis`. +* `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`. +* `argoCDAgent`: `ArgoCD` agent configuration sub-section. + +The Argo CD Agent supports the following configuration options in the `argoCDAgent` spec: + +* `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` Agent principal server address. +* `serverPort`: Override `ArgoCD` Agent principal server port. +* `mode`: Agent operation mode. The default is `managed`. +* `uninstall`: Uninstall only the agent while keeping the GitOps add-on. + +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: + ++ +[source,yaml] +---- +apiVersion: apps.open-cluster-management.io/v1beta1 +kind: GitOpsCluster +metadata: + name: gitops-custom-images + 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 + gitOpsOperatorImage: "registry.redhat.io/openshift-gitops-1/gitops-operator@sha256:..." + gitOpsImage: "registry.redhat.io/openshift-gitops-1/argocd@sha256:..." + redisImage: "registry.redhat.io/rhel8/redis-6@sha256:..." +---- + +. Customize the namespaces where you deploy the the {gitops-short}components by applying the following YAML: + ++ +[source,yaml] +---- +apiVersion: apps.open-cluster-management.io/v1beta1 +kind: GitOpsCluster +metadata: + name: gitops-custom-namespaces + 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 + gitOpsOperatorNamespace: openshift-gitops-operator + gitOpsNamespace: openshift-gitops +---- + +. Specify if the `ArgoCD` agent can reconcile application in all namespaces or only in its namespace by applying the following YAML: + ++ +[source,yaml] +---- +apiVersion: apps.open-cluster-management.io/v1beta1 +kind: GitOpsCluster +metadata: + name: gitops-reconcile-scope + 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 + reconcileScope: <1> or <2> +---- ++ +<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. + +[#skip-gitops-addon] +== Skipping the {gitops-short} add-on enforcement + +The {gitops-short} add-on enforces certain resources on the managed clusters to maintain consistency. You can skip enforcement for specific resources by adding the `gitops-addon.open-cluster-management.io/skip` annotation to those specific resources on the managed cluster. Skipping enforcements helps you when you need to customize the `ArgoCD` custom resource or other {gitops-short} components that the add-on manages. + +When a resource on the managed cluster has the skip annotation, the {gitops-short} add-on does not update or manage that resource. The add-on checks for this annotation before applying any changes, allowing you to maintain custom configurations that are different from the default settings for the add-on. + +*Note:* When using the skip annotation, ensure that your custom configurations are compatible with the {gitops-short} add-on requirements. Skipping enforcement means the {gitops-short} add-on does not manage or reconcile these resources, so you are responsible for maintaining their consistency and correctness. + +To skip enforcement for a resource, add the following annotation to the resource on the managed cluster: + +[source,yaml] +---- +metadata: + Annotations: + gitops-addon.open-cluster-management.io/skip: "true" +---- + +For managing skip annotations across many managed clusters at scale, use the {acm-short} `Policy` to apply the annotation across the fleet. + +[#skip-enforcements-argocd] +== Skipping enforcements by customizing the _ArgoCD_ custom resource + +Customizing the `ArgoCD` custom resource is a common use case to adjust resource limits, configure specific settings, or enable additional features. + +To skip enforcement by customizing the `ArgoCD` custom resource, complete the following steps: + +. On the managed cluster, edit the `ArgoCD` custom resource: + ++ +[source,bash] +---- +oc edit argocd openshift-gitops -n openshift-gitops +---- + +. Add the `gitops-addon.open-cluster-management.io/skip` annotation and set to `true`, as displayed in the following YAML: + ++ +[source,yaml] +---- +apiVersion: argoproj.io/v1beta1 +kind: ArgoCD +metadata: + name: openshift-gitops + namespace: openshift-gitops + annotations: + 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: + ++ +[source,yaml] +---- +apiVersion: apps.open-cluster-management.io/v1beta1 +kind: GitOpsCluster +metadata: + name: gitops-override-config + 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 + overrideExistingConfigs: true + gitOpsImage: "registry.redhat.io/openshift-gitops-1/argocd@sha256:..." +---- + +[#uninstall-gitops-addon] +== Uninstalling the {gitops-short} 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. +. Delete the `GitOpsCluster` resource by running the following command: + ++ +[source,bash] +---- +oc delete gitopscluster gitops-clusters -n openshift-gitops +---- + +. Verify that the `ManagedClusterAddOn` resources are removed from managed cluster namespaces by running the following command: : ++ +[source,bash] +---- +oc get managedclusteraddon gitops-addon -n +---- + +[#additional-resources] +== Additional resources + +For help with troubleshooting, see xref:../troubleshooting/trouble_gitops_addon.adoc#troubleshooting-gitops-addon[Troubleshooting {gitops} add-on]. + +To learn more about {gitops-short}, see the following documentation: + +* xref:../gitops/gitops_push_pull.adoc#gitops-push-pull[Deploying Argo CD with Push and Pull model] +* xref:../gitops/gitops_registering.adoc#gitops-register[Registering managed clusters to {gitops} operator] +* xref:../gitops/gitops_console.adoc#gitops-console[GitOps console] \ No newline at end of file diff --git a/gitops/gitops_openshift_deploy_argocd.adoc b/gitops/gitops_openshift_deploy_argocd.adoc deleted file mode 100644 index fd0dd8d175..0000000000 --- a/gitops/gitops_openshift_deploy_argocd.adoc +++ /dev/null @@ -1,304 +0,0 @@ -[#gitops-openshift-deploy-argocd] -= Deploying the {gitops} instances (Technology Preview) - -With the GitOps add-on, you can manage the lifecycle of the {gitops-short} instances on all kinds of {ocp} and non-{ocp-short} managed clusters for the `ArgoCD` pull model. - -When you create the `gitops-addon ManagedClusterAddon` add-on in the cluster namespace on your hub cluster, the GitOps add-on deploys on the managed cluster that manages the installation, upgrade, and deletion of the {gitops-short} instance. - -The {gitops-short} instance that is deployed by the GitOps add-on is mostly used for the {acm-short} `ArgoCD` pull model. Therefore, you can only access the following components that are installed on the managed cluster: - -* {gitops-short} application controller -* {gitops-short} repo server -* {gitops-short} Redis server - -To deploy the {gitops-short} instances for the `ArgoCD` pull model, complete the following sections: - -* <> -* <> -* <> -* <> -* <> - - -[#install-openshift-gitops-cluster] -== Installing an {gitops-short} instance on a managed cluster - -When you upgrade {acm-short} to its latest version, the {gitops-short} instance on all the managed clusters automatically upgrades, and is bundled with the GitOps add-on. - -To install an {gitops-short} instance on a managed cluster, complete the following steps: - -. On your hub cluster, in your selected cluster namespace, create a `managedClusterAddon` resource by applying the following YAML sample: - -+ -[source,yaml] ----- -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: ManagedClusterAddOn -metadata: - name: gitops-addon - namespace: -spec: - installNamespace: open-cluster-management-agent-addon ----- - -. Verify that the `gitops-addon controller` is running on the managed cluster by running the following command: - -+ -[source,bash] ----- -oc get pods -n open-cluster-management-agent-addon ----- - -. Verify that the {gitops-short} operator is running in the `openshift-gitops-operator` namespace by running the following command: - -+ -[source,bash] ----- -oc get pods -n openshift-gitops-operator ----- - -. Verify that {gitops-short} instance is running in the `openshift-gitops` namespace by running the following command: - -+ -[source,bash] ----- -oc get pods -n openshift-gitops ----- - -. If your {gitops-short} instance fails, check the logs from the following locations, depending on the failure you need to check: - -.. Check the logs of the GitOps add-on controller by going to your managed cluster and running the following command: - -+ -[source,bash] ----- -oc logs -n open-cluster-management-agent-addon -l app=gitops-addon ----- - -.. Check the logs of {ocp-short} GitOps operator manager by going to your managed cluster and running the following command: - -+ -[source,bash] ----- -oc get pods -n openshift-gitops-operator ----- - -.. Check the logs of {ocp-short} GitOps components by going to your managed cluster and running the following command: - -+ -[source,bash] ----- -oc get pods -n openshift-gitops ----- - -[#upgrade-openshift-gitops-instance] -== Upgrading an {gitops-short} instance and operator - -If you want to upgrade to a version that is not the current version, you must manually upgrade the {gitops-short} operator and its instance to the version that you want. - -If you attach the `AddOnDeploymentConfig` to the `gitops-addon ClusterManagementAddon`, the specified image tags are always applied to the {gitops-short} operator and its instance. The latest version of the operator and its instance do not automatically update. To apply the latest version, remove the custom image settings, `GITOPS_OPERATOR_IMAGE, GITOPS_IMAGE, REDIS_IMAGE` in the default `AddOnDeploymentConfig`. - -To upgrade an {gitops-short} instance and operator, complete the following steps: - -. Create an `AddOnDeploymentConfig` custom image by applying the following YAML sample: - -+ -[source,yaml] ----- -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: AddOnDeploymentConfig -metadata: - name: gitops-addon-config - namespace: <1> -spec: - customizedVariables: - - name: GITOPS_OPERATOR_IMAGE - value: <2> - - name: GITOPS_IMAGE - value: <3> - - name: REDIS_IMAGE - value: <4> ----- -<1> Add any namespace that you want. -<2> Specify the new image and tag of the {gitops-short} operator. For example, `registry.redhat.io/openshift-gitops-1/gitops-rhel8-operator@sha256:73f13a5587bbfbea5a64bd3507120eb83b6be85088139c6d65a9aa9cd56e186a`. -<3> Specify the new image and tag of the {gitops-short} instance. For example, `registry.redhat.io/openshift-gitops-1/argocd-rhel8@sha256:706d5c99715eece77616135da2fbf90863b7aef17fd64ab03bf7dd20877490ec`. -<4> Specify the new image and tag of the {gitops-short} Redis. For example, `registry.redhat.io/rhel8/redis-6@sha256:a848cc4edb4405846c673187dd68ce66c328dd1ad42f193f5737288c7971399d`. - -. Connect the `AddOnDeploymentConfig` to the `gitops-addon ClusterManagementAddon` by specifying the `defaultConfig` name and namespace of the `addondeploymentconfigs` resource by applying the following YAML sample: - -+ -[source,yaml] ----- -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: ClusterManagementAddOn -metadata: - name: gitops-addon - annotations: - addon.open-cluster-management.io/lifecycle: "gitops-addon" -spec: - addOnMeta: - description: gitops-addon - displayName: gitops-addon - supportedConfigs: - - group: addon.open-cluster-management.io - resource: addondeploymentconfigs - defaultConfig: - name: gitops-addon-config - namespace: ocm <1> - - group: addon.open-cluster-management.io - resource: addontemplates - defaultConfig: - name: gitops-addon ----- -<1> The namespace specified in the `AddOnDeploymentConfig`. - -. On the managed clusters, verify that the {gitops-short} operator pods and instance pods are restarted with the new image tags. - -. If your {gitops-short} instance fails, check the logs from the following locations, depending on the failure you need to check: - -.. Check the logs of the GitOps add-on controller by going to your managed cluster and running the following command: - -+ -[source,bash] ----- -oc logs -n open-cluster-management-agent-addon -l app=gitops-addon ----- - -.. Check the logs of {ocp-short} GitOps operator manager by going to your managed cluster and running the following command: - -+ -[source,bash] ----- -oc get pods -n openshift-gitops-operator ----- - -.. Check the logs of {ocp-short} GitOps components by going to your managed cluster and running the following command: - -+ -[source,bash] ----- -oc get pods -n openshift-gitops ----- - -[#delete-openshift-gitops-instance] -== Deleting an {gitops-short} instance and operator - -All the dependent `ArgoCD` custom resource definitions (CRDs) remain even after the {gitops-short} operator is removed, ensuring that all existing `ArgoCD` applications are not removed with the operator deletion. - -You can reinstall the {gitops-short} operator into the same default namespace. Always install the {gitops-short} operator into the default namespace, `openshift-gitops-operator`. The {gitops-short} operator watches the `ArgoCD` resources in any namespace regardless of the operator installation namespace. - -To delete an {gitops-short} instance and operator, complete the following steps: - -. Delete the {gitops-short} instance by applying the following YAML sample: - -+ -[source,yaml] ----- -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: AddOnDeploymentConfig -metadata: - name: gitops-addon-config - namespace: <1> -spec: - customizedVariables: - - name: ACTION - value: Delete-Instance ----- -<1> This is the namespace that you specified when you created the default `AddOnDeploymentConfig` connected to the `gitop-addon` `ClusterManagementAddOn`. - -. Delete the {gitops-short} operator by applying the following YAML sample: - -+ -[source,yaml] ----- -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: AddOnDeploymentConfig -metadata: - name: gitops-addon-config - namespace: <1> -spec: - customizedVariables: - - name: ACTION - value: Delete-Operator ----- -<1> This is the namespace that you specified when you created the default `AddOnDeploymentConfig` connected to the `gitop-addon` `ClusterManagementAddOn`. - -[#reconcile-argocd-applications] -== Reconciling _ArgoCD_ applications in any namespace - -You can configure the {gitops-short} instance to reconcile the `ArgoCD` application in any namespace. - -To reconcile `ArgoCD` applications in any namespace, complete the following step: - -. In the linked default `AddOnDeploymentConfig`, specify the customized variable, `RECONCILE_SCOPE` to `All-Namespaces` by applying the following YAML sample: - -+ -[source,yaml] ----- -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: AddOnDeploymentConfig -metadata: - name: gitops-addon-config - namespace: <1> -spec: - customizedVariables: - - name: RECONCILE_SCOPE - value: <2> ----- -<1> This is the namespace that you specified when you created the default `AddOnDeploymentConfig` connected to the `gitop-addon` `ClusterManagementAddOn`. -<2> You have two available options for this value. `All-Namespaces` where the GitOps `ArgoCD` instance can reconcile applications in all namespaces `Single-Namespace` the GitOps `ArgoCD` instance can only reconcile applications in the namespace where the GitOps `ArgoCD` instance is running. - -[#install-openshift-gitops-instance] -== Installing an {gitops-short} instance in another namespace - -By default, the {gitops-short} instance is installed in the `openshift-gitops` namespace. If you want to install the {gitops-short} instance in another namespace, complete the following steps: - -. Delete the {gitops-short} instance by applying the following YAML sample: - -+ -[source,yaml] ----- -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: AddOnDeploymentConfig -metadata: - name: gitops-addon-config - namespace: <1> -spec: - customizedVariables: - - name: ACTION - value: Delete-Instance ----- -<1> This is the namespace that you specified when you created the default `AddOnDeploymentConfig` connected to the `gitop-addon` `ClusterManagementAddOn`. - -. Verify that the {gitops-short} instance is removed by running the following command: - -+ -[source,bash] ----- -oc get pods -n openshift-gitops ----- - -. Install the {gitops-short} instance to another namespace by applying the following YAML sample: - -+ -[source,yaml] ----- -apiVersion: addon.open-cluster-management.io/v1alpha1 -kind: AddOnDeploymentConfig -metadata: - name: gitops-addon-config - namespace: <1> -spec: - customizedVariables: - - name: GITOPS_NAMESPACE - value: openshift-gitops-2 ----- -<1> This is the namespace that you specified when you created the default `AddOnDeploymentConfig` connected to the `gitop-addon` `ClusterManagementAddOn`. - -. Verify that the {gitops-short} instance is applying on the new namespace by running the following command: - -+ -[source,bash] ----- -oc get pods -n openshift-gitops-2 ----- diff --git a/gitops/gitops_overview.adoc b/gitops/gitops_overview.adoc index 593e65fa57..dab0e53bec 100644 --- a/gitops/gitops_overview.adoc +++ b/gitops/gitops_overview.adoc @@ -13,5 +13,7 @@ See the following topics to learn more about {acm} integration with {ocp-short} * xref:../gitops/gitops_push_pull.adoc#gitops-push-pull[Deploying Argo CD with the Push and Pull model] * xref:../gitops/gitops_policy_generator.adoc#gitops-policy-generator[Generating a policy to install GitOps Operator] * xref:../gitops/gitops_manage_policy_def.adoc#gitops-policy-definitions[Managing policy definitions with {ocp-short} GitOps (Argo CD)] -* xref:../gitops/gitops_openshift_deploy_argocd.adoc#gitops-openshift-deploy-argocd[Deploying the {gitops} instances (Technology Preview)] +* xref:../gitops/gitops_manage_addon.adoc#manage-gitops-addon[Managing the {gitops} add-on] +* 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] * xref:../gitops/gitops_appset_rollout_strategy.adoc#gitops_app_rollout_strategy[Implementing progressive rollout strategy by using _ApplicationSet_ resource (Technology Preview)] diff --git a/gitops/main.adoc b/gitops/main.adoc index 8ec548f0f3..0035aa0b6b 100644 --- a/gitops/main.adoc +++ b/gitops/main.adoc @@ -10,5 +10,7 @@ include::gitops_push_pull.adoc[leveloffset=+2] include::gitops_manage_policy_def.adoc[leveloffset=+2] include::gitops_policy_generator.adoc[leveloffset=+2] include::gitops_service_account_argo_cd.adoc[leveloffset=+2] -include::gitops_openshift_deploy_argocd.adoc[leveloffset=+2] +include::gitops_manage_addon.adoc[leveloffset=+2] +include::gitops_addon_with_argocd.adoc[leveloffset=+2] +include::gitops_addon_without_argocd.adoc[leveloffset=+2] include::gitops_appset_rollout_strategy.adoc[leveloffset=+2] diff --git a/release_notes/acm_new.adoc b/release_notes/acm_new.adoc index 194710182e..149b2b3151 100644 --- a/release_notes/acm_new.adoc +++ b/release_notes/acm_new.adoc @@ -76,9 +76,13 @@ Learn what is new for {global-hub} this release. [#application-new-features] == Applications -Read about new features for application management. +Learn about new features for application management. -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]. + +- For other Application and GitOps topics, see link:../applications/app_management_overview.adoc#managing-applications[Managing applications]. [#observability-new-features] == Observability diff --git a/troubleshooting/trouble_gitops_addon.adoc b/troubleshooting/trouble_gitops_addon.adoc new file mode 100644 index 0000000000..bfa3c45f60 --- /dev/null +++ b/troubleshooting/trouble_gitops_addon.adoc @@ -0,0 +1,116 @@ +[#troubleshooting-gitops-addon] +== Troubleshooting {gitops} add-on + +If you have issues with the {gitops} add-on deployment, complete the following troubleshooting guidance. + +[check-gitopscluster-status] +== Checking the _GitOpsCluster_ status + +To check the `GitOpsCluster` status, complete the following steps: + +. View the `GitOpsCluster` resource status by running the following command: + ++ +[source,bash] +---- +oc get gitopscluster -n openshift-gitops -o yaml +---- + +. Check the status conditions for specific failure information by running the following command: + ++ +[source,bash] +---- +oc get gitopscluster -n openshift-gitops -o jsonpath='{.status.conditions}' | jq +---- + +See the following common condition types to check: + +* `Ready` : Overall `GitOpsCluster` health +* `PlacementResolved` : `Placement` resource status +* `ClustersRegistered` : Cluster registration status +* `ArgoCDAgentPrereqsReady` : Agent prerequisites, if you have enabled the agent +* `CertificatesReady` : TLS certificate status, if you have enabled the agent. +* `ManifestWorksApplied` : `ManifestWork` propagation status if you have enabled the agent. + +[#check-gitops-addon-logs] +== Checking the GitOps add-on controller logs + +To check the GitOps add-on controller logs, complete the following steps: + +. Go to the managed cluster. +. Check the GitOps add-on controller logs by running the following command: + ++ +[source,bash] +---- +oc logs -n open-cluster-management-agent-addon -l app=gitops-addon +---- + +[#check-gitops-operator] +== Checking the {gitops-short} operator + +To confirm that the GitOps operator works, complete the following steps: + +. Verify the operator is working by running the following command: + ++ +[source,bash] +---- +oc get pods -n openshift-gitops-operator +---- + +. Check operator logs by running the following command: + ++ +[source,bash] +---- +oc logs -n openshift-gitops-operator -l control-plane=controller-manager +---- + +[#check-argocd] +== Checking the _ArgoCD_ instance and agent + +To check that the `ArgoCD` instance is working, complete the following steps: + +. Verify Argo CD components are working by running the following command: + ++ +[source,bash] +---- +oc get pods -n openshift-gitops +---- + +. Check `ArgoCD` application controller logs by running the following command: + ++ +[source,bash] +---- +oc logs -n openshift-gitops -l app.kubernetes.io/name=argocd-application-controller +---- + +If you have enabled the `ArgoCD` agent, check that it is working by completing the following steps: + +. Verify the agent is working by running the following command: + ++ +[source,bash] +---- +oc get pods -n openshift-gitops +---- + +. Check that the agent logs are working by running the following command: + ++ +[source,bash] +---- +oc logs -n openshift-gitops +---- + +. Verify that the `ManifestWork` status is set for the certificate authorization (CA) propagation by running the following command: + ++ +[source,bash] +---- +oc get manifestwork -n argocd-agent-ca-propagation -o yaml +----