OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Sharding clusters across Argo CD Application Controller replicas

Enabling the round-robin sharding algorithm

The round-robin sharding algorithm is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

By default, the Argo CD Application Controller uses the non-uniform legacy hash-based sharding algorithm to assign clusters to shards. This can result in uneven cluster distribution. You can enable the round-robin sharding algorithm to achieve more equal cluster distribution across all shards.

Using the round-robin sharding algorithm in Red Hat OpenShift GitOps provides the following benefits:

  • Ensure more balanced workload distribution

  • Prevent shards from being overloaded or underutilized

  • Optimize the efficiency of computing resources

  • Reduce the risk of bottlenecks

  • Improve overall performance and reliability of the Argo CD system

The introduction of alternative sharding algorithms allows for further customization based on specific use cases. You can select the algorithm that best aligns with your deployment needs, which results in greater flexibility and adaptability in diverse operational scenarios.

To leverage the benefits of alternative sharding algorithms in GitOps, it is crucial to enable sharding during deployment.

Enabling the round-robin sharding algorithm in the web console

You can enable the round-robin sharding algorithm by using the OpenShift Container Platform web console.

Prerequisites

  • You have installed the Red Hat OpenShift GitOps Operator in your cluster.

  • You have access to the OpenShift Container Platform web console.

  • You have access to the cluster with cluster-admin privileges.

Procedure

  1. In the Administrator perspective of the web console, go to Operators → Installed Operators.

  2. Click Red Hat OpenShift GitOps from the installed operators and go to the Argo CD tab.

  3. Click the Argo CD instance where you want to enable the round-robin sharding algorithm, for example, openshift-gitops.

  4. Click the YAML tab and edit the YAML file as shown in the following example:

    Example Argo CD instance with round-robin sharding algorithm enabled
    apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: openshift-gitops
  namespace: openshift-gitops
spec:
  controller:
    sharding:
      enabled: true (1)
      replicas: 3 (2)
    env: (3)
      - name: ARGOCD_CONTROLLER_SHARDING_ALGORITHM
        value: round-robin
    logLevel: debug (4)
    1 Set the sharding.enabled parameter to true to enable sharding.
    2 Set the number of replicas to the wanted value, for example, 3.
    3 Set the sharding algorithm to round-robin.
    4 Set the log level to debug so that you can verify to which shard each cluster is attached.

  5. Click Save.

    A success notification alert, openshift-gitops has been updated to version <version>, appears.

    If you edit the default openshift-gitops instance, the Managed resource dialog box is displayed. Click Save again to confirm the changes.

  6. Verify that the sharding is enabled with round-robin as the sharding algorithm by performing the following steps:

    1. Go to Workloads → StatefulSets.

    2. Select the namespace where you installed the Argo CD instance from the Project drop-down list.

    3. Click <instance_name>-application-controller, for example, openshift-gitops-application-controller, and go to the Pods tab.

    4. Observe the number of created application controller pods. It should correspond with the number of set replicas.

    5. Click on the controller pod you want to examine and go to the Logs tab to view the pod logs.

      Example controller pod logs snippet
      time="2023-12-13T09:05:34Z" level=info msg="ArgoCD Application Controller is starting" built="2023-12-01T19:21:49Z" commit=a3vd5c3df52943a6fff6c0rg181fth3248976299 namespace=openshift-gitops version=v2.9.2+c5ea5c4
time="2023-12-13T09:05:34Z" level=info msg="Processing clusters from shard 1"
time="2023-12-13T09:05:34Z" level=info msg="Using filter function:  round-robin" (1)
time="2023-12-13T09:05:34Z" level=info msg="Using filter function:  round-robin"
time="2023-12-13T09:05:34Z" level=info msg="appResyncPeriod=3m0s, appHardResyncPeriod=0s"
      1 Look for the "Using filter function: round-robin" message.

    6. In the log Search field, search for processed by shard to verify that the cluster distribution across shards is even, as shown in the following example.

      Ensure that you set the log level to debug to observe these logs.
      Example controller pod logs snippet
      time="2023-12-13T09:05:34Z" level=debug msg="ClustersList has 3 items"
time="2023-12-13T09:05:34Z" level=debug msg="Adding cluster with id= and name=in-cluster to cluster's map"
time="2023-12-13T09:05:34Z" level=debug msg="Adding cluster with id=068d8b26-6rhi-4w23-jrf6-wjjfyw833n23 and name=in-cluster2 to cluster's map"
time="2023-12-13T09:05:34Z" level=debug msg="Adding cluster with id=836d8b53-96k4-f68r-8wq0-sh72j22kl90w and name=in-cluster3 to cluster's map"
time="2023-12-13T09:05:34Z" level=debug msg="Cluster with id= will be processed by shard 0" (1)
time="2023-12-13T09:05:34Z" level=debug msg="Cluster with id=068d8b26-6rhi-4w23-jrf6-wjjfyw833n23 will be processed by shard 1" (1)
time="2023-12-13T09:05:34Z" level=debug msg="Cluster with id=836d8b53-96k4-f68r-8wq0-sh72j22kl90w will be processed by shard 2" (1)
      1 In this example, 3 clusters are attached consecutively to shard 0, shard 1, and shard 2.

      If the number of clusters "C" is a multiple of the number of shard replicas "R", then each shard must have the same number of assigned clusters "N", which is equal to "C" divided by "R". The previous example shows 3 clusters and 3 replicas; therefore, each shard has 1 cluster assigned.

