deploy: 1704c15e92432994d1682904d737fed3f50bdfcb

api-clustersecretstore/index.html

@@ -690,9 +690,110 @@
                   <h1>ClusterSecretStore</h1>
                 
                 <p><img alt="ClusterSecretStore" src="../pictures/diagrams-high-level-cluster-detail.png" /></p>
-<p>The <code>ClusterSecretStore</code> is a cluster scoped SecretStore that can be used by all
-<code>ExternalSecrets</code> from all namespaces unless you pin down its usage by using
-RBAC or Admission Control.</p>
+<p>The <code>ClusterSecretStore</code> is a cluster scoped SecretStore that can be referenced by all
+<code>ExternalSecrets</code> from all namespaces. Use it to offer a central gateway to your secret backend.</p>
+<div class="highlight"><pre><span></span><code><span class="nt">apiVersion</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">external-secrets.io/v1alpha1</span>
+<span class="nt">kind</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">SecretStore</span>
+<span class="nt">metadata</span><span class="p">:</span>
+  <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">example</span>
+  <span class="nt">namespace</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">example-ns</span>
+<span class="nt">spec</span><span class="p">:</span>
+
+  <span class="c1"># Used to select the correct ESO controller (think: ingress.ingressClassName)</span>
+  <span class="c1"># The ESO controller is instantiated with a specific controller name</span>
+  <span class="c1"># and filters ES based on this property</span>
+  <span class="c1"># Optional</span>
+  <span class="nt">controller</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">dev</span>
+
+  <span class="c1"># provider field contains the configuration to access the provider</span>
+  <span class="c1"># which contains the secret exactly one provider must be configured.</span>
+  <span class="nt">provider</span><span class="p">:</span>
+
+    <span class="c1"># (1): AWS Secrets Manager</span>
+    <span class="c1"># aws configures this store to sync secrets using AWS Secret Manager provider</span>
+    <span class="nt">aws</span><span class="p">:</span>
+      <span class="nt">service</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">SecretsManager</span>
+      <span class="c1"># Role is a Role ARN which the SecretManager provider will assume</span>
+      <span class="nt">role</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">iam-role</span>
+      <span class="c1"># AWS Region to be used for the provider</span>
+      <span class="nt">region</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">eu-central-1</span>
+      <span class="c1"># Auth defines the information necessary to authenticate against AWS by</span>
+      <span class="c1"># getting the accessKeyID and secretAccessKey from an already created Kubernetes Secret</span>
+      <span class="nt">auth</span><span class="p">:</span>
+        <span class="nt">secretRef</span><span class="p">:</span>
+          <span class="nt">accessKeyID</span><span class="p">:</span>
+            <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">awssm-secret</span>
+            <span class="nt">key</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">access-key</span>
+          <span class="nt">secretAccessKey</span><span class="p">:</span>
+            <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">awssm-secret</span>
+            <span class="nt">key</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">secret-access-key</span>
+
+    <span class="nt">vault</span><span class="p">:</span>
+      <span class="nt">server</span><span class="p">:</span> <span class="s">&quot;https://vault.acme.org&quot;</span>
+      <span class="c1"># Path is the mount path of the Vault KV backend endpoint</span>
+      <span class="nt">path</span><span class="p">:</span> <span class="s">&quot;secret&quot;</span>
+      <span class="c1"># Version is the Vault KV secret engine version.</span>
+      <span class="c1"># This can be either &quot;v1&quot; or &quot;v2&quot;, defaults to &quot;v2&quot;</span>
+      <span class="nt">version</span><span class="p">:</span> <span class="s">&quot;v2&quot;</span>
+      <span class="c1"># vault enterprise namespace: https://www.vaultproject.io/docs/enterprise/namespaces</span>
+      <span class="nt">namespace</span><span class="p">:</span> <span class="s">&quot;a-team&quot;</span>
+      <span class="nt">caBundle</span><span class="p">:</span> <span class="s">&quot;...&quot;</span>
+      <span class="nt">auth</span><span class="p">:</span>
+        <span class="c1"># static token: https://www.vaultproject.io/docs/auth/token</span>
+        <span class="nt">tokenSecretRef</span><span class="p">:</span>
+          <span class="nt">name</span><span class="p">:</span> <span class="s">&quot;my-secret&quot;</span>
+          <span class="nt">namespace</span><span class="p">:</span> <span class="s">&quot;secret-admin&quot;</span>
+          <span class="nt">key</span><span class="p">:</span> <span class="s">&quot;vault-token&quot;</span>
+
+        <span class="c1"># AppRole auth: https://www.vaultproject.io/docs/auth/approle</span>
+        <span class="nt">appRole</span><span class="p">:</span>
+          <span class="nt">path</span><span class="p">:</span> <span class="s">&quot;approle&quot;</span>
+          <span class="nt">roleId</span><span class="p">:</span> <span class="s">&quot;db02de05-fa39-4855-059b-67221c5c2f63&quot;</span>
+          <span class="nt">secretRef</span><span class="p">:</span>
+            <span class="nt">name</span><span class="p">:</span> <span class="s">&quot;my-secret&quot;</span>
+            <span class="nt">namespace</span><span class="p">:</span> <span class="s">&quot;secret-admin&quot;</span>
+            <span class="nt">key</span><span class="p">:</span> <span class="s">&quot;vault-token&quot;</span>
+
+        <span class="c1"># Kubernetes auth: https://www.vaultproject.io/docs/auth/kubernetes</span>
+        <span class="nt">kubernetes</span><span class="p">:</span>
+          <span class="nt">mountPath</span><span class="p">:</span> <span class="s">&quot;kubernetes&quot;</span>
+          <span class="nt">role</span><span class="p">:</span> <span class="s">&quot;demo&quot;</span>
+          <span class="c1"># Optional service account reference</span>
+          <span class="nt">serviceAccountRef</span><span class="p">:</span>
+            <span class="nt">name</span><span class="p">:</span> <span class="s">&quot;my-sa&quot;</span>
+            <span class="nt">namespace</span><span class="p">:</span> <span class="s">&quot;secret-admin&quot;</span>
+          <span class="c1"># Optional secret field containing a Kubernetes ServiceAccount JWT</span>
+          <span class="c1"># used for authenticating with Vault</span>
+          <span class="nt">secretRef</span><span class="p">:</span>
+            <span class="nt">name</span><span class="p">:</span> <span class="s">&quot;my-secret&quot;</span>
+            <span class="nt">namespace</span><span class="p">:</span> <span class="s">&quot;secret-admin&quot;</span>
+            <span class="nt">key</span><span class="p">:</span> <span class="s">&quot;vault&quot;</span>
+
+    <span class="c1"># (2): GCP Secret Manager</span>
+    <span class="nt">gcpsm</span><span class="p">:</span>
+      <span class="c1"># Auth defines the information necessary to authenticate against GCP by getting</span>
+      <span class="c1"># the credentials from an already created Kubernetes Secret.</span>
+      <span class="nt">auth</span><span class="p">:</span>
+        <span class="nt">secretRef</span><span class="p">:</span>
+          <span class="nt">secretAccessKeySecretRef</span><span class="p">:</span>
+            <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">gcpsm-secret</span>
+            <span class="nt">key</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">secret-access-credentials</span>
+      <span class="nt">projectID</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">myproject</span>
+    <span class="c1"># (TODO): add more provider examples here</span>
+
+<span class="nt">status</span><span class="p">:</span>
+  <span class="c1"># Standard condition schema</span>
+  <span class="nt">conditions</span><span class="p">:</span>
+  <span class="c1"># SecretStore ready condition indicates the given store is in ready</span>
+  <span class="c1"># state and able to referenced by ExternalSecrets</span>
+  <span class="c1"># If the `status` of this condition is `False`, ExternalSecret controllers</span>
+  <span class="c1"># should prevent attempts to fetch secrets</span>
+  <span class="p p-Indicator">-</span> <span class="nt">type</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">Ready</span>
+    <span class="nt">status</span><span class="p">:</span> <span class="s">&quot;False&quot;</span>
+    <span class="nt">reason</span><span class="p">:</span> <span class="s">&quot;ConfigError&quot;</span>
+    <span class="nt">message</span><span class="p">:</span> <span class="s">&quot;SecretStore</span><span class="nv"> </span><span class="s">validation</span><span class="nv"> </span><span class="s">failed&quot;</span>
+    <span class="nt">lastTransitionTime</span><span class="p">:</span> <span class="s">&quot;2019-08-12T12:33:02Z&quot;</span>
+</code></pre></div>
                 
               
               

