Argo CD instance
Installing and deploying Argo CD instances, enabling notifications with an Argo CD instance, and configuring the NotificationsConfiguration CR
Abstract
Chapter 1. Setting up an Argo CD instance
By default, Red Hat OpenShift GitOps installs an instance of Argo CD in the openshift-gitops
namespace with additional permissions for managing certain cluster-scoped resources. This default Argo CD instance is also called as the default cluster-scoped instance.
To prevent the default Argo CD instance from starting in the openshift-gitops
namespace, you can use the openshift-gitops-operator
subscription and configure the DISABLE_DEFAULT_ARGOCD_INSTANCE
environment variable in it by setting the string value to "true"
.
For GitOps version 1.13 and later:
-
Route TLS termination is set as default to the
reencrypt
mode for both the default and user-defined Argo CD instances. TLS connections to the Argo CD instances now receive the default ingress certificate that is set in OpenShift Container Platform, instead of the self-signed Argo CD certificate. You can modify the route TLS termination policy by configuring the.spec.server.route.tls
field of the Argo CD CR. -
Restricted pod security admission (PSA) labels are applied to the
openshift-gitops
namespace to ensure compliance with OpenShift Container Platform standards. If you are running additional workloads in this namespace, such as monitoring or logging, ensure that they comply with the restricted PSA requirements. If compliance is not feasible, consider using a user-defined, cluster-scoped Argo CD instance, where PSA labels are not applied or controlled by the GitOps Operator.
To manage cluster configurations or deploy applications, you can install and deploy a new user-defined Argo CD instance. By default, any new user-defined instance has permissions to manage resources only in the namespace where it is deployed.
You can create a user-defined Argo CD instance in any namespace, other than the openshift-gitops
namespace.
If you want to create a user-defined Argo CD instance within the openshift-gitops
namespace, set the DISABLE_DEFAULT_ARGOCD_INSTANCE
flag value in the openshift-gitops-operator
subscription to "true"
and do not name the instance as openshift-gitops
.
1.1. Installing a user-defined Argo CD instance
To manage cluster configurations or deploy applications, you can install and deploy a new user-defined Argo CD instance.
Prerequisites
-
You have access to the cluster with
cluster-admin
privileges. - You have installed the Red Hat OpenShift GitOps Operator in your cluster.
Procedure
- Log in to the OpenShift Container Platform web console.
- In the Administrator perspective of the web console, click Operators → Installed Operators.
- Create or select the project where you want to install the user-defined Argo CD instance from the Project list.
- Select Red Hat OpenShift GitOps from the installed Operators list and click the Argo CD tab.
Click Create ArgoCD to configure the parameters:
-
Enter the Name of the instance. By default, the Name is set to
example
. Create an external OS Route to access Argo CD server. Click Server → Route and check Enabled.
TipYou can alternatively configure YAML to create an external OS Route as shown in the following example:
Example Argo CD with external OS route created
apiVersion: argoproj.io/v1beta1 kind: ArgoCD metadata: name: example namespace: openshift-gitops spec: server: route: enabled: true
-
Optional: Modify the route TLS termination policy by configuring the
.spec.server.route.tls
field of the Argo CD CR.
-
Enter the Name of the instance. By default, the Name is set to
- Click Create.
- Go to Networking → Routes → <instance_name>-server in the project where the user-defined Argo CD instance is installed.
- On the Details tab, click the Argo CD web UI link under Route details → Location. The Argo CD web UI opens in a separate browser window.
Optional: To log in with your OpenShift Container Platform credentials, ensure you are a user of the
cluster-admins
group and then select theLOG IN VIA OPENSHIFT
option in the Argo CD user interface.NoteTo be a user of the
cluster-admins
group, use theoc adm groups new cluster-admins <user>
command, where<user>
is the default cluster role that you can bind to users and groups cluster-wide or locally.Obtain the password for the user-defined Argo CD instance:
- Use the navigation panel to go to the Workloads → Secrets page.
- Use the Project list and select the namespace where the user-defined Argo CD instance is created.
- Select the <argo_CD_instance_name>-cluster instance to display the password.
- On the Details tab, copy the password under Data → admin.password.
-
Use
admin
as the Username and the copied password as the Password to log in to the Argo CD UI in the new window.
1.2. Configuring common cluster roles by specifying user-defined cluster roles for namespace-scoped instances
As a cluster administrator, when you give an Argo CD access to a namespace by using the argocd.argoproj.io/managed-by
label, the Argo CD assumes namespace-admin
privileges. The Red Hat OpenShift GitOps Operator then automatically creates role bindings for all managed namespaces of the following GitOps control plane components:
- Argo CD Application Controller
- Argo CD server
- Argo CD ApplicationSet Controller
When you provide namespaces to non-administrator users, for example, development teams, they can use the namespace-admin
privileges to modify objects such as network policies. Installing an Argo CD instance in these namespaces gives the development teams admin
privileges and indirectly elevates their assigned privileges. These roles are highly privileged and can delete all resources. As a preventive action, you can define a specific set of reduced permissions to meet your security requirements by configuring common cluster roles for all managed namespaces in the role bindings that the Operator creates for the Argo CD Application Controller and Argo CD server components.
To configure common cluster roles for all managed namespaces, you can specify user-defined cluster roles for the CONTROLLER_CLUSTER_ROLE
and SERVER_CLUSTER_ROLE
environment variables in the Operator’s Subscription
object YAML file. As a result, instead of creating the default admin
role, the Operator uses the existing user-defined cluster roles and creates role bindings for all managed namespaces.
Prerequisites
- You have logged in to the OpenShift Container Platform cluster as an administrator.
- You have installed the Red Hat OpenShift GitOps Operator on your OpenShift Container Platform cluster.
Procedure
- In the Administrator perspective, navigate to Administration → CustomResourceDefinitions.
- Find the Subscription CRD and click to open it.
- Select the Instances tab and click the openshift-gitops-operator subscription.
Select the YAML tab and make your customization:
Specify the user-defined cluster roles for the
CONTROLLER_CLUSTER_ROLE
andSERVER_CLUSTER_ROLE
environment variables:Example Subscription
apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: openshift-gitops-operator namespace: openshift-gitops-operator spec: config: env: - name: CONTROLLER_CLUSTER_ROLE value: gitops-controller-role 1 - name: SERVER_CLUSTER_ROLE value: gitops-server-role 2
Alternatively, you can inject the preceding environment variables directly into the Operator’s Deployment
object YAML file.
1.3. Enabling replicas for Argo CD server and repo server
Argo CD-server and Argo CD-repo-server workloads are stateless. To better distribute your workloads among pods, you can increase the number of Argo CD-server and Argo CD-repo-server replicas. However, if a horizontal autoscaler is enabled on the Argo CD-server, it overrides the number of replicas you set.
Procedure
Set the
replicas
parameters for therepo
andserver
spec to the number of replicas you want to run:Example Argo CD custom resource
apiVersion: argoproj.io/v1beta1 kind: ArgoCD metadata: name: example-argocd labels: example: repo spec: repo: replicas: <number_of_replicas> server: replicas: <number_of_replicas> route: enabled: true path: / tls: insecureEdgeTerminationPolicy: Redirect termination: passthrough wildcardPolicy: None
1.4. Deploying resources to a different namespace
To allow Argo CD to manage resources in other namespaces apart from where it is installed, configure the target namespace with a argocd.argoproj.io/managed-by
label.
Procedure
Configure the target namespace by running the following command:
$ oc label namespace <target_namespace> \ argocd.argoproj.io/managed-by=<argocd_namespace>
where:
<target_namespace>
- Specifies the name of the namespace you want Argo CD to manage.
<argocd_namespace>
- Specifies the name of the namespace where Argo CD is installed.
1.5. Customizing the Argo CD console link
In a multi-tenant cluster, users might have to deal with multiple instances of Argo CD. For example, after installing an Argo CD instance in your namespace, you might find a different Argo CD instance attached to the Argo CD console link, instead of your own Argo CD instance, in the Console Application Launcher.
You can customize the Argo CD console link by setting the DISABLE_DEFAULT_ARGOCD_CONSOLELINK
environment variable:
-
When you set
DISABLE_DEFAULT_ARGOCD_CONSOLELINK
totrue
, the Argo CD console link is permanently deleted. -
When you set
DISABLE_DEFAULT_ARGOCD_CONSOLELINK
tofalse
or use the default value, the Argo CD console link is temporarily deleted and visible again when the Argo CD route is reconciled.
Prerequisites
- You have logged in to the OpenShift Container Platform cluster as an administrator.
- You have installed the Red Hat OpenShift GitOps Operator.
Procedure
- In the Administrator perspective, navigate to Administration → CustomResourceDefinitions.
- Find the Subscription CRD and click to open it.
- Select the Instances tab and click the openshift-gitops-operator subscription.
Select the YAML tab and make your customization:
To enable or disable the Argo CD console link, edit the value of
DISABLE_DEFAULT_ARGOCD_CONSOLELINK
as needed:apiVersion: operators.coreos.com/v1alpha1 kind: Subscription metadata: name: openshift-gitops-operator spec: config: env: - name: DISABLE_DEFAULT_ARGOCD_CONSOLELINK value: 'true'
Chapter 2. Argo CD custom resource and component properties
The ArgoCD
custom resource is a Kubernetes Custom Resource (CRD) that describes the desired state for a given Argo CD cluster that allows you to configure the components which make up an Argo CD cluster.
2.1. Argo CD custom resource properties
The Argo CD Custom Resource consists of the following properties:
Name | Description | Default | Properties |
---|---|---|---|
| Use aggregated cluster roles for the Argo CD Application Controller component of a cluster-scoped instance. |
| |
|
The |
| |
| The ApplicationSet Controller configuration options. |
|
|
| Adds a UI banner message. |
|
|
| Adds a configuration management plugin. |
| |
| Argo CD Application Controller options. |
|
|
| Disables the built-in admin user. |
| |
| Disables the creation of default cluster roles for a cluster-scoped instance. |
| |
|
Add any supplementary Argo CD settings to the |
| |
| Use a Google Analytics tracking ID. |
| |
| Enable hashed usernames sent to google analytics. |
| |
| High-availability options. |
|
|
| URL for getting chat help (this is typically your Slack channel for support). | ||
| The text that appears in a text box for getting chat help. |
| |
|
The container image for all Argo CD components. This overrides the |
| |
| Import configuration options for Argo CD. |
|
|
| Ingress configuration options. |
| |
| Initial Git repositories to configure Argo CD to use upon creation of the cluster. |
| |
| Defines the initial SSH Known Hosts data for Argo CD to use at cluster creation to connect to Git repositories through SSH. |
|
|
|
The build options and parameters to use with |
| |
|
Defines a list of |
|
|
| Defines the workload status monitoring configuration for your instance. |
|
|
| Notifications Controller configuration options. |
|
|
|
Defines |
|
|
| The OIDC configuration as an alternative to Dex. |
| |
| Prometheus configuration options. |
|
|
| RBAC configuration options. |
|
|
| Redis configuration options. |
|
|
| Git repository credential templates to configure Argo CD to use at cluster creation. |
| |
| Customize resource action behavior. |
| |
| Completely ignore entire classes of resource group. |
| |
| The configuration to identify which resource group/kinds are applied. |
| |
| Customize resource health check behavior. |
| |
| Customize resource ignore difference behavior. |
| |
| The field used by Argo CD to monitor its managed resources. |
| |
| Argo CD Server configuration options. |
|
|
| Specifies the namespaces within which you can create application resources. |
| |
| Single Sign-on options. |
|
|
| Enable application status badge. |
| |
| TLS configuration options. |
|
|
| Enable anonymous user access. |
| |
| The tag to use with the container image for all Argo CD components. | Latest Argo CD version |
2.2. Repo server properties
The following properties are available for configuring the Repo server component:
Name | Default | Description |
---|---|---|
|
|
Provider to use to set up TLS for the repo-server’s gRPC TLS certificate. Currently, only the |
|
| The environment to set for the Repo server workloads. |
|
| Flag that enables the Repo server during Argo CD installation. |
|
| Execution timeout in seconds for rendering tools, for example, Helm or Kustomize. |
|
| Passes command-line arguments to the Repo server workload. The command-line arguments are added to the list of arguments set by the Operator. |
|
|
The number of |
|
|
The container image for Argo CD Repo server. This propery overrides the |
|
|
The log level used by the Argo CD Repo server. Valid options are |
|
|
The log format to be used by the Argo CD repo server. Valid options are |
|
|
Defines whether the |
|
| Specifies the remote URL of the Repo server container. |
|
|
The number of replicas for the Argo CD Repo server. Must be greater than or equal to |
|
| The container compute resources. |
|
|
The name of the |
|
|
The number of |
|
| Defines whether to enforce strict TLS checking on all components when communicating with repo server. |
|
same as | The tag to use with the Argo CD Repo server. |
|
| Configures additional volumes used for the Repo server deployment. This field is optional. |
|
| Configures additional volume mounts used for the Repo server deployment. This field is optional. |
2.3. Enabling notifications with an Argo CD instance
Argo CD notifications allow you to send notifications to external services when events occur in your Argo CD instance. For example, you can send notifications to Slack or email when a sync operation fails. By default, notifications are disabled in Argo CD instances.
Prerequisites
-
You have access to an OpenShift Container Platform cluster with
cluster-admin
privileges and are logged into the web console. - You have installed the Red Hat OpenShift GitOps Operator on your cluster.
Procedure
To enable notifications for an Argo CD instance using the OpenShift Container Platform web console, complete the following steps:
- Navigate to the Operators → Installed Operators page.
- From the list of Installed Operators, select the Red Hat OpenShift GitOps Operator, and then click on the ArgoCD tab.
-
Select the Argo CD instance name you want to enable notifications. For example,
openshift-gitops
. Click on the YAML tab, and then edit and set the
spec.notifications.enabled
parameter totrue
:Example
apiVersion: argoproj.io/v1beta1 kind: ArgoCD metadata: name: openshift-gitops spec: notifications: enabled: true #....
- Click Save.
Alternatively, you can enable notifications by using the oc patch
command in the Openshift CLI. For example:
oc patch argocd openshift-gitops -n openshift-gitops --type merge --patch '{"spec": {"notifications": {"enabled": true}}}'
Additional resources
2.4. NotificationsConfiguration custom resource properties
The NotificationsConfiguration
resource is a Kubernetes custom resource (CR) that manages notifications in a Kubernetes cluster. In Red Hat OpenShift GitOps, you can add templates, triggers, services, and subscription resources to an Argo CD Notifications
config map by using the NotificationsConfiguration
CR.
When you create a cluster in Red Hat OpenShift GitOps with notifications enabled, a NotificationsConfiguration
CR is created by default with the name default-notifications-configuration
.
Any change made in the existing configuration of the NotificationsConfiguration
CR is replicated in the Argo CD Notifications
config map. For example, if the user adds trigger configuration in the NotificationsConfiguration
resource, this configuration is read, processed, and updated in the Argo CD Notifications
config map.
Any configuration changes must be updated in the default-notifications-configuration
CR. Custom resources created by the users for NotificationsConfiguration
resource are not supported.
Any modification to the Argo CD argocd-notifications-cm
config map is overridden by the changes made in the NotificationsConfiguration
CR.
Properties | Default | Description |
---|---|---|
Templates |
| Templates are used to generate the notification template message. |
Triggers |
| Triggers are used to define the condition when a notification is sent to the user and the list of templates required to generate the message. |
Services |
| Services are used to deliver a message. |
Subscriptions |
| Subscriptions contain centrally-managed global application subscriptions. |
The following examples define how to add templates, triggers, services, and subscription resources to the Argo CD argocd-notification-cm
config map by using the default-notifications-configuration
custom resource.
Example for templates
apiVersion: argoproj.io/v1alpha1 kind: NotificationsConfiguration metadata: name: default-notifications-configuration 1 spec: templates: template.my-custom-template: | 2 message: | Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}.
Example for triggers
apiVersion: argoproj.io/v1alpha1 kind: NotificationsConfiguration metadata: name: default-notifications-configuration 1 spec: triggers: trigger.on-sync-status-unknown: | 2 - when: app.status.sync.status == 'Unknown' send: [my-custom-template]
Example for services
apiVersion: argoproj.io/v1alpha1 kind: NotificationsConfiguration metadata: name: default-notifications-configuration 1 spec: services: service.slack: | token: $slack-token 2 username: <override-username> # optional username icon: <override-icon> # optional icon for the message (supports both emoji and url notation)
Example for subscriptions
apiVersion: argoproj.io/v1alpha1 kind: NotificationsConfiguration metadata: name: default-notifications-configuration 1 spec: subscriptions: | subscriptions: | 2 # subscription for on-sync-status-unknown trigger notifications - recipients: - slack:test2 - email:test@gmail.com triggers: - on-sync-status-unknown # subscription restricted to applications with matching labels only - recipients: - slack:test3 selector: test=true triggers: - on-sync-status-unknown icon: <override-icon> # optional icon for the message (supports both emoji and url notation)
You can configure the NotificationsConfiguration
CR by using the OpenShift Container Platform web console or the CLI (oc
).
2.4.1. Configuring the NotificationsConfiguration CR by using the web console
You can configure the NotificationsConfiguration
custom resource (CR) by using the web console.
Prerequisites
-
You have access to an OpenShift Container Platform cluster with
cluster-admin
privileges and are logged into the web console. - You have installed the Red Hat OpenShift GitOps Operator on your cluster.
- You have enabled notifications for the Argo CD instance. For more information, see "Enabling notifications with an Argo CD instance".
Procedure
- In the Administrator perspective of the OpenShift Container Platform web console, expand Operators → Installed Operators.
- From the list of Installed Operators, select the Red Hat OpenShift GitOps Operator, and then click on the NotificationsConfiguration tab.
-
On the NotificationsConfigurations page, click
default-notifications-configuration
. On the default-notifications-configuration page, click YAML and add the configuration for any supported resources such as
templates
,triggers
,services
, andsubscriptions
. For example, undertemplates
in the code, add the following sample configuration:Example template configuration
template.my-custom-template: | message: | Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}.
- Click Save.
Verify that the configuration changes made in the
NotificationsConfiguration
CR are reflected in theargocd-notifications-cm
config map:- Go to Workloads → ConfigMaps.
- Click argocd-notifications-cm and select the YAML tab.
- Scroll through the page in the YAML tab to verify the sample configuration added for the supported resources.
2.4.2. Configuring the NotificationsConfiguration CR by using the CLI
You can configure the NotificationsConfiguration
custom resource (CR) by using the CLI (oc
).
Prerequisites
-
You have access to an OpenShift Container Platform cluster with
cluster-admin
privileges. - You have installed the Red Hat OpenShift GitOps Operator on your cluster.
- You have enabled notifications for the Argo CD instance. For more information, see "Enabling notifications with an Argo CD instance".
Procedure
Edit the default
NotificationsConfiguration
CR in the cluster by running the following command:$ oc edit notificationsconfiguration default-notifications-configuration -n <namespace>
where:
default-notifications-configuration
-
Specifies the name of the default
NotificationsConfiguration
CR. <namespace>
- Specifies the name of the namespace.
Under the
templates
section of the CR, add a configuration similar to the following example:Example template configuration
template.my-custom-template: | message: | Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}.
Verify the contents of the
argocd-notifications-cm
config map by running the following command:$ oc edit cm argocd-notifications-cm -n <namespace>
The changes made in the existing configuration of the
NotificationsConfiguration
CR are reflected in theargocd-notifications-cm
config map.