ClusterExternalSecret

The ClusterExternalSecret is a cluster scoped resource that can be used to manage ExternalSecret resources in specific namespaces.

With namespaceSelectors you can select namespaces in which the ExternalSecret should be created. If there is a conflict with an existing resource the controller will error out.

Example

Below is an example of the ClusterExternalSecret in use.

apiVersion: external-secrets.io/v1
kind: ClusterExternalSecret
metadata:
  name: "hello-world"
spec:
  # The name to be used on the ExternalSecrets
  externalSecretName: "hello-world-es"

  # 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.
  # namespaceSelector:
  #   matchLabels:
  #     cool: label

  # This is a list of 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
  # The list is OR'd together, so if any of the namespaceSelectors match the namespace,
  # the ExternalSecret will be deployed to that namespace.
  namespaceSelectors:
  - matchLabels:
      cool: label

  # 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
  refreshTime: "1m"

  # This is the spec of the ExternalSecrets to be created
  # The content of this was taken from our ExternalSecret example
  externalSecretSpec:
    secretStoreRef:
      name: secret-store-name
      kind: SecretStore

    # RefreshPolicy determines how the ExternalSecret should be refreshed:
    # - CreatedOnce: Creates the Secret only if it does not exist and does not update it afterward
    # - Periodic: (default) Synchronizes the Secret at intervals specified by refreshInterval
    # - OnChange: Only synchronizes when the ExternalSecret's metadata or specification changes
    refreshPolicy: Periodic

    refreshInterval: "1h"
    target:
      name: my-secret
      creationPolicy: 'Merge'
      template:
        type: kubernetes.io/dockerconfigjson

        metadata:
          annotations: {}
          labels: {}
        data:
          config.yml: |
            endpoints:
            - https://{{ .data.user }}:{{ .data.password }}@api.exmaple.com
        templateFrom:
        - configMap:
            name: alertmanager
            items:
            - key: alertmanager.yaml
    data:
      - secretKey: secret-key-to-be-managed
        remoteRef:
          key: provider-key
          version: provider-key-version
          property: provider-key-property
    dataFrom:
    - key: provider-key
      version: provider-key-version
      property: provider-key-property

status:
  # This will list any namespaces where the creation of the ExternalSecret failed
  # This will not list any issues with the ExternalSecrets, you will have to check the
  # ExternalSecrets to see any issues with them.
  failedNamespaces:
    - namespace: "matching-ns-1"
      # This is one of the possible messages, and likely the most common
      reason: "external 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
  conditions:
  - type: PartiallyReady
    status: "True"
    lastTransitionTime: "2022-01-12T12:33:02Z"

Synchronizing corresponding ExternalSecrets

Regular refreshes can be controlled using the refreshPolicy and refreshInterval fields. Adhoc synchronizations can be triggered by setting, updating or deleting the annotation external-secrets.io/force-sync on the ClusterExternalSecret:

kubectl annotate ces my-ces external-secrets.io/force-sync=$(date +%s) --overwrite

Changes to this annotation will be synchronized to all ExternalSecrets owned by the ClusterExternalSecret.

Deprecations

namespaceSelector

The field namespaceSelector has been deprecated in favor of namespaceSelectors and will be removed in a future version.