{"config":{"lang":["en"],"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Introduction External Secrets Operator is a Kubernetes operator that integrates external secret management systems like AWS Secrets Manager , HashiCorp Vault , Google Secrets Manager , Azure Key Vault and many more. The operator reads information from external APIs and automatically injects the values into a Kubernetes Secret . What is the goal of External Secrets Operator? The goal of External Secrets Operator is to synchronize secrets from external APIs into Kubernetes. ESO is a collection of custom API resources - ExternalSecret , SecretStore and ClusterSecretStore that provide a user-friendly abstraction for the external API that stores and manages the lifecycle of the secrets for you. Where to get started To get started, please read through API overview this should give you a high-level overview to understand the API and use-cases. After that please follow one of our guides to get a jump start using the operator. See our getting started guide for installation instructions. For a complete reference of the API types please refer to our API Reference . How to get involved This project is driven by it's users and contributors and we welcome everybody to get involved. Join our meetings, open issues or ask questions in Slack. The success of this project depends on your input: No contribution is too small - even opinions matter! How to get involved: Bi-weekly Development Meeting every odd week at 5:30 PM Berlin Time ( agenda , jitsi call ) Kubernetes Slack #external-secrets Contributing Process Kicked off by","title":"Introduction"},{"location":"#introduction","text":"External Secrets Operator is a Kubernetes operator that integrates external secret management systems like AWS Secrets Manager , HashiCorp Vault , Google Secrets Manager , Azure Key Vault and many more. The operator reads information from external APIs and automatically injects the values into a Kubernetes Secret .","title":"Introduction"},{"location":"#what-is-the-goal-of-external-secrets-operator","text":"The goal of External Secrets Operator is to synchronize secrets from external APIs into Kubernetes. ESO is a collection of custom API resources - ExternalSecret , SecretStore and ClusterSecretStore that provide a user-friendly abstraction for the external API that stores and manages the lifecycle of the secrets for you.","title":"What is the goal of External Secrets Operator?"},{"location":"#where-to-get-started","text":"To get started, please read through API overview this should give you a high-level overview to understand the API and use-cases. After that please follow one of our guides to get a jump start using the operator. See our getting started guide for installation instructions. For a complete reference of the API types please refer to our API Reference .","title":"Where to get started"},{"location":"#how-to-get-involved","text":"This project is driven by it's users and contributors and we welcome everybody to get involved. Join our meetings, open issues or ask questions in Slack. The success of this project depends on your input: No contribution is too small - even opinions matter! How to get involved: Bi-weekly Development Meeting every odd week at 5:30 PM Berlin Time ( agenda , jitsi call ) Kubernetes Slack #external-secrets Contributing Process","title":"How to get involved"},{"location":"#kicked-off-by","text":"","title":"Kicked off by"},{"location":"api-clustersecretstore/","text":"The ClusterSecretStore is a cluster scoped SecretStore that can be referenced by all ExternalSecrets from all namespaces. Use it to offer a central gateway to your secret backend. apiVersion : external-secrets.io/v1alpha1 kind : ClusterSecretStore metadata : name : example spec : # Used to select the correct ESO controller (think: ingress.ingressClassName) # The ESO controller is instantiated with a specific controller name # and filters ES based on this property # Optional controller : dev # provider field contains the configuration to access the provider # which contains the secret exactly one provider must be configured. provider : # (1): AWS Secrets Manager # aws configures this store to sync secrets using AWS Secret Manager provider aws : service : SecretsManager # Role is a Role ARN which the SecretManager provider will assume role : iam-role # AWS Region to be used for the provider region : eu-central-1 # Auth defines the information necessary to authenticate against AWS auth : # Getting the accessKeyID and secretAccessKey from an already created Kubernetes Secret secretRef : accessKeyID : name : awssm-secret key : access-key secretAccessKey : name : awssm-secret key : secret-access-key # IAM roles for service accounts # https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts-technical-overview.html jwt : serviceAccountRef : name : my-serviceaccount namespace : sa-namespace vault : server : \"https://vault.acme.org\" # Path is the mount path of the Vault KV backend endpoint path : \"secret\" # Version is the Vault KV secret engine version. # This can be either \"v1\" or \"v2\", defaults to \"v2\" version : \"v2\" # vault enterprise namespace: https://www.vaultproject.io/docs/enterprise/namespaces namespace : \"a-team\" # base64 encoded string of certificate caBundle : \"...\" # Instead of caBundle you can also specify a caProvider # this will retrieve the cert from a Secret or ConfigMap caProvider : # Can be Secret or ConfigMap type : \"Secret\" # This is mandatory for ClusterSecretStore and not relevant for SecretStore namespace : \"my-cert-secret-namespace\" name : \"my-cert-secret\" key : \"cert-key\" auth : # static token: https://www.vaultproject.io/docs/auth/token tokenSecretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"vault-token\" # AppRole auth: https://www.vaultproject.io/docs/auth/approle appRole : path : \"approle\" roleId : \"db02de05-fa39-4855-059b-67221c5c2f63\" secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"vault-token\" # Kubernetes auth: https://www.vaultproject.io/docs/auth/kubernetes kubernetes : mountPath : \"kubernetes\" role : \"demo\" # Optional service account reference serviceAccountRef : name : \"my-sa\" namespace : \"secret-admin\" # Optional secret field containing a Kubernetes ServiceAccount JWT # used for authenticating with Vault secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"vault\" # (2): GCP Secret Manager gcpsm : # Auth defines the information necessary to authenticate against GCP by getting # the credentials from an already created Kubernetes Secret. auth : secretRef : secretAccessKeySecretRef : name : gcpsm-secret key : secret-access-credentials namespace : example projectID : myproject # (TODO): add more provider examples here status : # Standard condition schema conditions : # SecretStore ready condition indicates the given store is in ready # state and able to referenced by ExternalSecrets # If the `status` of this condition is `False`, ExternalSecret controllers # should prevent attempts to fetch secrets - type : Ready status : \"False\" reason : \"ConfigError\" message : \"SecretStore validation failed\" lastTransitionTime : \"2019-08-12T12:33:02Z\"","title":"ClusterSecretStore"},{"location":"api-externalsecret/","text":"The ExternalSecret describes what data should be fetched, how the data should be transformed and saved as a Kind=Secret : tells the operator what secrets should be synced by using spec.data to explicitly sync individual keys or use spec.dataFrom to get all values from the external API. you can specify how the secret should look like by specifying a spec.target.template Template When the controller reconciles the ExternalSecret it will use the spec.template as a blueprint to construct a new Kind=Secret . You can use golang templates to define the blueprint and use template functions to transform secret values. You can also pull in ConfigMaps that contain golang-template data using templateFrom . See advanced templating for details. Update Behavior The Kind=Secret is updated when: the spec.refreshInterval has passed and is not 0 the ExternalSecret 's labels or annotations are changed the ExternalSecret 's spec has been changed You can trigger a secret refresh by using kubectl or any other kubernetes api client: kubectl annotate es my-es force-sync=$(date +%s) --overwrite Example Take a look at an annotated example to understand the design behind the ExternalSecret . apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : \"hello-world\" # labels and annotations are copied over to the # secret that will be created labels : acme.org/owned-by : \"q-team\" annotations : acme.org/sha : 1234 spec : # SecretStoreRef defines which SecretStore to use when fetching the secret data secretStoreRef : name : secret-store-name kind : SecretStore # or ClusterSecretStore # RefreshInterval is the amount of time before the values reading again from the SecretStore provider # Valid time units are \"ns\", \"us\" (or \"\u00b5s\"), \"ms\", \"s\", \"m\", \"h\" (from time.ParseDuration) # May be set to zero to fetch and create it once refreshInterval : \"1h\" # the target describes the secret that shall be created # there can only be one target per ExternalSecret target : # The secret name of the resource # Defaults to .metadata.name of the ExternalSecret # It is immutable name : my-secret # Enum with values: 'Owner', 'Merge', or 'None' # Default value of 'Owner' # Owner creates the secret and sets .metadata.ownerReferences of the resource # Merge does not create the secret, but merges in the data fields to the secret # None does not create a secret (future use with injector) creationPolicy : 'Merge' # Specify a blueprint for the resulting Kind=Secret template : type : kubernetes.io/dockerconfigjson # or TLS... metadata : annotations : {} labels : {} # Use inline templates to construct your desired config file that contains your secret data : config.yml : | endpoints: - https://{{ .data.user }}:{{ .data.password }}@api.exmaple.com # Uses an existing template from configmap # Secret is fetched, merged and templated within the referenced configMap data # It does not update the configmap, it creates a secret with: data[\"alertmanager.yml\"] = ...result... templateFrom : - configMap : name : alertmanager items : - key : alertmanager.yaml # Data defines the connection between the Kubernetes Secret keys and the Provider data data : - secretKey : secret-key-to-be-managed remoteRef : key : provider-key version : provider-key-version property : provider-key-property # Used to fetch all properties from the Provider key # If multiple dataFrom are specified, secrets are merged in the specified order dataFrom : - key : provider-key version : provider-key-version property : provider-key-property status : # refreshTime is the time and date the external secret was fetched and # the target secret updated refreshTime : \"2019-08-12T12:33:02Z\" # Standard condition schema conditions : # ExternalSecret ready condition indicates the secret is ready for use. # This is defined as: # - The target secret exists # - The target secret has been refreshed within the last refreshInterval # - The target secret content is up-to-date based on any target templates - type : Ready status : \"True\" # False if last refresh was not successful reason : \"SecretSynced\" message : \"Secret was synced\" lastTransitionTime : \"2019-08-12T12:33:02Z\"","title":"ExternalSecret"},{"location":"api-externalsecret/#template","text":"When the controller reconciles the ExternalSecret it will use the spec.template as a blueprint to construct a new Kind=Secret . You can use golang templates to define the blueprint and use template functions to transform secret values. You can also pull in ConfigMaps that contain golang-template data using templateFrom . See advanced templating for details.","title":"Template"},{"location":"api-externalsecret/#update-behavior","text":"The Kind=Secret is updated when: the spec.refreshInterval has passed and is not 0 the ExternalSecret 's labels or annotations are changed the ExternalSecret 's spec has been changed You can trigger a secret refresh by using kubectl or any other kubernetes api client: kubectl annotate es my-es force-sync=$(date +%s) --overwrite","title":"Update Behavior"},{"location":"api-externalsecret/#example","text":"Take a look at an annotated example to understand the design behind the ExternalSecret . apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : \"hello-world\" # labels and annotations are copied over to the # secret that will be created labels : acme.org/owned-by : \"q-team\" annotations : acme.org/sha : 1234 spec : # SecretStoreRef defines which SecretStore to use when fetching the secret data secretStoreRef : name : secret-store-name kind : SecretStore # or ClusterSecretStore # RefreshInterval is the amount of time before the values reading again from the SecretStore provider # Valid time units are \"ns\", \"us\" (or \"\u00b5s\"), \"ms\", \"s\", \"m\", \"h\" (from time.ParseDuration) # May be set to zero to fetch and create it once refreshInterval : \"1h\" # the target describes the secret that shall be created # there can only be one target per ExternalSecret target : # The secret name of the resource # Defaults to .metadata.name of the ExternalSecret # It is immutable name : my-secret # Enum with values: 'Owner', 'Merge', or 'None' # Default value of 'Owner' # Owner creates the secret and sets .metadata.ownerReferences of the resource # Merge does not create the secret, but merges in the data fields to the secret # None does not create a secret (future use with injector) creationPolicy : 'Merge' # Specify a blueprint for the resulting Kind=Secret template : type : kubernetes.io/dockerconfigjson # or TLS... metadata : annotations : {} labels : {} # Use inline templates to construct your desired config file that contains your secret data : config.yml : | endpoints: - https://{{ .data.user }}:{{ .data.password }}@api.exmaple.com # Uses an existing template from configmap # Secret is fetched, merged and templated within the referenced configMap data # It does not update the configmap, it creates a secret with: data[\"alertmanager.yml\"] = ...result... templateFrom : - configMap : name : alertmanager items : - key : alertmanager.yaml # Data defines the connection between the Kubernetes Secret keys and the Provider data data : - secretKey : secret-key-to-be-managed remoteRef : key : provider-key version : provider-key-version property : provider-key-property # Used to fetch all properties from the Provider key # If multiple dataFrom are specified, secrets are merged in the specified order dataFrom : - key : provider-key version : provider-key-version property : provider-key-property status : # refreshTime is the time and date the external secret was fetched and # the target secret updated refreshTime : \"2019-08-12T12:33:02Z\" # Standard condition schema conditions : # ExternalSecret ready condition indicates the secret is ready for use. # This is defined as: # - The target secret exists # - The target secret has been refreshed within the last refreshInterval # - The target secret content is up-to-date based on any target templates - type : Ready status : \"True\" # False if last refresh was not successful reason : \"SecretSynced\" message : \"Secret was synced\" lastTransitionTime : \"2019-08-12T12:33:02Z\"","title":"Example"},{"location":"api-overview/","text":"API Overview Architecture The External Secrets Operator extends Kubernetes with Custom Resources , which define where secrets live and how to synchronize them. The controller fetches secrets from an external API and creates Kubernetes secrets . If the secret from the external API changes, the controller will reconcile the state in the cluster and update the secrets accordingly. Resource model To understand the mechanics of the operator let's start with the data model. The SecretStore references an bucket of key/value pairs. But because every external API is slightly different this bucket may be e.g. an instance of an Azure KeyVault or a AWS Secrets Manager in a certain AWS Account and region. Please take a look at the provider documentation to see what the Bucket actually maps to. SecretStore The idea behind the SecretStore resource is to separate concerns of authentication/access and the actual Secret and configuration needed for workloads. The ExternalSecret specifies what to fetch, the SecretStore specifies how to access. This resource is namespaced. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager region : us-east-1 auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key The SecretStore contains references to secrets which hold credentials to access the external API. ExternalSecret An ExternalSecret declares what data to fetch. It has a reference to a SecretStore which knows how to access that data. The controller uses that ExternalSecret as a blueprint to create secrets. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 1h secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created creationPolicy : Owner data : - secretKey : secret-key-to-be-managed remoteRef : key : provider-key version : provider-key-version property : provider-key-property dataFrom : - key : remote-key-in-the-provider ClusterSecretStore The ClusterSecretStore is a global, cluster-wide SecretStore that can be referenced from all namespaces. You can use it to provide a central gateway to your secret provider. Behavior The External Secret Operator (ESO for brevity) reconciles ExternalSecrets in the following manner: ESO uses spec.secretStoreRef to find an appropriate SecretStore . If it doesn't exist or the spec.controller field doesn't match it won't further process this ExternalSecret. ESO instanciates an external API client using the specified credentials from the SecretStore spec. ESO fetches the secrets as requested by the ExternalSecret , it will decode the secrets if required ESO creates an Kind=Secret based on the template provided by ExternalSecret.target.template . The Secret.data can be templated using the secret values from the external API. ESO ensures that the secret values stay in sync with the external API Roles and responsibilities The External Secret Operator is designed to target the following persona: Cluster Operator : The cluster operator is responsible for setting up the External Secret Operator, managing access policies and creating ClusterSecretStores. Application developer : The Application developer is responsible for defining ExternalSecrets and the application configuration Each persona will roughly map to a Kubernetes RBAC role. Depending on your environment these roles can map to a single user. Note: There is no Secret Operator that handles the lifecycle of the secret, this is out of the scope of ESO. Access Control The External Secrets Operator runs as a deployment in your cluster with elevated privileges. It will create/read/update secrets in all namespaces and has access to secrets stored in some external API. Ensure that the credentials you provide give ESO the least privilege necessary. Design your SecretStore / ClusterSecretStore carefully! Be sure to restrict access of application developers to read only certain keys in a shared environment. You should also consider using Kubernetes' admission control system (e.g. OPA or Kyverno ) for fine-grained access control. Running multiple Controller You can run multiple controller within the cluster. One controller can be limited to only process SecretStores with a predefined spec.controller field. Testers welcome This is not widely tested. Please help us test the setup and/or document use-cases.","title":"Overview"},{"location":"api-overview/#api-overview","text":"","title":"API Overview"},{"location":"api-overview/#architecture","text":"The External Secrets Operator extends Kubernetes with Custom Resources , which define where secrets live and how to synchronize them. The controller fetches secrets from an external API and creates Kubernetes secrets . If the secret from the external API changes, the controller will reconcile the state in the cluster and update the secrets accordingly.","title":"Architecture"},{"location":"api-overview/#resource-model","text":"To understand the mechanics of the operator let's start with the data model. The SecretStore references an bucket of key/value pairs. But because every external API is slightly different this bucket may be e.g. an instance of an Azure KeyVault or a AWS Secrets Manager in a certain AWS Account and region. Please take a look at the provider documentation to see what the Bucket actually maps to.","title":"Resource model"},{"location":"api-overview/#secretstore","text":"The idea behind the SecretStore resource is to separate concerns of authentication/access and the actual Secret and configuration needed for workloads. The ExternalSecret specifies what to fetch, the SecretStore specifies how to access. This resource is namespaced. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager region : us-east-1 auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key The SecretStore contains references to secrets which hold credentials to access the external API.","title":"SecretStore"},{"location":"api-overview/#externalsecret","text":"An ExternalSecret declares what data to fetch. It has a reference to a SecretStore which knows how to access that data. The controller uses that ExternalSecret as a blueprint to create secrets. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 1h secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created creationPolicy : Owner data : - secretKey : secret-key-to-be-managed remoteRef : key : provider-key version : provider-key-version property : provider-key-property dataFrom : - key : remote-key-in-the-provider","title":"ExternalSecret"},{"location":"api-overview/#clustersecretstore","text":"The ClusterSecretStore is a global, cluster-wide SecretStore that can be referenced from all namespaces. You can use it to provide a central gateway to your secret provider.","title":"ClusterSecretStore"},{"location":"api-overview/#behavior","text":"The External Secret Operator (ESO for brevity) reconciles ExternalSecrets in the following manner: ESO uses spec.secretStoreRef to find an appropriate SecretStore . If it doesn't exist or the spec.controller field doesn't match it won't further process this ExternalSecret. ESO instanciates an external API client using the specified credentials from the SecretStore spec. ESO fetches the secrets as requested by the ExternalSecret , it will decode the secrets if required ESO creates an Kind=Secret based on the template provided by ExternalSecret.target.template . The Secret.data can be templated using the secret values from the external API. ESO ensures that the secret values stay in sync with the external API","title":"Behavior"},{"location":"api-overview/#roles-and-responsibilities","text":"The External Secret Operator is designed to target the following persona: Cluster Operator : The cluster operator is responsible for setting up the External Secret Operator, managing access policies and creating ClusterSecretStores. Application developer : The Application developer is responsible for defining ExternalSecrets and the application configuration Each persona will roughly map to a Kubernetes RBAC role. Depending on your environment these roles can map to a single user. Note: There is no Secret Operator that handles the lifecycle of the secret, this is out of the scope of ESO.","title":"Roles and responsibilities"},{"location":"api-overview/#access-control","text":"The External Secrets Operator runs as a deployment in your cluster with elevated privileges. It will create/read/update secrets in all namespaces and has access to secrets stored in some external API. Ensure that the credentials you provide give ESO the least privilege necessary. Design your SecretStore / ClusterSecretStore carefully! Be sure to restrict access of application developers to read only certain keys in a shared environment. You should also consider using Kubernetes' admission control system (e.g. OPA or Kyverno ) for fine-grained access control.","title":"Access Control"},{"location":"api-overview/#running-multiple-controller","text":"You can run multiple controller within the cluster. One controller can be limited to only process SecretStores with a predefined spec.controller field. Testers welcome This is not widely tested. Please help us test the setup and/or document use-cases.","title":"Running multiple Controller"},{"location":"api-secretstore/","text":"The SecretStore is namespaced and specifies how to access the external API. The SecretStore maps to exactly one instance of an external API. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example namespace : example-ns spec : # Used to select the correct ESO controller (think: ingress.ingressClassName) # The ESO controller is instantiated with a specific controller name # and filters ES based on this property # Optional controller : dev # You can specify retry settings for the http connection # these fields allow you to set a maxRetries before failure, and # an interval between the retries. # Current supported providers: IBM retrySettings : maxRetries : 5 retryInterval : \"10s\" # provider field contains the configuration to access the provider # which contains the secret exactly one provider must be configured. provider : # (1): AWS Secrets Manager # aws configures this store to sync secrets using AWS Secret Manager provider aws : service : SecretsManager # Role is a Role ARN which the SecretManager provider will assume role : iam-role # AWS Region to be used for the provider region : eu-central-1 # Auth defines the information necessary to authenticate against AWS by # getting the accessKeyID and secretAccessKey from an already created Kubernetes Secret auth : secretRef : accessKeyID : name : awssm-secret key : access-key secretAccessKey : name : awssm-secret key : secret-access-key vault : server : \"https://vault.acme.org\" # Path is the mount path of the Vault KV backend endpoint path : \"secret\" # Version is the Vault KV secret engine version. # This can be either \"v1\" or \"v2\", defaults to \"v2\" version : \"v2\" # vault enterprise namespace: https://www.vaultproject.io/docs/enterprise/namespaces namespace : \"a-team\" # base64 encoded string of certificate caBundle : \"...\" # Instead of caBundle you can also specify a caProvider # this will retrieve the cert from a Secret or ConfigMap caProvider : # Can be Secret or ConfigMap type : \"Secret\" name : \"my-cert-secret\" key : \"cert-key\" auth : # static token: https://www.vaultproject.io/docs/auth/token tokenSecretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"vault-token\" # AppRole auth: https://www.vaultproject.io/docs/auth/approle appRole : path : \"approle\" roleId : \"db02de05-fa39-4855-059b-67221c5c2f63\" secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"vault-token\" # Kubernetes auth: https://www.vaultproject.io/docs/auth/kubernetes kubernetes : mountPath : \"kubernetes\" role : \"demo\" # Optional service account reference serviceAccountRef : name : \"my-sa\" namespace : \"secret-admin\" # Optional secret field containing a Kubernetes ServiceAccount JWT # used for authenticating with Vault secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"vault\" # (2): GCP Secret Manager gcpsm : # Auth defines the information necessary to authenticate against GCP by getting # the credentials from an already created Kubernetes Secret. auth : secretRef : secretAccessKeySecretRef : name : gcpsm-secret key : secret-access-credentials projectID : myproject # (TODO): add more provider examples here status : # Standard condition schema conditions : # SecretStore ready condition indicates the given store is in ready # state and able to referenced by ExternalSecrets # If the `status` of this condition is `False`, ExternalSecret controllers # should prevent attempts to fetch secrets - type : Ready status : \"False\" reason : \"ConfigError\" message : \"SecretStore validation failed\" lastTransitionTime : \"2019-08-12T12:33:02Z\"","title":"SecretStore"},{"location":"contributing-coc/","text":"Code of Conduct Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. Our Standards Examples of behavior that contributes to a positive environment for our community include: Demonstrating empathy and kindness toward other people Being respectful of differing opinions, viewpoints, and experiences Giving and gracefully accepting constructive feedback Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: The use of sexualized language or imagery, and sexual attention or advances of any kind Trolling, insulting or derogatory comments, and personal or political attacks Public or private harassment Publishing others' private information, such as a physical or email address, without their explicit permission Other conduct which could reasonably be considered inappropriate in a professional setting Enforcement Responsibilities Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. Scope This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at contact@external-secrets.io. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: 1. Correction Community Impact : Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. Consequence : A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. 2. Warning Community Impact : A violation through a single incident or series of actions. Consequence : A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. 3. Temporary Ban Community Impact : A serious violation of community standards, including sustained inappropriate behavior. Consequence : A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. 4. Permanent Ban Community Impact : Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. Consequence : A permanent ban from any sort of public interaction within the community. Attribution This Code of Conduct is adapted from the Contributor Covenant , version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html . Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder . For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq . Translations are available at https://www.contributor-covenant.org/translations .","title":"Code of Conduct"},{"location":"contributing-coc/#code-of-conduct","text":"","title":"Code of Conduct"},{"location":"contributing-coc/#our-pledge","text":"We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.","title":"Our Pledge"},{"location":"contributing-coc/#our-standards","text":"Examples of behavior that contributes to a positive environment for our community include: Demonstrating empathy and kindness toward other people Being respectful of differing opinions, viewpoints, and experiences Giving and gracefully accepting constructive feedback Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: The use of sexualized language or imagery, and sexual attention or advances of any kind Trolling, insulting or derogatory comments, and personal or political attacks Public or private harassment Publishing others' private information, such as a physical or email address, without their explicit permission Other conduct which could reasonably be considered inappropriate in a professional setting","title":"Our Standards"},{"location":"contributing-coc/#enforcement-responsibilities","text":"Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.","title":"Enforcement Responsibilities"},{"location":"contributing-coc/#scope","text":"This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.","title":"Scope"},{"location":"contributing-coc/#enforcement","text":"Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at contact@external-secrets.io. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident.","title":"Enforcement"},{"location":"contributing-coc/#enforcement-guidelines","text":"Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:","title":"Enforcement Guidelines"},{"location":"contributing-coc/#1-correction","text":"Community Impact : Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. Consequence : A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.","title":"1. Correction"},{"location":"contributing-coc/#2-warning","text":"Community Impact : A violation through a single incident or series of actions. Consequence : A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.","title":"2. Warning"},{"location":"contributing-coc/#3-temporary-ban","text":"Community Impact : A serious violation of community standards, including sustained inappropriate behavior. Consequence : A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.","title":"3. Temporary Ban"},{"location":"contributing-coc/#4-permanent-ban","text":"Community Impact : Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. Consequence : A permanent ban from any sort of public interaction within the community.","title":"4. Permanent Ban"},{"location":"contributing-coc/#attribution","text":"This Code of Conduct is adapted from the Contributor Covenant , version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html . Community Impact Guidelines were inspired by Mozilla's code of conduct enforcement ladder . For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq . Translations are available at https://www.contributor-covenant.org/translations .","title":"Attribution"},{"location":"contributing-devguide/","text":"Getting Started You must have a working Go environment and then clone the repo: git clone https://github.com/external-secrets/external-secrets.git cd external-secrets If you want to run controller tests you also need to install kubebuilder's envtest . The recommended way to do so is to install setup-envtest Here is an example on how to set it up: go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest # list available versions setup-envtest list --os $(go env GOOS) --arch $(go env GOARCH) # To use a specific version setup-envtest use -p path 1.20.2 #To set environment variables source <(setup-envtest use 1.20.2 -p env --os $(go env GOOS) --arch $(go env GOARCH)) for more information, please see setup-envtest docs Building & Testing The project uses the make build system. It'll run code generators, tests and static code analysis. Building the operator binary and docker image: make build make docker.build IMG = external-secrets:latest Run tests and lint the code: make test make lint Build the documentation: make docs Installing To install the External Secret Operator into a Kubernetes Cluster run: helm repo add external-secrets https://charts.external-secrets.io helm repo update helm install external-secrets external-secrets/external-secrets You can alternatively run the controller on your host system for development purposes: make crds.install make run To remove the CRDs run: make crds.uninstall If you need to test some other k8s integrations and need the operator to be deployed to the actuall cluster while developing, you can use the following workflow: kind create cluster --name external-secrets export TAG=v2 export IMAGE=eso-local #For building in linux docker build . -t $IMAGE:$TAG --build-arg TARGETARCH=amd64 --build-arg TARGETOS=linux #For building in MacOS (OSX) #docker build . -t $IMAGE:$TAG --build-arg TARGETARCH=amd64 --build-arg TARGETOS=darwin #For building in ARM #docker build . -t $IMAGE:$TAG --build-arg TARGETARCH=arm --build-arg TARGETOS=linux make helm.generate helm upgrade --install external-secrets ./deploy/charts/external-secrets/ --set image.repository=$IMAGE --set image.tag=$TAG Contributing Flow The HOW TO guide for contributing is at the Contributing Process page. Documentation We use mkdocs material to generate this documentation. See /docs for the source code and /hack/api-docs for the build process. When writing documentation it is advised to run the mkdocs server with livereload: make serve-docs Run the following command to run a complete build. The rendered assets are available under /site . make docs make serve-docs Open http://localhost:8000 in your browser.","title":"Developer guide"},{"location":"contributing-devguide/#getting-started","text":"You must have a working Go environment and then clone the repo: git clone https://github.com/external-secrets/external-secrets.git cd external-secrets If you want to run controller tests you also need to install kubebuilder's envtest . The recommended way to do so is to install setup-envtest Here is an example on how to set it up: go install sigs.k8s.io/controller-runtime/tools/setup-envtest@latest # list available versions setup-envtest list --os $(go env GOOS) --arch $(go env GOARCH) # To use a specific version setup-envtest use -p path 1.20.2 #To set environment variables source <(setup-envtest use 1.20.2 -p env --os $(go env GOOS) --arch $(go env GOARCH)) for more information, please see setup-envtest docs","title":"Getting Started"},{"location":"contributing-devguide/#building-testing","text":"The project uses the make build system. It'll run code generators, tests and static code analysis. Building the operator binary and docker image: make build make docker.build IMG = external-secrets:latest Run tests and lint the code: make test make lint Build the documentation: make docs","title":"Building &amp; Testing"},{"location":"contributing-devguide/#installing","text":"To install the External Secret Operator into a Kubernetes Cluster run: helm repo add external-secrets https://charts.external-secrets.io helm repo update helm install external-secrets external-secrets/external-secrets You can alternatively run the controller on your host system for development purposes: make crds.install make run To remove the CRDs run: make crds.uninstall If you need to test some other k8s integrations and need the operator to be deployed to the actuall cluster while developing, you can use the following workflow: kind create cluster --name external-secrets export TAG=v2 export IMAGE=eso-local #For building in linux docker build . -t $IMAGE:$TAG --build-arg TARGETARCH=amd64 --build-arg TARGETOS=linux #For building in MacOS (OSX) #docker build . -t $IMAGE:$TAG --build-arg TARGETARCH=amd64 --build-arg TARGETOS=darwin #For building in ARM #docker build . -t $IMAGE:$TAG --build-arg TARGETARCH=arm --build-arg TARGETOS=linux make helm.generate helm upgrade --install external-secrets ./deploy/charts/external-secrets/ --set image.repository=$IMAGE --set image.tag=$TAG Contributing Flow The HOW TO guide for contributing is at the Contributing Process page.","title":"Installing"},{"location":"contributing-devguide/#documentation","text":"We use mkdocs material to generate this documentation. See /docs for the source code and /hack/api-docs for the build process. When writing documentation it is advised to run the mkdocs server with livereload: make serve-docs Run the following command to run a complete build. The rendered assets are available under /site . make docs make serve-docs Open http://localhost:8000 in your browser.","title":"Documentation"},{"location":"contributing-process/","text":"Project Management The Code, our TODOs and Documentation is maintained on GitHub . All Issues should be opened in that repository. Issues Features, bugs and any issues regarding the documentation should be filed as GitHub Issue in our repository. We use labels like kind/feature , kind/bug , area/aws to organize the issues. Issues labeled good first issue and help wanted are especially good for a first contribution. If you want to pick up an issue just leave a comment. Submitting a Pull Request This project uses the well-known pull request process from GitHub. To submit a pull request, fork the repository and push any changes to a branch on the copy, from there a pull request can be made in the main repo. Merging a pull request requires the following steps to be completed before the pull request will be merged: ideally, there is an issue that documents the problem or feature in depth. code must have a reasonable amount of test coverage tests must pass PR needs be reviewed and approved Once these steps are completed the PR will be merged by a code owner. We're using the pull request assignee feature to track who is responsible for the lifecycle of the PR: review, merging, ping on inactivity, close. We close pull requests or issues if there is no response from the author for a period of time. Feel free to reopen if you want to get back on it. Proposal Process Before we introduce significant changes to the project we want to gather feedback from the community to ensure that we progress in the right direction before we develop and release big changes. Significant changes include for example: * creating new custom resources * proposing breaking changes * changing the behavior of the controller significantly Please create a document in the design/ directory based on the template 000-template.md and fill in your proposal. Open a pull request in draft mode and request feedback. Once the proposal is accepted and the pull request is merged we can create work packages and proceed with the implementation. Cutting Releases The external-secrets project is released on a as-needed basis. Feel free to open a issue to request a release. Details on how to cut a release can be found in the RELEASE.md file in the repo.","title":"Contributing Process"},{"location":"contributing-process/#project-management","text":"The Code, our TODOs and Documentation is maintained on GitHub . All Issues should be opened in that repository.","title":"Project Management"},{"location":"contributing-process/#issues","text":"Features, bugs and any issues regarding the documentation should be filed as GitHub Issue in our repository. We use labels like kind/feature , kind/bug , area/aws to organize the issues. Issues labeled good first issue and help wanted are especially good for a first contribution. If you want to pick up an issue just leave a comment.","title":"Issues"},{"location":"contributing-process/#submitting-a-pull-request","text":"This project uses the well-known pull request process from GitHub. To submit a pull request, fork the repository and push any changes to a branch on the copy, from there a pull request can be made in the main repo. Merging a pull request requires the following steps to be completed before the pull request will be merged: ideally, there is an issue that documents the problem or feature in depth. code must have a reasonable amount of test coverage tests must pass PR needs be reviewed and approved Once these steps are completed the PR will be merged by a code owner. We're using the pull request assignee feature to track who is responsible for the lifecycle of the PR: review, merging, ping on inactivity, close. We close pull requests or issues if there is no response from the author for a period of time. Feel free to reopen if you want to get back on it.","title":"Submitting a Pull Request"},{"location":"contributing-process/#proposal-process","text":"Before we introduce significant changes to the project we want to gather feedback from the community to ensure that we progress in the right direction before we develop and release big changes. Significant changes include for example: * creating new custom resources * proposing breaking changes * changing the behavior of the controller significantly Please create a document in the design/ directory based on the template 000-template.md and fill in your proposal. Open a pull request in draft mode and request feedback. Once the proposal is accepted and the pull request is merged we can create work packages and proceed with the implementation.","title":"Proposal Process"},{"location":"contributing-process/#cutting-releases","text":"The external-secrets project is released on a as-needed basis. Feel free to open a issue to request a release. Details on how to cut a release can be found in the RELEASE.md file in the repo.","title":"Cutting Releases"},{"location":"deprecation-policy/","text":"Deprecation Policy We follow the Kubernetes Deprecation Policy and API Versioning Scheme : alpha, beta, GA. The project is currently in alpha state. We track beta progress in this GitHub Project . Please try the alpha and beta features and provide feedback. After the features exit beta, it may not be practical to make more changes. alpha The support for a feature may be dropped at any time without notice. The API may change in incompatible ways in a later software release without notice. The software is recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support. beta The software is well tested. Enabling a feature is considered safe. Features are enabled by default. The support for a feature will not be dropped, though the details may change. The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens, migration instructions are provided. Schema changes may require deleting, editing, and re-creating API objects. The editing process may not be straightforward. The migration may require downtime for applications that rely on the feature. The software is not recommended for production uses. Subsequent releases may introduce incompatible changes. If you have multiple clusters which can be upgraded independently, you may be able to relax this restriction. GA The stable versions of features appear in released software for many subsequent versions. Use it in production ;) API Surface We define the following scope that is covered by our deprecation policy. We follow the 9 Rules of the Kuberenetes Deprecation Policy . Scope API Objects and fields: .Spec , .Status and .Status.Conditions[] Enums and constant values Controller Configuration: CLI flags & environment variables Metrics as defined in the Kubernetes docs a feature or specific behavior: ExternalSecret update mechanics Non-Scope We do not provide stability guarantee for source code imports . The Interfaces and the behavior will change in a unexpected and backwards-incompatible way. However, The maintained helm chart is not part of this deprecation policy.","title":"Deprecation Policy"},{"location":"deprecation-policy/#deprecation-policy","text":"We follow the Kubernetes Deprecation Policy and API Versioning Scheme : alpha, beta, GA. The project is currently in alpha state. We track beta progress in this GitHub Project . Please try the alpha and beta features and provide feedback. After the features exit beta, it may not be practical to make more changes. alpha The support for a feature may be dropped at any time without notice. The API may change in incompatible ways in a later software release without notice. The software is recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support. beta The software is well tested. Enabling a feature is considered safe. Features are enabled by default. The support for a feature will not be dropped, though the details may change. The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens, migration instructions are provided. Schema changes may require deleting, editing, and re-creating API objects. The editing process may not be straightforward. The migration may require downtime for applications that rely on the feature. The software is not recommended for production uses. Subsequent releases may introduce incompatible changes. If you have multiple clusters which can be upgraded independently, you may be able to relax this restriction. GA The stable versions of features appear in released software for many subsequent versions. Use it in production ;)","title":"Deprecation Policy"},{"location":"deprecation-policy/#api-surface","text":"We define the following scope that is covered by our deprecation policy. We follow the 9 Rules of the Kuberenetes Deprecation Policy .","title":"API Surface"},{"location":"deprecation-policy/#scope","text":"API Objects and fields: .Spec , .Status and .Status.Conditions[] Enums and constant values Controller Configuration: CLI flags & environment variables Metrics as defined in the Kubernetes docs a feature or specific behavior: ExternalSecret update mechanics","title":"Scope"},{"location":"deprecation-policy/#non-scope","text":"We do not provide stability guarantee for source code imports . The Interfaces and the behavior will change in a unexpected and backwards-incompatible way. However, The maintained helm chart is not part of this deprecation policy.","title":"Non-Scope"},{"location":"guides-all-keys-one-secret/","text":"All Keys, One Secret To get multiple key-values from an external secret, not having to worry about how many, or what these keys are, we have to use the dataFrom field of the ExternalSecret resource, instead of the data field. We will give an example here with the gcp provider (should work with other providers in the same way). Please follow the authentication and SecretStore steps of the Google Cloud Secrets Manager guide to setup access to your google cloud account first. Then create a secret in Google Cloud Secret Manager that contains a JSON string with multiple key values like this: Let's call this secret all-keys-example-secret on Google Cloud. Creating dataFrom external secret Now, when creating our ExternalSecret resource, instead of using the data field, we use the dataFrom field: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 1h # rate SecretManager pulls GCPSM secretStoreRef : kind : SecretStore name : example # name of the SecretStore (or kind specified) target : name : secret-to-be-created # name of the k8s Secret to be created creationPolicy : Owner dataFrom : - key : all-keys-example-secret # name of the GCPSM secret To check both values we can run: kubectl get secret secret-to-be-created -n <namespace> -o jsonpath='{.data.username}' | base64 -d kubectl get secret secret-to-be-created -n <namespace> -o jsonpath='{.data.surname}' | base64 -d","title":"All keys, One secret"},{"location":"guides-all-keys-one-secret/#all-keys-one-secret","text":"To get multiple key-values from an external secret, not having to worry about how many, or what these keys are, we have to use the dataFrom field of the ExternalSecret resource, instead of the data field. We will give an example here with the gcp provider (should work with other providers in the same way). Please follow the authentication and SecretStore steps of the Google Cloud Secrets Manager guide to setup access to your google cloud account first. Then create a secret in Google Cloud Secret Manager that contains a JSON string with multiple key values like this: Let's call this secret all-keys-example-secret on Google Cloud.","title":"All Keys, One Secret"},{"location":"guides-all-keys-one-secret/#creating-datafrom-external-secret","text":"Now, when creating our ExternalSecret resource, instead of using the data field, we use the dataFrom field: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 1h # rate SecretManager pulls GCPSM secretStoreRef : kind : SecretStore name : example # name of the SecretStore (or kind specified) target : name : secret-to-be-created # name of the k8s Secret to be created creationPolicy : Owner dataFrom : - key : all-keys-example-secret # name of the GCPSM secret To check both values we can run: kubectl get secret secret-to-be-created -n <namespace> -o jsonpath='{.data.username}' | base64 -d kubectl get secret secret-to-be-created -n <namespace> -o jsonpath='{.data.surname}' | base64 -d","title":"Creating dataFrom external secret"},{"location":"guides-common-k8s-secret-types/","text":"A few common k8s secret types examples Here we will give some examples of how to work with a few common k8s secret types. We will give this examples here with the gcp provider (should work with other providers in the same way). Please also check the guides on Advanced Templating to understand the details. Please follow the authentication and SecretStore steps of the Google Cloud Secrets Manager guide to setup access to your google cloud account first. Dockerconfigjson example First create a secret in Google Cloud Secrets Manager containing your docker config: Let's call this secret docker-config-example on Google Cloud. Then create a ExternalSecret resource taking advantage of templating to populate the generated secret: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : dk-cfg-example spec : refreshInterval : 1h secretStoreRef : name : example kind : SecretStore target : name : secret-to-be-created template : type : kubernetes.io/dockerconfigjson data : .dockerconfigjson : \"{{ .mysecret | toString }}\" name : secret-to-be-created creationPolicy : Owner data : - secretKey : mysecret remoteRef : key : docker-config-example This will generate a valid dockerconfigjson secret for you to use! You can get the final value with: kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath = \"{.data\\.dockerconfigjson}\" | base64 -d TLS Cert example We are assuming here that you already have valid certificates, maybe generated with letsencrypt or any other CA. So to simplify you can use openssl to generate a single secret pkcs12 cert based on your cert.pem and privkey.pen files. openssl pkcs12 -export -out certificate.p12 -inkey privkey.pem -in cert.pem With a certificate.p12 you can upload it to Google Cloud Secrets Manager: And now you can create an ExternalSecret that gets it. You will end up with a k8s secret of type tls with pem values. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : template-tls-example spec : refreshInterval : 1h secretStoreRef : name : example kind : SecretStore target : name : secret-to-be-created # this is how the Kind=Secret will look like template : type : kubernetes.io/tls data : tls.crt : \"{{ .mysecret | pkcs12cert | pemCertificate }}\" tls.key : \"{{ .mysecret | pkcs12key | pemPrivateKey }}\" data : # this is a pkcs12 archive that contains # a cert and a private key - secretKey : mysecret remoteRef : key : ssl-certificate-p12-example You can get their values with: kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath = \"{.data.tls\\.crt}\" | base64 -d kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath = \"{.data.tls\\.key}\" | base64 -d SSH Auth example Add the ssh privkey to a new Google Cloud Secrets Manager secret: And now you can create an ExternalSecret that gets it. You will end up with a k8s secret of type ssh-auth with the privatekey value. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : ssh-auth-example spec : refreshInterval : 1h secretStoreRef : name : example kind : SecretStore target : name : secret-to-be-created template : type : kubernetes.io/ssh-auth data : ssh-privatekey : \"{{ .mysecret | toString }}\" name : secret-to-be-created creationPolicy : Owner data : - secretKey : mysecret remoteRef : key : ssh-priv-key-example You can get the privkey value with: kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath = \"{.data.ssh-privatekey}\" | base64 -d More examples We need more examples here Feel free to contribute with our docs and add more examples here!","title":"Common K8S Secret Types"},{"location":"guides-common-k8s-secret-types/#a-few-common-k8s-secret-types-examples","text":"Here we will give some examples of how to work with a few common k8s secret types. We will give this examples here with the gcp provider (should work with other providers in the same way). Please also check the guides on Advanced Templating to understand the details. Please follow the authentication and SecretStore steps of the Google Cloud Secrets Manager guide to setup access to your google cloud account first.","title":"A few common k8s secret types examples"},{"location":"guides-common-k8s-secret-types/#dockerconfigjson-example","text":"First create a secret in Google Cloud Secrets Manager containing your docker config: Let's call this secret docker-config-example on Google Cloud. Then create a ExternalSecret resource taking advantage of templating to populate the generated secret: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : dk-cfg-example spec : refreshInterval : 1h secretStoreRef : name : example kind : SecretStore target : name : secret-to-be-created template : type : kubernetes.io/dockerconfigjson data : .dockerconfigjson : \"{{ .mysecret | toString }}\" name : secret-to-be-created creationPolicy : Owner data : - secretKey : mysecret remoteRef : key : docker-config-example This will generate a valid dockerconfigjson secret for you to use! You can get the final value with: kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath = \"{.data\\.dockerconfigjson}\" | base64 -d","title":"Dockerconfigjson example"},{"location":"guides-common-k8s-secret-types/#tls-cert-example","text":"We are assuming here that you already have valid certificates, maybe generated with letsencrypt or any other CA. So to simplify you can use openssl to generate a single secret pkcs12 cert based on your cert.pem and privkey.pen files. openssl pkcs12 -export -out certificate.p12 -inkey privkey.pem -in cert.pem With a certificate.p12 you can upload it to Google Cloud Secrets Manager: And now you can create an ExternalSecret that gets it. You will end up with a k8s secret of type tls with pem values. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : template-tls-example spec : refreshInterval : 1h secretStoreRef : name : example kind : SecretStore target : name : secret-to-be-created # this is how the Kind=Secret will look like template : type : kubernetes.io/tls data : tls.crt : \"{{ .mysecret | pkcs12cert | pemCertificate }}\" tls.key : \"{{ .mysecret | pkcs12key | pemPrivateKey }}\" data : # this is a pkcs12 archive that contains # a cert and a private key - secretKey : mysecret remoteRef : key : ssl-certificate-p12-example You can get their values with: kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath = \"{.data.tls\\.crt}\" | base64 -d kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath = \"{.data.tls\\.key}\" | base64 -d","title":"TLS Cert example"},{"location":"guides-common-k8s-secret-types/#ssh-auth-example","text":"Add the ssh privkey to a new Google Cloud Secrets Manager secret: And now you can create an ExternalSecret that gets it. You will end up with a k8s secret of type ssh-auth with the privatekey value. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : ssh-auth-example spec : refreshInterval : 1h secretStoreRef : name : example kind : SecretStore target : name : secret-to-be-created template : type : kubernetes.io/ssh-auth data : ssh-privatekey : \"{{ .mysecret | toString }}\" name : secret-to-be-created creationPolicy : Owner data : - secretKey : mysecret remoteRef : key : ssh-priv-key-example You can get the privkey value with: kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath = \"{.data.ssh-privatekey}\" | base64 -d","title":"SSH Auth example"},{"location":"guides-common-k8s-secret-types/#more-examples","text":"We need more examples here Feel free to contribute with our docs and add more examples here!","title":"More examples"},{"location":"guides-controller-class/","text":"Controller Classes NOTE: this feature is experimental and not highly tested Controller classes are a proprierty set during the deployment that allows multiple controllers to work in a group of workloard. It works by separating which secretStores are going to be attributed to which controller. For the behavior of a single controller, no extra configuration is needed. Setting up Controller Class In order to deploy the controller with a specific class, install the helm charts specifying the controller class, and create a SecretStore with the appropriate spec.controller values: helm install custom-external-secrets external-secrets/external-secrets --set controllerClass=custom apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : controller-custom-example spec : #define the controller label to the matching value of the deployment controller : custom #configure provider the same way provider : vault : server : \"http://vault.default:8200\" path : \"secret\" version : \"v2\" auth : kubernetes : mountPath : \"kubernetes\" role : \"demo-role\" Now, any ExternalSecret bound to this secret store will be evaluated by the operator with the controllerClass custom. Note: Any SecretStore without spec.controller set will be considered as valid by any operator, regardless of their respective controllerClasses.","title":"Controller Classes"},{"location":"guides-controller-class/#controller-classes","text":"NOTE: this feature is experimental and not highly tested Controller classes are a proprierty set during the deployment that allows multiple controllers to work in a group of workloard. It works by separating which secretStores are going to be attributed to which controller. For the behavior of a single controller, no extra configuration is needed.","title":"Controller Classes"},{"location":"guides-controller-class/#setting-up-controller-class","text":"In order to deploy the controller with a specific class, install the helm charts specifying the controller class, and create a SecretStore with the appropriate spec.controller values: helm install custom-external-secrets external-secrets/external-secrets --set controllerClass=custom apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : controller-custom-example spec : #define the controller label to the matching value of the deployment controller : custom #configure provider the same way provider : vault : server : \"http://vault.default:8200\" path : \"secret\" version : \"v2\" auth : kubernetes : mountPath : \"kubernetes\" role : \"demo-role\" Now, any ExternalSecret bound to this secret store will be evaluated by the operator with the controllerClass custom. Note: Any SecretStore without spec.controller set will be considered as valid by any operator, regardless of their respective controllerClasses.","title":"Setting up Controller Class"},{"location":"guides-getting-started/","text":"Getting started External-secrets runs within your Kubernetes cluster as a deployment resource. It utilizes CustomResourceDefinitions to configure access to secret providers through SecretStore resources and manages Kubernetes secret resources with ExternalSecret resources. Note: The minimum supported version of Kubernetes is 1.16.0 . Users still running Kubernetes v1.15 or below should upgrade to a supported version before installing external-secrets. Installing with Helm To automatically install and manage the CRDs as part of your Helm release, you must add the --set installCRDs=true flag to your Helm installation command. Uncomment the relevant line in the next steps to enable this. Option 1: Install from chart repository helm repo add external-secrets https://charts.external-secrets.io helm install external-secrets \\ external-secrets/external-secrets \\ -n external-secrets \\ --create-namespace \\ # --set installCRDs=true Option 2: Install chart from local build Build and install the Helm chart locally after cloning the repository. make helm.build helm install external-secrets \\ ./bin/chart/external-secrets.tgz \\ -n external-secrets \\ --create-namespace \\ # --set installCRDs=true Create a secret containing your AWS credentials echo -n 'KEYID' > ./access-key echo -n 'SECRETKEY' > ./secret-access-key kubectl create secret generic awssm-secret --from-file = ./access-key --from-file = ./secret-access-key Create your first SecretStore apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager region : us-east-1 auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key Create your first ExternalSecret apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 1h secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created creationPolicy : Owner data : - secretKey : secret-key-to-be-managed remoteRef : key : provider-key version : provider-key-version property : provider-key-property dataFrom : - key : remote-key-in-the-provider kubectl describe externalsecret example # [...] Name: example Status: Conditions: Last Transition Time: 2021 -02-24T16:45:23Z Message: Secret was synced Reason: SecretSynced Status: True Type: Ready Refresh Time: 2021 -02-24T16:45:24Z Events: <none> For more advanced examples, please read the other guides . Installing with OLM External-secrets can be managed by Operator Lifecycle Manager (OLM) via an installer operator. It is made available through OperatorHub.io , this installation method is suited best for OpenShift. See installation instructions on the external-secrets-operator package. Uninstalling Before continuing, ensure that all external-secret resources that have been created by users have been deleted. You can check for any existing resources with the following command: kubectl get SecretStores,ClusterSecretStores,ExternalSecrets --all-namespaces Once all these resources have been deleted you are ready to uninstall external-secrets. Uninstalling with Helm Uninstall the helm release using the delete command. helm delete external-secrets --namespace external-secrets","title":"Getting started"},{"location":"guides-getting-started/#getting-started","text":"External-secrets runs within your Kubernetes cluster as a deployment resource. It utilizes CustomResourceDefinitions to configure access to secret providers through SecretStore resources and manages Kubernetes secret resources with ExternalSecret resources. Note: The minimum supported version of Kubernetes is 1.16.0 . Users still running Kubernetes v1.15 or below should upgrade to a supported version before installing external-secrets.","title":"Getting started"},{"location":"guides-getting-started/#installing-with-helm","text":"To automatically install and manage the CRDs as part of your Helm release, you must add the --set installCRDs=true flag to your Helm installation command. Uncomment the relevant line in the next steps to enable this.","title":"Installing with Helm"},{"location":"guides-getting-started/#option-1-install-from-chart-repository","text":"helm repo add external-secrets https://charts.external-secrets.io helm install external-secrets \\ external-secrets/external-secrets \\ -n external-secrets \\ --create-namespace \\ # --set installCRDs=true","title":"Option 1: Install from chart repository"},{"location":"guides-getting-started/#option-2-install-chart-from-local-build","text":"Build and install the Helm chart locally after cloning the repository. make helm.build helm install external-secrets \\ ./bin/chart/external-secrets.tgz \\ -n external-secrets \\ --create-namespace \\ # --set installCRDs=true","title":"Option 2: Install chart from local build"},{"location":"guides-getting-started/#create-a-secret-containing-your-aws-credentials","text":"echo -n 'KEYID' > ./access-key echo -n 'SECRETKEY' > ./secret-access-key kubectl create secret generic awssm-secret --from-file = ./access-key --from-file = ./secret-access-key","title":"Create a secret containing your AWS credentials"},{"location":"guides-getting-started/#create-your-first-secretstore","text":"apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager region : us-east-1 auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key","title":"Create your first SecretStore"},{"location":"guides-getting-started/#create-your-first-externalsecret","text":"apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 1h secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created creationPolicy : Owner data : - secretKey : secret-key-to-be-managed remoteRef : key : provider-key version : provider-key-version property : provider-key-property dataFrom : - key : remote-key-in-the-provider kubectl describe externalsecret example # [...] Name: example Status: Conditions: Last Transition Time: 2021 -02-24T16:45:23Z Message: Secret was synced Reason: SecretSynced Status: True Type: Ready Refresh Time: 2021 -02-24T16:45:24Z Events: <none> For more advanced examples, please read the other guides .","title":"Create your first ExternalSecret"},{"location":"guides-getting-started/#installing-with-olm","text":"External-secrets can be managed by Operator Lifecycle Manager (OLM) via an installer operator. It is made available through OperatorHub.io , this installation method is suited best for OpenShift. See installation instructions on the external-secrets-operator package.","title":"Installing with OLM"},{"location":"guides-getting-started/#uninstalling","text":"Before continuing, ensure that all external-secret resources that have been created by users have been deleted. You can check for any existing resources with the following command: kubectl get SecretStores,ClusterSecretStores,ExternalSecrets --all-namespaces Once all these resources have been deleted you are ready to uninstall external-secrets.","title":"Uninstalling"},{"location":"guides-getting-started/#uninstalling-with-helm","text":"Uninstall the helm release using the delete command. helm delete external-secrets --namespace external-secrets","title":"Uninstalling with Helm"},{"location":"guides-gitops-using-fluxcd/","text":"GitOps using FluxCD (v2) FluxCD is a GitOps operator for Kubernetes. It synchronizes the status of the cluster from manifests allocated in different repositories (Git or Helm). This approach fits perfectly with External Secrets on clusters which are dynamically created, to get credentials with no manual intervention from the beginning. Advantages This approach has several advantages as follows: Homogenize environments allowing developers to use the same toolset in Kind in the same way they do in the cloud provider distributions such as EKS or GKE. This accelerates the development Reduce security risks , because credentials can be easily obtained, so temptation to store them locally is reduced. Application compatibility increase : Applications are deployed in different ways, and sometimes they need to share credentials. This can be done using External Secrets as a wire for them at real time. Automation by default oh, come on! The approach FluxCD is composed by several controllers dedicated to manage different custom resources. The most important ones are Kustomization (to clarify, Flux one, not Kubernetes' one) and HelmRelease to deploy using the approaches of the same names. External Secrets can be deployed using Helm as explained here . The deployment includes the CRDs if enabled on the values.yaml , but after this, you need to deploy some SecretStore to start getting credentials from your secrets manager with External Secrets. The idea of this guide is to deploy the whole stack, using flux, needed by developers not to worry about the credentials, but only about the application and its code. The problem This can sound easy, but External Secrets is deployed using Helm, which is managed by the HelmController, and your custom resources, for example a ClusterSecretStore and the related Secret , are often deployed using a kustomization.yaml , which is deployed by the KustomizeController. Both controllers manage the resources independently, at different moments, with no possibility to wait each other. This means that we have a wonderful race condition where sometimes the CRs ( SecretStore , ClusterSecretStore ...) tries to be deployed before than the CRDs needed to recognize them. The solution Let's see the conditions to start working on a solution: The External Secrets operator is deployed with Helm, and admits disabling the CRDs deployment The race condition only affects the deployment of CustomResourceDefinition and the CRs needed later CRDs can be deployed directly from the Git repository of the project using a Flux Kustomization Required CRs can be deployed using a Flux Kustomization too, allowing dependency between CRDs and CRs All previous manifests can be applied with a Kubernetes kustomization Create the main kustomization To have a better view of things needed later, the first manifest to be created is the kustomization.yaml apiVersion : kustomize.config.k8s.io/v1beta1 kind : Kustomization resources : # Deploy the Vault access secret - namespace.yaml - secret-token.yaml # Deploy the repositories - repositories.yaml # Deploy the CRDs - deployment-crds.yaml # Deploy the operator - deployment.yaml # Deploy default Custom Resources from 'crs' directory # INFO: This depends on the CRDs deployment. Will happen after it - deployment-crs.yaml Create the secret To access your secret manager, External Secrets needs some credentials. They are stored inside a Secret, which is intended to be deployed by automation as a good practise. This time, a placeholder called secret-token.yaml is show as an example: # The namespace.yaml first apiVersion : v1 kind : Namespace metadata : name : external-secrets apiVersion : v1 kind : Secret metadata : name : vault-token-global namespace : external-secrets stringData : # This token must be patched by overlays. Not here for security reasons token : change-me-placeholder Creating the references to repositories Create a manifest called repositories.yaml to store the references to external repositories for Flux # Reference to Helm repository apiVersion : source.toolkit.fluxcd.io/v1beta1 kind : HelmRepository metadata : name : external-secrets namespace : flux-system spec : interval : 10m url : https://charts.external-secrets.io --- apiVersion : source.toolkit.fluxcd.io/v1beta1 kind : GitRepository metadata : name : external-secrets namespace : flux-system spec : interval : 10m ref : branch : main url : http://github.com/external-secrets/external-secrets Deploy the CRDs As mentioned, CRDs can be deployed using the official Helm package, but to solve the race condition, they will be deployed from our git repository using a Kustomization manifest called deployment-crds.yaml as follows: --- apiVersion : kustomize.toolkit.fluxcd.io/v1beta2 kind : Kustomization metadata : name : external-secrets-crds namespace : flux-system spec : interval : 10m path : ./deploy/crds prune : true sourceRef : kind : GitRepository name : external-secrets Deploy the operator The operator is deployed using a HelmRelease manifest to deploy the Helm package, but due to the special race condition, the deployment must be disabled in the values of the manifest called deployment.yaml , as follows: # How to manage values files. Ref: https://fluxcd.io/docs/guides/helmreleases/#refer-to-values-inside-the-chart # How to inject values: https://fluxcd.io/docs/guides/helmreleases/#cloud-storage --- apiVersion : helm.toolkit.fluxcd.io/v2beta1 kind : HelmRelease metadata : name : external-secrets namespace : flux-system spec : # Override Release name to avoid the pattern Namespace-Release # Ref: https://fluxcd.io/docs/components/helm/api/#helm.toolkit.fluxcd.io/v2beta1.HelmRelease releaseName : external-secrets targetNamespace : external-secrets interval : 10m chart : spec : chart : external-secrets version : 0.3.9 sourceRef : kind : HelmRepository name : external-secrets namespace : flux-system values : installCRDs : false # Ref: https://fluxcd.io/docs/components/helm/api/#helm.toolkit.fluxcd.io/v2beta1.Install install : createNamespace : true Deploy the CRs Now, be ready for the arcane magic. Create a Kustomization manifest called deployment-crs.yaml with the following content: --- apiVersion : kustomize.toolkit.fluxcd.io/v1beta2 kind : Kustomization metadata : name : external-secrets-crs namespace : flux-system spec : dependsOn : - name : external-secrets-crds interval : 10m path : ./infrastructure/external-secrets/crs prune : true sourceRef : kind : GitRepository name : flux-system There are several interesting details to see here, that finally solves the race condition: First one is the field dependsOn , which points to a previous Kustomization called external-secrets-crds . This dependency forces this deployment to wait for the other to be ready, before start being deployed. The reference to the place where to find the CRs path : ./infrastructure/external-secrets/crs sourceRef : kind : GitRepository name : flux-system Custom Resources will be searched in the relative path ./infrastructure/external-secrets/crs of the GitRepository called flux-system , which is a reference to the same repository that FluxCD watches to synchronize the cluster. With fewer words, a reference to itself, but going to another directory called crs Of course, allocate inside the mentioned path ./infrastructure/external-secrets/crs , all the desired CRs to be deployed, for example, a manifest clusterSecretStore.yaml to reach your Hashicorp Vault as follows: apiVersion : external-secrets.io/v1alpha1 kind : ClusterSecretStore metadata : name : vault-backend-global spec : provider : vault : server : \"https://vault.your-domain.com\" path : secret version : v2 auth : # points to a secret that contains a vault token # https://www.vaultproject.io/docs/auth/token tokenSecretRef : name : \"vault-token-global\" key : \"token\" namespace : external-secrets Results At the end, the required files tree is shown in the following picture:","title":"GitOps using FluxCD"},{"location":"guides-gitops-using-fluxcd/#gitops-using-fluxcd-v2","text":"FluxCD is a GitOps operator for Kubernetes. It synchronizes the status of the cluster from manifests allocated in different repositories (Git or Helm). This approach fits perfectly with External Secrets on clusters which are dynamically created, to get credentials with no manual intervention from the beginning.","title":"GitOps using FluxCD (v2)"},{"location":"guides-gitops-using-fluxcd/#advantages","text":"This approach has several advantages as follows: Homogenize environments allowing developers to use the same toolset in Kind in the same way they do in the cloud provider distributions such as EKS or GKE. This accelerates the development Reduce security risks , because credentials can be easily obtained, so temptation to store them locally is reduced. Application compatibility increase : Applications are deployed in different ways, and sometimes they need to share credentials. This can be done using External Secrets as a wire for them at real time. Automation by default oh, come on!","title":"Advantages"},{"location":"guides-gitops-using-fluxcd/#the-approach","text":"FluxCD is composed by several controllers dedicated to manage different custom resources. The most important ones are Kustomization (to clarify, Flux one, not Kubernetes' one) and HelmRelease to deploy using the approaches of the same names. External Secrets can be deployed using Helm as explained here . The deployment includes the CRDs if enabled on the values.yaml , but after this, you need to deploy some SecretStore to start getting credentials from your secrets manager with External Secrets. The idea of this guide is to deploy the whole stack, using flux, needed by developers not to worry about the credentials, but only about the application and its code.","title":"The approach"},{"location":"guides-gitops-using-fluxcd/#the-problem","text":"This can sound easy, but External Secrets is deployed using Helm, which is managed by the HelmController, and your custom resources, for example a ClusterSecretStore and the related Secret , are often deployed using a kustomization.yaml , which is deployed by the KustomizeController. Both controllers manage the resources independently, at different moments, with no possibility to wait each other. This means that we have a wonderful race condition where sometimes the CRs ( SecretStore , ClusterSecretStore ...) tries to be deployed before than the CRDs needed to recognize them.","title":"The problem"},{"location":"guides-gitops-using-fluxcd/#the-solution","text":"Let's see the conditions to start working on a solution: The External Secrets operator is deployed with Helm, and admits disabling the CRDs deployment The race condition only affects the deployment of CustomResourceDefinition and the CRs needed later CRDs can be deployed directly from the Git repository of the project using a Flux Kustomization Required CRs can be deployed using a Flux Kustomization too, allowing dependency between CRDs and CRs All previous manifests can be applied with a Kubernetes kustomization","title":"The solution"},{"location":"guides-gitops-using-fluxcd/#create-the-main-kustomization","text":"To have a better view of things needed later, the first manifest to be created is the kustomization.yaml apiVersion : kustomize.config.k8s.io/v1beta1 kind : Kustomization resources : # Deploy the Vault access secret - namespace.yaml - secret-token.yaml # Deploy the repositories - repositories.yaml # Deploy the CRDs - deployment-crds.yaml # Deploy the operator - deployment.yaml # Deploy default Custom Resources from 'crs' directory # INFO: This depends on the CRDs deployment. Will happen after it - deployment-crs.yaml","title":"Create the main kustomization"},{"location":"guides-gitops-using-fluxcd/#create-the-secret","text":"To access your secret manager, External Secrets needs some credentials. They are stored inside a Secret, which is intended to be deployed by automation as a good practise. This time, a placeholder called secret-token.yaml is show as an example: # The namespace.yaml first apiVersion : v1 kind : Namespace metadata : name : external-secrets apiVersion : v1 kind : Secret metadata : name : vault-token-global namespace : external-secrets stringData : # This token must be patched by overlays. Not here for security reasons token : change-me-placeholder","title":"Create the secret"},{"location":"guides-gitops-using-fluxcd/#creating-the-references-to-repositories","text":"Create a manifest called repositories.yaml to store the references to external repositories for Flux # Reference to Helm repository apiVersion : source.toolkit.fluxcd.io/v1beta1 kind : HelmRepository metadata : name : external-secrets namespace : flux-system spec : interval : 10m url : https://charts.external-secrets.io --- apiVersion : source.toolkit.fluxcd.io/v1beta1 kind : GitRepository metadata : name : external-secrets namespace : flux-system spec : interval : 10m ref : branch : main url : http://github.com/external-secrets/external-secrets","title":"Creating the references to repositories"},{"location":"guides-gitops-using-fluxcd/#deploy-the-crds","text":"As mentioned, CRDs can be deployed using the official Helm package, but to solve the race condition, they will be deployed from our git repository using a Kustomization manifest called deployment-crds.yaml as follows: --- apiVersion : kustomize.toolkit.fluxcd.io/v1beta2 kind : Kustomization metadata : name : external-secrets-crds namespace : flux-system spec : interval : 10m path : ./deploy/crds prune : true sourceRef : kind : GitRepository name : external-secrets","title":"Deploy the CRDs"},{"location":"guides-gitops-using-fluxcd/#deploy-the-operator","text":"The operator is deployed using a HelmRelease manifest to deploy the Helm package, but due to the special race condition, the deployment must be disabled in the values of the manifest called deployment.yaml , as follows: # How to manage values files. Ref: https://fluxcd.io/docs/guides/helmreleases/#refer-to-values-inside-the-chart # How to inject values: https://fluxcd.io/docs/guides/helmreleases/#cloud-storage --- apiVersion : helm.toolkit.fluxcd.io/v2beta1 kind : HelmRelease metadata : name : external-secrets namespace : flux-system spec : # Override Release name to avoid the pattern Namespace-Release # Ref: https://fluxcd.io/docs/components/helm/api/#helm.toolkit.fluxcd.io/v2beta1.HelmRelease releaseName : external-secrets targetNamespace : external-secrets interval : 10m chart : spec : chart : external-secrets version : 0.3.9 sourceRef : kind : HelmRepository name : external-secrets namespace : flux-system values : installCRDs : false # Ref: https://fluxcd.io/docs/components/helm/api/#helm.toolkit.fluxcd.io/v2beta1.Install install : createNamespace : true","title":"Deploy the operator"},{"location":"guides-gitops-using-fluxcd/#deploy-the-crs","text":"Now, be ready for the arcane magic. Create a Kustomization manifest called deployment-crs.yaml with the following content: --- apiVersion : kustomize.toolkit.fluxcd.io/v1beta2 kind : Kustomization metadata : name : external-secrets-crs namespace : flux-system spec : dependsOn : - name : external-secrets-crds interval : 10m path : ./infrastructure/external-secrets/crs prune : true sourceRef : kind : GitRepository name : flux-system There are several interesting details to see here, that finally solves the race condition: First one is the field dependsOn , which points to a previous Kustomization called external-secrets-crds . This dependency forces this deployment to wait for the other to be ready, before start being deployed. The reference to the place where to find the CRs path : ./infrastructure/external-secrets/crs sourceRef : kind : GitRepository name : flux-system Custom Resources will be searched in the relative path ./infrastructure/external-secrets/crs of the GitRepository called flux-system , which is a reference to the same repository that FluxCD watches to synchronize the cluster. With fewer words, a reference to itself, but going to another directory called crs Of course, allocate inside the mentioned path ./infrastructure/external-secrets/crs , all the desired CRs to be deployed, for example, a manifest clusterSecretStore.yaml to reach your Hashicorp Vault as follows: apiVersion : external-secrets.io/v1alpha1 kind : ClusterSecretStore metadata : name : vault-backend-global spec : provider : vault : server : \"https://vault.your-domain.com\" path : secret version : v2 auth : # points to a secret that contains a vault token # https://www.vaultproject.io/docs/auth/token tokenSecretRef : name : \"vault-token-global\" key : \"token\" namespace : external-secrets","title":"Deploy the CRs"},{"location":"guides-gitops-using-fluxcd/#results","text":"At the end, the required files tree is shown in the following picture:","title":"Results"},{"location":"guides-introduction/","text":"Guides The following guides demonstrate use-cases and provide examples of how to use the API. Please pick one of the following guides: Getting started Advanced Templating Multi-Tenancy Design Considerations","title":"Introduction"},{"location":"guides-introduction/#guides","text":"The following guides demonstrate use-cases and provide examples of how to use the API. Please pick one of the following guides: Getting started Advanced Templating Multi-Tenancy Design Considerations","title":"Guides"},{"location":"guides-metrics/","text":"Metrics The External Secrets Operator exposes its Prometheus metrics in the /metrics path. To enable it, set the prometheus.enabled Helm flag to true . The Operator has the metrics inherited from Kubebuilder plus some custom metrics with the external_secret prefix.","title":"Metrics"},{"location":"guides-metrics/#metrics","text":"The External Secrets Operator exposes its Prometheus metrics in the /metrics path. To enable it, set the prometheus.enabled Helm flag to true . The Operator has the metrics inherited from Kubebuilder plus some custom metrics with the external_secret prefix.","title":"Metrics"},{"location":"guides-multi-tenancy/","text":"External Secrets Operator provides different modes of operation to fulfill ogranizational needs. This guide outlines the flexibility of ESO and should give you a first impression of how you can employ this operator in your organization. For a multi-tenant deployment you should first examine your organizational structure: what roles (i.e. Application Developers , Cluster Admins , ...) do you have in your organization, what responsibilities do they have and how does that map to Kubernetes RBAC roles. Further, you should examine how your external API provider manages access control for your secrets. Can you limit access by secret names (e.g. db/dev/* )? Or only on a bucket level? Please keep in mind that not all external APIs provide fine-grained access management for secrets. Note: The following examples should not be considered as best practice but rather as a example to show how to combine different mechanics and techniques for tenant isolation. Shared ClusterSecretStore A Cluster Administrator deploys a ClusterSecretStore (CSS) and manages access to the external API. The CSS is shared by all tenants within the cluster. Application Developers do reference it in a ExternalSecret but can not create a ClusterSecretStores or SecretStores on their own. Now all application developers have access to all the secrets. You probably want to limit access to certain keys or prefixes that should be used. ESO does not provide a mechanic to limit access to certain keys per namespace. More advanced validation should be done with an Admission Webhook, e.g. with Kyverno or Open Policy Agent ). This setup suites well if you have one central bucket that contains all of your secrets and your Cluster Administrators should manage access to it. This setup is very simple but does not scale very well. Managed SecretStore per Namespace Cluster Administrators manage one or multipe SecretStores per Namespace. Each SecretStore uses it's own role that limits access to a small set of keys. The peculiarity of this is approach is, that access is actually managed by the external API which provides the roles. The Cluster Administrator does just the wiring. This approach may be desirable if you have an external entity - let's call it Secret Administrator - that manages access and lifecycle of the secrets. ESO as a Service Every namespace is self-contained. Application developers manage SecretStore , ExternalSecret and secret infrastructure on their own. Cluster Administrators just provide the External Secrets Operator as a service. This makes sense if application developers should be completely autonomous while a central team provides common services.","title":"Multi Tenancy"},{"location":"guides-multi-tenancy/#shared-clustersecretstore","text":"A Cluster Administrator deploys a ClusterSecretStore (CSS) and manages access to the external API. The CSS is shared by all tenants within the cluster. Application Developers do reference it in a ExternalSecret but can not create a ClusterSecretStores or SecretStores on their own. Now all application developers have access to all the secrets. You probably want to limit access to certain keys or prefixes that should be used. ESO does not provide a mechanic to limit access to certain keys per namespace. More advanced validation should be done with an Admission Webhook, e.g. with Kyverno or Open Policy Agent ). This setup suites well if you have one central bucket that contains all of your secrets and your Cluster Administrators should manage access to it. This setup is very simple but does not scale very well.","title":"Shared ClusterSecretStore"},{"location":"guides-multi-tenancy/#managed-secretstore-per-namespace","text":"Cluster Administrators manage one or multipe SecretStores per Namespace. Each SecretStore uses it's own role that limits access to a small set of keys. The peculiarity of this is approach is, that access is actually managed by the external API which provides the roles. The Cluster Administrator does just the wiring. This approach may be desirable if you have an external entity - let's call it Secret Administrator - that manages access and lifecycle of the secrets.","title":"Managed SecretStore per Namespace"},{"location":"guides-multi-tenancy/#eso-as-a-service","text":"Every namespace is self-contained. Application developers manage SecretStore , ExternalSecret and secret infrastructure on their own. Cluster Administrators just provide the External Secrets Operator as a service. This makes sense if application developers should be completely autonomous while a central team provides common services.","title":"ESO as a Service"},{"location":"guides-templating/","text":"With External Secrets Operator you can transform the data from the external secret provider before it is stored as Kind=Secret . You can do this with the Spec.Target.Template . Each data value is interpreted as a golang template . Examples You can use templates to inject your secrets into a configuration file that you mount into your pod: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : template spec : refreshInterval : 1h secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created # this is how the Kind=Secret will look like template : type : kubernetes.io/tls data : # multiline string config : | datasources: - name: Graphite type: graphite access: proxy url: http://localhost:8080 password: \"{{ .password | toString }}\" # <-- convert []byte to string user: \"{{ .user | toString }}\" # <-- convert []byte to string data : - secretKey : user remoteRef : key : /grafana/user - secretKey : password remoteRef : key : /grafana/password You can also use pre-defined functions to extract data from your secrets. Here: extract key/cert from a pkcs12 archive and store it as PEM. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : template spec : refreshInterval : 1h secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created # this is how the Kind=Secret will look like template : type : kubernetes.io/tls data : tls.crt : \"{{ .mysecret | pkcs12cert | pemCertificate }}\" tls.key : \"{{ .mysecret | pkcs12key | pemPrivateKey }}\" data : # this is a pkcs12 archive that contains # a cert and a private key - secretKey : mysecret remoteRef : key : example TemplateFrom You do not have to define your templates inline in an ExternalSecret but you can pull ConfigMaps or other Secrets that contain a template. Consider the following example: # define your template in a config map apiVersion : v1 kind : ConfigMap metadata : name : grafana-config-tpl data : config.yaml : | datasources: - name: Graphite type: graphite access: proxy url: http://localhost:8080 password: \"{{ .password | toString }}\" # <-- convert []byte to string user: \"{{ .user | toString }}\" # <-- convert []byte to string --- apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : my-template-example spec : # ... target : name : secret-to-be-created template : templateFrom : - configMap : # name of the configmap to pull in name : grafana-config-tpl # here you define the keys that should be used as template items : - key : config.yaml data : - secretKey : user remoteRef : key : /grafana/user - secretKey : password remoteRef : key : /grafana/password Helper functions We provide a bunch of convenience functions that help you transform your secrets. A secret value is a []byte . Function Description Input Output pkcs12key extracts the private key from a pkcs12 archive []byte []byte pkcs12keyPass extracts the private key from a pkcs12 archive using the provided password password string , data []byte []byte pkcs12cert extracts the certificate from a pkcs12 archive []byte []byte pkcs12certPass extracts the certificate from a pkcs12 archive using the provided password password string , data []byte []byte pemPrivateKey PEM encodes the provided bytes as private key []byte string pemCertificate PEM encodes the provided bytes as certificate []byte string jwkPublicKeyPem takes an json-serialized JWK as []byte and returns an PEM block of type PUBLIC KEY that contains the public key ( see here ) for details []byte string jwkPrivateKeyPem takes an json-serialized JWK as []byte and returns an PEM block of type PRIVATE KEY that contains the private key in PKCS #8 format ( see here ) for details []byte string base64decode decodes the provided bytes as base64 []byte []byte base64encode encodes the provided bytes as base64 []byte []byte fromJSON parses the bytes as JSON so you can access individual properties []byte interface{} toJSON encodes the provided object as json string interface{} string toString converts bytes to string []byte string toBytes converts string to bytes string []byte upper converts all characters to their upper case string string lower converts all character to their lower case string string","title":"Advanced Templating"},{"location":"guides-templating/#examples","text":"You can use templates to inject your secrets into a configuration file that you mount into your pod: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : template spec : refreshInterval : 1h secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created # this is how the Kind=Secret will look like template : type : kubernetes.io/tls data : # multiline string config : | datasources: - name: Graphite type: graphite access: proxy url: http://localhost:8080 password: \"{{ .password | toString }}\" # <-- convert []byte to string user: \"{{ .user | toString }}\" # <-- convert []byte to string data : - secretKey : user remoteRef : key : /grafana/user - secretKey : password remoteRef : key : /grafana/password You can also use pre-defined functions to extract data from your secrets. Here: extract key/cert from a pkcs12 archive and store it as PEM. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : template spec : refreshInterval : 1h secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created # this is how the Kind=Secret will look like template : type : kubernetes.io/tls data : tls.crt : \"{{ .mysecret | pkcs12cert | pemCertificate }}\" tls.key : \"{{ .mysecret | pkcs12key | pemPrivateKey }}\" data : # this is a pkcs12 archive that contains # a cert and a private key - secretKey : mysecret remoteRef : key : example","title":"Examples"},{"location":"guides-templating/#templatefrom","text":"You do not have to define your templates inline in an ExternalSecret but you can pull ConfigMaps or other Secrets that contain a template. Consider the following example: # define your template in a config map apiVersion : v1 kind : ConfigMap metadata : name : grafana-config-tpl data : config.yaml : | datasources: - name: Graphite type: graphite access: proxy url: http://localhost:8080 password: \"{{ .password | toString }}\" # <-- convert []byte to string user: \"{{ .user | toString }}\" # <-- convert []byte to string --- apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : my-template-example spec : # ... target : name : secret-to-be-created template : templateFrom : - configMap : # name of the configmap to pull in name : grafana-config-tpl # here you define the keys that should be used as template items : - key : config.yaml data : - secretKey : user remoteRef : key : /grafana/user - secretKey : password remoteRef : key : /grafana/password","title":"TemplateFrom"},{"location":"guides-templating/#helper-functions","text":"We provide a bunch of convenience functions that help you transform your secrets. A secret value is a []byte . Function Description Input Output pkcs12key extracts the private key from a pkcs12 archive []byte []byte pkcs12keyPass extracts the private key from a pkcs12 archive using the provided password password string , data []byte []byte pkcs12cert extracts the certificate from a pkcs12 archive []byte []byte pkcs12certPass extracts the certificate from a pkcs12 archive using the provided password password string , data []byte []byte pemPrivateKey PEM encodes the provided bytes as private key []byte string pemCertificate PEM encodes the provided bytes as certificate []byte string jwkPublicKeyPem takes an json-serialized JWK as []byte and returns an PEM block of type PUBLIC KEY that contains the public key ( see here ) for details []byte string jwkPrivateKeyPem takes an json-serialized JWK as []byte and returns an PEM block of type PRIVATE KEY that contains the private key in PKCS #8 format ( see here ) for details []byte string base64decode decodes the provided bytes as base64 []byte []byte base64encode encodes the provided bytes as base64 []byte []byte fromJSON parses the bytes as JSON so you can access individual properties []byte interface{} toJSON encodes the provided object as json string interface{} string toString converts bytes to string []byte string toBytes converts string to bytes string []byte upper converts all characters to their upper case string string lower converts all character to their lower case string string","title":"Helper functions"},{"location":"guides-using-latest-image/","text":"You can test a feature that was not yet released using the following method, use it at your own discretion: Create a values.yaml file with the following content: replicaCount: 1 image: repository: ghcr.io/external-secrets/external-secrets pullPolicy: IfNotPresent # -- The image tag to use. The default is the chart appVersion. tag: \"main\" # -- If set, install and upgrade CRDs through helm chart. installCRDs: false Install the crds make crds.install Install the external-secrets Helm chart indicating the values file created before: helm install external-secrets external-secrets/external-secrets -f values.yaml","title":"Using Latest Image"},{"location":"provider-akeyless/","text":"Akeyless Vault External Secrets Operator integrates with Akeyless API . Authentication The API requires an access-id, access-type and access-Type-param. The supported auth-methods and their params are: accessType accessTypeParam api_key The access key. k8s The k8s configuration name aws_iam - gcp The gcp audience azure_ad azure object id (optional) form more information about Akeyless Authentication Methods Akeless credentials secret Create a secret containing your credentials: apiVersion : v1 kind : Secret metadata : name : akeylss-secret-creds type : Opaque stringData : accessId : \"p-XXXX\" accessType : # k8s/aws_iam/gcp/azure_ad/api_key accessTypeParam : # can be one of the following: k8s-conf-name/gcp-audience/azure-obj-id/access-key Update secret store Be sure the akeyless provider is listed in the Kind=SecretStore and the akeylessGWApiURL is set (def: \"https://api.akeless.io\". apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : akeyless-secret-store spec : provider : akeyless : # URL of your akeyless API akeylessGWApiURL : \"https://api.akeyless.io\" authSecretRef : secretRef : accessID : name : akeylss-secret-creds key : accessId accessType : name : akeylss-secret-creds key : accessType accessTypeParam : name : akeylss-secret-creds key : accessTypeParam Creating external secret To get a secret from Akeyless and secret it on the Kubernetes cluster, a Kind=ExternalSecret is needed. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : akeyless-external-secret-example spec : refreshInterval : 1h secretStoreRef : kind : SecretStore name : akeyless-secret-store # Must match SecretStore on the cluster target : name : akeyless-secret-to-create # Name for the secret to be created on the cluster creationPolicy : Owner data : - secretKey : secretKey # Key given to the secret to be created on the cluster remoteRef : key : secret-name # Full path of the secret on Akeyless Using DataFrom DataFrom can be used to get a secret as a JSON string and attempt to parse it. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : akeyless-external-secret-example-json spec : refreshInterval : 1h secretStoreRef : kind : SecretStore name : akeyless-secret-store # Must match SecretStore on the cluster target : name : akeyless-secret-to-create-json # Name for the secret to be created on the cluster creationPolicy : Owner # for json formatted secrets: each key in the json will be used as the secret key in the SECRET k8s target object dataFrom : - key : secret-name # Full path of the secret on Akeyless Getting the Kubernetes secret The operator will fetch the secret and inject it as a Kind=Secret . kubectl get secret akeyless-secret-to-create -o jsonpath='{.data.secretKey}' | base64 -d kubectl get secret akeyless-secret-to-create-json -o jsonpath='{.data}'","title":"Akeyless"},{"location":"provider-akeyless/#akeyless-vault","text":"External Secrets Operator integrates with Akeyless API .","title":"Akeyless Vault"},{"location":"provider-akeyless/#authentication","text":"The API requires an access-id, access-type and access-Type-param. The supported auth-methods and their params are: accessType accessTypeParam api_key The access key. k8s The k8s configuration name aws_iam - gcp The gcp audience azure_ad azure object id (optional) form more information about Akeyless Authentication Methods","title":"Authentication"},{"location":"provider-akeyless/#akeless-credentials-secret","text":"Create a secret containing your credentials: apiVersion : v1 kind : Secret metadata : name : akeylss-secret-creds type : Opaque stringData : accessId : \"p-XXXX\" accessType : # k8s/aws_iam/gcp/azure_ad/api_key accessTypeParam : # can be one of the following: k8s-conf-name/gcp-audience/azure-obj-id/access-key","title":"Akeless credentials secret"},{"location":"provider-akeyless/#update-secret-store","text":"Be sure the akeyless provider is listed in the Kind=SecretStore and the akeylessGWApiURL is set (def: \"https://api.akeless.io\". apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : akeyless-secret-store spec : provider : akeyless : # URL of your akeyless API akeylessGWApiURL : \"https://api.akeyless.io\" authSecretRef : secretRef : accessID : name : akeylss-secret-creds key : accessId accessType : name : akeylss-secret-creds key : accessType accessTypeParam : name : akeylss-secret-creds key : accessTypeParam","title":"Update secret store"},{"location":"provider-akeyless/#creating-external-secret","text":"To get a secret from Akeyless and secret it on the Kubernetes cluster, a Kind=ExternalSecret is needed. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : akeyless-external-secret-example spec : refreshInterval : 1h secretStoreRef : kind : SecretStore name : akeyless-secret-store # Must match SecretStore on the cluster target : name : akeyless-secret-to-create # Name for the secret to be created on the cluster creationPolicy : Owner data : - secretKey : secretKey # Key given to the secret to be created on the cluster remoteRef : key : secret-name # Full path of the secret on Akeyless","title":"Creating external secret"},{"location":"provider-akeyless/#using-datafrom","text":"DataFrom can be used to get a secret as a JSON string and attempt to parse it. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : akeyless-external-secret-example-json spec : refreshInterval : 1h secretStoreRef : kind : SecretStore name : akeyless-secret-store # Must match SecretStore on the cluster target : name : akeyless-secret-to-create-json # Name for the secret to be created on the cluster creationPolicy : Owner # for json formatted secrets: each key in the json will be used as the secret key in the SECRET k8s target object dataFrom : - key : secret-name # Full path of the secret on Akeyless","title":"Using DataFrom"},{"location":"provider-akeyless/#getting-the-kubernetes-secret","text":"The operator will fetch the secret and inject it as a Kind=Secret . kubectl get secret akeyless-secret-to-create -o jsonpath='{.data.secretKey}' | base64 -d kubectl get secret akeyless-secret-to-create-json -o jsonpath='{.data}'","title":"Getting the Kubernetes secret"},{"location":"provider-aws-parameter-store/","text":"Parameter Store A ParameterStore points to AWS SSM Parameter Store in a certain account within a defined region. You should define Roles that define fine-grained access to individual secrets and pass them to ESO using spec.provider.aws.role . This way users of the SecretStore can only access the secrets necessary. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : ParameterStore # define a specific role to limit access # to certain secrets role : iam-role region : eu-central-1 auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key API Pricing & Throttling The SSM Parameter Store API is charged by throughput and is available in different tiers, see pricing . Please estimate your costs before using ESO. Cost depends on the RefreshInterval of your ExternalSecrets. IAM Policy Create a IAM Policy to pin down access to secrets matching dev-* , for further information see AWS Documentation : { \"Version\" : \"2012-10-17\" , \"Statement\" : [ { \"Effect\" : \"Allow\" , \"Action\" : [ \"ssm:GetParameter*\" ], \"Resource\" : \"arn:aws:ssm:us-east-2:123456789012:parameter/dev-*\" } ] } JSON Secret Values You can store JSON objects in a parameter. You can access nested values or arrays using gjson syntax : Consider the following JSON object that is stored in the Parameter Store key my-json-secret : { \"name\" : { \"first\" : \"Tom\" , \"last\" : \"Anderson\" }, \"friends\" : [ { \"first\" : \"Dale\" , \"last\" : \"Murphy\" }, { \"first\" : \"Roger\" , \"last\" : \"Craig\" }, { \"first\" : \"Jane\" , \"last\" : \"Murphy\" } ] } This is an example on how you would look up nested keys in the above json object: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : # [omitted for brevity] data : - secretKey : firstname remoteRef : key : my-json-secret property : name.first # Tom - secretKey : first_friend remoteRef : key : my-json-secret property : friends.1.first # Roger AWS Authentication Controller's Pod Identity This is basicially a zero-configuration authentication method that inherits the credentials from the runtime environment using the aws sdk default credential chain . You can attach a role to the pod using IRSA , kiam or kube2iam . When no other authentication method is configured in the Kind=Secretstore this role is used to make all API calls against AWS Secrets Manager or SSM Parameter Store. Based on the Pod's identity you can do a sts:assumeRole before fetching the secrets to limit access to certain keys in your provider. This is optional. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: do a sts:assumeRole before fetching secrets role : team-b Access Key ID & Secret Access Key You can store Access Key ID & Secret Access Key in a Kind=Secret and reference it from a SecretStore. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: assume role before fetching secrets role : team-b auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key EKS Service Account credentials This feature lets you use short-lived service account tokens to authenticate with AWS. You must have Service Account Volume Projection enabled - it is by default on EKS. See EKS guide on how to set up IAM roles for service accounts. The big advantage of this approach is that ESO runs without any credentials. apiVersion : v1 kind : ServiceAccount metadata : annotations : eks.amazonaws.com/role-arn : arn:aws:iam::123456789012:role/team-a name : my-serviceaccount namespace : default Reference the service account from above in the Secret Store: apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager region : eu-central-1 auth : jwt : serviceAccountRef : name : my-serviceaccount","title":"Parameter Store"},{"location":"provider-aws-parameter-store/#parameter-store","text":"A ParameterStore points to AWS SSM Parameter Store in a certain account within a defined region. You should define Roles that define fine-grained access to individual secrets and pass them to ESO using spec.provider.aws.role . This way users of the SecretStore can only access the secrets necessary. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : ParameterStore # define a specific role to limit access # to certain secrets role : iam-role region : eu-central-1 auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key API Pricing & Throttling The SSM Parameter Store API is charged by throughput and is available in different tiers, see pricing . Please estimate your costs before using ESO. Cost depends on the RefreshInterval of your ExternalSecrets.","title":"Parameter Store"},{"location":"provider-aws-parameter-store/#iam-policy","text":"Create a IAM Policy to pin down access to secrets matching dev-* , for further information see AWS Documentation : { \"Version\" : \"2012-10-17\" , \"Statement\" : [ { \"Effect\" : \"Allow\" , \"Action\" : [ \"ssm:GetParameter*\" ], \"Resource\" : \"arn:aws:ssm:us-east-2:123456789012:parameter/dev-*\" } ] }","title":"IAM Policy"},{"location":"provider-aws-parameter-store/#json-secret-values","text":"You can store JSON objects in a parameter. You can access nested values or arrays using gjson syntax : Consider the following JSON object that is stored in the Parameter Store key my-json-secret : { \"name\" : { \"first\" : \"Tom\" , \"last\" : \"Anderson\" }, \"friends\" : [ { \"first\" : \"Dale\" , \"last\" : \"Murphy\" }, { \"first\" : \"Roger\" , \"last\" : \"Craig\" }, { \"first\" : \"Jane\" , \"last\" : \"Murphy\" } ] } This is an example on how you would look up nested keys in the above json object: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : # [omitted for brevity] data : - secretKey : firstname remoteRef : key : my-json-secret property : name.first # Tom - secretKey : first_friend remoteRef : key : my-json-secret property : friends.1.first # Roger","title":"JSON Secret Values"},{"location":"provider-aws-parameter-store/#aws-authentication","text":"","title":"AWS Authentication"},{"location":"provider-aws-parameter-store/#controllers-pod-identity","text":"This is basicially a zero-configuration authentication method that inherits the credentials from the runtime environment using the aws sdk default credential chain . You can attach a role to the pod using IRSA , kiam or kube2iam . When no other authentication method is configured in the Kind=Secretstore this role is used to make all API calls against AWS Secrets Manager or SSM Parameter Store. Based on the Pod's identity you can do a sts:assumeRole before fetching the secrets to limit access to certain keys in your provider. This is optional. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: do a sts:assumeRole before fetching secrets role : team-b","title":"Controller's Pod Identity"},{"location":"provider-aws-parameter-store/#access-key-id-secret-access-key","text":"You can store Access Key ID & Secret Access Key in a Kind=Secret and reference it from a SecretStore. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: assume role before fetching secrets role : team-b auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key","title":"Access Key ID &amp; Secret Access Key"},{"location":"provider-aws-parameter-store/#eks-service-account-credentials","text":"This feature lets you use short-lived service account tokens to authenticate with AWS. You must have Service Account Volume Projection enabled - it is by default on EKS. See EKS guide on how to set up IAM roles for service accounts. The big advantage of this approach is that ESO runs without any credentials. apiVersion : v1 kind : ServiceAccount metadata : annotations : eks.amazonaws.com/role-arn : arn:aws:iam::123456789012:role/team-a name : my-serviceaccount namespace : default Reference the service account from above in the Secret Store: apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager region : eu-central-1 auth : jwt : serviceAccountRef : name : my-serviceaccount","title":"EKS Service Account credentials"},{"location":"provider-aws-secrets-manager/","text":"Secrets Manager A SecretStore points to AWS Secrets Manager in a certain account within a defined region. You should define Roles that define fine-grained access to individual secrets and pass them to ESO using spec.provider.aws.role . This way users of the SecretStore can only access the secrets necessary. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager # define a specific role to limit access # to certain secrets. # role is a optional field that # can be omitted for test purposes role : iam-role region : eu-central-1 auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key IAM Policy Create a IAM Policy to pin down access to secrets matching dev-* . { \"Version\" : \"2012-10-17\" , \"Statement\" : [ { \"Effect\" : \"Allow\" , \"Action\" : [ \"secretsmanager:GetResourcePolicy\" , \"secretsmanager:GetSecretValue\" , \"secretsmanager:DescribeSecret\" , \"secretsmanager:ListSecretVersionIds\" ], \"Resource\" : [ \"arn:aws:secretsmanager:us-west-2:111122223333:secret:dev-*\" , ] } ] } JSON Secret Values SecretsManager supports simple key/value pairs that are stored as json. If you use the API you can store more complex JSON objects. You can access nested values or arrays using gjson syntax : Consider the following JSON object that is stored in the SecretsManager key my-json-secret : { \"name\" : { \"first\" : \"Tom\" , \"last\" : \"Anderson\" }, \"friends\" : [ { \"first\" : \"Dale\" , \"last\" : \"Murphy\" }, { \"first\" : \"Roger\" , \"last\" : \"Craig\" }, { \"first\" : \"Jane\" , \"last\" : \"Murphy\" } ] } This is an example on how you would look up nested keys in the above json object: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 1m secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created creationPolicy : Owner data : - secretKey : firstname remoteRef : key : my-json-secret property : name.first # Tom - secretKey : first_friend remoteRef : key : my-json-secret property : friends.1.first # Roger AWS Authentication Controller's Pod Identity This is basicially a zero-configuration authentication method that inherits the credentials from the runtime environment using the aws sdk default credential chain . You can attach a role to the pod using IRSA , kiam or kube2iam . When no other authentication method is configured in the Kind=Secretstore this role is used to make all API calls against AWS Secrets Manager or SSM Parameter Store. Based on the Pod's identity you can do a sts:assumeRole before fetching the secrets to limit access to certain keys in your provider. This is optional. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: do a sts:assumeRole before fetching secrets role : team-b Access Key ID & Secret Access Key You can store Access Key ID & Secret Access Key in a Kind=Secret and reference it from a SecretStore. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: assume role before fetching secrets role : team-b auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key EKS Service Account credentials This feature lets you use short-lived service account tokens to authenticate with AWS. You must have Service Account Volume Projection enabled - it is by default on EKS. See EKS guide on how to set up IAM roles for service accounts. The big advantage of this approach is that ESO runs without any credentials. apiVersion : v1 kind : ServiceAccount metadata : annotations : eks.amazonaws.com/role-arn : arn:aws:iam::123456789012:role/team-a name : my-serviceaccount namespace : default Reference the service account from above in the Secret Store: apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager region : eu-central-1 auth : jwt : serviceAccountRef : name : my-serviceaccount","title":"Secrets Manager"},{"location":"provider-aws-secrets-manager/#secrets-manager","text":"A SecretStore points to AWS Secrets Manager in a certain account within a defined region. You should define Roles that define fine-grained access to individual secrets and pass them to ESO using spec.provider.aws.role . This way users of the SecretStore can only access the secrets necessary. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager # define a specific role to limit access # to certain secrets. # role is a optional field that # can be omitted for test purposes role : iam-role region : eu-central-1 auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key","title":"Secrets Manager"},{"location":"provider-aws-secrets-manager/#iam-policy","text":"Create a IAM Policy to pin down access to secrets matching dev-* . { \"Version\" : \"2012-10-17\" , \"Statement\" : [ { \"Effect\" : \"Allow\" , \"Action\" : [ \"secretsmanager:GetResourcePolicy\" , \"secretsmanager:GetSecretValue\" , \"secretsmanager:DescribeSecret\" , \"secretsmanager:ListSecretVersionIds\" ], \"Resource\" : [ \"arn:aws:secretsmanager:us-west-2:111122223333:secret:dev-*\" , ] } ] }","title":"IAM Policy"},{"location":"provider-aws-secrets-manager/#json-secret-values","text":"SecretsManager supports simple key/value pairs that are stored as json. If you use the API you can store more complex JSON objects. You can access nested values or arrays using gjson syntax : Consider the following JSON object that is stored in the SecretsManager key my-json-secret : { \"name\" : { \"first\" : \"Tom\" , \"last\" : \"Anderson\" }, \"friends\" : [ { \"first\" : \"Dale\" , \"last\" : \"Murphy\" }, { \"first\" : \"Roger\" , \"last\" : \"Craig\" }, { \"first\" : \"Jane\" , \"last\" : \"Murphy\" } ] } This is an example on how you would look up nested keys in the above json object: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 1m secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created creationPolicy : Owner data : - secretKey : firstname remoteRef : key : my-json-secret property : name.first # Tom - secretKey : first_friend remoteRef : key : my-json-secret property : friends.1.first # Roger","title":"JSON Secret Values"},{"location":"provider-aws-secrets-manager/#aws-authentication","text":"","title":"AWS Authentication"},{"location":"provider-aws-secrets-manager/#controllers-pod-identity","text":"This is basicially a zero-configuration authentication method that inherits the credentials from the runtime environment using the aws sdk default credential chain . You can attach a role to the pod using IRSA , kiam or kube2iam . When no other authentication method is configured in the Kind=Secretstore this role is used to make all API calls against AWS Secrets Manager or SSM Parameter Store. Based on the Pod's identity you can do a sts:assumeRole before fetching the secrets to limit access to certain keys in your provider. This is optional. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: do a sts:assumeRole before fetching secrets role : team-b","title":"Controller's Pod Identity"},{"location":"provider-aws-secrets-manager/#access-key-id-secret-access-key","text":"You can store Access Key ID & Secret Access Key in a Kind=Secret and reference it from a SecretStore. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: assume role before fetching secrets role : team-b auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key","title":"Access Key ID &amp; Secret Access Key"},{"location":"provider-aws-secrets-manager/#eks-service-account-credentials","text":"This feature lets you use short-lived service account tokens to authenticate with AWS. You must have Service Account Volume Projection enabled - it is by default on EKS. See EKS guide on how to set up IAM roles for service accounts. The big advantage of this approach is that ESO runs without any credentials. apiVersion : v1 kind : ServiceAccount metadata : annotations : eks.amazonaws.com/role-arn : arn:aws:iam::123456789012:role/team-a name : my-serviceaccount namespace : default Reference the service account from above in the Secret Store: apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager region : eu-central-1 auth : jwt : serviceAccountRef : name : my-serviceaccount","title":"EKS Service Account credentials"},{"location":"provider-azure-key-vault/","text":"Azure Key vault External Secrets Operator integrates with Azure Key vault for secrets, certificates and Keys management. Authentication We support Service Principals and Managed Identity authentication . To use Managed Identity authentication, you should use aad-pod-identity to assign the identity to external-secrets operator. To add the selector to external-secrets operator, use podLabels in your values.yaml in case of Helm installation of external-secrets. Service Principal key authentication A service Principal client and Secret is created and the JSON keyfile is stored in a Kind=Secret . The ClientID and ClientSecret should be configured for the secret. This service principal should have proper access rights to the keyvault to be managed by the operator Managed Identity authentication A Managed Identity should be created in Azure, and that Identity should have proper rights to the keyvault to be managed by the operator. If there are multiple Managed Identitites for different keyvaults, the operator should have been assigned all identities via aad-pod-identity , then the SecretStore configuration should include the Id of the idenetity to be used via the identityId field. apiVersion : v1 kind : Secret metadata : name : azure-secret-sp type : Opaque data : ClientID : bXktc2VydmljZS1wcmluY2lwbGUtY2xpZW50LWlkCg== #service-principal-ID ClientSecret : bXktc2VydmljZS1wcmluY2lwbGUtY2xpZW50LXNlY3JldAo= #service-principal-secret Update secret store Be sure the azurekv provider is listed in the Kind=SecretStore apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example-secret-store spec : provider : # provider type: azure keyvault azurekv : # azure tenant ID, see: https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-how-to-find-tenant tenantId : \"d3bc2180-xxxx-xxxx-xxxx-154105743342\" # URL of your vault instance, see: https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates vaultUrl : \"https://my-keyvault-name.vault.azure.net\" authSecretRef : # points to the secret that contains # the azure service principal credentials clientId : name : azure-secret-sp key : ClientID clientSecret : name : azure-secret-sp key : ClientSecret Or in case of Managed Idenetity authentication: apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example-secret-store spec : provider : # provider type: azure keyvault azurekv : authType : ManagedIdentity # Optionally set the Id of the Managed Identity, if multiple identities are assigned to external-secrets operator identityId : \"<MI_clientId>\" # URL of your vault instance, see: https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates vaultUrl : \"https://my-keyvault-name.vault.azure.net\" Object Types Azure KeyVault manages different object types , we support keys , secrets and certificates . Simply prefix the key with key , secret or cert to retrieve the desired type (defaults to secret). Object Type Return Value secret the raw secret value. key A JWK which contains the public key. Azure KeyVault does not export the private key. You may want to use template functions to transform this JWK into PEM encoded PKIX ASN.1 DER format. certificate The raw CER contents of the x509 certificate. You may want to use template functions to transform this into your desired encoding Creating external secret To create a kubernetes secret from the Azure Key vault secret a Kind=ExternalSecret is needed. You can manage keys/secrets/certificates saved inside the keyvault , by setting a \"/\" prefixed type in the secret name , the default type is a secret . other supported values are cert and key to select all secrets inside the key vault , you can use the dataFrom directive apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example-external-secret spec : refreshInterval : 1h secretStoreRef : kind : SecretStore name : example-secret-store target : name : secret-to-be-created creationPolicy : Owner data : # name of the SECRET in the Azure KV (no prefix is by default a SECRET) - secretKey : dev-secret-test remoteRef : key : dev-secret-test # explicit type and name of secret in the Azure KV - secretKey : dev-another-secret-test remoteRef : key : secret/dev-secret-test # type/name of certificate in the Azure KV # raw value will be returned, use templating features for data processing - secretKey : dev-cert-test remoteRef : key : cert/dev-cert-test # type/name of the public key in the Azure KV # the key is returned PEM encoded - secretKey : dev-key-test remoteRef : key : key/dev-key-test The operator will fetch the Azure Key vault secret and inject it as a Kind=Secret kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath='{.data.dev-secret-test}' | base64 -d","title":"Key Vault"},{"location":"provider-azure-key-vault/#azure-key-vault","text":"External Secrets Operator integrates with Azure Key vault for secrets, certificates and Keys management.","title":"Azure Key vault"},{"location":"provider-azure-key-vault/#authentication","text":"We support Service Principals and Managed Identity authentication . To use Managed Identity authentication, you should use aad-pod-identity to assign the identity to external-secrets operator. To add the selector to external-secrets operator, use podLabels in your values.yaml in case of Helm installation of external-secrets.","title":"Authentication"},{"location":"provider-azure-key-vault/#service-principal-key-authentication","text":"A service Principal client and Secret is created and the JSON keyfile is stored in a Kind=Secret . The ClientID and ClientSecret should be configured for the secret. This service principal should have proper access rights to the keyvault to be managed by the operator","title":"Service Principal key authentication"},{"location":"provider-azure-key-vault/#managed-identity-authentication","text":"A Managed Identity should be created in Azure, and that Identity should have proper rights to the keyvault to be managed by the operator. If there are multiple Managed Identitites for different keyvaults, the operator should have been assigned all identities via aad-pod-identity , then the SecretStore configuration should include the Id of the idenetity to be used via the identityId field. apiVersion : v1 kind : Secret metadata : name : azure-secret-sp type : Opaque data : ClientID : bXktc2VydmljZS1wcmluY2lwbGUtY2xpZW50LWlkCg== #service-principal-ID ClientSecret : bXktc2VydmljZS1wcmluY2lwbGUtY2xpZW50LXNlY3JldAo= #service-principal-secret","title":"Managed Identity authentication"},{"location":"provider-azure-key-vault/#update-secret-store","text":"Be sure the azurekv provider is listed in the Kind=SecretStore apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example-secret-store spec : provider : # provider type: azure keyvault azurekv : # azure tenant ID, see: https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-how-to-find-tenant tenantId : \"d3bc2180-xxxx-xxxx-xxxx-154105743342\" # URL of your vault instance, see: https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates vaultUrl : \"https://my-keyvault-name.vault.azure.net\" authSecretRef : # points to the secret that contains # the azure service principal credentials clientId : name : azure-secret-sp key : ClientID clientSecret : name : azure-secret-sp key : ClientSecret Or in case of Managed Idenetity authentication: apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example-secret-store spec : provider : # provider type: azure keyvault azurekv : authType : ManagedIdentity # Optionally set the Id of the Managed Identity, if multiple identities are assigned to external-secrets operator identityId : \"<MI_clientId>\" # URL of your vault instance, see: https://docs.microsoft.com/en-us/azure/key-vault/general/about-keys-secrets-certificates vaultUrl : \"https://my-keyvault-name.vault.azure.net\"","title":"Update secret store"},{"location":"provider-azure-key-vault/#object-types","text":"Azure KeyVault manages different object types , we support keys , secrets and certificates . Simply prefix the key with key , secret or cert to retrieve the desired type (defaults to secret). Object Type Return Value secret the raw secret value. key A JWK which contains the public key. Azure KeyVault does not export the private key. You may want to use template functions to transform this JWK into PEM encoded PKIX ASN.1 DER format. certificate The raw CER contents of the x509 certificate. You may want to use template functions to transform this into your desired encoding","title":"Object Types"},{"location":"provider-azure-key-vault/#creating-external-secret","text":"To create a kubernetes secret from the Azure Key vault secret a Kind=ExternalSecret is needed. You can manage keys/secrets/certificates saved inside the keyvault , by setting a \"/\" prefixed type in the secret name , the default type is a secret . other supported values are cert and key to select all secrets inside the key vault , you can use the dataFrom directive apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example-external-secret spec : refreshInterval : 1h secretStoreRef : kind : SecretStore name : example-secret-store target : name : secret-to-be-created creationPolicy : Owner data : # name of the SECRET in the Azure KV (no prefix is by default a SECRET) - secretKey : dev-secret-test remoteRef : key : dev-secret-test # explicit type and name of secret in the Azure KV - secretKey : dev-another-secret-test remoteRef : key : secret/dev-secret-test # type/name of certificate in the Azure KV # raw value will be returned, use templating features for data processing - secretKey : dev-cert-test remoteRef : key : cert/dev-cert-test # type/name of the public key in the Azure KV # the key is returned PEM encoded - secretKey : dev-key-test remoteRef : key : key/dev-key-test The operator will fetch the Azure Key vault secret and inject it as a Kind=Secret kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath='{.data.dev-secret-test}' | base64 -d","title":"Creating external secret"},{"location":"provider-gitlab-project-variables/","text":"Gitlab Project Variables External Secrets Operator integrates with Gitlab API to sync Gitlab project variables to secrets held on the Kubernetes cluster. Authentication The API requires an access token and project ID. To create a new access token, go to your user settings and select 'access tokens'. Give your token a name, expiration date, and select the permissions required (Note 'api' is required). Click 'Create personal access token', and your token will be generated and displayed on screen. Copy or save this token since you can't access it again. Access Token secret Create a secret containing your access token: apiVersion : v1 kind : Secret metadata : name : gitlab-secret labels : type : gitlab type : Opaque stringData : token : \"**access token goes here**\" Update secret store Be sure the gitlab provider is listed in the Kind=SecretStore and the ProjectID is set. If you are not using https://gitlab.com , you must set the url field as well. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : gitlab-secret-store spec : provider : # provider type: gitlab gitlab : # url: https://gitlab.mydomain.com/ auth : SecretRef : accessToken : name : gitlab-secret key : token projectID : \"**project ID goes here**\" Your project ID can be found on your project's page. Creating external secret To sync a Gitlab variable to a secret on the Kubernetes cluster, a Kind=ExternalSecret is needed. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : gitlab-external-secret-example spec : refreshInterval : 1h secretStoreRef : kind : SecretStore name : gitlab-secret-store # Must match SecretStore on the cluster target : name : gitlab-secret-to-create # Name for the secret to be created on the cluster creationPolicy : Owner data : - secretKey : secretKey # Key given to the secret to be created on the cluster remoteRef : key : myGitlabVariable # Key of the variable on Gitlab Using DataFrom DataFrom can be used to get a variable as a JSON string and attempt to parse it. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : gitlab-external-secret-example spec : refreshInterval : 1h secretStoreRef : kind : SecretStore name : gitlab-secret-store # Must match SecretStore on the cluster target : name : gitlab-secret-to-create # Name for the secret to be created on the cluster creationPolicy : Owner # each secret name in the KV will be used as the secret key in the SECRET k8s target object dataFrom : - key : \"myJsonVariable\" # Key of the variable on Gitlab Getting the Kubernetes secret The operator will fetch the project variable and inject it as a Kind=Secret . kubectl get secret gitlab-secret-to-create -o jsonpath='{.data.secretKey}' | base64 -d","title":"Gitlab Project Variables"},{"location":"provider-gitlab-project-variables/#gitlab-project-variables","text":"External Secrets Operator integrates with Gitlab API to sync Gitlab project variables to secrets held on the Kubernetes cluster.","title":"Gitlab Project Variables"},{"location":"provider-gitlab-project-variables/#authentication","text":"The API requires an access token and project ID. To create a new access token, go to your user settings and select 'access tokens'. Give your token a name, expiration date, and select the permissions required (Note 'api' is required). Click 'Create personal access token', and your token will be generated and displayed on screen. Copy or save this token since you can't access it again.","title":"Authentication"},{"location":"provider-gitlab-project-variables/#access-token-secret","text":"Create a secret containing your access token: apiVersion : v1 kind : Secret metadata : name : gitlab-secret labels : type : gitlab type : Opaque stringData : token : \"**access token goes here**\"","title":"Access Token secret"},{"location":"provider-gitlab-project-variables/#update-secret-store","text":"Be sure the gitlab provider is listed in the Kind=SecretStore and the ProjectID is set. If you are not using https://gitlab.com , you must set the url field as well. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : gitlab-secret-store spec : provider : # provider type: gitlab gitlab : # url: https://gitlab.mydomain.com/ auth : SecretRef : accessToken : name : gitlab-secret key : token projectID : \"**project ID goes here**\" Your project ID can be found on your project's page.","title":"Update secret store"},{"location":"provider-gitlab-project-variables/#creating-external-secret","text":"To sync a Gitlab variable to a secret on the Kubernetes cluster, a Kind=ExternalSecret is needed. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : gitlab-external-secret-example spec : refreshInterval : 1h secretStoreRef : kind : SecretStore name : gitlab-secret-store # Must match SecretStore on the cluster target : name : gitlab-secret-to-create # Name for the secret to be created on the cluster creationPolicy : Owner data : - secretKey : secretKey # Key given to the secret to be created on the cluster remoteRef : key : myGitlabVariable # Key of the variable on Gitlab","title":"Creating external secret"},{"location":"provider-gitlab-project-variables/#using-datafrom","text":"DataFrom can be used to get a variable as a JSON string and attempt to parse it. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : gitlab-external-secret-example spec : refreshInterval : 1h secretStoreRef : kind : SecretStore name : gitlab-secret-store # Must match SecretStore on the cluster target : name : gitlab-secret-to-create # Name for the secret to be created on the cluster creationPolicy : Owner # each secret name in the KV will be used as the secret key in the SECRET k8s target object dataFrom : - key : \"myJsonVariable\" # Key of the variable on Gitlab","title":"Using DataFrom"},{"location":"provider-gitlab-project-variables/#getting-the-kubernetes-secret","text":"The operator will fetch the project variable and inject it as a Kind=Secret . kubectl get secret gitlab-secret-to-create -o jsonpath='{.data.secretKey}' | base64 -d","title":"Getting the Kubernetes secret"},{"location":"provider-google-secrets-manager/","text":"Google Cloud Secret Manager External Secrets Operator integrates with GCP Secret Manager for secret management. Authentication Workload Identity Your Google Kubernetes Engine (GKE) applications can consume GCP services like Secrets Manager without using static, long-lived authentication tokens. This is our recommended approach of handling credentials in GCP. ESO offers two options for integrating with GKE workload identity: pod-based workload identity and using service accounts directly . Before using either way you need to create a service account - this is covered below. Creating Workload Identity Service Accounts You can find the documentation for Workload Identity here . We will walk you through how to navigate it here. Search the documment for this editable values and change them to your values: CLUSTER_NAME : The name of your cluster PROJECT_ID : Your project ID (not your Project number nor your Project name) K8S_NAMESPACE : For us folowing these steps here it will be es , but this will be the namespace where you deployed the external-secrets operator KSA_NAME : external-secrets (if you are not creating a new one to attach to the deployemnt) GSA_NAME : external-secrets for simplicity, or something else if you have to follow different naming convetions for cloud resources ROLE_NAME : should be roles/secretmanager.secretAccessor - so you make the pod only be able to access secrets on Secret Manager Using Service Accounts directly Let's assume you have created a service account correctly and attached a appropriate workload identity. It should roughly look like this: apiVersion : v1 kind : ServiceAccount metadata : name : team-a namespace : team-a annotations : iam.gke.io/gcp-service-account : example-team-a@my-project.iam.gserviceaccount.com You can reference this particular ServiceAccount in a SecretStore or ClusterSecretStore . It's important that you also set the projectID , clusterLocation and clusterName . The Namespace on the serviceAccountRef is ignored when using a SecretStore resource. This is needed to isolate the namespaces properly. apiVersion : external-secrets.io/v1alpha1 kind : ClusterSecretStore metadata : name : example spec : provider : gcpsm : projectID : my-project auth : workloadIdentity : # name of the cluster region clusterLocation : europe-central2 # name of the GKE cluster clusterName : example-workload-identity # reference the sa from above serviceAccountRef : name : team-a namespace : team-a You need to give the Google service account the roles/iam.serviceAccountTokenCreator role so it can generate a service account token for you (not necessary in the Pod-based Workload Identity bellow) Using Pod-based Workload Identity You can attach a Workload Identity directly to the ESO pod. ESO then has access to all the APIs defined in the attached service account policy. You attach the workload identity by (1) creating a service account with a attached workload identity (described above) and (2) using this particular service account in the pod's serviceAccountName field. For this example we will assume that you installed ESO using helm and that you named the chart installation external-secrets and the namespace where it lives es like: helm install external-secrets external-secrets/external-secrets --namespace es Then most of the resources would have this name, the important one here being the k8s service account attached to the external-secrets operator deployment: # ... containers : - image : ghcr.io/external-secrets/external-secrets:vVERSION name : external-secrets ports : - containerPort : 8080 protocol : TCP restartPolicy : Always schedulerName : default-scheduler serviceAccount : external-secrets serviceAccountName : external-secrets # <--- here The pod now has the identity. Now you need to configure the SecretStore . You just need to set the projectID , all other fields can be omitted. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example spec : provider : gcpsm : projectID : pid GCP Service Account authentication You can use GCP Service Account to authenticate with GCP. These are static, long-lived credentials. A GCP Service Account is a JSON file that needs to be stored in a Kind=Secret . ESO will use that Secret to authenticate with GCP. See here how you manage GCP Service Accounts . apiVersion : v1 kind : Secret metadata : name : gcpsm-secret labels : type : gcpsm type : Opaque stringData : secret-access-credentials : |- { \"type\": \"service_account\", \"project_id\": \"external-secrets-operator\", \"private_key_id\": \"\", \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nA key\\n-----END PRIVATE KEY-----\\n\", \"client_email\": \"test-service-account@external-secrets-operator.iam.gserviceaccount.com\", \"client_id\": \"client ID\", \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\", \"token_uri\": \"https://oauth2.googleapis.com/token\", \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\", \"client_x509_cert_url\": \"https://www.googleapis.com/robot/v1/metadata/x509/test-service-account%40external-secrets-operator.iam.gserviceaccount.com\" } Update secret store Be sure the gcpsm provider is listed in the Kind=SecretStore apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example spec : provider : gcpsm : # gcpsm provider auth : secretRef : secretAccessKeySecretRef : name : gcpsm-secret # secret name containing SA key key : secret-access-credentials # key name containing SA key projectID : myproject # name of Google Cloud project Creating external secret To create a kubernetes secret from the GCP Secret Manager secret a Kind=ExternalSecret is needed. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 1h # rate SecretManager pulls GCPSM secretStoreRef : kind : SecretStore name : example # name of the SecretStore (or kind specified) target : name : secret-to-be-created # name of the k8s Secret to be created creationPolicy : Owner data : - secretKey : dev-secret-test # name of the GCPSM secret key remoteRef : key : dev-secret-test The operator will fetch the GCP Secret Manager secret and inject it as a Kind=Secret kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath='{.data.dev-secret-test}' | base64 -d","title":"Secrets Manager"},{"location":"provider-google-secrets-manager/#google-cloud-secret-manager","text":"External Secrets Operator integrates with GCP Secret Manager for secret management.","title":"Google Cloud Secret Manager"},{"location":"provider-google-secrets-manager/#authentication","text":"","title":"Authentication"},{"location":"provider-google-secrets-manager/#workload-identity","text":"Your Google Kubernetes Engine (GKE) applications can consume GCP services like Secrets Manager without using static, long-lived authentication tokens. This is our recommended approach of handling credentials in GCP. ESO offers two options for integrating with GKE workload identity: pod-based workload identity and using service accounts directly . Before using either way you need to create a service account - this is covered below.","title":"Workload Identity"},{"location":"provider-google-secrets-manager/#creating-workload-identity-service-accounts","text":"You can find the documentation for Workload Identity here . We will walk you through how to navigate it here. Search the documment for this editable values and change them to your values: CLUSTER_NAME : The name of your cluster PROJECT_ID : Your project ID (not your Project number nor your Project name) K8S_NAMESPACE : For us folowing these steps here it will be es , but this will be the namespace where you deployed the external-secrets operator KSA_NAME : external-secrets (if you are not creating a new one to attach to the deployemnt) GSA_NAME : external-secrets for simplicity, or something else if you have to follow different naming convetions for cloud resources ROLE_NAME : should be roles/secretmanager.secretAccessor - so you make the pod only be able to access secrets on Secret Manager","title":"Creating Workload Identity Service Accounts"},{"location":"provider-google-secrets-manager/#using-service-accounts-directly","text":"Let's assume you have created a service account correctly and attached a appropriate workload identity. It should roughly look like this: apiVersion : v1 kind : ServiceAccount metadata : name : team-a namespace : team-a annotations : iam.gke.io/gcp-service-account : example-team-a@my-project.iam.gserviceaccount.com You can reference this particular ServiceAccount in a SecretStore or ClusterSecretStore . It's important that you also set the projectID , clusterLocation and clusterName . The Namespace on the serviceAccountRef is ignored when using a SecretStore resource. This is needed to isolate the namespaces properly. apiVersion : external-secrets.io/v1alpha1 kind : ClusterSecretStore metadata : name : example spec : provider : gcpsm : projectID : my-project auth : workloadIdentity : # name of the cluster region clusterLocation : europe-central2 # name of the GKE cluster clusterName : example-workload-identity # reference the sa from above serviceAccountRef : name : team-a namespace : team-a You need to give the Google service account the roles/iam.serviceAccountTokenCreator role so it can generate a service account token for you (not necessary in the Pod-based Workload Identity bellow)","title":"Using Service Accounts directly"},{"location":"provider-google-secrets-manager/#using-pod-based-workload-identity","text":"You can attach a Workload Identity directly to the ESO pod. ESO then has access to all the APIs defined in the attached service account policy. You attach the workload identity by (1) creating a service account with a attached workload identity (described above) and (2) using this particular service account in the pod's serviceAccountName field. For this example we will assume that you installed ESO using helm and that you named the chart installation external-secrets and the namespace where it lives es like: helm install external-secrets external-secrets/external-secrets --namespace es Then most of the resources would have this name, the important one here being the k8s service account attached to the external-secrets operator deployment: # ... containers : - image : ghcr.io/external-secrets/external-secrets:vVERSION name : external-secrets ports : - containerPort : 8080 protocol : TCP restartPolicy : Always schedulerName : default-scheduler serviceAccount : external-secrets serviceAccountName : external-secrets # <--- here The pod now has the identity. Now you need to configure the SecretStore . You just need to set the projectID , all other fields can be omitted. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example spec : provider : gcpsm : projectID : pid","title":"Using Pod-based Workload Identity"},{"location":"provider-google-secrets-manager/#gcp-service-account-authentication","text":"You can use GCP Service Account to authenticate with GCP. These are static, long-lived credentials. A GCP Service Account is a JSON file that needs to be stored in a Kind=Secret . ESO will use that Secret to authenticate with GCP. See here how you manage GCP Service Accounts . apiVersion : v1 kind : Secret metadata : name : gcpsm-secret labels : type : gcpsm type : Opaque stringData : secret-access-credentials : |- { \"type\": \"service_account\", \"project_id\": \"external-secrets-operator\", \"private_key_id\": \"\", \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nA key\\n-----END PRIVATE KEY-----\\n\", \"client_email\": \"test-service-account@external-secrets-operator.iam.gserviceaccount.com\", \"client_id\": \"client ID\", \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\", \"token_uri\": \"https://oauth2.googleapis.com/token\", \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\", \"client_x509_cert_url\": \"https://www.googleapis.com/robot/v1/metadata/x509/test-service-account%40external-secrets-operator.iam.gserviceaccount.com\" }","title":"GCP Service Account authentication"},{"location":"provider-google-secrets-manager/#update-secret-store","text":"Be sure the gcpsm provider is listed in the Kind=SecretStore apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example spec : provider : gcpsm : # gcpsm provider auth : secretRef : secretAccessKeySecretRef : name : gcpsm-secret # secret name containing SA key key : secret-access-credentials # key name containing SA key projectID : myproject # name of Google Cloud project","title":"Update secret store"},{"location":"provider-google-secrets-manager/#creating-external-secret","text":"To create a kubernetes secret from the GCP Secret Manager secret a Kind=ExternalSecret is needed. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 1h # rate SecretManager pulls GCPSM secretStoreRef : kind : SecretStore name : example # name of the SecretStore (or kind specified) target : name : secret-to-be-created # name of the k8s Secret to be created creationPolicy : Owner data : - secretKey : dev-secret-test # name of the GCPSM secret key remoteRef : key : dev-secret-test The operator will fetch the GCP Secret Manager secret and inject it as a Kind=Secret kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath='{.data.dev-secret-test}' | base64 -d","title":"Creating external secret"},{"location":"provider-hashicorp-vault/","text":"Hashicorp Vault External Secrets Operator integrates with HashiCorp Vault for secret management. Vault itself implements lots of different secret engines, as of now we only support the KV Secrets Engine . Example First, create a SecretStore with a vault backend. For the sake of simplicity we'll use a static token root : apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend spec : provider : vault : server : \"http://my.vault.server:8200\" path : \"secret\" version : \"v2\" auth : # points to a secret that contains a vault token # https://www.vaultproject.io/docs/auth/token tokenSecretRef : name : \"vault-token\" namespace : \"default\" key : \"token\" --- apiVersion : v1 kind : Secret metadata : name : vault-token data : token : cm9vdA== # \"root\" Then create a simple k/v pair at path secret/foo : vault kv put secret/foo my-value=s3cr3t Now create a ExternalSecret that uses the above SecretStore: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : vault-example spec : refreshInterval : \"15s\" secretStoreRef : name : vault-backend kind : SecretStore target : name : example-sync data : - secretKey : foobar remoteRef : key : secret/foo property : my-value --- # will create a secret with: kind : Secret metadata : name : example-sync data : foobar : czNjcjN0 Limitations Vault supports only simple key/value pairs - nested objects are not supported. Hence specifying gjson properties like other providers support it is not supported. Authentication We support five different modes for authentication: token-based , appRole , kubernetes-native , ldap and jwt/odic , each one comes with it's own trade-offs. Depending on the authentication method you need to adapt your environment. Token-based authentication A static token is stored in a Kind=Secret and is used to authenticate with vault. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend namespace : example spec : provider : vault : server : \"https://vault.acme.org\" path : \"secret\" version : \"v2\" auth : # points to a secret that contains a vault token # https://www.vaultproject.io/docs/auth/token tokenSecretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"vault-token\" AppRole authentication example AppRole authentication reads the secret id from a Kind=Secret and uses the specified roleId to aquire a temporary token to fetch secrets. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend namespace : example spec : provider : vault : server : \"https://vault.acme.org\" path : \"secret\" version : \"v2\" auth : # VaultAppRole authenticates with Vault using the # App Role auth mechanism # https://www.vaultproject.io/docs/auth/approle appRole : # Path where the App Role authentication backend is mounted path : \"approle\" # RoleID configured in the App Role authentication backend roleId : \"db02de05-fa39-4855-059b-67221c5c2f63\" # Reference to a key in a K8 Secret that contains the App Role SecretId secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"secret-id\" Kubernetes authentication Kubernetes-native authentication has three options of optaining credentials for vault: by using a service account jwt referenced in serviceAccountRef by using the jwt from a Kind=Secret referenced by the secretRef by using transient credentials from the mounted service account token within the external-secrets operator apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend namespace : example spec : provider : vault : server : \"https://vault.acme.org\" path : \"secret\" version : \"v2\" auth : # Authenticate against Vault using a Kubernetes ServiceAccount # token stored in a Secret. # https://www.vaultproject.io/docs/auth/kubernetes kubernetes : # Path where the Kubernetes authentication backend is mounted in Vault mountPath : \"kubernetes\" # A required field containing the Vault Role to assume. role : \"demo\" # Optional service account field containing the name # of a kubernetes ServiceAccount serviceAccountRef : name : \"my-sa\" namespace : \"secret-admin\" # Optional secret field containing a Kubernetes ServiceAccount JWT # used for authenticating with Vault secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"vault\" LDAP authentication LDAP authentication uses username/password pair to get an access token. Username is stored directly in a Kind=SecretStore or Kind=ClusterSecretStore resource, password is stored in a Kind=Secret referenced by the secretRef . apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend namespace : example spec : provider : vault : server : \"https://vault.acme.org\" path : \"secret\" version : \"v2\" auth : # VaultLdap authenticates with Vault using the LDAP auth mechanism # https://www.vaultproject.io/docs/auth/ldap ldap : # Path where the LDAP authentication backend is mounted path : \"ldap\" # LDAP username username : \"username\" secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"ldap-password\" JWT/OIDC authentication JWT/OIDC uses a JWT token stored in a Kind=Secret and referenced by the secretRef . Optionally a role field can be defined in a Kind=SecretStore or Kind=ClusterSecretStore resource. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend namespace : example spec : provider : vault : server : \"https://vault.acme.org\" path : \"secret\" version : \"v2\" auth : # VaultJwt authenticates with Vault using the JWT/OIDC auth mechanism # https://www.vaultproject.io/docs/auth/jwt jwt : # Path where the JWT authentication backend is mounted path : \"jwt\" # JWT role configured in a Vault server, optional. role : \"vault-jwt-role\" secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"jwt-token\" Vault Enterprise and Eventual Consistency When using Vault Enterprise with performance standby nodes , any follower can handle read requests immediately after the provider has authenticated. Since Vault becomes eventually consistent in this mode, these requests can fail if the login has not yet propagated to each server's local state. Below are two different solutions to this scenario. You'll need to review them and pick the best fit for your environment and Vault configuration. Read Your Writes The simplest method is simply utilizing the X-Vault-Index header returned on all write requests (including logins). Passing this header back on subsequent requests instructs the Vault client to retry the request until the server has an index greater than or equal to that returned with the last write. Obviously though, this has a performance hit because the read is blocked until the follower's local state has caught up. Forward Inconsistent In addition to the aforementioned X-Vault-Index header, Vault also supports proxying inconsistent requests to the current cluster leader for immediate read-after-write consistency. This is achieved by setting the X-Vault-Inconsistent header to forward-active-node . By default, this behavior is disabled and must be explicitly enabled in the server's replication configuration .","title":"HashiCorp Vault"},{"location":"provider-hashicorp-vault/#hashicorp-vault","text":"External Secrets Operator integrates with HashiCorp Vault for secret management. Vault itself implements lots of different secret engines, as of now we only support the KV Secrets Engine .","title":"Hashicorp Vault"},{"location":"provider-hashicorp-vault/#example","text":"First, create a SecretStore with a vault backend. For the sake of simplicity we'll use a static token root : apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend spec : provider : vault : server : \"http://my.vault.server:8200\" path : \"secret\" version : \"v2\" auth : # points to a secret that contains a vault token # https://www.vaultproject.io/docs/auth/token tokenSecretRef : name : \"vault-token\" namespace : \"default\" key : \"token\" --- apiVersion : v1 kind : Secret metadata : name : vault-token data : token : cm9vdA== # \"root\" Then create a simple k/v pair at path secret/foo : vault kv put secret/foo my-value=s3cr3t Now create a ExternalSecret that uses the above SecretStore: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : vault-example spec : refreshInterval : \"15s\" secretStoreRef : name : vault-backend kind : SecretStore target : name : example-sync data : - secretKey : foobar remoteRef : key : secret/foo property : my-value --- # will create a secret with: kind : Secret metadata : name : example-sync data : foobar : czNjcjN0","title":"Example"},{"location":"provider-hashicorp-vault/#limitations","text":"Vault supports only simple key/value pairs - nested objects are not supported. Hence specifying gjson properties like other providers support it is not supported.","title":"Limitations"},{"location":"provider-hashicorp-vault/#authentication","text":"We support five different modes for authentication: token-based , appRole , kubernetes-native , ldap and jwt/odic , each one comes with it's own trade-offs. Depending on the authentication method you need to adapt your environment.","title":"Authentication"},{"location":"provider-hashicorp-vault/#token-based-authentication","text":"A static token is stored in a Kind=Secret and is used to authenticate with vault. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend namespace : example spec : provider : vault : server : \"https://vault.acme.org\" path : \"secret\" version : \"v2\" auth : # points to a secret that contains a vault token # https://www.vaultproject.io/docs/auth/token tokenSecretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"vault-token\"","title":"Token-based authentication"},{"location":"provider-hashicorp-vault/#approle-authentication-example","text":"AppRole authentication reads the secret id from a Kind=Secret and uses the specified roleId to aquire a temporary token to fetch secrets. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend namespace : example spec : provider : vault : server : \"https://vault.acme.org\" path : \"secret\" version : \"v2\" auth : # VaultAppRole authenticates with Vault using the # App Role auth mechanism # https://www.vaultproject.io/docs/auth/approle appRole : # Path where the App Role authentication backend is mounted path : \"approle\" # RoleID configured in the App Role authentication backend roleId : \"db02de05-fa39-4855-059b-67221c5c2f63\" # Reference to a key in a K8 Secret that contains the App Role SecretId secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"secret-id\"","title":"AppRole authentication example"},{"location":"provider-hashicorp-vault/#kubernetes-authentication","text":"Kubernetes-native authentication has three options of optaining credentials for vault: by using a service account jwt referenced in serviceAccountRef by using the jwt from a Kind=Secret referenced by the secretRef by using transient credentials from the mounted service account token within the external-secrets operator apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend namespace : example spec : provider : vault : server : \"https://vault.acme.org\" path : \"secret\" version : \"v2\" auth : # Authenticate against Vault using a Kubernetes ServiceAccount # token stored in a Secret. # https://www.vaultproject.io/docs/auth/kubernetes kubernetes : # Path where the Kubernetes authentication backend is mounted in Vault mountPath : \"kubernetes\" # A required field containing the Vault Role to assume. role : \"demo\" # Optional service account field containing the name # of a kubernetes ServiceAccount serviceAccountRef : name : \"my-sa\" namespace : \"secret-admin\" # Optional secret field containing a Kubernetes ServiceAccount JWT # used for authenticating with Vault secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"vault\"","title":"Kubernetes authentication"},{"location":"provider-hashicorp-vault/#ldap-authentication","text":"LDAP authentication uses username/password pair to get an access token. Username is stored directly in a Kind=SecretStore or Kind=ClusterSecretStore resource, password is stored in a Kind=Secret referenced by the secretRef . apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend namespace : example spec : provider : vault : server : \"https://vault.acme.org\" path : \"secret\" version : \"v2\" auth : # VaultLdap authenticates with Vault using the LDAP auth mechanism # https://www.vaultproject.io/docs/auth/ldap ldap : # Path where the LDAP authentication backend is mounted path : \"ldap\" # LDAP username username : \"username\" secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"ldap-password\"","title":"LDAP authentication"},{"location":"provider-hashicorp-vault/#jwtoidc-authentication","text":"JWT/OIDC uses a JWT token stored in a Kind=Secret and referenced by the secretRef . Optionally a role field can be defined in a Kind=SecretStore or Kind=ClusterSecretStore resource. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : vault-backend namespace : example spec : provider : vault : server : \"https://vault.acme.org\" path : \"secret\" version : \"v2\" auth : # VaultJwt authenticates with Vault using the JWT/OIDC auth mechanism # https://www.vaultproject.io/docs/auth/jwt jwt : # Path where the JWT authentication backend is mounted path : \"jwt\" # JWT role configured in a Vault server, optional. role : \"vault-jwt-role\" secretRef : name : \"my-secret\" namespace : \"secret-admin\" key : \"jwt-token\"","title":"JWT/OIDC authentication"},{"location":"provider-hashicorp-vault/#vault-enterprise-and-eventual-consistency","text":"When using Vault Enterprise with performance standby nodes , any follower can handle read requests immediately after the provider has authenticated. Since Vault becomes eventually consistent in this mode, these requests can fail if the login has not yet propagated to each server's local state. Below are two different solutions to this scenario. You'll need to review them and pick the best fit for your environment and Vault configuration.","title":"Vault Enterprise and Eventual Consistency"},{"location":"provider-hashicorp-vault/#read-your-writes","text":"The simplest method is simply utilizing the X-Vault-Index header returned on all write requests (including logins). Passing this header back on subsequent requests instructs the Vault client to retry the request until the server has an index greater than or equal to that returned with the last write. Obviously though, this has a performance hit because the read is blocked until the follower's local state has caught up.","title":"Read Your Writes"},{"location":"provider-hashicorp-vault/#forward-inconsistent","text":"In addition to the aforementioned X-Vault-Index header, Vault also supports proxying inconsistent requests to the current cluster leader for immediate read-after-write consistency. This is achieved by setting the X-Vault-Inconsistent header to forward-active-node . By default, this behavior is disabled and must be explicitly enabled in the server's replication configuration .","title":"Forward Inconsistent"},{"location":"provider-ibm-secrets-manager/","text":"IBM Cloud Secret Manager External Secrets Operator integrates with IBM Secret Manager for secret management. Authentication At the moment, we only support API key authentication for this provider. To generate your key (for test purposes we are going to generate from your user), first got to your (Access IAM) page: On the left, click \"IBM Cloud API Keys\": Press \"Create an IBM Cloud API Key\": Pick a name and description for your key: You have created a key. Press the eyeball to show the key. Copy or save it because keys can't be displayed or downloaded twice. API key secret Create a secret containing your apiKey: kubectl create secret generic ibm-secret --from-literal = apiKey = 'API_KEY_VALUE' Update secret store Be sure the ibm provider is listed in the Kind=SecretStore apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : ibm : serviceUrl : \"https://SECRETS_MANAGER_ID.REGION.secrets-manager.appdomain.cloud\" auth : secretRef : secretApiKeySecretRef : name : ibm-secret key : apiKey To find your serviceURL, under your Secrets Manager resource, go to \"Endpoints\" on the left. Note: Use the url without the /api suffix that is presented in the UI. See here for a list of publicly available endpoints . Secret Types We support all secret types of IBM Secrets Manager : arbitrary , username_password , iam_credentials and imported_cert . To define the type of secret you would like to sync you need to prefix the secret id with the desired type. If the secret type is not specified it is defaulted to arbitrary : apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : ibm-sample spec : # [...] data : - secretKey : test remoteRef : # defaults to type=arbitrary key : xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - secretKey : foo remoteRef : key : username_password/yyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy - secretKey : bar remoteRef : key : iam_credentials/zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz - secretKey : baz remoteRef : key : imported_cert/zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz The behavior for the different secret types is as following: arbitrary remoteRef retrieves a string from secrets manager and sets it for specified secretKey dataFrom retrieves a string from secrets manager and tries to parse it as JSON object setting the key:values pairs in resulting Kubernetes secret if successful username_password remoteRef requires a property to be set for either username or password to retrieve respective fields from the secrets manager secret and set in specified secretKey dataFrom retrieves both username and password fields from the secrets manager secret and sets appropriate key:value pairs in the resulting Kubernetes secret iam_credentials remoteRef retrieves an apikey from secrets manager and sets it for specified secretKey dataFrom retrieves an apikey from secrets manager and sets it for the apikey Kubernetes secret key imported_cert remoteRef requires a property to be set for either certificate , private_key or intermediate to retrieve respective fields from the secrets manager secret and set in specified secretKey dataFrom retrieves all certificate , private_key and intermediate fields from the secrets manager secret and sets appropriate key:value pairs in the resulting Kubernetes secret Creating external secret To create a kubernetes secret from the IBM Secrets Manager, a Kind=ExternalSecret is needed. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : external-secret-sample spec : refreshInterval : 1m secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created creationPolicy : Owner data : - secretKey : test remoteRef : key : xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Currently we can only get the secret by its id and not its name, so something like 565287ce-578f-8d96-a746-9409d531fe2a . Getting the Kubernetes secret The operator will fetch the IBM Secret Manager secret and inject it as a Kind=Secret kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath='{.data.test}' | base64 -d","title":"Secrets Manager"},{"location":"provider-ibm-secrets-manager/#ibm-cloud-secret-manager","text":"External Secrets Operator integrates with IBM Secret Manager for secret management.","title":"IBM Cloud Secret Manager"},{"location":"provider-ibm-secrets-manager/#authentication","text":"At the moment, we only support API key authentication for this provider. To generate your key (for test purposes we are going to generate from your user), first got to your (Access IAM) page: On the left, click \"IBM Cloud API Keys\": Press \"Create an IBM Cloud API Key\": Pick a name and description for your key: You have created a key. Press the eyeball to show the key. Copy or save it because keys can't be displayed or downloaded twice.","title":"Authentication"},{"location":"provider-ibm-secrets-manager/#api-key-secret","text":"Create a secret containing your apiKey: kubectl create secret generic ibm-secret --from-literal = apiKey = 'API_KEY_VALUE'","title":"API key secret"},{"location":"provider-ibm-secrets-manager/#update-secret-store","text":"Be sure the ibm provider is listed in the Kind=SecretStore apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : ibm : serviceUrl : \"https://SECRETS_MANAGER_ID.REGION.secrets-manager.appdomain.cloud\" auth : secretRef : secretApiKeySecretRef : name : ibm-secret key : apiKey To find your serviceURL, under your Secrets Manager resource, go to \"Endpoints\" on the left. Note: Use the url without the /api suffix that is presented in the UI. See here for a list of publicly available endpoints .","title":"Update secret store"},{"location":"provider-ibm-secrets-manager/#secret-types","text":"We support all secret types of IBM Secrets Manager : arbitrary , username_password , iam_credentials and imported_cert . To define the type of secret you would like to sync you need to prefix the secret id with the desired type. If the secret type is not specified it is defaulted to arbitrary : apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : ibm-sample spec : # [...] data : - secretKey : test remoteRef : # defaults to type=arbitrary key : xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - secretKey : foo remoteRef : key : username_password/yyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy - secretKey : bar remoteRef : key : iam_credentials/zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz - secretKey : baz remoteRef : key : imported_cert/zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz The behavior for the different secret types is as following:","title":"Secret Types"},{"location":"provider-ibm-secrets-manager/#arbitrary","text":"remoteRef retrieves a string from secrets manager and sets it for specified secretKey dataFrom retrieves a string from secrets manager and tries to parse it as JSON object setting the key:values pairs in resulting Kubernetes secret if successful","title":"arbitrary"},{"location":"provider-ibm-secrets-manager/#username_password","text":"remoteRef requires a property to be set for either username or password to retrieve respective fields from the secrets manager secret and set in specified secretKey dataFrom retrieves both username and password fields from the secrets manager secret and sets appropriate key:value pairs in the resulting Kubernetes secret","title":"username_password"},{"location":"provider-ibm-secrets-manager/#iam_credentials","text":"remoteRef retrieves an apikey from secrets manager and sets it for specified secretKey dataFrom retrieves an apikey from secrets manager and sets it for the apikey Kubernetes secret key","title":"iam_credentials"},{"location":"provider-ibm-secrets-manager/#imported_cert","text":"remoteRef requires a property to be set for either certificate , private_key or intermediate to retrieve respective fields from the secrets manager secret and set in specified secretKey dataFrom retrieves all certificate , private_key and intermediate fields from the secrets manager secret and sets appropriate key:value pairs in the resulting Kubernetes secret","title":"imported_cert"},{"location":"provider-ibm-secrets-manager/#creating-external-secret","text":"To create a kubernetes secret from the IBM Secrets Manager, a Kind=ExternalSecret is needed. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : external-secret-sample spec : refreshInterval : 1m secretStoreRef : name : secretstore-sample kind : SecretStore target : name : secret-to-be-created creationPolicy : Owner data : - secretKey : test remoteRef : key : xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx Currently we can only get the secret by its id and not its name, so something like 565287ce-578f-8d96-a746-9409d531fe2a .","title":"Creating external secret"},{"location":"provider-ibm-secrets-manager/#getting-the-kubernetes-secret","text":"The operator will fetch the IBM Secret Manager secret and inject it as a Kind=Secret kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath='{.data.test}' | base64 -d","title":"Getting the Kubernetes secret"},{"location":"provider-oracle-vault/","text":"Oracle Vault External Secrets Operator integrates with OCI API to sync secret on the Oracle Vault to secrets held on the Kubernetes cluster. Authentication The API requires a userOCID, tenancyOCID, fingerprint, key file and a region. The fingerprint and key file should be supplied in the secret with the rest being provided in the secret store. See url for what region you you are accessing. Select tenancy in the top right to see your user OCID as shown below. Select your user in the top right to see your user OCID as shown below. Service account key authentication Create a secret containing your private key and fingerprint: apiVersion : v1 kind : Secret metadata : name : oracle-secret labels : type : oracle type : Opaque stringData : privateKey : fingerprint : Your fingerprint will be attatched to your API key, once it has been generated. Found on the same page as the user OCID. Once you click \"Add API Key\" you will be shown the following, where you can download the RSA key in the necessary PEM format for API requests. This will automatically generate a fingerprint. Update secret store Be sure the oracle provider is listed in the Kind=SecretStore . apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example spec : provider : oracle : #Needs to match value in secretstore_types.go vault : # The vault OCID user : tenancy : region : auth : secretRef : privatekey : name : oracle-secret key : privateKey #Needs to match stringData val in secret_oracle.yml fingerprint : name : oracle-secret key : fingerprint Creating external secret To create a kubernetes secret from the Oracle Cloud Interface secret a Kind=ExternalSecret is needed. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 0.03m secretStoreRef : kind : SecretStore name : example # Must match SecretStore on the cluster target : name : secret-to-be-created # Name for the secret on the cluster creationPolicy : Owner dataFrom : - key : the-secret-name Getting the Kubernetes secret The operator will fetch the project variable and inject it as a Kind=Secret . kubectl get secret oracle-secret-to-create -o jsonpath='{.data.dev-secret-test}' | base64 -d","title":"Oracle Vault"},{"location":"provider-oracle-vault/#oracle-vault","text":"External Secrets Operator integrates with OCI API to sync secret on the Oracle Vault to secrets held on the Kubernetes cluster.","title":"Oracle Vault"},{"location":"provider-oracle-vault/#authentication","text":"The API requires a userOCID, tenancyOCID, fingerprint, key file and a region. The fingerprint and key file should be supplied in the secret with the rest being provided in the secret store. See url for what region you you are accessing. Select tenancy in the top right to see your user OCID as shown below. Select your user in the top right to see your user OCID as shown below.","title":"Authentication"},{"location":"provider-oracle-vault/#service-account-key-authentication","text":"Create a secret containing your private key and fingerprint: apiVersion : v1 kind : Secret metadata : name : oracle-secret labels : type : oracle type : Opaque stringData : privateKey : fingerprint : Your fingerprint will be attatched to your API key, once it has been generated. Found on the same page as the user OCID. Once you click \"Add API Key\" you will be shown the following, where you can download the RSA key in the necessary PEM format for API requests. This will automatically generate a fingerprint.","title":"Service account key authentication"},{"location":"provider-oracle-vault/#update-secret-store","text":"Be sure the oracle provider is listed in the Kind=SecretStore . apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : example spec : provider : oracle : #Needs to match value in secretstore_types.go vault : # The vault OCID user : tenancy : region : auth : secretRef : privatekey : name : oracle-secret key : privateKey #Needs to match stringData val in secret_oracle.yml fingerprint : name : oracle-secret key : fingerprint","title":"Update secret store"},{"location":"provider-oracle-vault/#creating-external-secret","text":"To create a kubernetes secret from the Oracle Cloud Interface secret a Kind=ExternalSecret is needed. apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : example spec : refreshInterval : 0.03m secretStoreRef : kind : SecretStore name : example # Must match SecretStore on the cluster target : name : secret-to-be-created # Name for the secret on the cluster creationPolicy : Owner dataFrom : - key : the-secret-name","title":"Creating external secret"},{"location":"provider-oracle-vault/#getting-the-kubernetes-secret","text":"The operator will fetch the project variable and inject it as a Kind=Secret . kubectl get secret oracle-secret-to-create -o jsonpath='{.data.dev-secret-test}' | base64 -d","title":"Getting the Kubernetes secret"},{"location":"provider-webhook/","text":"Generic Webhook External Secrets Operator can integrate with simple web apis by specifying the endpoint Example First, create a SecretStore with a webhook backend. We'll use a static user/password root : apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : webhook-backend spec : provider : webhook : url : \"http://httpbin.org/get?parameter={{ .remoteRef.key }}\" result : jsonPath : \"$.args.parameter\" headers : Content-Type : application/json Authorization : Basic {{ print .auth.username \":\" .auth.password | b64enc }} secrets : - name : auth secretRef : name : webhook-credentials --- apiVersion : v1 kind : Secret metadata : name : webhook-credentials data : username : dGVzdA== # \"test\" password : dGVzdA== # \"test\" NB: This is obviously not practical because it just returns the key as the result, but it shows how it works Now create an ExternalSecret that uses the above SecretStore: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : webhook-example spec : refreshInterval : \"15s\" secretStoreRef : name : webhook-backend kind : SecretStore target : name : example-sync data : - secretKey : foobar remoteRef : key : secret --- # will create a secret with: kind : Secret metadata : name : example-sync data : foobar : c2VjcmV0 Limitations Webhook does not support authorization, other than what can be sent by generating http headers Templating Generic WebHook provider uses the templating engine to generate the API call. It can be used in the url, headers, body and result.jsonPath fields. The provider inserts the secret to be retrieved in the object named remoteRef . In addition, secrets can be added as named objects, for example to use in authorization headers. Each secret has a name property which determines the name of the object in the templating engine. All Parameters apiVersion : external-secrets.io/v1alpha1 kind : ClusterSecretStore metadata : name : statervault spec : provider : webhook : # Url to call. Use templating engine to fill in the request parameters url : <url> # http method, defaults to GET method : <method> # Timeout in duration (1s, 1m, etc) timeout : 1s result : # [jsonPath](https://jsonpath.com) syntax, which also can be templated jsonPath : <jsonPath> # Map of headers, can be templated headers : <Header-Name> : <header contents> # Body to sent as request, can be templated (optional) body : <body> # List of secrets to expose to the templating engine secrets : # Use this name to refer to this secret in templating, above - name : <name> secretRef : namespace : <namespace> name : <name> # Add CAs here for the TLS handshake caBundle : <base64 encoded cabundle> caProvider : type : Secret or COnfigMap name : <name of secret or configmap> namespace : <namespace> key : <key inside secret>","title":"Webhook"},{"location":"provider-webhook/#generic-webhook","text":"External Secrets Operator can integrate with simple web apis by specifying the endpoint","title":"Generic Webhook"},{"location":"provider-webhook/#example","text":"First, create a SecretStore with a webhook backend. We'll use a static user/password root : apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : webhook-backend spec : provider : webhook : url : \"http://httpbin.org/get?parameter={{ .remoteRef.key }}\" result : jsonPath : \"$.args.parameter\" headers : Content-Type : application/json Authorization : Basic {{ print .auth.username \":\" .auth.password | b64enc }} secrets : - name : auth secretRef : name : webhook-credentials --- apiVersion : v1 kind : Secret metadata : name : webhook-credentials data : username : dGVzdA== # \"test\" password : dGVzdA== # \"test\" NB: This is obviously not practical because it just returns the key as the result, but it shows how it works Now create an ExternalSecret that uses the above SecretStore: apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : webhook-example spec : refreshInterval : \"15s\" secretStoreRef : name : webhook-backend kind : SecretStore target : name : example-sync data : - secretKey : foobar remoteRef : key : secret --- # will create a secret with: kind : Secret metadata : name : example-sync data : foobar : c2VjcmV0","title":"Example"},{"location":"provider-webhook/#limitations","text":"Webhook does not support authorization, other than what can be sent by generating http headers","title":"Limitations"},{"location":"provider-webhook/#templating","text":"Generic WebHook provider uses the templating engine to generate the API call. It can be used in the url, headers, body and result.jsonPath fields. The provider inserts the secret to be retrieved in the object named remoteRef . In addition, secrets can be added as named objects, for example to use in authorization headers. Each secret has a name property which determines the name of the object in the templating engine.","title":"Templating"},{"location":"provider-webhook/#all-parameters","text":"apiVersion : external-secrets.io/v1alpha1 kind : ClusterSecretStore metadata : name : statervault spec : provider : webhook : # Url to call. Use templating engine to fill in the request parameters url : <url> # http method, defaults to GET method : <method> # Timeout in duration (1s, 1m, etc) timeout : 1s result : # [jsonPath](https://jsonpath.com) syntax, which also can be templated jsonPath : <jsonPath> # Map of headers, can be templated headers : <Header-Name> : <header contents> # Body to sent as request, can be templated (optional) body : <body> # List of secrets to expose to the templating engine secrets : # Use this name to refer to this secret in templating, above - name : <name> secretRef : namespace : <namespace> name : <name> # Add CAs here for the TLS handshake caBundle : <base64 encoded cabundle> caProvider : type : Secret or COnfigMap name : <name of secret or configmap> namespace : <namespace> key : <key inside secret>","title":"All Parameters"},{"location":"provider-yandex-lockbox/","text":"Yandex Lockbox External Secrets Operator integrates with Yandex Lockbox for secret management. Prerequisites External Secrets Operator installed Yandex.Cloud CLI installed Authentication At the moment, authorized key authentication is only supported: Create a service account in Yandex.Cloud: yc iam service-account create --name eso-service-account Create an authorized key for the service account and save it to authorized-key.json file: yc iam key create \\ --service-account-name eso-service-account \\ --output authorized-key.json Create a k8s secret containing the authorized key saved above: kubectl create secret generic yc-auth --from-file = authorized-key = authorized-key.json Create a SecretStore pointing to yc-auth k8s secret: apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secret-store spec : provider : yandexlockbox : auth : authorizedKeySecretRef : name : yc-auth key : authorized-key Creating external secret To make External Secrets Operator sync a k8s secret with a Lockbox secret: Create a Lockbox secret, if not already created: yc lockbox secret create \\ --name lockbox-secret \\ --payload '[{\"key\": \"password\",\"textValue\": \"p@$$w0rd\"}]' Assign the lockbox.payloadViewer role for accessing the lockbox-secret payload to the service account used for authentication: yc lockbox secret add-access-binding \\ --name lockbox-secret \\ --service-account-name eso-service-account \\ --role lockbox.payloadViewer Run the following command to ensure that the correct access binding has been added: yc lockbox secret list-access-bindings --name lockbox-secret Create an ExternalSecret pointing to secret-store and lockbox-secret : apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : external-secret spec : refreshInterval : 1h secretStoreRef : name : secret-store kind : SecretStore target : name : k8s-secret # the target k8s secret name data : - secretKey : password # the target k8s secret key remoteRef : key : ***** # ID of lockbox-secret property : password # (optional) payload entry key of lockbox-secret The operator will fetch the Yandex Lockbox secret and inject it as a Kind=Secret kubectl get secret k8s-secret -n <namespace> | -o jsonpath='{.data.password}' | base64 -d","title":"Lockbox"},{"location":"provider-yandex-lockbox/#yandex-lockbox","text":"External Secrets Operator integrates with Yandex Lockbox for secret management.","title":"Yandex Lockbox"},{"location":"provider-yandex-lockbox/#prerequisites","text":"External Secrets Operator installed Yandex.Cloud CLI installed","title":"Prerequisites"},{"location":"provider-yandex-lockbox/#authentication","text":"At the moment, authorized key authentication is only supported: Create a service account in Yandex.Cloud: yc iam service-account create --name eso-service-account Create an authorized key for the service account and save it to authorized-key.json file: yc iam key create \\ --service-account-name eso-service-account \\ --output authorized-key.json Create a k8s secret containing the authorized key saved above: kubectl create secret generic yc-auth --from-file = authorized-key = authorized-key.json Create a SecretStore pointing to yc-auth k8s secret: apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secret-store spec : provider : yandexlockbox : auth : authorizedKeySecretRef : name : yc-auth key : authorized-key","title":"Authentication"},{"location":"provider-yandex-lockbox/#creating-external-secret","text":"To make External Secrets Operator sync a k8s secret with a Lockbox secret: Create a Lockbox secret, if not already created: yc lockbox secret create \\ --name lockbox-secret \\ --payload '[{\"key\": \"password\",\"textValue\": \"p@$$w0rd\"}]' Assign the lockbox.payloadViewer role for accessing the lockbox-secret payload to the service account used for authentication: yc lockbox secret add-access-binding \\ --name lockbox-secret \\ --service-account-name eso-service-account \\ --role lockbox.payloadViewer Run the following command to ensure that the correct access binding has been added: yc lockbox secret list-access-bindings --name lockbox-secret Create an ExternalSecret pointing to secret-store and lockbox-secret : apiVersion : external-secrets.io/v1alpha1 kind : ExternalSecret metadata : name : external-secret spec : refreshInterval : 1h secretStoreRef : name : secret-store kind : SecretStore target : name : k8s-secret # the target k8s secret name data : - secretKey : password # the target k8s secret key remoteRef : key : ***** # ID of lockbox-secret property : password # (optional) payload entry key of lockbox-secret The operator will fetch the Yandex Lockbox secret and inject it as a Kind=Secret kubectl get secret k8s-secret -n <namespace> | -o jsonpath='{.data.password}' | base64 -d","title":"Creating external secret"},{"location":"spec/","text":"Packages: external-secrets.io/v1alpha1 external-secrets.io/v1alpha1 Package v1alpha1 contains resources for external-secrets Resource Types: AWSAuth ( Appears on: AWSProvider ) AWSAuth tells the controller how to do authentication with aws. Only one of secretRef or jwt can be specified. if none is specified the controller will load credentials using the aws sdk defaults. Field Description secretRef AWSAuthSecretRef (Optional) jwt AWSJWTAuth (Optional) AWSAuthSecretRef ( Appears on: AWSAuth ) AWSAuthSecretRef holds secret references for AWS credentials both AccessKeyID and SecretAccessKey must be defined in order to properly authenticate. Field Description accessKeyIDSecretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector The AccessKeyID is used for authentication secretAccessKeySecretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector The SecretAccessKey is used for authentication AWSJWTAuth ( Appears on: AWSAuth ) Authenticate against AWS using service account tokens. Field Description serviceAccountRef github.com/external-secrets/external-secrets/apis/meta/v1.ServiceAccountSelector AWSProvider ( Appears on: SecretStoreProvider ) AWSProvider configures a store to sync secrets with AWS. Field Description service AWSServiceType Service defines which service should be used to fetch the secrets auth AWSAuth (Optional) Auth defines the information necessary to authenticate against AWS if not set aws sdk will infer credentials from your environment see: https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials role string (Optional) Role is a Role ARN which the SecretManager provider will assume region string AWS Region to be used for the provider AWSServiceType ( string alias) ( Appears on: AWSProvider ) AWSServiceType is a enum that defines the service/API that is used to fetch the secrets. Value Description \"ParameterStore\" AWSServiceParameterStore is the AWS SystemsManager ParameterStore. see: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html \"SecretsManager\" AWSServiceSecretsManager is the AWS SecretsManager. see: https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html AkeylessAuth ( Appears on: AkeylessProvider ) Field Description secretRef AkeylessAuthSecretRef AkeylessAuthSecretRef ( Appears on: AkeylessAuth ) AkeylessAuthSecretRef AKEYLESS_ACCESS_TYPE_PARAM: AZURE_OBJ_ID OR GCP_AUDIENCE OR ACCESS_KEY OR KUB_CONFIG_NAME. Field Description accessID github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector The SecretAccessID is used for authentication accessType github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector accessTypeParam github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector AkeylessProvider ( Appears on: SecretStoreProvider ) AkeylessProvider Configures an store to sync secrets using Akeyless KV. Field Description akeylessGWApiURL string Akeyless GW API Url from which the secrets to be fetched from. authSecretRef AkeylessAuth Auth configures how the operator authenticates with Akeyless. AlibabaAuth ( Appears on: AlibabaProvider ) AlibabaAuth contains a secretRef for credentials. Field Description secretRef AlibabaAuthSecretRef AlibabaAuthSecretRef ( Appears on: AlibabaAuth ) AlibabaAuthSecretRef holds secret references for Alibaba credentials. Field Description accessKeyIDSecretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector The AccessKeyID is used for authentication accessKeySecretSecretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector The AccessKeySecret is used for authentication AlibabaProvider ( Appears on: SecretStoreProvider ) AlibabaProvider configures a store to sync secrets using the Alibaba Secret Manager provider. Field Description auth AlibabaAuth endpoint string (Optional) regionID string Alibaba Region to be used for the provider AuthType ( string alias) ( Appears on: AzureKVProvider ) AuthType describes how to authenticate to the Azure Keyvault Only one of the following auth types may be specified. If none of the following auth type is specified, the default one is ServicePrincipal. Value Description \"ManagedIdentity\" Using Managed Identity to authenticate. Used with aad-pod-identity instelled in the clister. \"ServicePrincipal\" Using service principal to authenticate, which needs a tenantId, a clientId and a clientSecret. AzureKVAuth ( Appears on: AzureKVProvider ) Configuration used to authenticate with Azure. Field Description clientId github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector The Azure clientId of the service principle used for authentication. clientSecret github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector The Azure ClientSecret of the service principle used for authentication. AzureKVProvider ( Appears on: SecretStoreProvider ) Configures an store to sync secrets using Azure KV. Field Description authType AuthType (Optional) Auth type defines how to authenticate to the keyvault service. Valid values are: - \u201cServicePrincipal\u201d (default): Using a service principal (tenantId, clientId, clientSecret) - \u201cManagedIdentity\u201d: Using Managed Identity assigned to the pod (see aad-pod-identity) vaultUrl string Vault Url from which the secrets to be fetched from. tenantId string (Optional) TenantID configures the Azure Tenant to send requests to. Required for ServicePrincipal auth type. authSecretRef AzureKVAuth (Optional) Auth configures how the operator authenticates with Azure. Required for ServicePrincipal auth type. identityId string (Optional) If multiple Managed Identity is assigned to the pod, you can select the one to be used CAProvider ( Appears on: VaultProvider ) Defines a location to fetch the cert for the vault provider from. Field Description type CAProviderType The type of provider to use such as \u201cSecret\u201d, or \u201cConfigMap\u201d. name string The name of the object located at the provider type. key string The key the value inside of the provider type to use, only used with \u201cSecret\u201d type namespace string (Optional) The namespace the Provider type is in. CAProviderType ( string alias) ( Appears on: CAProvider ) Value Description \"ConfigMap\" \"Secret\" ClusterSecretStore ClusterSecretStore represents a secure external location for storing secrets, which can be referenced as part of storeRef fields. Field Description metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec SecretStoreSpec controller string (Optional) Used to select the correct KES controller (think: ingress.ingressClassName) The KES controller is instantiated with a specific controller name and filters ES based on this property provider SecretStoreProvider Used to configure the provider. Only one provider may be set retrySettings SecretStoreRetrySettings (Optional) Used to configure http retries if failed status SecretStoreStatus ExternalSecret ExternalSecret is the Schema for the external-secrets API. Field Description metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec ExternalSecretSpec secretStoreRef SecretStoreRef target ExternalSecretTarget refreshInterval Kubernetes meta/v1.Duration RefreshInterval is the amount of time before the values are read again from the SecretStore provider Valid time units are \u201cns\u201d, \u201cus\u201d (or \u201c\u00b5s\u201d), \u201cms\u201d, \u201cs\u201d, \u201cm\u201d, \u201ch\u201d May be set to zero to fetch and create it once. Defaults to 1h. data []ExternalSecretData (Optional) Data defines the connection between the Kubernetes Secret keys and the Provider data dataFrom []ExternalSecretDataRemoteRef (Optional) DataFrom is used to fetch all properties from a specific Provider data If multiple entries are specified, the Secret keys are merged in the specified order status ExternalSecretStatus ExternalSecretConditionType ( string alias) ( Appears on: ExternalSecretStatusCondition ) Value Description \"Deleted\" \"Ready\" ExternalSecretCreationPolicy ( string alias) ( Appears on: ExternalSecretTarget ) ExternalSecretCreationPolicy defines rules on how to create the resulting Secret. Value Description \"Merge\" Merge does not create the Secret, but merges the data fields to the Secret. \"None\" None does not create a Secret (future use with injector). \"Owner\" Owner creates the Secret and sets .metadata.ownerReferences to the ExternalSecret resource. ExternalSecretData ( Appears on: ExternalSecretSpec ) ExternalSecretData defines the connection between the Kubernetes Secret key (spec.data. ) and the Provider data. Field Description secretKey string remoteRef ExternalSecretDataRemoteRef ExternalSecretDataRemoteRef ( Appears on: ExternalSecretData , ExternalSecretSpec ) ExternalSecretDataRemoteRef defines Provider data location. Field Description key string Key is the key used in the Provider, mandatory version string (Optional) Used to select a specific version of the Provider value, if supported property string (Optional) Used to select a specific property of the Provider value (if a map), if supported ExternalSecretSpec ( Appears on: ExternalSecret ) ExternalSecretSpec defines the desired state of ExternalSecret. Field Description secretStoreRef SecretStoreRef target ExternalSecretTarget refreshInterval Kubernetes meta/v1.Duration RefreshInterval is the amount of time before the values are read again from the SecretStore provider Valid time units are \u201cns\u201d, \u201cus\u201d (or \u201c\u00b5s\u201d), \u201cms\u201d, \u201cs\u201d, \u201cm\u201d, \u201ch\u201d May be set to zero to fetch and create it once. Defaults to 1h. data []ExternalSecretData (Optional) Data defines the connection between the Kubernetes Secret keys and the Provider data dataFrom []ExternalSecretDataRemoteRef (Optional) DataFrom is used to fetch all properties from a specific Provider data If multiple entries are specified, the Secret keys are merged in the specified order ExternalSecretStatus ( Appears on: ExternalSecret ) Field Description refreshTime Kubernetes meta/v1.Time refreshTime is the time and date the external secret was fetched and the target secret updated syncedResourceVersion string SyncedResourceVersion keeps track of the last synced version conditions []ExternalSecretStatusCondition (Optional) ExternalSecretStatusCondition ( Appears on: ExternalSecretStatus ) Field Description type ExternalSecretConditionType status Kubernetes core/v1.ConditionStatus reason string (Optional) message string (Optional) lastTransitionTime Kubernetes meta/v1.Time (Optional) ExternalSecretTarget ( Appears on: ExternalSecretSpec ) ExternalSecretTarget defines the Kubernetes Secret to be created There can be only one target per ExternalSecret. Field Description name string (Optional) Name defines the name of the Secret resource to be managed This field is immutable Defaults to the .metadata.name of the ExternalSecret resource creationPolicy ExternalSecretCreationPolicy (Optional) CreationPolicy defines rules on how to create the resulting Secret Defaults to \u2018Owner\u2019 template ExternalSecretTemplate (Optional) Template defines a blueprint for the created Secret resource. immutable bool (Optional) Immutable defines if the final secret will be immutable ExternalSecretTemplate ( Appears on: ExternalSecretTarget ) ExternalSecretTemplate defines a blueprint for the created Secret resource. we can not use native corev1.Secret, it will have empty ObjectMeta values: https://github.com/kubernetes-sigs/controller-tools/issues/448 Field Description type Kubernetes core/v1.SecretType (Optional) metadata ExternalSecretTemplateMetadata (Optional) data map[string]string (Optional) templateFrom []TemplateFrom (Optional) ExternalSecretTemplateMetadata ( Appears on: ExternalSecretTemplate ) ExternalSecretTemplateMetadata defines metadata fields for the Secret blueprint. Field Description annotations map[string]string (Optional) labels map[string]string (Optional) GCPSMAuth ( Appears on: GCPSMProvider ) Field Description secretRef GCPSMAuthSecretRef (Optional) workloadIdentity GCPWorkloadIdentity (Optional) GCPSMAuthSecretRef ( Appears on: GCPSMAuth ) Field Description secretAccessKeySecretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector (Optional) The SecretAccessKey is used for authentication GCPSMProvider ( Appears on: SecretStoreProvider ) GCPSMProvider Configures a store to sync secrets using the GCP Secret Manager provider. Field Description auth GCPSMAuth (Optional) Auth defines the information necessary to authenticate against GCP projectID string ProjectID project where secret is located GCPWorkloadIdentity ( Appears on: GCPSMAuth ) Field Description serviceAccountRef github.com/external-secrets/external-secrets/apis/meta/v1.ServiceAccountSelector clusterLocation string clusterName string GenericStore GenericStore is a common interface for interacting with ClusterSecretStore or a namespaced SecretStore. GitlabAuth ( Appears on: GitlabProvider ) Field Description SecretRef GitlabSecretRef GitlabProvider ( Appears on: SecretStoreProvider ) Configures a store to sync secrets with a GitLab instance. Field Description url string URL configures the GitLab instance URL. Defaults to https://gitlab.com/ . auth GitlabAuth Auth configures how secret-manager authenticates with a GitLab instance. projectID string ProjectID specifies a project where secrets are located. GitlabSecretRef ( Appears on: GitlabAuth ) Field Description accessToken github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector AccessToken is used for authentication. IBMAuth ( Appears on: IBMProvider ) Field Description secretRef IBMAuthSecretRef IBMAuthSecretRef ( Appears on: IBMAuth ) Field Description secretApiKeySecretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector (Optional) The SecretAccessKey is used for authentication IBMProvider ( Appears on: SecretStoreProvider ) Configures an store to sync secrets using a IBM Cloud Secrets Manager backend. Field Description auth IBMAuth Auth configures how secret-manager authenticates with the IBM secrets manager. serviceUrl string ServiceURL is the Endpoint URL that is specific to the Secrets Manager service instance OracleAuth ( Appears on: OracleProvider ) Field Description secretRef OracleSecretRef SecretRef to pass through sensitive information. OracleProvider ( Appears on: SecretStoreProvider ) Configures an store to sync secrets using a Oracle Vault backend. Field Description auth OracleAuth Auth configures how secret-manager authenticates with the Oracle Vault. user string User is an access OCID specific to the account. tenancy string Tenancy is the tenancy OCID where secret is located. region string Region is the region where secret is located. vault string Vault is the vault\u2019s OCID of the specific vault where secret is located. OracleSecretRef ( Appears on: OracleAuth ) Field Description privatekey github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector PrivateKey is the user\u2019s API Signing Key in PEM format, used for authentication. fingerprint github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector Fingerprint is the fingerprint of the API private key. SecretStore SecretStore represents a secure external location for storing secrets, which can be referenced as part of storeRef fields. Field Description metadata Kubernetes meta/v1.ObjectMeta Refer to the Kubernetes API documentation for the fields of the metadata field. spec SecretStoreSpec controller string (Optional) Used to select the correct KES controller (think: ingress.ingressClassName) The KES controller is instantiated with a specific controller name and filters ES based on this property provider SecretStoreProvider Used to configure the provider. Only one provider may be set retrySettings SecretStoreRetrySettings (Optional) Used to configure http retries if failed status SecretStoreStatus SecretStoreConditionType ( string alias) ( Appears on: SecretStoreStatusCondition ) Value Description \"Ready\" SecretStoreProvider ( Appears on: SecretStoreSpec ) SecretStoreProvider contains the provider-specific configration. Field Description aws AWSProvider (Optional) AWS configures this store to sync secrets using AWS Secret Manager provider azurekv AzureKVProvider (Optional) AzureKV configures this store to sync secrets using Azure Key Vault provider akeyless AkeylessProvider (Optional) Akeyless configures this store to sync secrets using Akeyless Vault provider vault VaultProvider (Optional) Vault configures this store to sync secrets using Hashi provider gcpsm GCPSMProvider (Optional) GCPSM configures this store to sync secrets using Google Cloud Platform Secret Manager provider oracle OracleProvider (Optional) Oracle configures this store to sync secrets using Oracle Vault provider ibm IBMProvider (Optional) IBM configures this store to sync secrets using IBM Cloud provider yandexlockbox YandexLockboxProvider (Optional) YandexLockbox configures this store to sync secrets using Yandex Lockbox provider gitlab GitlabProvider (Optional) GItlab configures this store to sync secrets using Gitlab Variables provider alibaba AlibabaProvider (Optional) Alibaba configures this store to sync secrets using Alibaba Cloud provider webhook WebhookProvider (Optional) Webhook configures this store to sync secrets using a generic templated webhook SecretStoreRef ( Appears on: ExternalSecretSpec ) SecretStoreRef defines which SecretStore to fetch the ExternalSecret data. Field Description name string Name of the SecretStore resource kind string (Optional) Kind of the SecretStore resource (SecretStore or ClusterSecretStore) Defaults to SecretStore SecretStoreRetrySettings ( Appears on: SecretStoreSpec ) Field Description maxRetries int32 retryInterval string SecretStoreSpec ( Appears on: ClusterSecretStore , SecretStore ) SecretStoreSpec defines the desired state of SecretStore. Field Description controller string (Optional) Used to select the correct KES controller (think: ingress.ingressClassName) The KES controller is instantiated with a specific controller name and filters ES based on this property provider SecretStoreProvider Used to configure the provider. Only one provider may be set retrySettings SecretStoreRetrySettings (Optional) Used to configure http retries if failed SecretStoreStatus ( Appears on: ClusterSecretStore , SecretStore ) SecretStoreStatus defines the observed state of the SecretStore. Field Description conditions []SecretStoreStatusCondition (Optional) SecretStoreStatusCondition ( Appears on: SecretStoreStatus ) Field Description type SecretStoreConditionType status Kubernetes core/v1.ConditionStatus reason string (Optional) message string (Optional) lastTransitionTime Kubernetes meta/v1.Time (Optional) TemplateFrom ( Appears on: ExternalSecretTemplate ) Field Description configMap TemplateRef secret TemplateRef TemplateRef ( Appears on: TemplateFrom ) Field Description name string items []TemplateRefItem TemplateRefItem ( Appears on: TemplateRef ) Field Description key string VaultAppRole ( Appears on: VaultAuth ) VaultAppRole authenticates with Vault using the App Role auth mechanism, with the role and secret stored in a Kubernetes Secret resource. Field Description path string Path where the App Role authentication backend is mounted in Vault, e.g: \u201capprole\u201d roleId string RoleID configured in the App Role authentication backend when setting up the authentication backend in Vault. secretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector Reference to a key in a Secret that contains the App Role secret used to authenticate with Vault. The key field must be specified and denotes which entry within the Secret resource is used as the app role secret. VaultAuth ( Appears on: VaultProvider ) VaultAuth is the configuration used to authenticate with a Vault server. Only one of tokenSecretRef , appRole , kubernetes , ldap , jwt or cert can be specified. Field Description tokenSecretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector (Optional) TokenSecretRef authenticates with Vault by presenting a token. appRole VaultAppRole (Optional) AppRole authenticates with Vault using the App Role auth mechanism, with the role and secret stored in a Kubernetes Secret resource. kubernetes VaultKubernetesAuth (Optional) Kubernetes authenticates with Vault by passing the ServiceAccount token stored in the named Secret resource to the Vault server. ldap VaultLdapAuth (Optional) Ldap authenticates with Vault by passing username/password pair using the LDAP authentication method jwt VaultJwtAuth (Optional) Jwt authenticates with Vault by passing role and JWT token using the JWT/OIDC authentication method cert VaultCertAuth (Optional) Cert authenticates with TLS Certificates by passing client certificate, private key and ca certificate Cert authentication method VaultCertAuth ( Appears on: VaultAuth ) VaultJwtAuth authenticates with Vault using the JWT/OIDC authentication method, with the role name and token stored in a Kubernetes Secret resource. Field Description clientCert github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector (Optional) ClientCert is a certificate to authenticate using the Cert Vault authentication method secretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector SecretRef to a key in a Secret resource containing client private key to authenticate with Vault using the Cert authentication method VaultJwtAuth ( Appears on: VaultAuth ) VaultJwtAuth authenticates with Vault using the JWT/OIDC authentication method, with the role name and token stored in a Kubernetes Secret resource. Field Description path string Path where the JWT authentication backend is mounted in Vault, e.g: \u201cjwt\u201d role string (Optional) Role is a JWT role to authenticate using the JWT/OIDC Vault authentication method secretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector SecretRef to a key in a Secret resource containing JWT token to authenticate with Vault using the JWT/OIDC authentication method VaultKVStoreVersion ( string alias) ( Appears on: VaultProvider ) Value Description \"v1\" \"v2\" VaultKubernetesAuth ( Appears on: VaultAuth ) Authenticate against Vault using a Kubernetes ServiceAccount token stored in a Secret. Field Description mountPath string Path where the Kubernetes authentication backend is mounted in Vault, e.g: \u201ckubernetes\u201d serviceAccountRef github.com/external-secrets/external-secrets/apis/meta/v1.ServiceAccountSelector (Optional) Optional service account field containing the name of a kubernetes ServiceAccount. If the service account is specified, the service account secret token JWT will be used for authenticating with Vault. If the service account selector is not supplied, the secretRef will be used instead. secretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector (Optional) Optional secret field containing a Kubernetes ServiceAccount JWT used for authenticating with Vault. If a name is specified without a key, token is the default. If one is not specified, the one bound to the controller will be used. role string A required field containing the Vault Role to assume. A Role binds a Kubernetes ServiceAccount with a set of Vault policies. VaultLdapAuth ( Appears on: VaultAuth ) VaultLdapAuth authenticates with Vault using the LDAP authentication method, with the username and password stored in a Kubernetes Secret resource. Field Description path string Path where the LDAP authentication backend is mounted in Vault, e.g: \u201cldap\u201d username string Username is a LDAP user name used to authenticate using the LDAP Vault authentication method secretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector SecretRef to a key in a Secret resource containing password for the LDAP user used to authenticate with Vault using the LDAP authentication method VaultProvider ( Appears on: SecretStoreProvider ) Configures an store to sync secrets using a HashiCorp Vault KV backend. Field Description auth VaultAuth Auth configures how secret-manager authenticates with the Vault server. server string Server is the connection address for the Vault server, e.g: \u201c https://vault.example.com:8200\u201d . path string (Optional) Path is the mount path of the Vault KV backend endpoint, e.g: \u201csecret\u201d. The v2 KV secret engine version specific \u201c/data\u201d path suffix for fetching secrets from Vault is optional and will be appended if not present in specified path. version VaultKVStoreVersion Version is the Vault KV secret engine version. This can be either \u201cv1\u201d or \u201cv2\u201d. Version defaults to \u201cv2\u201d. namespace string (Optional) Name of the vault namespace. Namespaces is a set of features within Vault Enterprise that allows Vault environments to support Secure Multi-tenancy. e.g: \u201cns1\u201d. More about namespaces can be found here https://www.vaultproject.io/docs/enterprise/namespaces caBundle []byte (Optional) PEM encoded CA bundle used to validate Vault server certificate. Only used if the Server URL is using HTTPS protocol. This parameter is ignored for plain HTTP protocol connection. If not set the system root certificates are used to validate the TLS connection. caProvider CAProvider (Optional) The provider for the CA bundle to use to validate Vault server certificate. readYourWrites bool (Optional) ReadYourWrites ensures isolated read-after-write semantics by providing discovered cluster replication states in each request. More information about eventual consistency in Vault can be found here https://www.vaultproject.io/docs/enterprise/consistency forwardInconsistent bool (Optional) ForwardInconsistent tells Vault to forward read-after-write requests to the Vault leader instead of simply retrying within a loop. This can increase performance if the option is enabled serverside. https://www.vaultproject.io/docs/configuration/replication#allow_forwarding_via_header WebhookCAProvider ( Appears on: WebhookProvider ) Defines a location to fetch the cert for the webhook provider from. Field Description type WebhookCAProviderType The type of provider to use such as \u201cSecret\u201d, or \u201cConfigMap\u201d. name string The name of the object located at the provider type. key string The key the value inside of the provider type to use, only used with \u201cSecret\u201d type namespace string (Optional) The namespace the Provider type is in. WebhookCAProviderType ( string alias) ( Appears on: WebhookCAProvider ) Value Description \"ConfigMap\" \"Secret\" WebhookProvider ( Appears on: SecretStoreProvider ) AkeylessProvider Configures an store to sync secrets using Akeyless KV. Field Description method string Webhook Method url string Webhook url to call headers map[string]string (Optional) Headers body string (Optional) Body timeout Kubernetes meta/v1.Duration (Optional) Timeout result WebhookResult Result formatting secrets []WebhookSecret (Optional) Secrets to fill in templates These secrets will be passed to the templating function as key value pairs under the given name caBundle []byte (Optional) PEM encoded CA bundle used to validate webhook server certificate. Only used if the Server URL is using HTTPS protocol. This parameter is ignored for plain HTTP protocol connection. If not set the system root certificates are used to validate the TLS connection. caProvider WebhookCAProvider (Optional) The provider for the CA bundle to use to validate webhook server certificate. WebhookResult ( Appears on: WebhookProvider ) Field Description jsonPath string (Optional) Json path of return value WebhookSecret ( Appears on: WebhookProvider ) Field Description name string Name of this secret in templates secretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector Secret ref to fill in credentials YandexLockboxAuth ( Appears on: YandexLockboxProvider ) Field Description authorizedKeySecretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector (Optional) The authorized key used for authentication YandexLockboxCAProvider ( Appears on: YandexLockboxProvider ) Field Description certSecretRef github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector YandexLockboxProvider ( Appears on: SecretStoreProvider ) YandexLockboxProvider Configures a store to sync secrets using the Yandex Lockbox provider. Field Description apiEndpoint string (Optional) Yandex.Cloud API endpoint (e.g. \u2018api.cloud.yandex.net:443\u2019) auth YandexLockboxAuth Auth defines the information necessary to authenticate against Yandex Lockbox caProvider YandexLockboxCAProvider (Optional) The provider for the CA bundle to use to validate Yandex.Cloud server certificate. Generated with gen-crd-api-reference-docs .","title":"API specification"},{"location":"snippets/provider-aws-access/","text":"AWS Authentication Controller's Pod Identity This is basicially a zero-configuration authentication method that inherits the credentials from the runtime environment using the aws sdk default credential chain . You can attach a role to the pod using IRSA , kiam or kube2iam . When no other authentication method is configured in the Kind=Secretstore this role is used to make all API calls against AWS Secrets Manager or SSM Parameter Store. Based on the Pod's identity you can do a sts:assumeRole before fetching the secrets to limit access to certain keys in your provider. This is optional. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: do a sts:assumeRole before fetching secrets role : team-b Access Key ID & Secret Access Key You can store Access Key ID & Secret Access Key in a Kind=Secret and reference it from a SecretStore. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: assume role before fetching secrets role : team-b auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key EKS Service Account credentials This feature lets you use short-lived service account tokens to authenticate with AWS. You must have Service Account Volume Projection enabled - it is by default on EKS. See EKS guide on how to set up IAM roles for service accounts. The big advantage of this approach is that ESO runs without any credentials. apiVersion : v1 kind : ServiceAccount metadata : annotations : eks.amazonaws.com/role-arn : arn:aws:iam::123456789012:role/team-a name : my-serviceaccount namespace : default Reference the service account from above in the Secret Store: apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager region : eu-central-1 auth : jwt : serviceAccountRef : name : my-serviceaccount","title":"Provider aws access"},{"location":"snippets/provider-aws-access/#aws-authentication","text":"","title":"AWS Authentication"},{"location":"snippets/provider-aws-access/#controllers-pod-identity","text":"This is basicially a zero-configuration authentication method that inherits the credentials from the runtime environment using the aws sdk default credential chain . You can attach a role to the pod using IRSA , kiam or kube2iam . When no other authentication method is configured in the Kind=Secretstore this role is used to make all API calls against AWS Secrets Manager or SSM Parameter Store. Based on the Pod's identity you can do a sts:assumeRole before fetching the secrets to limit access to certain keys in your provider. This is optional. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: do a sts:assumeRole before fetching secrets role : team-b","title":"Controller's Pod Identity"},{"location":"snippets/provider-aws-access/#access-key-id-secret-access-key","text":"You can store Access Key ID & Secret Access Key in a Kind=Secret and reference it from a SecretStore. apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : team-b-store spec : provider : aws : service : SecretsManager region : eu-central-1 # optional: assume role before fetching secrets role : team-b auth : secretRef : accessKeyIDSecretRef : name : awssm-secret key : access-key secretAccessKeySecretRef : name : awssm-secret key : secret-access-key","title":"Access Key ID &amp; Secret Access Key"},{"location":"snippets/provider-aws-access/#eks-service-account-credentials","text":"This feature lets you use short-lived service account tokens to authenticate with AWS. You must have Service Account Volume Projection enabled - it is by default on EKS. See EKS guide on how to set up IAM roles for service accounts. The big advantage of this approach is that ESO runs without any credentials. apiVersion : v1 kind : ServiceAccount metadata : annotations : eks.amazonaws.com/role-arn : arn:aws:iam::123456789012:role/team-a name : my-serviceaccount namespace : default Reference the service account from above in the Secret Store: apiVersion : external-secrets.io/v1alpha1 kind : SecretStore metadata : name : secretstore-sample spec : provider : aws : service : SecretsManager region : eu-central-1 auth : jwt : serviceAccountRef : name : my-serviceaccount","title":"EKS Service Account credentials"}]}