docs: Add applicationset controller policy configuration documentation (

#1596)

* Add applicationset controller policy configuration documentation

Signed-off-by: nmirasch <[email protected]>

---------

Signed-off-by: nmirasch <[email protected]>

docs/reference/applicationSet.md

@@ -0,0 +1,83 @@
+# ApplicationSet Controller policies 
+
+The ApplicationSet controller supports a parameter `--policy`, which is specified on launch (within the controller Deployment container), and which restricts what types of modifications will be made to managed Argo CD `Application` resources.
+
+### ApplicationSet Controller Policy configuration 
+
+The `--policy` parameter takes four values: `sync`, `create-only`, `create-delete`, and `create-update`. (`sync` is the default, which is used if the `--policy` parameter is not specified; the other policies are described below).
+
+- Policy `create-only`: Prevents ApplicationSet controller from modifying or deleting Applications. **WARNING**: It doesn't prevent Application controller from deleting Applications according to [ownerReferences](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/) when deleting ApplicationSet.
+- Policy `create-update`: Prevents ApplicationSet controller from deleting Applications. Update is allowed. **WARNING**: It doesn't prevent Application controller from deleting Applications according to [ownerReferences](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/) when deleting ApplicationSet.
+- Policy `create-delete`: Prevents ApplicationSet controller from modifying Applications. Delete is allowed.
+- Policy `sync`: Update and Delete are allowed.
+
+It is also possible to set this policy per ApplicationSet. This can be achieved using the configuration described in the Argo CD [documentation][argocd_applicationset_polices].
+
+If the controller parameter `--policy` is set, it takes precedence on the ApplicationSet field `applicationsSync`. It is possible to allow per ApplicationSet sync policy by setting variable `ARGOCD_APPLICATIONSET_CONTROLLER_ENABLE_POLICY_OVERRIDE` to argocd-cmd-params-cm `applicationsetcontroller.enable.policy.override` or directly with controller parameter `--enable-policy-override` (default to `false`).
+
+### Policy `create-only`: Prevent ApplicationSet controller from modifying and deleting Applications
+To allow the ApplicationSet controller to *create* `Application` resources, but prevent any further modification, such as *deletion*, or modification of Application fields, add this parameter in the ApplicationSet controller:
+
+```
+--policy create-only
+```
+**WARNING**: "*deletion*" indicates the case as the result of comparing generated Application between before and after, there are Applications which no longer exist. It doesn't indicate the case Applications are deleted according to ownerReferences to ApplicationSet. See [How to prevent Application controller from deleting Applications when deleting ApplicationSet][argocd_appliocationset_how_to_prevent_deletion]
+
+**Example:**
+```yaml
+apiVersion: argoproj.io/v1beta1
+kind: ArgoCD
+metadata:
+  name: argocd-sample
+spec:
+  applicationSet:
+    extraCommandArgs:
+      - --policy create-only
+```
+
+### Policy `create-update`: Prevent ApplicationSet controller from deleting Applications
+
+To allow the ApplicationSet controller to create or modify `Application` resources, but prevent Applications from being deleted, add the following parameter to the ApplicationSet controller:
+
+```
+--policy create-update
+```
+
+**WARNING**: "*deletion*" indicates the case as the result of comparing generated Application between before and after, there are Applications which no longer exist. It doesn't indicate the case Applications are deleted according to ownerReferences to ApplicationSet. See [How to prevent Application controller from deleting Applications when deleting ApplicationSet][argocd_appliocationset_how_to_prevent_deletion]
+
+This may be useful to users looking for additional protection against deletion of the Applications generated by the controller.
+
+**Example:**
+```yaml
+apiVersion: argoproj.io/v1beta1
+kind: ArgoCD
+metadata:
+  name: argocd-sample
+spec:
+  applicationSet:
+    extraCommandArgs:
+      - --policy create-update
+```
+
+### Policy `create-delete`: Prevent ApplicationSet controller from modifying Applications
+
+To allow the ApplicationSet controller to create or delete `Application` resources, but prevent Applications from being modified, add the following parameter to the ApplicationSet controller:
+
+```
+--policy create-delete
+```
+
+**Example:**
+```yaml
+apiVersion: argoproj.io/v1beta1
+kind: ArgoCD
+metadata:
+  name: argocd-sample
+spec:
+  applicationSet:
+    extraCommandArgs:
+      - --policy create-delete
+```
+
+[argocd_applicationset_polices]:https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Controlling-Resource-Modification/#managed-applications-modification-policies
+[argocd_appliocationset_how_to_prevent_deletion]:https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Controlling-Resource-Modification/#how-to-prevent-application-controller-from-deleting-applications-when-deleting-applicationset

mkdocs.yml

@@ -62,6 +62,8 @@ nav:
     - Custom labels and annotations: usage/custom_labels_annotations.md
   - Reference:
     - ArgoCD: reference/argocd.md
+    - ApplicationSet:
+        - Policies: reference/applicationSet.md
     - ArgoCDExport: reference/argocdexport.md
     - API Docs: reference/api.html.md
     - NotificationsConfiguration: reference/notificationsconfiguration.md