Add Kustomize FAQ to docs

Signed-off-by: Stefan Prodan <stefan.prodan@gmail.com>

docs/faq/index.md

@@ -92,3 +92,153 @@ There are a variety of ways and we look forward to having you on board building
 In an announcement in August 2019, the expectation was set that the Flux project would integrate the GitOps Engine, then being factored out of ArgoCD. Since the result would be backward-incompatible, it would require a major version bump: Flux v2.
 
 After experimentation and considerable thought, we (the maintainers) have found a path to Flux v2 that we think better serves our vision of GitOps: the GitOps Toolkit. In consequence, we do not now plan to integrate GitOps Engine into Flux.
+
+## Kustomize questions
+
+### Are there two Kustomization types?
+
+Yes, the `kustomization.kustomize.toolkit.fluxcd.io` is a Kubernetes
+[custom resource](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+while `kustomization.kustomize.config.k8s.io` is the type used to configure a
+[Kustomize overlay](https://kubectl.docs.kubernetes.io/references/kustomize/).
+
+The `kustomization.kustomize.toolkit.fluxcd.io` object refers to a `kustomization.yaml`
+file path inside a Git repository or Bucket source.
+
+### How do I use them together?
+
+Assuming an app repository with `./deploy/prod/kustomization.yaml`:
+
+```yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - deployment.yaml
+  - service.yaml
+  - ingress.yaml
+```
+
+Define a source of type `gitrepository.source.toolkit.fluxcd.io`
+that pulls changes from the app repository every 5 minutes inside the cluster:
+
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: GitRepository
+metadata:
+  name: my-app
+  namespace: default
+spec:
+  interval: 5m
+  url: https://github.com/my-org/my-app
+  ref:
+    branch: main
+```
+
+Then define a `kustomization.kustomize.toolkit.fluxcd.io` that uses the `kustomization.yaml`
+from `./deploy/prod` to determine which resources to create, update or delete:
+
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
+kind: Kustomization
+metadata:
+  name: my-app
+  namespace: default
+spec:
+  interval: 15m
+  path: "./deploy/prod"
+  prune: true
+  sourceRef:
+    kind: GitRepository
+    name: my-app
+```
+
+### What is a Kustomization reconciliation?
+
+In the above example, we pull changes from Git every 5 minutes,
+and a new commit will trigger a reconciliation of
+all the `Kustomization` objects using that source.
+
+Depending on your configuration, a reconciliation can mean:
+
+* generating a kustomization.yaml file in the specified path
+* building the kustomize overlay
+* decrypting secrets
+* validating the manifests with client or server-side dry-run
+* applying changes on the cluster
+* health checking of deployed workloads
+* garbage collection of resources removed from Git
+* issuing events about the reconciliation result
+* recoding metrics about the reconciliation process 
+
+The 15 minutes reconciliation interval, is the interval at which you want to undo manual changes
+.e.g. `kubectl set image deployment/my-app` by reapplying the latest commit on the cluster.
+
+Note that a reconciliation will override all fields of a Kubernetes object, that diverge from Git.
+For example, you'll have to omit the `spec.replicas` field from your `Deployments` YAMLs if you 
+are using a `HorizontalPodAutoscaler` that changes the replicas in-cluster.
+
+### Can I use repositories with plain YAMLs?
+
+Yes, you can specify the path where the Kubernetes manifests are,
+and kustomize-controller will generate a `kustomization.yaml` if one doesn't exist.
+
+Assuming an app repository with the following structure:
+
+```
+├── deploy
+│   └── prod
+│       ├── .yamllint.yaml
+│       ├── deployment.yaml
+│       ├── service.yaml
+│       └── ingress.yaml
+└── src
+```
+
+Create a `GitRepository` definition and exclude all the files that are not Kubernetes manifests:
+
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1beta1
+kind: GitRepository
+metadata:
+  name: my-app
+  namespace: default
+spec:
+  interval: 5m
+  url: https://github.com/my-org/my-app
+  ref:
+    branch: main
+  ignore: |
+    # exclude all
+    /*
+    # include deploy dir
+    !/deploy
+    # exclude non-Kubernetes YAMLs
+    /deploy/**/.yamllint.yaml
+```
+
+Then create a `Kustomization` definition to reconcile the `./deploy/prod` dir:
+
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
+kind: Kustomization
+metadata:
+  name: my-app
+  namespace: default
+spec:
+  interval: 15m
+  path: "./deploy/prod"
+  prune: true
+  sourceRef:
+    kind: GitRepository
+    name: my-app
+```
+
+With the above configuration, source-controller will pull the Kubernetes manifests
+from the app repository and kustomize-controller will generate a
+`kustomization.yaml` including all the resources found with `./deploy/prod/**/*.yaml`.
+
+The kustomize-controller creates `kustomization.yaml` files similar to:
+
+```sh
+cd ./deploy/prod && kustomize create --autodetect --recursive
+```