Argo CD instance

To manage cluster configurations or deploy applications, you can install and deploy a new user-defined Argo CD instance.

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:

When you give 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. To reduce this risk, configure common cluster roles with limited permissions in the role bindings that the Operator creates for the Argo CD Application Controller and Argo CD server.

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.

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.

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.

In a multitenant cluster, users might have to deal with many instances of Argo CD. After installing an Argo CD instance in your namespace, the Argo CD console link in the Console Application Launcher might open another Argo CD instance.

You can customize the Argo CD console link by setting the DISABLE_DEFAULT_ARGOCD_CONSOLELINK environment variable:

The GitOps Operator lets administrators configure imagePullPolicy at multiple levels to control how Argo CD components pull container images.

The imagePullPolicy configuration follows a hierarchical precedence system, where the most specific configuration takes priority:

You can define a global image pull policy for all Argo CD instances managed by the Operator by setting the IMAGE_PULL_POLICY environment variable in the Operator’s Subscription. For example:

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: openshift-gitops-operator
spec:
  config:
    env:
      - name: IMAGE_PULL_POLICY
        value: "Always"

An instance-level configuration overrides the Operator-level policy and applies the configuration only to the specific instance defined in the CR.

The following example shows how to configure imagePullPolicy for all the components in an Argo CD instance.

apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: argocd
  namespace: argocd
spec:
  imagePullPolicy: IfNotPresent

The following example shows how to define imagePullPolicy for all the components in a GitOpsService instance.

apiVersion: pipelines.openshift.io/v1alpha1
kind: GitOpsService
metadata:
  name: gitops-service
  namespace: openshift-gitops
spec:
  imagePullPolicy: Always

The following example shows how to set imagePullPolicy for all the components in a RolloutsManager instance.

apiVersion: argoproj.io/v1alpha1
kind: RolloutManager
metadata:
  name: argo-rollout
  labels:
    example: basic
spec:
  imagePullPolicy: Always

By configuring the imagePullPolicy at an appropriate level, you can control how often container images are updated for your GitOps components.

The Argo CD Custom Resource consists of the following properties:

The following properties are available for configuring the repo server component:

apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: example-argocd
  labels:
    example: repo
spec:
  repo:
    systemCATrust:
      secrets:
        - name: my-local-cert-secret
          items:
            - key: key-name-in-the-secret-object
              path: desired-file-name-of-the-certificate.crt
      configMaps:
        - name: my-local-cert-cm
          items: []

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.

oc patch argocd openshift-gitops -n openshift-gitops --type merge --patch '{"spec": {"notifications": {"enabled": true}}}'

Argo CD provides support for Helm, Jsonnet, and Kustomize as built-in config management tools. To use a different config management tool, or to enable features not provided by the built-in config management tools, you can use the Config Management Plugin (CMP).

In Argo CD, the CMP is specified as a sidecar container for the Argo CD repo server container. For more information, see "Config Management Plugins".

In the Red Hat OpenShift GitOps Operator, you can configure the Config Management plugin as a sidecar container in the Argo CD custom resource (CR). When you configure the sidecar container, you either specify an off-the-shelf or a custom-built container image. If you do not specify an image, the system uses the same image as the repo server for the plugin.

To configure a sidecar container in the Red Hat OpenShift GitOps Operator, add the .spec.repo.sidecarContainers key in the Argo CD CR.

Example Config Management Plugin configuration:

apiVersion: argoproj.io/v1alpha1
kind: ArgoCD
metadata:
 name: <my_argocd>
spec:
 repo:
   sidecarContainers:
     - name: <my_cmp>
       command: [/var/run/argocd/argocd-cmp-server]
       image: <my_image>
       securityContext:
         runAsNonRoot: <true>
         runAsUser: 

       volumeMounts:
         - mountPath: /var/run/argocd
           name: <var_files>
         - mountPath: /home/argocd/cmp-server/plugins
           name: plugins
         - mountPath: /tmp
           name: tmp
         - mountPath: /home/argocd/cmp-server/config/plugin.yaml
           subPath: <plugin.yaml>
           name: <cmp_plugin>

where:

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.

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
spec:
 templates:
  template.my-custom-template: |
    message: |
     Application details: {{.context.argocdUrl}}/applications/{{.app.metadata.name}}.

where:

Example for triggers:

apiVersion: argoproj.io/v1alpha1
kind: NotificationsConfiguration
metadata:
 name: default-notifications-configuration
