ApplicationSet 0.2.0 release notes (draft)

[jgwest]

NOTE: This is pre-release draft text for the ApplicationSet 0.2.0 release notes: content is not relevant until on or after release day.

(WIP) Draft Release Notes

I am happy to announce the second release of the Argo CD ApplicationSet controller, v0.2.0. Many new features were contributed as part of this release, including support for combining generator parameters, support for building Argo CD Applications based on GitHub/GitLab organizations, and support for using custom resources to select clusters, plus oft requested improvements to existing generators, and of course doc updates, usability improvements, stability fixes, and more.

You can learn more about this from the ApplicationSet documentation or check out the source and learn how you can contribute.

Contributors

Many many thanks to all the folks who have contributed to the ApplicationSet controller over the past few months. These many contributions, both big and small, general and specific, help to bring a more featureful and polished experience to Argo CD users. We could not do this without all of you!

• Omer Kahani (@OmerKahani)
• Joshua Packer (@jnpacker)
• Jonathan West (@jgwest)
• Noah Kantrowitz (@coderanger)
• Lior Lieberman (@LiorLieberman)
• Michael Matur (@mmatur)
• TJ Miller (@teejaded)
• John Thompson (@empath-nirvana)
• Ishita Sequeira (@ishitasequeira)
• Chetan Banavikalmutt (@chetan-rns)
• William Tam (@wtam2018)
• John Watson (@dctrwatson)
• Tencho Tenev (@tenevdev)
• Ryan Umstead (@rumstead)
• Stephan Auerhahn(@palp)
• Christian Hernandez (@christianh814)
• Mohit Kumar Sharma (@mksha)
• Vivien Fricadel (@vivienfricadelamadeus)
• Gareth Western (@gdubya)
• William Jeffries (@williamcodes)
• Mehran Poursadeghi (@mehran-prs)

