Deployed 818fc37ee to main with MkDocs 1.6.1 and mike 1.2.0.dev0

main/api/clusterexternalsecret/index.html

@@ -3924,6 +3924,12 @@ If there is a conflict with an existing resource the controller will error out.<
 <span class="w">      </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">secret-store-name</span>
 <span class="w">      </span><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">SecretStore</span>
 
+<span class="w">    </span><span class="c1"># RefreshPolicy determines how the ExternalSecret should be refreshed:</span>
+<span class="w">    </span><span class="c1"># - CreatedOnce: Creates the Secret only if it does not exist and does not update it afterward</span>
+<span class="w">    </span><span class="c1"># - Periodic: (default) Synchronizes the Secret at intervals specified by refreshInterval</span>
+<span class="w">    </span><span class="c1"># - OnChange: Only synchronizes when the ExternalSecret&#39;s metadata or specification changes</span>
+<span class="w">    </span><span class="nt">refreshPolicy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Periodic</span>
+
 <span class="w">    </span><span class="nt">refreshInterval</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;1h&quot;</span>
 <span class="w">    </span><span class="nt">target</span><span class="p">:</span>
 <span class="w">      </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">my-secret</span>
@@ -3968,7 +3974,7 @@ If there is a conflict with an existing resource the controller will error out.<
 <span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&quot;matching-ns-3&quot;</span>
 <span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="s">&quot;matching-ns-2&quot;</span>
 
-<span class="w">  </span><span class="c1"># The condition can be Ready, PartiallyReady, or NotReady </span>
+<span class="w">  </span><span class="c1"># The condition can be Ready, PartiallyReady, or NotReady</span>
 <span class="w">  </span><span class="c1"># PartiallyReady would indicate an error in 1 or more namespaces</span>
 <span class="w">  </span><span class="c1"># NotReady would indicate errors in all namespaces meaning all ExternalSecrets resulted in errors</span>
 <span class="w">  </span><span class="nt">conditions</span><span class="p">:</span>

main/api/externalsecret/index.html

@@ -862,9 +862,51 @@
 </li>
       
         <li class="md-nav__item">
-  <a href="#update-behavior" class="md-nav__link">
+  <a href="#update-behavior-with-3-different-refresh-policies" class="md-nav__link">
     <span class="md-ellipsis">
-      Update Behavior
+      Update behavior with 3 different refresh policies
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Update behavior with 3 different refresh policies">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#createdonce" class="md-nav__link">
+    <span class="md-ellipsis">
+      CreatedOnce
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#periodic" class="md-nav__link">
+    <span class="md-ellipsis">
+      Periodic
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#onchange" class="md-nav__link">
+    <span class="md-ellipsis">
+      OnChange
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#manual-refresh" class="md-nav__link">
+    <span class="md-ellipsis">
+      Manual Refresh
     </span>
   </a>
   
@@ -3843,9 +3885,51 @@
 </li>
       
         <li class="md-nav__item">
-  <a href="#update-behavior" class="md-nav__link">
+  <a href="#update-behavior-with-3-different-refresh-policies" class="md-nav__link">
     <span class="md-ellipsis">
-      Update Behavior
+      Update behavior with 3 different refresh policies
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="Update behavior with 3 different refresh policies">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#createdonce" class="md-nav__link">
+    <span class="md-ellipsis">
+      CreatedOnce
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#periodic" class="md-nav__link">
+    <span class="md-ellipsis">
+      Periodic
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#onchange" class="md-nav__link">
+    <span class="md-ellipsis">
+      OnChange
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#manual-refresh" class="md-nav__link">
+    <span class="md-ellipsis">
+      Manual Refresh
     </span>
   </a>
   
@@ -3901,14 +3985,56 @@ be transformed and saved as a <code>Kind=Secret</code>:</p>
 </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. You can also pull in <code>ConfigMaps</code> that contain golang-template data using <code>templateFrom</code>. 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 one of the following conditions is met and <code>spec.refreshInterval</code> is not <code>0</code>:</p>