spec:
 triggers:
  trigger.on-sync-status-unknown: |
   - when: app.status.sync.status == 'Unknown'
   send: [my-custom-template]

where:

Example for services:

apiVersion: argoproj.io/v1alpha1
kind: NotificationsConfiguration
metadata:
 name: default-notifications-configuration
spec:
 services:
  service.slack: |
    token: $slack-token
    username: <override-username> # optional username
    icon: <override-icon> # optional icon for the message (supports both emoji and url notation)

where:

Example for subscriptions:

apiVersion: argoproj.io/v1alpha1
kind: NotificationsConfiguration
metadata:
 name: default-notifications-configuration
spec:
 subscriptions:
  subscriptions: |
    # 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

where:

You can configure the NotificationsConfiguration CR by using the OpenShift Container Platform web console or the CLI (oc).

By default, Argo CD manages notification configuration only within the control plane namespace. With Red Hat OpenShift GitOps Operator, cluster administrators can enable teams to manage notification settings for their applications from additional namespaces.

To enable this functionality, configure the target namespaces in the Argo CD custom resource (CR). The Red Hat OpenShift GitOps Operator reconciles the corresponding notification resources only for namespaces that are explicitly defined in the ArgoCD CR.

Red Hat OpenShift GitOps Operator enhances multi-instance support by improving annotation-based resource tracking in Argo CD.Multiple Argo CD instances can use annotation-based tracking by assigning each instance a unique installationID, which enables them to correctly differentiate resources with identical application names, prevent conflicts, avoid infinite sync loops, and operate safely in parallel.

You can perform the following actions by using the OpenShift Container Platform web console:

Argo CD uses webhook secrets to validate incoming webhook requests from Git providers. You can configure webhook secrets declaratively by using the spec.webhookSecrets field in the Argo CD custom resource (CR).

Using declarative webhook secrets provides the following benefits:

When you configure spec.webhookSecrets, the Red Hat OpenShift GitOps Operator automatically populates the required keys in the argocd-secret secret that Argo CD uses internally.

The following Git providers are supported for declarative webhook secret configuration:

You can configure webhook secrets for Git providers by creating a Kubernetes Secret resource and referencing it in the Argo CD custom resource (CR).

After configuring declarative webhook secrets, verify that the Red Hat OpenShift GitOps Operator synchronized the webhook secret values to the argocd-secret secret.

$ oc rollout restart deployment/<argocd_cr_name>-server -n <namespace>

Argo CD Image Updater automatically updates container image versions for workloads managed by Argo CD. It monitors container registries for new image tags that match configured version constraints and updates applications through Argo CD.

In the Red Hat OpenShift GitOps Operator, Argo CD Image Updater is provided as a productized controller that you enable through the Argo CD custom resource.

The Argo CD Image Updater controller runs a reconciliation loop that continuously watches configured Argo CD applications and queries container registries for newer image versions. When a qualifying new version is discovered, the controller instructs Argo CD to update the application. You define which images to track and what version constraints to enforce by creating ImageUpdater custom resources.

Depending on the Argo CD application sync policy, updated images are either deployed automatically or marked as out of sync for manual approval.

The Image Updater provides the following capabilities:

Image selection and update behavior

Application support

Persistence and Git workflows

Registry integration

Observability

Argo CD Image Updater has the following limitations:

You can enable the Argo CD Image Updater controller for an Argo CD instance by configuring the Argo CD custom resource (CR). The Argo CD Image Updater controller is namespace-scoped by default, watching only the namespace in which it is installed.

By default, the Argo CD Image Updater controller watches only the namespace in which it is installed. To configure the Argo CD Image Updater controller to watch additional namespaces, set the IMAGE_UPDATER_WATCH_NAMESPACES environment variable to a comma-separated list of namespaces.

To configure the Argo CD Image Updater to track and update images for an Argo CD application, you create an ImageUpdater custom resource (CR). The ImageUpdater CR specifies which Argo CD applications to monitor, which images to track, the update strategy to use, and how to write back image updates.

The ImageUpdater CR must reside in the same namespace as the Argo CD applications it references. The controller uses metadata.namespace to determine the namespace in which to search for matching applications.

The following example shows a basic ImageUpdater CR that matches applications whose names start with my-app- and tracks the nginx image with a version constraint of ~1.26, which restricts updates to patch versions within the 1.26 minor release (for example, 1.26.0, 1.26.1, 1.26.2):

