Split generators into separate doc pages, plus general doc updates

README.md

@@ -66,7 +66,8 @@ Development builds can be installed by running the following command:
 ```
 kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/applicationset/master/manifests/install.yaml
 ```
-Commits to the `master` branch will automatically push new container images to the container registry used by this install, and see this link for automatically updated [documentation for these builds](https://argocd-applicationset.readthedocs.io/en/master/). See [Development builds](docs/Geting-Started.md) for more details.
+Commits to the `master` branch will automatically push new container images to the container registry used by this install, and see this link for automatically updated [documentation for these builds](https://argocd-applicationset.readthedocs.io/en/master/). See [Development builds](https://argocd-applicationset.readthedocs.io/en/master/Getting-Started/) for more details.
+
 
 ## Development
 

docs/Generators-Cluster-Decision-Resource.md

@@ -0,0 +1,74 @@
+# Cluster Decision Resource Generator
+
+The cluster decision resource generates a list of Argo CD clusters. This is done using [duck-typing](https://pkg.go.dev/knative.dev/pkg/apis/duck), 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:
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+ name: guestbook
+spec:
+ generators:
+ - clusterDecisionResource:
+ configMapRef: my-configmap # ConfigMap with GVK information for the duck type resource
+ name: quak # Choose either "name" of the resource or "labelSelector"
+ labelSelector:
+ matchLabels: # OPTIONAL
+ duck: spotted
+ matchExpression: # OPTIONAL
+ - key: duck
+ operator: In
+ values:
+ - "spotted"
+ - "canvasback" 
+ requeueAfterSeconds: 60 # OPTIONAL: Checks for changes every 60sec (default 3min)
+ template:
+ metadata:
+ name: '{{name}}-guestbook'
+ spec:
+ project: "default"
+ source:
+ repoURL: https://github.com/argoproj/argocd-example-apps/
+ targetRevision: HEAD
+ path: guestbook
+ destination:
+ server: '{{clusterName}}' # 'server' field of the secret
+ namespace: guestbook
+```
+The `quak` resource, referenced by the ApplicationSet `clusterDecisionResource` generator:
+```yaml
+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
+```
+The `ApplicationSet` resource references a `ConfigMap` that defines the resource to be used in this duck-typing. Only one ConfigMap is required per `ArgoCD` instance, to identify a resource. You can support multiple resource types by creating a `ConfigMap` for each.
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: my-configmap
+data:
+ apiVersion: mallard.io/v1beta1 # apiVersion of the target resource
+ kind: ducks # kind of the target resource
+ statusListKey: decisions # status key name that holds the list of Argo CD clusters
+ matchKey: clusterName # The key in the status list whose value is the cluster name found in Argo CD
+```
+
+(*The full example can be found [here](https://github.com/argoproj-labs/applicationset/tree/master/examples/clusterDecisionResource).*)
+
+This example leverages the cluster management capabilities of the [open-cluster-management.io community](https://open-cluster-management.io/). By creating a `ConfigMap` with the GVK for the `open-cluster-management.io` Placement rule, your ApplicationSet can provision to different clusters in a number of novel ways. One example is to have the ApplicationSet maintain only two Argo CD Applications across 3 or more clusters. Then as maintenance or outages occur, the ApplicationSet will always maintain two Applications, moving the application to available clusters under the Placement rule's direction. 
+
+## How it works
+The ApplicationSet needs to be created in the Argo CD namespace, placing the `ConfigMap` in the same namespace allows the ClusterDecisionResource generator to read it. The `ConfigMap` stores the GVK information as well as the status key definitions. In the open-cluster-management example, the ApplicationSet generator will read the kind `placementrules` with an apiVersion of `apps.open-cluster-management.io/v1`. It will attempt to extract the **list** of clusters from the key `decisions`. It then validates the actual cluster name as defined in Argo CD against the **value** from the key `clusterName` in each of the elements in the list.
+
+The ClusterDecisionResource generator passes the 'name', 'server' and any other key/value in the duck-type resource's status list as parameters into the ApplicationSet template. In this example, the decision array contained an additional key `clusterName`, which is now available to the ApplicationSet template.
+
+!!! note "Clusters listed as `Status.Decisions` must be predefined in Argo CD"
+ The cluster names listed in the `Status.Decisions` *must* be defined within Argo CD, in order to generate applications for these values. The ApplicationSet controller does not create clusters within Argo CD.
+
+ The Default Cluster list key is `clusters`.

docs/Generators-Cluster.md

@@ -0,0 +1,112 @@
+# Cluster Generator
+
+In Argo CD, managed clusters [are stored within Secrets](https://argoproj.github.io/argo-cd/operator-manual/declarative-setup/#clusters) in the Argo CD namespace. The ApplicationSet controller uses those same Secrets to generate parameters to identify and target available clusters.
+
+For each cluster registered with Argo CD, the Cluster generator produces parameters based on the list of items found within the cluster secret. 
+
+It automatically provides the following parameter values to the Application template for each cluster:
+
+- `name`
+- `server`
+- `metadata.labels.<key>` *(for each label in the Secret)*
+- `metadata.annotations.<key>` *(for each annotation in the Secret)*
+
+Within [Argo CD cluster Secrets](https://argoproj.github.io/argo-cd/operator-manual/declarative-setup/#clusters) are data fields describing the cluster:
+```yaml
+kind: Secret
+data:
+ # Within Kubernetes these fields are actually encoded in Base64; they are decoded here for convenience. 
+ # (They are likewise decoded when passed as parameters by the Cluster generator)
+ config: "{'tlsClientConfig':{'insecure':false}}"
+ name: "in-cluster2"
+ server: "https://kubernetes.default.svc"
+metadata:
+ labels:
+ argocd.argoproj.io/secret-type: cluster
+# (...)
+```
+
+The Cluster generator will automatically identify clusters defined with Argo CD, and extract the cluster data as parameters:
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+ name: guestbook
+spec:
+ generators:
+ - clusters: {} # Automatically use all clusters defined within Argo CD
+ template:
+ metadata:
+ name: '{{name}}-guestbook' # 'name' field of the Secret
+ spec:
+ project: "default"
+ source:
+ repoURL: https://github.com/argoproj/argocd-example-apps/
+ targetRevision: HEAD
+ path: guestbook
+ destination:
+ server: '{{server}}' # 'server' field of the secret
+ namespace: guestbook
+```
+(*The full example can be found [here](https://github.com/argoproj-labs/applicationset/tree/master/examples/cluster).*)
+
+In this example, the cluster secret's `name` and `server` fields are used to populate the `Application` resource `name` and `server` (which are then used to target that same cluster).
+
+### Label selector
+
+A label selector may be used to narrow the scope of targeted clusters to only those matching a specific label:
+```yaml
+kind: ApplicationSet
+metadata:
+ name: guestbook
+spec:
+ generators:
+ - clusters:
+ selector:
+ matchLabels:
+ staging: true
+ template:
+ # (...)
+```
+
+This would match an Argo CD cluster secret containing:
+```yaml
+kind: Secret
+data:
+ # (... fields as above ...)
+metadata:
+ labels:
+ argocd.argoproj.io/secret-type: cluster
+ staging: "true"
+# (...)
+```
+
+The cluster selector also supports set-based requirements, as used by [several core Kubernetes resources](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements).
+
+### Deploying to the local cluster
+
+In Argo CD, the 'local cluster' is the cluster upon which Argo CD (and the ApplicationSet controller) is installed. This is to distinguish it from 'remote clusters', which are those that are added to Argo CD [declaratively](https://argoproj.github.io/argo-cd/operator-manual/declarative-setup/#clusters) or via the [Argo CD CLI](https://argoproj.github.io/argo-cd/getting_started/#5-register-a-cluster-to-deploy-apps-to-optional).
+
+The cluster generator will automatically target both local and non-local clusters, for every cluster that matches the cluster selector.
+
+If you wish to target only remote clusters with your Applications (e.g. you want to exclude the local cluster), then use a cluster selector with labels, for example:
+```yaml
+spec:
+ generators:
+ - clusters:
+ selector:
+ matchLabels:
+ argocd.argoproj.io/secret-type: cluster
+```
+
+This selector will not match the default local cluster, since the default local cluster does not have a Secret (and thus does not have the `argocd.argoproj.io/secret-type` label on that secret). Any cluster selector that selects on that label will automatically exclude the default local cluster.
+
+However, if you do wish to target both local and non-local clusters, while also using label matching, you can create a secret for the local cluster within the Argo CD web UI:
+
+1. Within the Argo CD web UI, select *Settings*, then *Clusters*.
+2. Select your local cluster, usually named `in-cluster`.
+3. Click the *Edit* button, and change the the *NAME* of the cluster to another value, for example `in-cluster-local`. Any other value here is fine. 
+4. Leave all other fields unchanged.
+5. Click *Save*.
+
+These steps might seem counterintuitive, but the act of changing one of the default values for the local cluster causes the Argo CD Web UI to create a new secret for this cluster. In the Argo CD namespace, you should now see a Secret resource named `cluster-(cluster suffix)` with label `argocd.argoproj.io/secret-type": "cluster"`. You may also create a local [cluster secret declaratively](https://argoproj.github.io/argo-cd/operator-manual/declarative-setup/#clusters), or with the CLI using `argocd cluster add "(context name)" --in-cluster`, rather than through the Web UI.