-<ul>
-<li>the <code>spec.refreshInterval</code> has passed</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>
+<h2 id="update-behavior-with-3-different-refresh-policies">Update behavior with 3 different refresh policies</h2>
+<p>You can control how and when the <code>ExternalSecret</code> is refreshed by setting the <code>spec.refreshPolicy</code> field. If not specified, the default behavior is <code>Periodic</code>.</p>
+<h3 id="createdonce">CreatedOnce</h3>
+<p>With <code>refreshPolicy: CreatedOnce</code>, the controller will:
+- Create the <code>Kind=Secret</code> only if it does not exist yet
+- Never update the <code>Kind=Secret</code> afterwards if the source data changes
+- Update/ Recreate the <code>Kind=Secret</code> if it gets changed/Deleted
+- Useful for immutable credentials or when you want to manage updates manually</p>
+<p>Example:
+<div class="highlight"><pre><span></span><code><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">external-secrets.io/v1beta1</span>
+<span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ExternalSecret</span>
+<span class="nt">metadata</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">example</span>
+<span class="nt">spec</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">refreshPolicy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">CreatedOnce</span>
+<span class="w">  </span><span class="c1"># other fields...</span>
+</code></pre></div></p>
+<h3 id="periodic">Periodic</h3>
+<p>With <code>refreshPolicy: Periodic</code> (the default behavior), the controller will:
+- Create the <code>Kind=Secret</code> if it doesn't exist
+- Update the <code>Kind=Secret</code> regularly based on the <code>spec.refreshInterval</code> duration
+- When <code>spec.refreshInterval</code> is set to zero, it will only create the secret once and not update it afterward
+- When <code>spec.refreshInterval</code> is set to a value greater than zero, the controller will update the <code>Kind=Secret</code> at the specified interval or when the <code>ExternalSecret</code> specification changes</p>
+<p>Example:
+<div class="highlight"><pre><span></span><code><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">external-secrets.io/v1beta1</span>
+<span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ExternalSecret</span>
+<span class="nt">metadata</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">example</span>
+<span class="nt">spec</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">refreshPolicy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Periodic</span>
+<span class="w">  </span><span class="nt">refreshInterval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">1h</span><span class="w">  </span><span class="c1"># Update every hour</span>
+<span class="w">  </span><span class="c1"># other fields...</span>
+</code></pre></div></p>
+<h3 id="onchange">OnChange</h3>
+<p>With <code>refreshPolicy: OnChange</code>, the controller will:
+- Create the <code>Kind=Secret</code> if it doesn't exist
+- Update the <code>Kind=Secret</code> only when the <code>ExternalSecret</code>'s metadata or specification changes
+- This policy is independent of the <code>refreshInterval</code> value
+- Useful when you want to manually control when the secret is updated, by modifying the <code>ExternalSecret</code> resource</p>
+<p>Example:
+<div class="highlight"><pre><span></span><code><span class="nt">apiVersion</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">external-secrets.io/v1beta1</span>
+<span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ExternalSecret</span>
+<span class="nt">metadata</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">example</span>
+<span class="nt">spec</span><span class="p">:</span>
+<span class="w">  </span><span class="nt">refreshPolicy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">OnChange</span>
+<span class="w">  </span><span class="c1"># other fields...</span>
+</code></pre></div></p>
+<h2 id="manual-refresh">Manual Refresh</h2>
+<p>Regardless of the refresh policy, you can always manually trigger a refresh of the <code>Kind=Secret</code> by updating the annotations of the <code>ExternalSecret</code>:</p>
 <div class="highlight"><pre><span></span><code>kubectl annotate es my-es force-sync=$(date +%s) --overwrite
 </code></pre></div>
 <h2 id="features">Features</h2>
