feat: Merge applicationset docs and examples

applicationset/examples/cluster/cluster-example.yaml

@@ -0,0 +1,19 @@
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: guestbook
+spec:
+  generators:
+  - clusters: {}
+  template:
+    metadata:
+      name: '{{name}}-guestbook'
+    spec:
+      project: "default"
+      source:
+        repoURL: https://github.com/argoproj/argocd-example-apps/
+        targetRevision: HEAD
+        path: guestbook
+      destination:
+        server: '{{server}}'
+        namespace: guestbook

applicationset/examples/clusterDecisionResource/README.md

@@ -0,0 +1,57 @@
+# How the Cluster Decision Resource generator works for clusterDecisionResource
+1. The Cluster Decision Resource generator reads a configurable status format:
+```yaml
+status:
+  clusters:
+  - name: cluster-01
+  - name: cluster-02
+```
+This is a common status format.  Another format that could be read looks like this:
+```yaml
+status:
+  decisions:
+  - clusterName: cluster-01
+    namespace: cluster-01
+  - clusterName: cluster-02
+    namespace: cluster-02
+```
+2. Any resource that has a list of key / value pairs, where the value matches ArgoCD cluster names can be used.
+3. The key / value pairs found in each element of the list will be available to the template. As well, `name` and `server` will still be available to the template.
+4. The Service Account used by the ApplicationSet controller must have access to `Get` the resource you want to retrieve the duck type definition from
+5. A configMap is used to identify the resource to read status of generated ArgoCD clusters from. You can use multiple resources by creating a ConfigMap for each one in the ArgoCD namespace.
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: my-configmap
+data:
+  apiVersion: group.io/v1
+  kind: mykinds
+  statusListKey: clusters
+  matchKey: name
+```
+  * `apiVersion`    - This is the apiVersion of your resource
+  * `kind`          - This is the plural kind of your resource
+  * `statusListKey` - Default is 'clusters', this is the key found in your resource's status that is a list of ArgoCD clusters.
+  * `matchKey`      - Is the key name found in the cluster list, `name` and `clusterName` are the keys in the examples above.
+
+# Applying the example
+1. Connect to a cluster with the ApplicationSet controller running
+2. Edit the Role for the ApplicationSet service account, and grant it permission to `list` the `placementdecisions` resources, from apiGroups `cluster.open-cluster-management.io/v1alpha1`
+```yaml
+- apiGroups:
+  - "cluster.open-cluster-management.io/v1alpha1"
+  resources:
+  - placementdecisions
+  verbs:
+  - list
+```
+3. Apply the following controller and associated ManagedCluster CRD's:
+https://github.com/open-cluster-management/placement
+4. Now apply the PlacementDecision and an ApplicationSet:
+```bash
+kubectl apply -f ./placementdecision.yaml
+kubectl apply -f ./configMap.yaml
+kubectl apply -f ./ducktype-example.yaml
+```
+5. For now this won't do anything until you create a controller that populates the `Status.Decisions` array.

applicationset/examples/clusterDecisionResource/configMap.yaml

@@ -0,0 +1,11 @@
+# To generate a Status.Decisions from this CRD, requires https://github.com/open-cluster-management/multicloud-operators-placementrule be deployed
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: ocm-placement
+data:
+  apiVersion: apps.open-cluster-management.io/v1
+  kind: placementrules
+  statusListKey: decisions
+  matchKey: clusterName

applicationset/examples/clusterDecisionResource/ducktype-example.yaml

@@ -0,0 +1,27 @@
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: book-import
+spec:
+  generators:
+    - clusterDecisionResource:
+        configMapRef: ocm-placement
+        name: test-placement
+        requeueAfterSeconds: 30
+  template:
+    metadata:
+      name: '{{clusterName}}-book-import'
+    spec:
+      project: "default"
+      source:
+        repoURL: https://github.com/open-cluster-management/application-samples.git
+        targetRevision: HEAD
+        path: book-import
+      destination:
+        name: '{{clusterName}}'
+        namespace: bookimport
+      syncPolicy:
+        automated:
+          prune: true
+        syncOptions:
+          - CreateNamespace=true

applicationset/examples/clusterDecisionResource/placementdecision.yaml

@@ -0,0 +1,18 @@
+---
+apiVersion: apps.open-cluster-management.io/v1
+kind: PlacementRule
+metadata:
+  name: test-placement
+spec:
+  clusterReplicas: 1   # Availability choice, maximum number of clusters to provision at once
+  clusterSelector:
+    matchLabels:
+      'usage': 'development'
+  clusterConditions:
+    - type: ManagedClusterConditionAvailable
+      status: "True"
+# Below is sample output the generator can consume.
+status:
+  decisions:
+  - clusterName: cluster-01
+  - clusterName: cluster-02

applicationset/examples/design-doc/applicationset.yaml

@@ -0,0 +1,22 @@
+# This is an example of a typical ApplicationSet which uses the cluster generator.
+# An ApplicationSet is comprised with two stanzas:
+#  - spec.generator - producer of a list of values supplied as arguments to an app template
+#  - spec.template - an application template, which has been parameterized
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: guestbook
+spec:
+  generators:
+  - clusters: {}
+  template:
+    metadata:
+      name: '{{name}}-guestbook'
+    spec:
+      source:
+        repoURL: https://github.com/infra-team/cluster-deployments.git
+        targetRevision: HEAD
+        chart: guestbook
+      destination:
+        server: '{{server}}'
+        namespace: guestbook

applicationset/examples/design-doc/clusters.yaml

@@ -0,0 +1,33 @@
+# The cluster generator produces an items list from all clusters registered to Argo CD.
+# It automatically provides the following fields as values to the app template:
+#  - name
+#  - server
+#  - metadata.labels.<key>
+#  - metadata.annotations.<key>
+#  - values.<key>
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: guestbook
+spec:
+  generators:
+  - clusters:
+      selector:
+        matchLabels:
+          argocd.argoproj.io/secret-type: cluster
+      values:
+        project: default
+  template:
+    metadata:
+      name: '{{name}}-guestbook'
+      labels:
+        environment: '{{metadata.labels.environment}}'
+    spec:
+      project: '{{values.project}}'
+      source:
+        repoURL: https://github.com/infra-team/cluster-deployments.git
+        targetRevision: HEAD
+        chart: guestbook
+      destination:
+        server: '{{server}}'
+        namespace: guestbook

applicationset/examples/design-doc/git-directory-discovery.yaml

@@ -0,0 +1,44 @@
+# This example demonstrates the git directory generator, which produces an items list 
+# based on discovery of directories in a git repo matching a specified pattern.
+# Git generators automatically provide {{path}} and {{path.basename}} as available
+# variables to the app template.
+#
+# Suppose the following git directory structure (note the use of different config tools):
+#
+# cluster-deployments
+# └── add-ons
+#     ├── argo-rollouts
+#     │   ├── all.yaml
+#     │   └── kustomization.yaml
+#     ├── argo-workflows
+#     │   └── install.yaml
+#     ├── grafana
+#     │   ├── Chart.yaml
+#     │   └── values.yaml
+#     └── prometheus-operator
+#         ├── Chart.yaml
+#         └── values.yaml
+#
+# The following ApplicationSet would produce four applications (in different namespaces),
+# using the directory basename as both the namespace and application name. 
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: cluster-addons
+spec:
+  generators:
+  - git:
+      repoURL: https://github.com/infra-team/cluster-deployments.git
+      directories:
+      - path: add-ons/*
+  template:
+    metadata:
+      name: '{{path.basename}}'
+    spec:
+      source:
+        repoURL: https://github.com/infra-team/cluster-deployments.git
+        targetRevision: HEAD
+        path: '{{path}}'
+      destination:
+        server: http://kubernetes.default.svc
+        namespace: '{{path.basename}}'

applicationset/examples/design-doc/git-files-discovery.yaml

@@ -0,0 +1,55 @@
+# This example demonstrates a git file generator which traverses the directory structure of a git
+# repository to discover items based on a filename convention. For each file discovered, the
+# contents of the discovered files themselves, act as the set of inputs to the app template.
+#
+# Suppose the following git directory structure:
+#
+# cluster-deployments
+# ├── apps
+# │   └── guestbook
+# │       └── install.yaml
+# └── cluster-config
+#     ├── engineering
+#     │   ├── dev
+#     │   │   └── config.json
+#     │   └── prod
+#     │       └── config.json
+#     └── finance
+#         ├── dev
+#         │   └── config.json
+#         └── prod
+#             └── config.json
+#
+# The discovered files (e.g. config.json) files can be any structured data supplied to the
+# generated application. e.g.:
+# {
+#    "aws_account": "123456",
+#    "asset_id": "11223344"
+#    "cluster": {
+#        "owner": "Jesse_Suen@intuit.com",
+#        "name": "engineering-dev",
+#        "address": "http://1.2.3.4"
+#    }
+# }
+#
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: guestbook
+spec:
+  generators:
+  - git:
+      repoURL: https://github.com/infra-team/cluster-deployments.git
+      files:
+      - path: "**/config.json"
+  template:
+    metadata:
+      name: '{{cluster.name}}-guestbook'
+    spec:
+      source:
+        repoURL: https://github.com/infra-team/cluster-deployments.git
+        targetRevision: HEAD
+        path: apps/guestbook
+      destination:
+        server: '{{cluster.address}}'
+        namespace: guestbook

applicationset/examples/design-doc/git-files-literal.yaml

@@ -0,0 +1,68 @@
+# This example demonstrates a git file generator which produces its items based on one or
+# more files referenced in a git repo. The referenced files would contain a json/yaml list of
+# arbitrary structured objects. Each item of the list would become a set of parameters to a
+# generated application.
+#
+# Suppose the following git directory structure:
+#  
+# cluster-deployments
+# ├── apps
+# │   └── guestbook
+# │       ├── v1.0
+# │       │   └── install.yaml
+# │       └── v2.0
+# │           └── install.yaml
+# └── config
+#     └── clusters.json
+#
+# In this example, the `clusters.json` file is json list of structured data:
+# [
+#     {
+#         "account": "123456",
+#         "asset_id": "11223344",
+#         "cluster": {
+#             "owner": "Jesse_Suen@intuit.com",
+#             "name": "engineering-dev",
+#             "address": "http://1.2.3.4"
+#         },
+#         "appVersions": {
+#             "prometheus-operator": "v0.38",
+#             "guestbook": "v2.0"
+#         }
+#     },
+#     {
+#         "account": "456789",
+#         "asset_id": "55667788",
+#         "cluster": {
+#             "owner": "Alexander_Matyushentsev@intuit.com",
+#             "name": "engineering-prod",
+#             "address": "http://2.4.6.8"
+#         },
+#         "appVersions": {
+#             "prometheus-operator": "v0.38",
+#             "guestbook": "v1.0"
+#         }
+#     }
+# ]
+#
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: guestbook
+spec:
+  generators:
+  - git:
+      repoURL: https://github.com/infra-team/cluster-deployments.git
+      files:
+      - path: config/clusters.json
+  template:
+    metadata:
+      name: '{{cluster.name}}-guestbook'
+    spec:
+      source:
+        repoURL: https://github.com/infra-team/cluster-deployments.git
+        targetRevision: HEAD
+        path: apps/guestbook/{{appVersions.guestbook}}
+      destination:
+        server: http://kubernetes.default.svc
+        namespace: guestbook

applicationset/examples/design-doc/list.yaml

@@ -0,0 +1,33 @@
+# The list generator specifies a literal list of argument values to the app spec template.
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: guestbook
+spec:
+  generators:
+  - list:
+      elements:
+      - cluster: engineering-dev
+        url: https://1.2.3.4
+        values:
+          project: dev
+      - cluster: engineering-prod
+        url: https://2.4.6.8
+        values:
+          project: prod
+      - cluster: finance-preprod
+        url: https://9.8.7.6
+        values:
+          project: preprod
+  template:
+    metadata:
+      name: '{{cluster}}-guestbook'
+    spec:
+      project: '{{values.project}}'
+      source:
+        repoURL: https://github.com/infra-team/cluster-deployments.git
+        targetRevision: HEAD
+        path: guestbook/{{cluster}}
+      destination:
+        server: '{{url}}'
+        namespace: guestbook