Updated kustomization doc.

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

Author: vlasov-y

docs/spec/v1/kustomizations.md

@@ -725,7 +725,7 @@ For more information, see [remote clusters/Cluster-API](#remote-clusterscluster-
 ### Decryption
 
 `.spec.decryption` is an optional field to specify the configuration to decrypt
-Secrets that are a part of the Kustomization.
+Secrets, ConfigMaps and patches that are a part of the Kustomization.
 
 Since Secrets are either plain text or `base64` encoded, it's unsafe to store
 them in plain text in a public or private Git repository. In order to store
@@ -734,9 +734,11 @@ encrypt your Kubernetes Secret data with [age](https://age-encryption.org/v1/)
 and/or [OpenPGP](https://www.openpgp.org) keys, or with provider implementations
 like Azure Key Vault, GCP KMS or Hashicorp Vault.
 
-**Note:** You should encrypt only the `data/stringData` section of the Kubernetes
-Secret, encrypting the `metadata`, `kind` or `apiVersion` fields is not supported.
-An easy way to do this is by appending `--encrypted-regex '^(data|stringData)$'`
+Also, you may want to encrypt some parts of resources as well. In order to do that,
+you may encrypt patches as well.
+
+**Note:** You must leave `metadata`, `kind` or `apiVersion` in plain text.
+An easy way to do this is to limit encrypted keys by appending `--encrypted-regex '^(data|stringData)$'`
 to your `sops --encrypt` command.
 
 It has two fields:
@@ -788,6 +790,86 @@ data:
   sops.vault-token: <BASE64>
 ```
 
+#### Important case: SOPS decryption encrypted_regex conflict
+
+If your resource is encrypted it will be decrypted right before apply, but it may happen, that
+your patches will bring fields that match SOPS' encrypted_regex expression and SOPS will fail
+during the decryption. Let's say we have a simple resource.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod
+spec:
+  containers:
+    - name: main
+      image: nginx:stable-alpine
+      env:
+        - name: ENC[AES256_GCM,data:...
+          value: ENC[AES256_GCM,data:...
+      resources:
+        limits:
+          memory: 50Mi
+          cpu: 50m
+sops:
+  ...
+  encrypted_regex: ^env$ # There it is
+  ...
+```
+
+This Pod has every env list encrypted since we have `encrypted_regex` set during SOPS encryption.
+But next we have a patch like this.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod
+spec:
+  containers:
+    - name: patched
+      image: nginx:stable-alpine
+      env:
+        - name: MainEnvValueIsEncrypted
+          value: but this one is not
+```
+
+And as a result you will have.
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod
+spec:
+  containers:
+    - name: main
+      image: nginx:stable-alpine
+      env:
+        - name: ENC[AES256_GCM,data:...
+          value: ENC[AES256_GCM,data:...
+      resources:
+        limits:
+          memory: 50Mi
+          cpu: 50m
+    - name: patched
+      image: nginx:stable-alpine
+      env:
+        - name: MainEnvValueIsEncrypted
+          value: but this one is not
+sops:
+  ...
+  encrypted_regex: ^env$ # There it is
+  ...
+```
+
+At this point, Flux will call SOPS to decrypt the file and SOPS will try to decrypt
+all `env` keys, but container `patched` has this list in a plain text. That is where SOPS fails.
+
+**Solution**: move all your secrets to patches and your resource will not require a
+decryption at the end, since patches are decrypted before.
+
 #### age Secret entry
 
 To specify an age private key in a Kubernetes Secret, suffix the key of the