github.com/argoproj/argo-cd/v2@v2.10.9/docs/operator-manual/applicationset/index.md (about)

     1  # Introduction to ApplicationSet controller
     2  
     3  ## Introduction
     4  
     5  The ApplicationSet controller is a [Kubernetes controller](https://kubernetes.io/docs/concepts/architecture/controller/) that adds support for an `ApplicationSet` [CustomResourceDefinition](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) (CRD). This controller/CRD enables both automation and greater flexibility managing [Argo CD](../../index.md) Applications across a large number of clusters and within monorepos, plus it makes self-service usage possible on multitenant Kubernetes clusters.
     6  
     7  The ApplicationSet controller works alongside an existing [Argo CD installation](../../index.md). Argo CD is a declarative, GitOps continuous delivery tool, which allows developers to define and control deployment of Kubernetes application resources from within their existing Git workflow.
     8  
     9  Starting with Argo CD v2.3, the ApplicationSet controller is bundled with Argo CD.
    10  
    11  The ApplicationSet controller, supplements Argo CD by adding additional features in support of cluster-administrator-focused scenarios. The `ApplicationSet` controller provides:
    12  
    13  - The ability to use a single Kubernetes manifest to target multiple Kubernetes clusters with Argo CD
    14  - The ability to use a single Kubernetes manifest to deploy multiple applications from one or multiple Git repositories with Argo CD
    15  - Improved support for monorepos: in the context of Argo CD, a monorepo is multiple Argo CD Application resources defined within a single Git repository
    16  - Within multitenant clusters, improves the ability of individual cluster tenants to deploy applications using Argo CD (without needing to involve privileged cluster administrators in enabling the destination clusters/namespaces)
    17  
    18  !!! note
    19      Be aware of the [security implications](./Security.md) of ApplicationSets before using them.
    20  
    21  ## The ApplicationSet resource
    22  
    23  This example defines a new `guestbook` resource of kind `ApplicationSet`:
    24  ```yaml
    25  apiVersion: argoproj.io/v1alpha1
    26  kind: ApplicationSet
    27  metadata:
    28    name: guestbook
    29  spec:
    30    goTemplate: true
    31    goTemplateOptions: ["missingkey=error"]
    32    generators:
    33    - list:
    34        elements:
    35        - cluster: engineering-dev
    36          url: https://1.2.3.4
    37        - cluster: engineering-prod
    38          url: https://2.4.6.8
    39        - cluster: finance-preprod
    40          url: https://9.8.7.6
    41    template:
    42      metadata:
    43        name: '{{.cluster}}-guestbook'
    44      spec:
    45        project: my-project
    46        source:
    47          repoURL: https://github.com/infra-team/cluster-deployments.git
    48          targetRevision: HEAD
    49          path: guestbook/{{.cluster}}
    50        destination:
    51          server: '{{.url}}'
    52          namespace: guestbook
    53  ```
    54  
    55  In this example, we want to deploy our `guestbook` application (with the Kubernetes resources for this application coming from Git, since this is GitOps) to a list of Kubernetes clusters (with the list of target clusters defined in the List items element of the `ApplicationSet` resource).
    56  
    57  While there are multiple types of *generators* that are available to use with the `ApplicationSet` resource, this example uses the List generator, which simply contains a fixed, literal list of clusters to target. This list of clusters will be the clusters upon which Argo CD deploys the `guestbook` application resources, once the ApplicationSet controller has processed the `ApplicationSet` resource.
    58  
    59  Generators, such as the List generator, are responsible for generating *parameters*. Parameters are key-values pairs that are substituted into the `template:` section of the ApplicationSet resource during template rendering.
    60  
    61  There are multiple generators currently supported by the ApplicationSet controller:
    62  
    63  - **List generator**: Generates parameters based on a fixed list of cluster name/URL values, as seen in the example above.
    64  - **Cluster generator**: Rather than a literal list of clusters (as with the list generator), the cluster generator automatically generates cluster parameters based on the clusters that are defined within Argo CD.
    65  - **Git generator**: The Git generator generates parameters based on files or folders that are contained within the Git repository defined within the generator resource.
    66      - Files containing JSON values will be parsed and converted into template parameters.
    67      - Individual directory paths within the Git repository may be used as parameter values, as well.
    68  - **Matrix generator**: The Matrix generators combines the generated parameters of two other generators.
    69  
    70  See the [generator section](Generators.md) for more information about individual generators, and the other generators not listed above.
    71  
    72  ## Parameter substitution into templates
    73  
    74  Independent of which generator is used, parameters generated by a generator are substituted into `{{parameter name}}` values within the `template:` section of the `ApplicationSet` resource. In this example, the List generator defines `cluster` and `url` parameters, which are then substituted into the template's `{{cluster}}` and `{{url}}` values, respectively.
    75  
    76  After substitution, this `guestbook` `ApplicationSet` resource is applied to the Kubernetes cluster:
    77  
    78  1. The ApplicationSet controller processes the generator entries, producing a set of template parameters.
    79  2. These parameters are substituted into the template, once for each set of parameters.
    80  3. Each rendered template is converted into an Argo CD `Application` resource, which is then created (or updated) within the Argo CD namespace.
    81  4. Finally, the Argo CD controller is notified of these `Application` resources and is responsible for handling them.
    82  
    83  
    84  With the three different clusters defined in our example -- `engineering-dev`, `engineering-prod`, and `finance-preprod` -- this will produce three new Argo CD `Application` resources: one for each cluster.
    85  
    86  Here is an example of one of the `Application` resources that would be created, for the `engineering-dev` cluster at `1.2.3.4`:
    87  ```yaml
    88  apiVersion: argoproj.io/v1alpha1
    89  kind: Application
    90  metadata:
    91    name: engineering-dev-guestbook
    92  spec:
    93    source:
    94      repoURL: https://github.com/infra-team/cluster-deployments.git
    95      targetRevision: HEAD
    96      path: guestbook/engineering-dev
    97    destination:
    98      server: https://1.2.3.4
    99      namespace: guestbook
   100  ```
   101  We can see that the generated values have been substituted into the `server` and `path` fields of the template, and the template has been rendered into a fully-fleshed out Argo CD Application.
   102  
   103  The Applications are now also visible from within the Argo CD UI:
   104  
   105  ![List generator example in Argo CD Web UI](../../assets/applicationset/Introduction/List-Example-In-Argo-CD-Web-UI.png)
   106  
   107  The ApplicationSet controller will ensure that any changes, updates, or deletions made to `ApplicationSet` resources are automatically applied to the corresponding `Application`(s).
   108  
   109  For instance, if a new cluster/URL list entry was added to the List generator, a new Argo CD `Application` resource would be accordingly created for this new cluster. Any edits made to the `guestbook` `ApplicationSet` resource will affect all the Argo CD Applications that were instantiated by that resource, including the new Application.
   110  
   111  While the List generator's literal list of clusters is fairly simplistic, much more sophisticated scenarios are supported by the other available generators in the ApplicationSet controller.