Chapter 2. Install and configure Argo CD

Procedure

1. Add Argo CD instance information to your app-config.yaml configmap as shown in the following example:

   argocd:
     appLocatorMethods:
       - type: 'config'
         instances:
           - name: argoInstance1
             url: https://argoInstance1.com
             username: ${ARGOCD_USERNAME}
             password: ${ARGOCD_PASSWORD}
           - name: argoInstance2
             url: https://argoInstance2.com
             username: ${ARGOCD_USERNAME}
             password: ${ARGOCD_PASSWORD}

   Note

   Avoid using a trailing slash in the url, as it might cause unexpected behavior.

2. Add the following annotation to the entity's catalog-info.yaml file to identify the Argo CD applications.

   annotations:
     ...
     # The label that Argo CD uses to fetch all the applications. The format to be used is label.key=label.value. For example, rht-gitops.com/janus-argocd=quarkus-app.
   
     argocd/app-selector: '${ARGOCD_LABEL_SELECTOR}'

3. (Optional) Add the following annotation to the entity's catalog-info.yaml file to switch between Argo CD instances as shown in the following example:

    annotations:
      ...
       # The Argo CD instance name used in `app-config.yaml`.
   
       argocd/instance-name: '${ARGOCD_INSTANCE}'

   Note

   If you do not set this annotation, the Argo CD plugin defaults to the first Argo CD instance configured in app-config.yaml.

4. To enable the Argo CD plugin, set the disabled property to false in your dynamic-plugins.yaml file as follows:

   plugins:
     - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-argocd-backend:<tag>
       disabled: false
       pluginConfig:
         argocd:
             username: ${ARGOCD_USERNAME}
             password: ${ARGOCD_PASSWORD}
             appLocatorMethods:
               - type: config
                 instances:
                   - name: argoInstance1
                     url: ${ARGOCD_INSTANCE1_URL}
                     token: ${ARGOCD_AUTH_TOKEN}
     - package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/backstage-community-plugin-argocd:<tag>
       disabled: false
       pluginConfig:
         dynamicPlugins:
           frontend:
             backstage-community.plugin-argocd:
               translationResources:
                 - importName: argocdTranslations
                   module: Alpha
                   ref: argocdTranslationRef
               mountPoints:
                 - mountPoint: entity.page.overview/cards
                   importName: ArgocdDeploymentSummary
                   config:
                     layout:
                       gridColumnEnd:
                         lg: span 8
                         xs: span 12
                     if:
                       allOf:
                         - isArgocdConfigured
                 - mountPoint: entity.page.cd/cards
                   importName: ArgocdDeploymentLifecycle
                   config:
                     layout:
                       gridColumn: 1 / -1
                     if:
                       allOf:
                         - isArgocdConfigured

   where:

   <tag>

   Enter your RHDH version of Backstage and the plugin version, in the format bs_<backstage-version>__<plugin-version> (note the double underscore delimiter). To find these versions, complete the following steps:

   1. Find your Backstage version in the RHDH release notes preface.

   2. Locate the plugin version in the Dynamic Plugins Reference guide. For example, for RHDH 1.10 based on Backstage 1.49.4, use the format bs_1.49.4__<plugin-version>.

      Tip

      To ensure environment stability, use a SHA256 digest instead of a version tag. See Determining SHA256 Digests.

   Important

   Argo CD contains multiple plugin options you can choose from for your Argo CD configuration:

   • Community Argo CD:

     • @backstage-community/plugin-argocd
     • @backstage-community/plugin-argocd-backend

   • Roadie Argo CD:

     • @roadiehq/backstage-plugin-argo-cd
     • @roadiehq/backstage-plugin-argo-cd-backend

   Community and Roadie plugins are comparable in functionality but have different features. For example, both versions feature scaffolder actions, however, their implementation is different: the Community version contains scaffolder actions by default, the Roadie version requires an additional plugin.

   The recommended combination is to use @backstage-community/plugin-argocd together with @backstage-community/plugin-argocd-backend.

   However, you can also combine @roadiehq/backstage-plugin-argo-cd together with @roadiehq/backstage-plugin-argo-cd-backend.

   Mixing Community and Roadie plugins is not recommended.

Procedure

1. In the app-config.yaml file in your Developer Hub instance, add the following customResources component under the kubernetes configuration to enable Argo Rollouts and Analysis Runs:

   kubernetes:
     ...
     customResources:
       - group: 'argoproj.io'
         apiVersion: 'v1alpha1'
         plural: 'Rollouts'
       - group: 'argoproj.io'
         apiVersion: 'v1alpha1'
         plural: 'analysisruns'

2. Grant ClusterRole permissions for custom resources.

   Note
   1. If the Developer Hub Kubernetes plugin is already configured, the ClusterRole permissions for Rollouts and AnalysisRuns might already be granted.
   2. Use the prepared manifest to give read-only ClusterRole access to both the Kubernetes and ArgoCD plugins.
   1. If the ClusterRole permission is not granted, use the following YAML manifest to create the ClusterRole:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: backstage-read-only
   rules:
     - apiGroups:
         - argoproj.io
       resources:
         - rollouts
         - analysisruns
       verbs:
         - get
         - list

   1. Apply the manifest to the cluster using kubectl:

      $ kubectl apply -f <your_cluster_role_file>.yaml

   2. Ensure the ServiceAccount accessing the cluster has this ClusterRole assigned.

3. Add annotations to catalog-info.yaml to identify Kubernetes resources for Backstage.

   1. For identifying resources by entity ID:

      annotations:
        ...
        backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

   2. (Optional) For identifying resources by namespace:

      annotations:
        ...
        backstage.io/kubernetes-namespace: <RESOURCE_NAMESPACE>

   3. For using custom label selectors, which override resource identification by entity ID or namespace:

      annotations:
        ...
        backstage.io/kubernetes-label-selector: 'app=my-app,component=front-end'

      Note

      Ensure you specify the labels declared in backstage.io/kubernetes-label-selector on your Kubernetes resources. This annotation overrides entity-based or namespace-based identification annotations, such as backstage.io/kubernetes-id and backstage.io/kubernetes-namespace.

4. Add label to Kubernetes resources to enable Developer Hub to find the appropriate Kubernetes resources.

   1. Developer Hub Kubernetes plugin label: Add this label to map resources to specific Developer Hub entities.

      labels:
        ...
        backstage.io/kubernetes-id: <BACKSTAGE_ENTITY_NAME>

   2. GitOps application mapping: Add this label to map Argo CD Rollouts to a specific GitOps application

      labels:
        ...
        app.kubernetes.io/instance: <GITOPS_APPLICATION_NAME>

   Note

   If using the label selector annotation (backstage.io/kubernetes-label-selector), ensure the specified labels are present on the resources. The label selector will override other annotations such as kubernetes-id or kubernetes-namespace.

Verification

1. Push the updated configuration to your GitOps repository to trigger a rollout.
2. Open Red Hat Developer Hub interface and navigate to the entity you configured.
3. Select the CD tab and then select the GitOps application. The side panel opens.

4. In the Resources table of the side panel, verify that the following resources are displayed:

   • Rollouts
   • Analysis Runs (optional)

5. Expand a rollout resource and review the following details:

   • The Revisions row displays traffic distribution details for different rollout versions.
   • The Analysis Runs row displays the status of analysis tasks that evaluate rollout success.