api-externalsecret/index.html

@@ -72,7 +72,7 @@
     <div data-md-component="skip">
       
         
-        <a href="#example" class="md-skip">
+        <a href="#template" class="md-skip">
           Skip to content
         </a>
       
@@ -289,6 +289,20 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#template" class="md-nav__link">
+    Template
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#update-behavior" class="md-nav__link">
+    Update Behavior
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#example" class="md-nav__link">
     Example
@@ -726,6 +740,20 @@
     </label>
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
+        <li class="md-nav__item">
+  <a href="#template" class="md-nav__link">
+    Template
+  </a>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#update-behavior" class="md-nav__link">
+    Update Behavior
+  </a>
+  
+</li>
+      
         <li class="md-nav__item">
   <a href="#example" class="md-nav__link">
     Example
@@ -761,6 +789,19 @@ be transformed and saved as a <code>Kind=Secret</code>:</p>
 <li>you can specify how the secret should look like by specifying a
   <code>spec.target.template</code></li>
 </ul>
+<h2 id="template">Template</h2>
+<p>When the controller reconciles the <code>ExternalSecret</code> it will use the <code>spec.template</code> as a blueprint to construct a new <code>Kind=Secret</code>. You can use golang templates to define the blueprint and use template functions to transform secret values. See <a href="../guides-templating/">advanced templating</a> for details.</p>
+<h2 id="update-behavior">Update Behavior</h2>
+<p>The <code>Kind=Secret</code> is updated when:</p>
+<ul>
+<li>the <code>spec.refreshInterval</code> has passed and is not <code>0</code></li>
+<li>the <code>ExternalSecret</code>'s <code>labels</code> or <code>annotations</code> are changed</li>
+<li>the <code>ExternalSecret</code>'s <code>spec</code> has been changed</li>
+</ul>
+<p>You can trigger a secret refresh by using kubectl or any other kubernetes api client:</p>
+<div class="highlight"><pre><span></span><code>kubectl annotate es my-es force-sync=$(date +%s) --overwrite
+</code></pre></div>
+
 <h2 id="example">Example</h2>
 <p>Take a look at an annotated example to understand the design behind the
 <code>ExternalSecret</code>.</p>