Enabling the round-robin sharding algorithm by using the CLI

You can enable the round-robin sharding algorithm by using the command-line interface.

Prerequisites

  • You have installed the Red Hat OpenShift GitOps Operator in your cluster.

  • You have access to the cluster with cluster-admin privileges.

Procedure

  1. Enable sharding and set the number of replicas to the wanted value by running the following command:

    $ oc patch argocd <argocd_instance> -n <namespace> --patch='{"spec":{"controller":{"sharding":{"enabled":true,"replicas":<value>}}}}' --type=merge
    Example output
    argocd.argoproj.io/<argocd_instance> patched

  2. Configure the sharding algorithm to round-robin by running the following command:

    $ oc patch argocd <argocd_instance> -n <namespace> --patch='{"spec":{"controller":{"env":[{"name":"ARGOCD_CONTROLLER_SHARDING_ALGORITHM","value":"round-robin"}]}}}' --type=merge
    Example output
    argocd.argoproj.io/<argocd_instance> patched

  3. Verify that the number of Argo CD Application Controller pods corresponds with the number of set replicas by running the following command:

    $ oc get pods -l app.kubernetes.io/name=<argocd_instance>-application-controller -n <namespace>
    Example output
    NAME                                        READY   STATUS    RESTARTS   AGE
<argocd_instance>-application-controller-0   1/1     Running   0          11s
<argocd_instance>-application-controller-1   1/1     Running   0          32s
<argocd_instance>-application-controller-2   1/1     Running   0          22s

  4. Verify that the sharding is enabled with round-robin as the sharding algorithm by running the following command:

    $ oc logs <argocd_application_controller_pod> -n <namespace>
    Example output snippet
    time="2023-12-13T09:05:34Z" level=info msg="ArgoCD Application Controller is starting" built="2023-12-01T19:21:49Z" commit=a3vd5c3df52943a6fff6c0rg181fth3248976299 namespace=<namespace> version=v2.9.2+c5ea5c4
time="2023-12-13T09:05:34Z" level=info msg="Processing clusters from shard 1"
time="2023-12-13T09:05:34Z" level=info msg="Using filter function:  round-robin" (1)
time="2023-12-13T09:05:34Z" level=info msg="Using filter function:  round-robin"
time="2023-12-13T09:05:34Z" level=info msg="appResyncPeriod=3m0s, appHardResyncPeriod=0s"
    1 Look for the "Using filter function: round-robin" message.

  5. Verify that the cluster distribution across shards is even by performing the following steps:

    1. Set the log level to debug by running the following command:

      $ oc patch argocd <argocd_instance> -n <namespace> --patch='{"spec":{"controller":{"logLevel":"debug"}}}' --type=merge
      Example output
      argocd.argoproj.io/<argocd_instance> patched

    2. View the logs and search for processed by shard to observe to which shard each cluster is attached by running the following command:

      $ oc logs <argocd_application_controller_pod> -n <namespace> | grep "processed by shard"
      Example output snippet
      time="2023-12-13T09:05:34Z" level=debug msg="Cluster with id= will be processed by shard 0" (1)
time="2023-12-13T09:05:34Z" level=debug msg="Cluster with id=068d8b26-6rhi-4w23-jrf6-wjjfyw833n23 will be processed by shard 1" (1)
time="2023-12-13T09:05:34Z" level=debug msg="Cluster with id=836d8b53-96k4-f68r-8wq0-sh72j22kl90w will be processed by shard 2" (1)
      1 In this example, 3 clusters are attached consecutively to shard 0, shard 1, and shard 2.

      If the number of clusters "C" is a multiple of the number of shard replicas "R", then each shard must have the same number of assigned clusters "N", which is equal to "C" divided by "R". The previous example shows 3 clusters and 3 replicas; therefore, each shard has 1 cluster assigned.

Enabling dynamic scaling of shards of the Argo CD Application Controller

Dynamic scaling of shards is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

By default, the Argo CD Application Controller assigns clusters to shards indefinitely. If you are using the round-robin sharding algorithm, this static assignment can result in uneven distribution of shards, particularly when replicas are added or removed. You can enable dynamic scaling of shards to automatically adjust the number of shards based on the number of clusters managed by the Argo CD Application Controller at a given time. This ensures that shards are well-balanced and optimizes the use of compute resources.