@@ -3943,6 +4069,12 @@ be transformed and saved as a <code>Kind=Secret</code>:</p>
 <span class="w">    </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">aws-store</span>
 <span class="w">    </span><span class="nt">kind</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">SecretStore</span><span class="w">  </span><span class="c1"># or ClusterSecretStore</span>
 
+<span class="w">  </span><span class="c1"># RefreshPolicy determines how the ExternalSecret should be refreshed.</span>
+<span class="w">  </span><span class="c1"># - CreatedOnce: Creates the Secret only if it does not exist and does not update it afterward</span>
+<span class="w">  </span><span class="c1"># - Periodic: (default) Synchronizes the Secret at intervals specified by refreshInterval</span>
+<span class="w">  </span><span class="c1"># - OnChange: Only synchronizes when the ExternalSecret&#39;s metadata or specification changes</span>
+<span class="w">  </span><span class="nt">refreshPolicy</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Periodic</span>
+
 <span class="w">  </span><span class="c1"># RefreshInterval is the amount of time before the values reading again from the SecretStore provider</span>
 <span class="w">  </span><span class="c1"># Valid time units are &quot;ns&quot;, &quot;us&quot; (or &quot;µs&quot;), &quot;ms&quot;, &quot;s&quot;, &quot;m&quot;, &quot;h&quot; (from time.ParseDuration)</span>
 <span class="w">  </span><span class="c1"># May be set to zero to fetch and create it once</span>

main/api/spec/index.html

@@ -6920,6 +6920,24 @@ ExternalSecretTarget
 </tr>
 <tr>
 <td>
+<code>refreshPolicy</code></br>
+<em>
+<a href="#external-secrets.io/v1beta1.ExternalSecretRefreshPolicy">
+ExternalSecretRefreshPolicy
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>RefreshPolicy determines how the ExternalSecret should be refreshed:
+- CreatedOnce: Creates the Secret only if it does not exist and does not update it thereafter
+- Periodic: Synchronizes the Secret from the external source at regular intervals specified by refreshInterval.
+No periodic updates occur if refreshInterval is 0.
+- OnChange: Only synchronizes the Secret when the ExternalSecret&rsquo;s metadata or specification changes</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>refreshInterval</code></br>
 <em>
 <a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration">
@@ -7498,6 +7516,29 @@ map[string]string
 <td></td>
 </tr></tbody>
 </table>
+<h3 id="external-secrets.io/v1beta1.ExternalSecretRefreshPolicy">ExternalSecretRefreshPolicy
+(<code>string</code> alias)</p></h3>
+<p>
+(<em>Appears on:</em>
+<a href="#external-secrets.io/v1beta1.ExternalSecretSpec">ExternalSecretSpec</a>)
+</p>
+<p>
+</p>
+<table>
+<thead>
+<tr>
+<th>Value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr><td><p>&#34;CreatedOnce&#34;</p></td>
+<td></td>
+</tr><tr><td><p>&#34;OnChange&#34;</p></td>
+<td></td>
+</tr><tr><td><p>&#34;Periodic&#34;</p></td>
+<td></td>
+</tr></tbody>
+</table>
 <h3 id="external-secrets.io/v1beta1.ExternalSecretRewrite">ExternalSecretRewrite
 </h3>
 <p>
@@ -7662,6 +7703,24 @@ ExternalSecretTarget
 </tr>
 <tr>
 <td>
+<code>refreshPolicy</code></br>
+<em>
+<a href="#external-secrets.io/v1beta1.ExternalSecretRefreshPolicy">
+ExternalSecretRefreshPolicy
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>RefreshPolicy determines how the ExternalSecret should be refreshed:
+- CreatedOnce: Creates the Secret only if it does not exist and does not update it thereafter
+- Periodic: Synchronizes the Secret from the external source at regular intervals specified by refreshInterval.
+No periodic updates occur if refreshInterval is 0.
+- OnChange: Only synchronizes the Secret when the ExternalSecret&rsquo;s metadata or specification changes</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>refreshInterval</code></br>
 <em>
 <a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration">