Want to join us for our next release? Check out the project repository (https://github.com/argoproj-labs/applicationset) or visit us on #argo-cd-appset on Slack (https://argoproj.github.io/community/join-slack/).

New in this Release

Matrix generator

The Matrix generator is a new generator that combines the parameters generated by two child generators, iterating through every combination of each generator's set:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-git
spec:
  generators:
    - matrix: # 'Parent' Matrix Generator
        generators:
          - git: # 'Child' generator A
              repoURL: https://github.com/argoproj-labs/applicationset.git
              revision: HEAD
              directories:
                - path: examples/matrix/cluster-addons/*
          - clusters: # 'Child' generator B
              selector:
                matchLabels:
                  argocd.argoproj.io/secret-type: cluster
  template:
  # (...)

The parameters generated by a Git generator (looking for directories within a Git Repository), and by a Cluster generator (looking for Argo CD-managed clusters), are combined: this will generate Argo CD Applications that target each of the Git directories (containing Kubernetes manifests), for each cluster managed by Argo CD.

See the Matrix generator documentation for an in-depth example of how generator parameters are combined. Contributed by @OmerKahani.

SCM Provider generator

The SCM Provider generator is a new generator that utilizes the API of GitHub/GitLab to automatically discover repositories within an organization, allowing the repository values to be used for targeting generated Argo CD Applications. This fits well with GitOps layout patterns that split microservices across many repositories, rather than those patterns that stick to a single repository (which can be handled by other ApplicationSet generators).

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: myapps
spec:
  generators:
  - scmProvider:
      github:
        organization: myorg         # The GitHub organization to scan.
        tokenRef: { } # Reference to a Secret containing an access token. (optional)
  template:
  # ...

The ApplicationSet controller will then scan the provided GitHub/GitLab organization and produce template parameters for each discovered repository/branch, which may be used to generate Argo CD Applications for each of these repositories.

See the SCM Provider generator documentation for more information. Initial implementation and GitHub support contributed by @coderanger, and GitLab support contributed by @empath-nirvana.

Cluster Decision Resource generator

The Cluster Decision Resource generator is a new generator that generates a list of Argo CD clusters based on the contents of an external custom resource (CR), with that custom resource managed by an external controller. With the Cluster Decision Resource generator, you may 'outsource' the logic (of which clusters to target) to third party controllers/CRs, such as the Open Cluster Management's Placements.

This is handled seamlessly using duck-typing, which does not require knowledge of the full shape of the referenced Kubernetes resource. The following is an example of a cluster-decision-resource-based ApplicationSet generator:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
 name: guestbook
spec:
 generators:
 - clusterDecisionResource:
    # ConfigMap with GVK information for the duck type resource
    configMapRef: my-configmap      
    name: quak  # Choose either "name" of the resource or "labelSelector"

Which might reference an external resource named quak, managed by an external controller, containing a list of clusters:

apiVersion: mallard.io/v1beta1
kind: Duck
metadata:
  name: quak
spec: {}
status:
  decisions:   # Duck-typing ignores all other aspects of the resource except the "decisions" list
  - clusterName: cluster-01
  - clusterName: cluster-02

See the Cluster Decision Resource generator documentation for more information. Cluster Decision Resource generator and labelSelector support contributed by @jnpacker.

Preserve Application child resources on deletion of parent ApplicationSet

By default, Applications created and managed by the ApplicationSet controller include the Argo CD resource deletion finalizer. This means that when an ApplicationSet is deleted, its child Applications will be deleted, as well as the cluster resources of those child Applications. This is the same behaviour as a cascade delete within Argo CD.

However, this behaviour is not always desirable: one may want to preserve the Application child resources on deletion of the parent Application. To enable this, using the .spec.syncPolicy.preserveResourcesOnDeletion value in the parent ApplicationSet:

kind: ApplicationSet
spec:
  generators:
    - clusters: {}
  template:
    # (...)
  syncPolicy:
    # Don't delete Application's child resources, on parent deletion:
    preserveResourcesOnDeletion: true

See the Application Deletion Behaviour documentation for more information. Contributed by @mmatur.

Add YAML configuration file support to Git File generator

In the previous ApplicationSet release, only JSON-formatted configuration files were supported by the Git File generator. Now, both JSON and YAML files are supported, and may be used interchangeably. Contributed by @teejaded.

Allow any key/value pair in List generator

The List generator previously only supported a fixed list of cluster name/URL values, with an optional values field for user-defined values. You can now specify any key/value pair:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
spec:
 generators:
 - list:
     elements:
     # current form, still supported:
     - cluster: engineering-dev
       url: https://kubernetes.default.svc
       values:
         additional: value
     # new form, does not require cluster/URL keys:
     - staging: true
       gitRepo: https://kubernetes.default.svc   
 template:
   # (...)

This new form is fully backwards compatible with existing v0.1.0-originated ApplicationSets, and no migration steps are needed. See the List generator documentation for more information. Contributed by @ishitasequeira.

Added additional path params to Git File generator

The Git File generator now produces {{ path }} and {{ path.basename }} parameters, containing the path of the configuration file, similar to the same parameters already produced by the Git Directory generator. Contributed by @ishitasequeira.

Add exclude path support to Git directories

The Git Directory generator scans directories within a Git repository, looking for directories that match specific criteria. However, with the previous ApplicationSet release, there was no way to exclude folders from the scan.

The ability to exclude individual paths from being scanned is now supported:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-addons
spec:
  generators:
  - git:
      repoURL: https://github.com/argoproj-labs/applicationset.git
      revision: HEAD
      directories:
      # Include this first path 
      - path: examples/git-generator-directory/excludes/cluster-addons/* 
      # But, exclude this second path:
      - path: examples/git-generator-directory/excludes/cluster-addons/exclude-helm-guestbook
        exclude: true

Contributed by @LiorLieberman.

Quality of Life Improvements

• Git Directory generator should ignore all folders starting with '.' (#201, contributed by @LiorLieberman)
• Add support for custom 'finalizers' in Application templates (#289, contributed by @tenevdev)
• Enable the ability to set log level on ApplicationSet controller startup (#249, contributed by @rumstead)
• Add 'appset/appsets' shortnames to the ApplicationSet CRD (#184, contributed by @christianh814)
• Log appset version during controller startup log (#241, contributed by @chetan-rns)

Fixes, infrastructure, and docs

Fixes:

• Race condition on cluster creation/deletion causes unexpected behaviour (#198, contributed by @jgwest)
• Sanitize cluster name param by replacing unsupported character (#237, contributed by @chetan-rns)
• Remove the unused SkipPrune from ApplicationSetSyncPolicy (#268, contributed by @ishitasequeira)
• ApplicationSets that initially fail validation might not be re-reconciled (#296, contributed by @jgwest)
• Remove unnecessary RBAC permissions 'delete events' and 'update events' that are not available at namespace level (#278, contributed by @vivienfricadelamadeus)
• Issue 170 is not solved when using server, only when using name for destination (#282, contributed by @jgwest)
• Check path exists passed in application spec (#253, contributed by @mksha)
• Handle conversion to string in git generator (#235, contributed by @chetan-rns)
• Add git-lfs to resolve error using files generator (#215, contributed by @palp)
• Preserve ArgoCD Notification state (#193, contributed by @dctrwatson)
• Matrix generator's getParams should check error return to avoid panic (#326, contributed by @jgwest )
• Add missing generators to supported Matrix child generators (#328, contributed by @jgwest)

Test/infrastructure improvements:

• Use a fixed version of Kustomize in the Makefile to generate manifests (#207, contributed by @jgwest)
• Intermittent E2E test failure on TestSimpleGitFilesPreserveResourcesOnDeletion (#229, contributed by @jgwest)
• Write additional tests for repo_service.go (#226, contributed by @jgwest)
• Add more cluster e2e tests (#148, contributed by @OmerKahani)
• Rebase go.mod to latest Argo CD v2.0, adopt new APIs as needed, and retest (#281, contributed by @jgwest)
• TestGetFileContent test is failing when running go test, on Mac (#246, contributed by @jgwest)
• Update build scripts to target 'argoproj/applicationset' on quay.io (#242, contributed by @jgwest)
• Automatically build and push a container image to argoproj/argocd-applicationset:latest on each master commit (#256, contributed by @jgwest)
• Split generators into separate doc pages, plus general doc updates (#267, contributed by @jgwest)
• Use image-push target to build and push an image (#264, contributed by @chetan-rns)
• Update Argo CD dependency to latest, and update changed APIs (#310, contributed by @jgwest)
• Increment version for next release (#188, contributed by @jgwest)
• Use a fixed version of controller-gen in the Makefile to generate manifests (#233 contributed by @jgwest)
• Update Dockerfile to latest Argo CD base and better cleanup apt dependencies #302, contributed by @jgwest)
• Add GITHUB_TOKEN and GITLAB_TOKEN to actions and test secrets (#320)

Doc updates:

• Document the policy parameter of the controller (#297, contributed by @jgwest)
• Update documentation to mention development builds (#263, contributed by @jgwest)
• Add a note regarding use of set-based requirements (#228, contributed by @gdubya)
• Refresh README.md based on new documentation (#191, contributed by @jgwest )
• Fix minor grammar mistake in README (#217, contributed by @williamcodes)
• Correct list generator syntax (#204, contributed by @gdubya)
• Update Generators-Git.md
• Tweak List and Git generator docs (#333, contributed by @jgwest)
• Generator updates, upgrade instructions, and misc updates (#313, contributed by @jgwest)

Installation

The ApplicationSet controller must be installed into the same namespace as the Argo CD it is targeting:

kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/applicationset/v0.2.0/manifests/install.yaml

Once installed, the ApplicationSet controller requires no additional setup. You can learn more about ApplicationSet controller installation from the Getting Started page.