api-overview/index.html

@@ -897,7 +897,7 @@ take a look at the provider documentation to see what the Bucket actually maps
 to.</p>
 <p><img alt="Resource Mapping" src="../pictures/diagrams-resource-mapping.png" /></p>
 <h3 id="secretstore">SecretStore</h3>
-<p>The idea behind the <code>SecretStore</code> resource is to separate concerns of
+<p>The idea behind the <a href="../api-secretstore/">SecretStore</a> 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.</p>
@@ -924,7 +924,7 @@ how to access. This resource is namespaced.</p>
 The <code>SecretStore</code> contains references to secrets which hold credentials to
 access the external API.</p>
 <h3 id="externalsecret">ExternalSecret</h3>
-<p>An ExternalSecret declares what data to fetch. It has a reference to a
+<p>An <a href="../api-externalsecret/">ExternalSecret</a> declares what data to fetch. It has a reference to a
 <code>SecretStore</code> which knows how to access that data. The controller uses that
 <code>ExternalSecret</code> as a blueprint to create secrets.</p>
 <div class="highlight"><pre><span></span><code><span class="nt">apiVersion</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">external-secrets.io/v1alpha1</span>
@@ -950,8 +950,8 @@ access the external API.</p>
 </code></pre></div>
 
 <h3 id="clustersecretstore">ClusterSecretStore</h3>
-<p>The <code>ClusterSecretStore</code> is just a global, cluster-wide SecretStore that can be
-referenced from all namespaces.</p>
+<p>The <a href="../api-clustersecretstore/">ClusterSecretStore</a> 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.</p>
 <h2 id="behavior">Behavior</h2>
 <p>The External Secret Operator (ESO for brevity) reconciles <code>ExternalSecrets</code> in
 the following manner:</p>

sitemap.xml

@@ -1,79 +1,79 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url><url>
      <loc>None</loc>
-     <lastmod>2021-06-25</lastmod>
+     <lastmod>2021-06-27</lastmod>
      <changefreq>daily</changefreq>
     </url>
 </urlset>

snippets/full-cluster-secret-store.yaml

@@ -0,0 +1,100 @@
+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 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"
+      caBundle: "..."
+      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"

spec/index.html

@@ -1039,6 +1039,18 @@ SecretStoreProvider
 </table>
 </td>
 </tr>
+<tr>
+<td>
+<code>status</code></br>
+<em>
+<a href="#external-secrets.io/v1alpha1.SecretStoreStatus">
+SecretStoreStatus
+</a>
+</em>
+</td>
+<td>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="external-secrets.io/v1alpha1.ExternalSecret">ExternalSecret
@@ -2068,6 +2080,7 @@ SecretStoreProvider
 </h3>
 <p>
 (<em>Appears on:</em>
+<a href="#external-secrets.io/v1alpha1.ClusterSecretStore">ClusterSecretStore</a>, 
 <a href="#external-secrets.io/v1alpha1.SecretStore">SecretStore</a>)
 </p>
 <p>