Skip to main content

Declarative management

There are two types of settings that can be managed using the declarative approach:

  • End users/developers specific settings such as Application, ApplicationSet, and AppProject resources.
  • Platform-specific settings such as IP allow lists, system accounts and availability of additional Argo CD components.

Developers-specific settings​

Declarative management allows you to use the Argo CD control plane on the Akuity platform to host Application, ApplicationSet, and AppProject resources. This is used for implementing:

  • Argo CD's app of apps pattern to declaratively specify one Argo CD Application resource that points to a Git repository consisting only of other Application resources.
  • ApplicationSet resources to manage a set of Argo CD Applications.

The resources deployed into the control plane must specify the namespace argocd and the destination name in-cluster (server https://kubernetes.default.svc). The child Applications (that deploy anything other than an Application, ApplicationSet, or AppProject) must target a connected cluster other than in-cluster.

Example: App of Apps​

The parent Application created via the Argo CD dashboard:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: example-apps
  namespace: argocd
spec:
    destination:
      namespace: argocd
      name: in-cluster
    project: default
    source:
      repoURL: 'https://github.com/argoproj/argocd-example-apps'
      path: apps
      targetRevision: HEAD  
      helm:  # Set the destination cluster for the child Applications in the Helm chart.
        values: |-
          spec:
            destination:
              name: my-cluster
  • The destination.name is in-cluster and the destination.namespace is argocd. This will deploy child Applications into the Argo CD control plane on the Akuity Platform.

The child Application created by the parent app:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: helm-guestbook
  namespace: argocd
spec:
  destination:
    name: my-cluster
    namespace: default
  project: default
  source:
    path: helm-guestbook
    repoURL: 'https://github.com/argoproj/argocd-example-apps'
    targetRevision: HEAD
  • The destination.name is my-cluster, which is an external cluster connected to the Argo CD instance on the Akuity Platform (See "Connect a Kubernetes cluster"). This is where the resources for the guestbook app will be deployed (i.e., the Deployment and Service).

Enabling declarative management​

To enable declarative management:

  1. Navigate to Argo CD → your instance → Settings → General.

  2. Scroll down to Control Plane Cluster (in-cluster) and toggle the Enabled switch.

  3. Click Save.

Once the Argo CD instance has finished progressing, the in-cluster destination will be available.

Application Set​

By default, the ApplicationSet Controller will run on the Control Plane which is fine for most use cases. ApplicationSet Delegate (Single Managed Cluster) compliments the Repo Server Delegate by allowing ApplicationSets that use webhooks, private Helm, or private git repositories to access the credentials needed to perform git operations.

ApplicationSet Delegate​

  1. Switch from Control plane to Single Managed Cluster

  2. Select the cluster you want to use as the ApplicationSet Delegate.

  3. Click Save.

Policy (Global)​

A Policy defines how application is synced between the generator and the cluster. Default is 'empty', options: 'sync' (create & update & delete), 'create-only', 'create-update' (no deletion), 'create-delete' (no update)

Allow Override​

Starting with Argo CD v2.8 a policy can be specified per ApplicationSet. Enabling the override will allow a policy per ApplicationSet to override a global policy.

Progressive Syncs​

Alpha

This feature is currently in Alpha status.

The Progressive Syncs feature allows you to control the order in which the ApplicationSet controller will create or update the Applications owned by an ApplicationSet resource. This is useful when you need to roll out changes to applications in a controlled, sequential manner rather than all at once.

For more details on Progressive Syncs, see the Argo CD Progressive Syncs documentation.

To enable Progressive Syncs:

  1. Navigate to Argo CD → your instance → Settings → Application Set.

  2. Scroll down to Progressive Syncs and toggle the Enabled switch.

  3. Click Save.

SCM Providers​

The SCM Provider and Pull Request generators call an SCM API with a token read from the tokenRef of the ApplicationSet. Three settings control them:

  • Enabled: runs the two generators. When off, every ApplicationSet that uses them fails to generate. On by default.
  • Allowed API URLs: the custom API URLs (protocol included, matched exactly, for example https://git.example.com/) a generator may call. Empty allows any URL. Providers that do not take a custom api are always allowed.
  • TokenRef Strict Mode: lets tokenRef read only secrets labelled argocd.argoproj.io/secret-type: scm-creds. The platform-managed application-set-secret carries that label, as can a managed secret. On by default; with it off, any secret the controller can read can be sent to the generator's API URL.

The allow list and strict mode only apply while the generators are enabled. These map to the applicationsetcontroller.enable.scm.providers, applicationsetcontroller.allowed.scm.providers and applicationsetcontroller.enable.tokenref.strict.mode Argo CD parameters.

To change them:

  1. Navigate to Argo CD → your instance → Settings → Application Set.

  2. Scroll down to SCM Providers and set the switches and the allowed API URLs.

  3. Click Save.

ApplicationSets in Any Namespace​

By default the ApplicationSet controller only reconciles ApplicationSets in the argocd namespace. This setting lets it reconcile ApplicationSets in any namespace of the control plane cluster; the generated Applications are created in the ApplicationSet's namespace. See the Argo CD documentation.

The platform checks two prerequisites when you save, because the controller refuses to start without them:

The AppProject an ApplicationSet uses must also list its namespace in spec.sourceNamespaces:

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: default
  namespace: argocd
spec:
  sourceNamespaces:
    - team-a

To enable it:

  1. Navigate to Argo CD → your instance → Settings → Application Set.

  2. Scroll down to ApplicationSets in Any Namespace and toggle the Enabled switch.

  3. Click Save.

Using secrets in ApplicationSets​

With TokenRef Strict Mode on (the default), a tokenRef in an ApplicationSet can only read secrets labelled argocd.argoproj.io/secret-type: scm-creds. The platform-managed secret named application-set-secret carries that label, so the credentials used by your ApplicationSets are managed and audited by the platform.

note

A managed secret can be given the argocd.argoproj.io/secret-type: scm-creds label to be usable from a tokenRef as well. Repository credentials are not, so they can no longer be referenced unless strict mode is turned off.

warning

If you are using the Secret Syncing feature and a managed cluster has synced its own application-set-secret, that cluster owns the notification secret.

The Akuity Platform UI will display a warning banner and disable the edit controls for application-set-secret to prevent conflicting changes.

See Adoptable Secrets for details on how adoption works and how to return control to the Akuity Platform control plane.

Setting Up Secrets

To configure secrets for use with ApplicationSets:

  1. Navigate to Argo CD → your instance → Settings → Application Set.

  2. Scroll down to Secrets and add your key-value pairs (e.g., tokens, credentials) that you want to store in the application-set-secret.

  3. Save the configuration. The platform will automatically create or update the application-set-secret.

Plugins Generator​

The ApplicationSet Plugin Generator allows you to configure custom plugin generators that can be used with ApplicationSets. This feature enables you to extend the functionality of ApplicationSet generators by providing your own custom logic for generating application parameters.

For detailed information about implementing plugin generators, see the Argo CD Plugin Generator documentation.

Adding a Plugin​

  1. Navigate to Argo CD → your instance → Settings → Application Set.

  2. Under Secrets, add a key that holds the token your plugin expects, for example plugin-token. See Using secrets in ApplicationSets.

  3. Scroll down to the Plugins Generator section.

  4. Configure the following fields:

    • Name: A unique identifier for your plugin (the field is pre-filled with plugin-, so you would enter something like my-custom-plugin to create plugin-my-custom-plugin)
    • Base URL: The base URL of the Kubernetes service exposing your plugin in the cluster (e.g., http://myplugin.plugin-ns.svc.cluster.local). In most cases, this will be a deployment running on your cluster and not publicly accessible.
    • Request Timeout: Timeout for requests to the plugin in seconds
    • Token: A reference to the secret key that holds your plugin token, not the token itself. For the key added above, enter $application-set-secret:plugin-token.

  5. Click + Add Plugin to add the plugin configuration.

  6. Click Save to apply the changes.

tip

The Token field only accepts a secret key reference:

  • $application-set-secret:<key> reads <key> from application-set-secret, which you manage under Secrets.

  • $<key> reads <key> from argocd-secret.

Saving a value that does not start with $ fails. The ApplicationSet controller resolves the reference when it calls your plugin, so the token itself never appears in the instance configuration.

note

The base URL should point to a Kubernetes service that exposes your plugin. The service should be accessible from the ApplicationSet controller's namespace.

Important: If your plugin service is not publicly accessible, you will need to enable the ApplicationSet Delegate feature and delegate to the cluster where your plugin service is running.