After you enable dynamic scaling, you cannot manually modify the shard count. The system automatically adjusts the number of shards based on the number of clusters managed by the Argo CD Application Controller at a given time.

Enabling dynamic scaling of shards in the web console

You can enable dynamic scaling of shards by using the OpenShift Container Platform web console.

Prerequisites

  • You have access to the cluster with cluster-admin privileges.

  • You have access to the OpenShift Container Platform web console.

  • You have installed the Red Hat OpenShift GitOps Operator in your cluster.

Procedure

  1. In the Administator perspective of the OpenShift Container Platform web console, go to Operators → Installed Operators.

  2. From the the list of Installed Operators, select the Red Hat OpenShift GitOps Operator, and then click the ArgoCD tab.

  3. Select the Argo CD instance name for which you want to enable dynamic scaling of shards, for example, openshift-gitops.

  4. Click the YAML tab, and then edit and configure the spec.controller.sharding properties as follows:

    Example Argo CD YAML file with dynamic scaling enabled
    apiVersion: argoproj.io/v1beta1
kind: ArgoCD
metadata:
  name: openshift-gitops
  namespace: openshift-gitops
spec:
  controller:
    sharding:
      dynamicScalingEnabled: true (1)
      minShards: 1 (2)
      maxShards: 3 (3)
      clustersPerShard: 1 (4)
    1 Set dynamicScalingEnabled to true to enable dynamic scaling.
    2 Set minShards to the minimum number of shards that you want to have. The value must be set to 1 or greater.
    3 Set maxShards to the maximum number of shards that you want to have. The value must be greater than the value of minShards.
    4 Set clustersPerShard to the number of clusters that you want to have per shard. The value must be set to 1 or greater.

  5. Click Save.

    A success notification alert, openshift-gitops has been updated to version <version>, appears.

    If you edit the default openshift-gitops instance, the Managed resource dialog box is displayed. Click Save again to confirm the changes.
Verification

Verify that sharding is enabled by checking the number of pods in the namespace:

  1. Go to Workloads → StatefulSets.

  2. Select the namespace where the Argo CD instance is deployed from the Project drop-down list, for example, openshift-gitops.

  3. Click the name of the StatefulSet object that has the name of the Argo CD instance, for example openshift-gitops-apllication-controller.

  4. Click the Pods tab, and then verify that the number of pods is equal to or greater than the value of minShards that you have set in the Argo CD YAML file.

Enabling dynamic scaling of shards by using the CLI

You can enable dynamic scaling of shards by using the OpenShift CLI (oc).

Prerequisites

  • You have installed the Red Hat OpenShift GitOps Operator in your cluster.

  • You have access to the cluster with cluster-admin privileges.

Procedure

  1. Log in to the cluster by using the oc tool as a user with cluster-admin privileges.

  2. Enable dynamic scaling by running the following command:

    $ oc patch argocd <argocd_instance> -n <namespace> --type=merge --patch='{"spec":{"controller":{"sharding":{"dynamicScalingEnabled":true,"minShards":<value>,"maxShards":<value>,"clustersPerShard":<value>}}}}'
    Example command
    $ oc patch argocd openshift-gitops -n openshift-gitops --type=merge --patch='{"spec":{"controller":{"sharding":{"dynamicScalingEnabled":true,"minShards":1,"maxShards":3,"clustersPerShard":1}}}}' (1)
    1 The example command enables dynamic scaling for the openshift-gitops Argo CD instance in the openshift-gitops namespace, and sets the minimum number of shards to 1, the maximum number of shards to 3, and the number of clusters per shard to 1. The values of minShard and clustersPerShard must be set to 1 or greater. The value of maxShard must be equal to or greater than the value of minShard.
    Example output
    argocd.argoproj.io/openshift-gitops patched
Verification

  1. Check the spec.controller.sharding properties of the Argo CD instance:

    $ oc get argocd <argocd_instance> -n <namespace> -o jsonpath='{.spec.controller.sharding}'
    Example command
    $ oc get argocd openshift-gitops -n openshift-gitops -o jsonpath='{.spec.controller.sharding}'
    Example output when dynamic scaling of shards is enabled
    {"dynamicScalingEnabled":true,"minShards":1,"maxShards":3,"clustersPerShard":1}

  2. Optional: Verify that dynamic scaling is enabled by checking the configured spec.controller.sharding properties in the configuration YAML file of the Argo CD instance in the OpenShift Container Platform web console.

  3. Check the number of Argo CD Application Controller pods:

    $ oc get pods -n <namespace> -l app.kubernetes.io/name=<argocd_instance>-application-controller
    Example command
    $ oc get pods -n openshift-gitops -l app.kubernetes.io/name=openshift-gitops-application-controller
    Example output
    NAME                                           READY   STATUS    RESTARTS   AGE
openshift-gitops-application-controller-0      1/1     Running   0          2m  (1)
    1 The number of Argo CD Application Controller pods must be greater than or equal to the value of minShard.
Additional resources