apiVersion: argocd-image-updater.argoproj.io/v1alpha1
kind: ImageUpdater
metadata:
  name: my-image-updater
  namespace: openshift-gitops
spec:
  applicationRefs:
    - namePattern: "my-app-*"
      images:
        - alias: "nginx"
          imageName: "nginx:~1.26"

The applicationRefs field in the ImageUpdater custom resource determines which Argo CD applications the Argo CD Image Updater controller monitors. Applications can be selected by name pattern, by label, or by a combination of both.

You can use glob patterns to match application names. The namePattern field supports glob-based selection. An exact name matches a single application, while wildcards match multiple applications.

Example: Using a name pattern with wildcards:

spec:
  applicationRefs:
    - namePattern: "frontend-*"
      images:
        - alias: "nginx"
          imageName: "nginx:~1.26"

You can select applications based on their Kubernetes labels. The labelSelectors field selects applications by their Kubernetes labels, supporting both matchLabels for key-value pairs and matchExpressions for operator-based conditions.

Example: Using label selectors:

spec:
  applicationRefs:
    - labelSelectors:
        matchLabels:
          tier: "frontend"
        matchExpressions:
          - key: env
            operator: In
            values:
              - staging
              - production
      images:
        - alias: "nginx"
          imageName: "nginx:~1.26"

You can combine name patterns and label selectors for more precise application selection. For example, to match only applications whose names start with web- and that have a tier: "frontend" label:

Example: Combining name pattern and label selectors:

spec:
  applicationRefs:
    - namePattern: "web-*"
      labelSelectors:
        matchLabels:
          tier: "frontend"
      images:
        - alias: "nginx"
          imageName: "nginx:~1.26"

Applications can provide image configuration through annotations as an alternative to CR-based configuration. When working with ApplicationSets that generate many Applications, each Application can provide its own image configuration through annotations instead of defining images in the ImageUpdater CR. Set useAnnotations: true on an applicationRef to enable this.

Example: Using annotations for image configuration:

spec:
  applicationRefs:
    - namePattern: "generated-app-*"
      useAnnotations: true

When useAnnotations is enabled, the controller reads image configuration from the argocd-image-updater.argoproj.io/image-list annotation on each matching Application resource.

For that applicationRef, any image configuration defined in the CR is ignored. Only the namePattern and labelSelectors fields remain effective.

Example: Using annotations for image configuration:

spec:
  applicationRefs:
    - namePattern: "*"
      labelSelectors:
        matchLabels:
          image-updater: my-image-updater
      useAnnotations: true

The Argo CD Image Updater supports four strategies for determining which image version to update to. Configure the strategy using the commonUpdateSettings.updateStrategy field.

Example: Using the newest-build strategy with a tag filter:

spec:
  applicationRefs:
    - namePattern: "my-app"
      images:
        - alias: "myimage"
          imageName: "myorg/myimage"
          commonUpdateSettings:
            updateStrategy: "newest-build"
            allowTags: "regexp:^v1\\.0\\.0-[0-9a-zA-Z]+$"

You can control which image tags are eligible for updates using the following parameters:

Example: Tag filtering with allowTags and ignoreTags:

spec:
  applicationRefs:
    - namePattern: "my-app"
      images:
        - alias: "myimage"
          imageName: "myorg/myimage"
          commonUpdateSettings:
            allowTags: "regexp:^v[0-9]+\\.[0-9]+\\.[0-9]+$"
            ignoreTags: "*-rc*"

This example allows only tags matching a specific semantic version pattern and ignores release candidate tags.

The Argo CD Image Updater supports three methods for writing back image updates to your applications: Argo CD API method, Git method, and pull request or merge request method.

The Argo CD API method is the default write-back method and requires no additional configuration. It updates the Argo CD Application resource directly via the Kubernetes API. No additional configuration is required. This method is best suited for applications created imperatively through the Argo CD Web UI or CLI.

The Git method provides persistent storage by committing changes to the application’s Git repository. The Argo CD Image Updater controller fetches the remote repository, checks out the target branch, creates or updates a parameter override file, and commits and pushes the change.

Example: Git write-back method:

spec:
  applicationRefs:
    - namePattern: "my-app"
      images:
        - alias: "nginx"
          imageName: "nginx:~1.26"
  writeBackConfig:
    method: "git"
    gitConfig:
      repository: "https://github.com/myorg/my-app-config.git"
      branch: "main"

To use credentials other than the ones configured in Argo CD, reference a Kubernetes secret:

Example: Git write-back with custom credentials:

