docs(core): correct CRD examples and document missing fields (#6441)

Audit of the core CRD docs against the controller code surfaced several
copy-paste-level errors and gaps:

- SecretStore/ClusterSecretStore: the example annotation to suppress
  unmaintained-store warnings was external-secrets.io/disable-maintenance-checks,
  but the controller only honours external-secrets.io/ignore-maintenance-checks.
  Also replace the non-existent status reason "ConfigError" with "ValidationFailed".
- PushSecret: the example set both selector.secret and selector.generatorRef in
  one selector, which violates the MaxProperties=1 validation and is rejected by
  the API server. Show secret and comment generatorRef as the alternative, and
  note that deletionPolicy defaults to None.
- ClusterExternalSecret/ClusterPushSecret: status examples documented condition
  types PartiallyReady/NotReady that the controllers never emit (only Ready,
  True/False). Fix the ClusterPushSecret failure reason ("external secret" ->
  "push secret already exists in namespace"). Document the previously missing
  fields: ClusterExternalSecret namespaces (deprecated) and externalSecretMetadata,
  ClusterPushSecret pushSecretMetadata, and the refreshTime unset fallback.
- decoding-strategy guide: a note referenced decodeStrategy; the field is
  decodingStrategy.

Signed-off-by: Alexander Chernov <alexander@chernov.it>
Co-authored-by: Gergely Bräutigam <gergely.brautigam@sap.com>

docs/guides/decoding-strategy.md

@@ -47,4 +47,4 @@ data:
 At this time, decoding Strategy Auto is only trying to check if the original input is valid to perform Base64 operations. As there is no reliable way to detect base64 encoded values, this means that some non-encoded secret values might end up being decoded, producing gibberish. For example, this is the case for alphanumeric values with a length divisible by 4, like `1234` or `happy/street`. 
 
 !!! note 
-    If you are using `decodeStrategy: Auto` and start to see ESO pulling completely wrong secret values into your kubernetes secret, consider changing it to `None` to investigate it.
+    If you are using `decodingStrategy: Auto` and start to see ESO pulling completely wrong secret values into your kubernetes secret, consider changing it to `None` to investigate it.

docs/snippets/full-cluster-external-secret.yaml

@@ -4,9 +4,15 @@ kind: ClusterExternalSecret
 metadata:
   name: "hello-world"
 spec:
-  # The name to be used on the ExternalSecrets
+  # The name to be used on the ExternalSecrets.
+  # Defaults to the name of the ClusterExternalSecret when omitted.
   externalSecretName: "hello-world-es"
 
+  # Optional labels and annotations to set on every created ExternalSecret.
+  externalSecretMetadata:
+    labels: {}
+    annotations: {}
+
   # This is a basic label selector to select the namespaces to deploy ExternalSecrets to.
   # you can read more about them here https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
   # Deprecated: Use namespaceSelectors instead.
@@ -22,8 +28,14 @@ spec:
   - matchLabels:
       cool: label
 
+  # Choose namespaces by name. This is OR'd with anything namespaceSelectors matches.
+  # Deprecated: Use namespaceSelectors instead.
+  # namespaces:
+  #   - my-namespace
+
   # How often the ClusterExternalSecret should reconcile itself
   # This will decide how often to check and make sure that the ExternalSecrets exist in the matching namespaces
+  # If omitted, the controller's default requeue interval is used.
   refreshTime: "1m"
 
   # This is the spec of the ExternalSecrets to be created
@@ -83,11 +95,12 @@ status:
     - "matching-ns-3"
     - "matching-ns-2"
 
-  # The condition can be Ready, PartiallyReady, or NotReady
-  # PartiallyReady would indicate an error in 1 or more namespaces
-  # NotReady would indicate errors in all namespaces meaning all ExternalSecrets resulted in errors
+  # The only condition type is Ready. status is "True" when all matching
+  # namespaces synced, and "False" if one or more namespaces failed (the failed
+  # ones are listed under failedNamespaces above).
   conditions:
-  - type: PartiallyReady
-    status: "True"
+  - type: Ready
+    status: "False"
+    message: "one or more namespaces failed"
     lastTransitionTime: "2022-01-12T12:33:02Z"
 {% endraw %}

docs/snippets/full-cluster-push-secret.yaml

@@ -13,9 +13,15 @@ kind: ClusterPushSecret
 metadata:
   name: "hello-world"
 spec:
-  # The name to be used on the PushSecrets
+  # The name to be used on the PushSecrets.
+  # Defaults to the name of the ClusterPushSecret when omitted.
   pushSecretName: "hello-world-ps"
 
+  # Optional labels and annotations to set on every created PushSecret.
+  pushSecretMetadata:
+    labels: {}
+    annotations: {}
+
   # This is a list of basic label selector to select the namespaces to deploy PushSecrets to.
   # you can read more about them here https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#resources-that-support-set-based-requirements
   # The list is OR'd together, so if any of the namespaceSelectors match the namespace,
@@ -26,6 +32,7 @@ spec:
 
   # How often the ClusterPushSecret should reconcile itself
   # This will decide how often to check and make sure that the PushSecrets exist in the matching namespaces
+  # If omitted, the controller's default requeue interval is used.
   refreshTime: "1m"
 
   # This is the spec of the PushSecrets to be created
@@ -76,18 +83,19 @@ status:
   failedNamespaces:
     - namespace: "matching-ns-1"
       # This is one of the possible messages, and likely the most common
-      reason: "external secret already exists in namespace"
+      reason: "push secret already exists in namespace"
 
   # You can find all matching and successfully deployed namespaces here
   provisionedNamespaces:
     - "matching-ns-3"
     - "matching-ns-2"
 
-  # The condition can be Ready, PartiallyReady, or NotReady
-  # PartiallyReady would indicate an error in 1 or more namespaces
-  # NotReady would indicate errors in all namespaces meaning all ExternalSecrets resulted in errors
+  # The only condition type is Ready. status is "True" when all matching
+  # namespaces synced, and "False" if one or more namespaces failed (the failed
+  # ones are listed under failedNamespaces above).
   conditions:
-  - type: PartiallyReady
-    status: "True"
+  - type: Ready
+    status: "False"
+    message: "one or more namespaces failed"
     lastTransitionTime: "2022-01-12T12:33:02Z"
 {% endraw %}

docs/snippets/full-cluster-secret-store.yaml

@@ -4,7 +4,7 @@ metadata:
   name: example
   annotations:
     ## Add this annotation to disable controller warning events for unmaintained stores
-    external-secrets.io/disable-maintenance-checks: "true"
+    external-secrets.io/ignore-maintenance-checks: "true"
 spec:
   # Used to select the correct ESO controller (think: ingress.ingressClassName)
   # The ESO controller is instantiated with a specific controller name
@@ -177,6 +177,6 @@ status:
     # should prevent attempts to fetch secrets
     - type: Ready
       status: "False"
-      reason: "ConfigError"
+      reason: "ValidationFailed"
       message: "SecretStore validation failed"
       lastTransitionTime: "2019-08-12T12:33:02Z"

docs/snippets/full-pushsecret.yaml

@@ -15,19 +15,21 @@ metadata:
   namespace: default # Same of the SecretStores
 spec:
   updatePolicy: Replace # Policy to overwrite existing secrets in the provider on sync
-  deletionPolicy: Delete # the provider' secret will be deleted if the PushSecret is deleted
+  deletionPolicy: Delete # delete the provider secret when the PushSecret is deleted (default: None, which keeps it)
   refreshInterval: 1h0m0s # Refresh interval for which push secret will reconcile
   secretStoreRefs: # A list of secret stores to push secrets to
     - name: aws-parameterstore
       kind: SecretStore
+  # Exactly one of selector.secret or selector.generatorRef may be set.
   selector:
     secret:
       name: pokedex-credentials # Source Kubernetes secret to be pushed
-    # Alternatively, you can point to a generator that produces values to be pushed
-    generatorRef:
-      apiVersion: generators.external-secrets.io/v1alpha1
-      kind: ECRAuthorizationToken
-      name: prod-registry-credentials
+    # Alternatively (mutually exclusive with secret), point to a generator
+    # that produces the values to be pushed:
+    # generatorRef:
+    #   apiVersion: generators.external-secrets.io/v1alpha1
+    #   kind: ECRAuthorizationToken
+    #   name: prod-registry-credentials
   template:
     metadata:
       annotations: { }

docs/snippets/full-secret-store.yaml

@@ -5,7 +5,7 @@ metadata:
   namespace: example-ns
   annotations:
     ## Add this annotation to disable controller warning events for unmaintained stores
-    external-secrets.io/disable-maintenance-checks: "true"
+    external-secrets.io/ignore-maintenance-checks: "true"
 spec:
 
   # Used to select the correct ESO controller (think: ingress.ingressClassName)
@@ -141,6 +141,6 @@ status:
   # should prevent attempts to fetch secrets
   - type: Ready
     status: "False"
-    reason: "ConfigError"
+    reason: "ValidationFailed"
     message: "SecretStore validation failed"
     lastTransitionTime: "2019-08-12T12:33:02Z"