docs(api/components): add Components guide from cli-experimental

- add reference to Concept page

Author: bugoverdose

site/content/en/docs/Reference/API/components.md

@@ -1,11 +1,385 @@
 ---
-title: "components"
-linkTitle: "components"
+title: "Components"
+linkTitle: "Components"
 type: docs
 weight: 5
 description: >
     Compose kustomizations.
 ---
 
-Please check out the existing [components guide](/guides/config_management/components/) for explanation with examples. 
-More examples are in progress
+As of ``v3.7.0`` Kustomize supports a special type of kustomization that allows
+one to define reusable pieces of configuration logic that can be included from
+multiple overlays.
+
+Components come in handy when dealing with applications that support multiple
+optional features and you wish to enable only a subset of them in different
+overlays, i.e., different features for different environments or audiences.
+
+For more details regarding this feature you can read the
+[Kustomize Components KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-cli/1802-kustomize-components)
+and the [components concept](/docs/concepts/components/) page.
+
+## Use case
+
+Suppose you've written a very simple Web application:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: example
+spec:
+  template:
+    spec:
+      containers:
+      - name: example
+        image: example:1.0
+```
+
+You want to deploy a **community** edition of this application as SaaS, so you
+add support for persistence (e.g. an external database), and bot detection
+(e.g. Google reCAPTCHA).
+
+You've now attracted **enterprise** customers who want to deploy it
+on-premises, so you add LDAP support, and disable Google reCAPTCHA. At the same
+time, the **devs** need to be able to test parts of the application, so they
+want to deploy it with some features enabled and others not.
+
+Here's a matrix with the deployments of this application and the features
+enabled for each one:
+
+|            | External DB        | LDAP               | reCAPTCHA          |
+|------------|:------------------:|:------------------:|:------------------:|
+| Community  | ✔️                  |                    | ✔️                  |
+| Enterprise | ✔️                  | ✔️                  |                    |
+| Dev        | ✅                 | ✅                 | ✅                 |
+
+(✔️ enabled, ✅: optional)
+
+So, you want to make it easy to deploy your application in any of the above
+three environments. Here's how you can do this with Kustomize components: each
+opt-in feature gets packaged as a component, so that it can be referred to from
+multiple higher-level overlays.
+
+First, define a place to work:
+
+```shell
+DEMO_HOME=$(mktemp -d)
+```
+
+Define a common **base** that has a `Deployment` and a simple `ConfigMap`, that
+is mounted on the application's container.
+
+```bash
+BASE=$DEMO_HOME/base
+mkdir $BASE
+```
+
+```bash
+# $BASE/kustomization.yaml
+resources:
+- deployment.yaml
+
+configMapGenerator:
+- name: conf
+  literals:
+    - main.conf=|
+        color=cornflower_blue
+        log_level=info
+```
+
+```bash
+# $BASE/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: example
+spec:
+  template:
+    spec:
+      containers:
+      - name: example
+        image: example:1.0
+        volumeMounts:
+        - name: conf
+          mountPath: /etc/config
+      volumes:
+        - name: conf
+          configMap:
+            name: conf
+```
+
+Define an `external_db` component, using `kind: Component`, that creates a
+`Secret` for the DB password and a new entry in the `ConfigMap`:
+
+```shell
+EXT_DB=$DEMO_HOME/components/external_db
+mkdir -p $EXT_DB
+```
+
+```bash
+# $EXT_DB/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1alpha1  # <-- Component notation
+kind: Component
+
+secretGenerator:
+- name: dbpass
+  files:
+    - dbpass.txt
+
+patchesStrategicMerge:
+  - configmap.yaml
+
+patchesJson6902:
+- target:
+    group: apps
+    version: v1
+    kind: Deployment
+    name: example
+  path: deployment.yaml
+```
+
+```bash
+# $EXT_DB/deployment.yaml
+- op: add
+  path: /spec/template/spec/volumes/0
+  value:
+    name: dbpass
+    secret:
+      secretName: dbpass
+- op: add
+  path: /spec/template/spec/containers/0/volumeMounts/0
+  value:
+    mountPath: /var/run/secrets/db/
+    name: dbpass
+```
+
+```bash
+# $EXT_DB/configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: conf
+data:
+  db.conf: |
+    endpoint=127.0.0.1:1234
+    name=app
+    user=admin
+    pass=/var/run/secrets/db/dbpass.txt
+```
+
+Define an `ldap` component, that creates a `Secret` for the LDAP password
+and a new entry in the `ConfigMap`:
+
+```shell
+LDAP=$DEMO_HOME/components/ldap
+mkdir -p $LDAP
+```
+
+```bash
+# $LDAP/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1alpha1
+kind: Component
+
+secretGenerator:
+- name: ldappass
+  files:
+    - ldappass.txt
+
+patchesStrategicMerge:
+  - configmap.yaml
+
+patchesJson6902:
+- target:
+    group: apps
+    version: v1
+    kind: Deployment
+    name: example
+  path: deployment.yaml
+```
+
+```bash
+# $LDAP/deployment.yaml
+- op: add
+  path: /spec/template/spec/volumes/0
+  value:
+    name: ldappass
+    secret:
+      secretName: ldappass
+- op: add
+  path: /spec/template/spec/containers/0/volumeMounts/0
+  value:
+    mountPath: /var/run/secrets/ldap/
+    name: ldappass
+```
+
+```bash
+# $LDAP/configmap.yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: conf
+data:
+  ldap.conf: |
+    endpoint=ldap://ldap.example.com
+    bindDN=cn=admin,dc=example,dc=com
+    pass=/var/run/secrets/ldap/ldappass.txt
+```
+
+Define a `recaptcha` component, that creates a `Secret` for the reCAPTCHA
+site/secret keys and a new entry in the `ConfigMap`:
+
+```shell
+RECAPTCHA=$DEMO_HOME/components/recaptcha
+mkdir -p $RECAPTCHA
+```
+
+```bash
+# $RECAPTCHA/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1alpha1
+kind: Component
+
+secretGenerator:
+- name: recaptcha
+  files:
+    - site_key.txt
+    - secret_key.txt
+
+# Updating the ConfigMap works with generators as well.
+configMapGenerator:
+- name: conf
+  behavior: merge
+  literals:
+    - recaptcha.conf=|
+        enabled=true
+        site_key=/var/run/secrets/recaptcha/site_key.txt
+        secret_key=/var/run/secrets/recaptcha/secret_key.txt
+
+patchesJson6902:
+- target:
+    group: apps
+    version: v1
+    kind: Deployment
+    name: example
+  path: deployment.yaml
+```
+
+```bash
+# $RECAPTCHA/deployment.yaml
+- op: add
+  path: /spec/template/spec/volumes/0
+  value:
+    name: recaptcha
+    secret:
+      secretName: recaptcha
+- op: add
+  path: /spec/template/spec/containers/0/volumeMounts/0
+  value:
+    mountPath: /var/run/secrets/recaptcha/
+    name: recaptcha
+```
+
+Define a `community` variant, that bundles the external DB and reCAPTCHA
+components:
+
+```shell
+COMMUNITY=$DEMO_HOME/overlays/community
+mkdir -p $COMMUNITY
+```
+
+```bash
+
+# $COMMUNITY/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+
+components:
+  - ../../components/external_db
+  - ../../components/recaptcha
+```
+
+Define an `enterprise` overlay, that bundles the external DB and LDAP
+components:
+
+```shell
+ENTERPRISE=$DEMO_HOME/overlays/enterprise
+mkdir -p $ENTERPRISE
+```
+
+```bash
+# $ENTERPRISE/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+
+components:
+  - ../../components/external_db
+  - ../../components/ldap
+```
+
+Define a `dev` overlay, that points to all the components and has LDAP
+disabled:
+
+```shell
+DEV=$DEMO_HOME/overlays/dev
+mkdir -p $DEV
+```
+
+```bash
+# $DEV/kustomization.yaml
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - ../../base
+
+components:
+  - ../../components/external_db
+  #- ../../components/ldap
+  - ../../components/recaptcha
+```
+
+Now, the workspace has the following directories:
+
+```shell
+├── base
+│   ├── deployment.yaml
+│   └── kustomization.yaml
+├── components
+│   ├── external_db
+│   │   ├── configmap.yaml
+│   │   ├── dbpass.txt
+│   │   ├── deployment.yaml
+│   │   └── kustomization.yaml
+│   ├── ldap
+│   │   ├── configmap.yaml
+│   │   ├── deployment.yaml
+│   │   ├── kustomization.yaml
+│   │   └── ldappass.txt
+│   └── recaptcha
+│       ├── deployment.yaml
+│       ├── kustomization.yaml
+│       ├── secret_key.txt
+│       └── site_key.txt
+└── overlays
+    ├── community
+    │   └── kustomization.yaml
+    ├── dev
+    │   └── kustomization.yaml
+    └── enterprise
+        └── kustomization.yaml
+```
+
+With this structure, you can generate the YAML manifests for each deployment
+using `kustomize build`:
+
+```shell
+kustomize build overlays/community
+kustomize build overlays/enterprise
+kustomize build overlays/dev
+```