spec:
  writeBackConfig:
    method: "git:secret:openshift-gitops/git-creds"
    gitConfig:
      branch: "main"

The Git method supports multiple write-back targets. By default, it creates or updates an .argocd-source-<appName>.yaml file in the application path. For Kustomization applications, you can set the writeBackTarget to kustomization to commit changes as a kustomize edit set image operation. For Helm applications, you can specify a Helm values file path using writeBackTarget: "helmvalues:/helm/config/values.yaml" to update the values file directly.

Example: Kustomization write-back target:

spec:
  writeBackConfig:
    method: "git"
    gitConfig:
      branch: "main"
      writeBackTarget: "kustomization"

Example: Helm values file write-back target:

spec:
  writeBackConfig:
    method: "git"
    gitConfig:
      branch: "main"
      writeBackTarget: "helmvalues:/helm/config/values.yaml"

The pull request or merge request method creates PRs or MRs for review instead of directly committing to the target branch. The PR/MR method extends the Git method by pushing changes to an auto-generated branch and opening a pull request or merge request instead of pushing directly to the target branch. This method is ideal when the target branch is protected or when image updates should go through a review workflow.

The Image Updater pushes the commit to a branch named image-updater-<namespace>-<appName>-<sha256> and opens a pull or merge request from that branch into the configured base branch. If a PR already exists for the same branch pair, no duplicate is created.

Example: GitHub pull request:

spec:
  writeBackConfig:
    method: "git:secret:openshift-gitops/git-creds"
    gitConfig:
      repository: "https://github.com/example/example.git"
      branch: "main"
      pullRequest:
        github: {}

Example: GitLab merge request:

spec:
  writeBackConfig:
    method: "git:secret:openshift-gitops/gitlab-creds"
    gitConfig:
      repository: "https://gitlab.com/org/repo.git"
      branch: "main"
      pullRequest:
        gitlab: {}

For Helm charts that use non-standard parameter names for image references, configure the manifestTargets.helm field in the ImageUpdater custom resource to explicitly map the image parameters.

When replacing one image with another, for example, switching registries, use the manifestTargets.kustomize.name field to identify the original image in the kustomization.

The Argo CD Image Updater works with most container registries that implement the Docker Registry v2 API out of the box. For custom or private registries, you can configure registry settings in the argocd-image-updater-config ConfigMap.

The Image Updater works with the following container registries out of the box:

Per-image pull secrets authenticate with private container registries. The pullSecret field supports the following formats:

Pull secret formats:

By default, the Argo CD Image Updater discovers new image versions by periodically polling container registries. You can also configure webhooks so that registries push notifications to the Image Updater immediately when a new image is available, eliminating the delay between image publication and update.

The webhook server exposes two endpoints:

Registry webhook URLs include a type query parameter that identifies the registry. For example: https://image-updater.example.com/webhook?type=docker.io.

The ImageUpdater custom resource exposes a status subresource with standard Kubernetes conditions that provide information about the operational state of the Argo CD Image Updater controller.

The following example shows a complete ImageUpdater custom resource that tracks two images for a Helm-based application, uses semantic versioning constraints, and writes back updates as pull requests to a GitHub repository. This example demonstrates tracking a frontend image with patch version updates within 2.0, a backend image with minor and patch updates within 1.x using semantic versioning strategy, pull secret authentication, and Git write-back with GitHub pull request creation.

Example: Complete ImageUpdater CR:

apiVersion: argocd-image-updater.argoproj.io/v1alpha1
kind: ImageUpdater
metadata:
  name: my-app-updater
  namespace: openshift-gitops
spec:
  applicationRefs:
    - namePattern: "my-app"
      images:
        - alias: "frontend"
          imageName: "myorg/frontend:~2.0"
          manifestTargets:
            helm:
              name: "frontend.image.repository"
              tag: "frontend.image.tag"
        - alias: "backend"
          imageName: "myorg/backend:^1.5"
          commonUpdateSettings:
            updateStrategy: "semver"
            allowTags: "regexp:^v[0-9]+\\.[0-9]+\\.[0-9]+$"
          manifestTargets:
            helm:
              name: "backend.image.repository"
              tag: "backend.image.tag"
          pullSecret: "pullsecret:openshift-gitops/myregistry-pull-secret"
  writeBackConfig:
    method: "git:secret:openshift-gitops/git-creds"
    gitConfig:
      repository: "https://github.com/myorg/my-app-config.git"
      branch: "main"
      pullRequest:
        github: {}