main/introduction/faq/index.html

@@ -3932,11 +3932,14 @@ You just need to change an annotation, label or the spec of the resource:</p>
 <div class="highlight"><pre><span></span><code>kubectl annotate es my-es force-sync=$(date +%s) --overwrite
 </code></pre></div>
 <h2 id="how-do-i-know-when-my-secret-was-last-synced">How do I know when my secret was last synced?</h2>
-<p>The last synchronization timestamp of an ExternalSecret can be retrieved from the field <code>refreshTime</code>. </p>
+<p>The last synchronization timestamp of an ExternalSecret can be retrieved from the field <code>refreshTime</code>.</p>
 <div class="highlight"><pre><span></span><code>kubectl get es my-external-secret -o yaml | grep refreshTime
   refreshTime: &quot;2022-05-21T23:02:47Z&quot;
 </code></pre></div>
-<p>The interval can be changed by the <code>spec.refreshInterval</code> in the ExternalSecret.</p>
+<p>The interval can be changed by the <code>spec.refreshInterval</code> in the ExternalSecret. You can also control the refresh behavior by setting <code>spec.refreshPolicy</code> to one of the following options:
+- <code>Periodic</code> (default): Update regularly based on refreshInterval
+- <code>CreatedOnce</code>: Create the Secret only once and never update it afterward
+- <code>OnChange</code>: Only update when the ExternalSecret's metadata or specification changes</p>
 <h2 id="how-do-i-know-when-the-status-of-my-secret-changed-the-last-time">How do I know when the status of my secret changed the last time?</h2>
 <p>Every ExternalSecret resource contains a status condition that indicates whether a secret was successfully synchronized, along with the timestamp of the last status change of the ExternalSecret (e.g. from SecretSyncedError to SecretSynced). This can be obtained from the field <code>lastTransitionTime</code>:</p>
 <div class="highlight"><pre><span></span><code>kubectl get es my-external-secret -o yaml | grep condition -A 5

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

@@ -33,6 +33,12 @@ spec:
       name: secret-store-name
       kind: SecretStore
 
+    # RefreshPolicy determines how the ExternalSecret should be refreshed:
+    # - CreatedOnce: Creates the Secret only if it does not exist and does not update it afterward
+    # - Periodic: (default) Synchronizes the Secret at intervals specified by refreshInterval
+    # - OnChange: Only synchronizes when the ExternalSecret's metadata or specification changes
+    refreshPolicy: Periodic
+
     refreshInterval: "1h"
     target:
       name: my-secret
@@ -71,13 +77,13 @@ status:
     - namespace: "matching-ns-1"
       # This is one of the possible messages, and likely the most common
       reason: "external secret already exists in namespace"
-  
+
   # You can find all matching and successfully deployed namespaces here
   provisionedNamespaces:
     - "matching-ns-3"
     - "matching-ns-2"
-  
-  # The condition can be Ready, PartiallyReady, or NotReady 
+
+  # The condition can be Ready, PartiallyReady, or NotReady
   # PartiallyReady would indicate an error in 1 or more namespaces
   # NotReady would indicate errors in all namespaces meaning all ExternalSecrets resulted in errors
   conditions:

main/snippets/full-external-secret.yaml

@@ -18,6 +18,12 @@ spec:
     name: aws-store
     kind: SecretStore  # or ClusterSecretStore
 
+  # RefreshPolicy determines how the ExternalSecret should be refreshed.
+  # - CreatedOnce: Creates the Secret only if it does not exist and does not update it afterward
+  # - Periodic: (default) Synchronizes the Secret at intervals specified by refreshInterval
+  # - OnChange: Only synchronizes when the ExternalSecret's metadata or specification changes
+  refreshPolicy: Periodic
+
   # RefreshInterval is the amount of time before the values reading again from the SecretStore provider
   # Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h" (from time.ParseDuration)
   # May be set to zero to fetch and create it once