Deployed bbc9b97b9 to main with MkDocs 1.6.1 and mike 2.2.0

main/api/externalsecret/index.html

@@ -1001,6 +1001,67 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#syncwindows" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        SyncWindows
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="SyncWindows">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#example-allow-syncs-only-during-business-hours-mon-fri-0900-1700-utc" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Example: allow syncs only during business hours (Mon-Fri 09:00-17:00 UTC)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#example-block-syncs-during-a-saturday-maintenance-window-0200-0400-utc" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Example: block syncs during a Saturday maintenance window (02:00-04:00 UTC)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#multiple-windows" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Multiple windows
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#interaction-with-refreshinterval" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Interaction with refreshInterval
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -5048,6 +5109,67 @@
     </span>
   </a>
   
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#syncwindows" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        SyncWindows
+      
+    </span>
+  </a>
+  
+    <nav class="md-nav" aria-label="SyncWindows">
+      <ul class="md-nav__list">
+        
+          <li class="md-nav__item">
+  <a href="#example-allow-syncs-only-during-business-hours-mon-fri-0900-1700-utc" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Example: allow syncs only during business hours (Mon-Fri 09:00-17:00 UTC)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#example-block-syncs-during-a-saturday-maintenance-window-0200-0400-utc" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Example: block syncs during a Saturday maintenance window (02:00-04:00 UTC)
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#multiple-windows" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Multiple windows
+      
+    </span>
+  </a>
+  
+</li>
+        
+          <li class="md-nav__item">
+  <a href="#interaction-with-refreshinterval" class="md-nav__link">
+    <span class="md-ellipsis">
+      
+        Interaction with refreshInterval
+      
+    </span>
+  </a>
+  
+</li>
+        
+      </ul>
+    </nav>
+  
 </li>
       
         <li class="md-nav__item">
@@ -5163,6 +5285,44 @@ be transformed and saved as a <code>Kind=Secret</code>:</p>
 <p>If supported by the configured <code>refreshPolicy</code>, you can 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="syncwindows">SyncWindows</h2>
+<p><code>syncWindows</code> restricts <strong>when</strong> periodic refreshes may occur. It is evaluated in UTC and applies only to the <code>Periodic</code> refresh policy (or when <code>refreshPolicy</code> is unset). <code>OnChange</code> and <code>CreatedOnce</code> policies are unaffected.</p>
+<p>A sync-windows block carries a shared <code>kind</code> and a list of <code>schedule + duration</code> entries:</p>
+<ul>
+<li><code>kind: allow</code> -- periodic syncs are permitted <strong>only</strong> while at least one window is active; all other times are blocked.</li>
+<li><code>kind: deny</code> -- periodic syncs are <strong>blocked</strong> while any window is active; all other times proceed normally.</li>
+</ul>
+<p>Each entry in <code>windows</code> uses a standard 5-field cron <code>schedule</code> (UTC) and a <code>duration</code> string (e.g. <code>8h</code>, <code>30m</code>). The window stays open for <code>duration</code> after each schedule firing. A window entry with an unparseable <code>schedule</code> is silently ignored and treated as inactive, so a typo does not permanently block syncs.</p>
+<h3 id="example-allow-syncs-only-during-business-hours-mon-fri-0900-1700-utc">Example: allow syncs only during business hours (Mon-Fri 09:00-17:00 UTC)</h3>
+<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/v1</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">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="nt">syncWindows</span><span class="p">:</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">allow</span>
+<span class="w">    </span><span class="nt">windows</span><span class="p">:</span>
+<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">schedule</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;0</span><span class="nv"> </span><span class="s">9</span><span class="nv"> </span><span class="s">*</span><span class="nv"> </span><span class="s">*</span><span class="nv"> </span><span class="s">1-5&quot;</span><span class="w">  </span><span class="c1"># weekdays at 09:00 UTC</span>
+<span class="w">        </span><span class="nt">duration</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">8h</span><span class="w">              </span><span class="c1"># window open until 17:00 UTC</span>
+</code></pre></div>
+<h3 id="example-block-syncs-during-a-saturday-maintenance-window-0200-0400-utc">Example: block syncs during a Saturday maintenance window (02:00-04:00 UTC)</h3>
+<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/v1</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">refreshInterval</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">30m</span>
+<span class="w">  </span><span class="nt">syncWindows</span><span class="p">:</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">deny</span>
+<span class="w">    </span><span class="nt">windows</span><span class="p">:</span>
+<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">schedule</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;0</span><span class="nv"> </span><span class="s">2</span><span class="nv"> </span><span class="s">*</span><span class="nv"> </span><span class="s">*</span><span class="nv"> </span><span class="s">6&quot;</span><span class="w">  </span><span class="c1"># Saturdays at 02:00 UTC</span>
+<span class="w">        </span><span class="nt">duration</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2h</span><span class="w">            </span><span class="c1"># block until 04:00 UTC</span>
+</code></pre></div>
+<h3 id="multiple-windows">Multiple windows</h3>
+<p>You can list several entries under <code>windows</code>. For <code>kind: allow</code>, the sync is permitted when <strong>any</strong> window is active. For <code>kind: deny</code>, the sync is blocked when <strong>any</strong> window is active.</p>
+<h3 id="interaction-with-refreshinterval">Interaction with refreshInterval</h3>
+<p><code>syncWindows</code> only suppresses sync operations -- it does not change how often the controller checks. The controller still requeues at <code>refreshInterval</code> regardless of whether a sync was blocked. This means that if <code>refreshInterval</code> is longer than <code>window.duration</code>, a window could open and close entirely between two consecutive checks and the sync would be missed for that occurrence. This is by design: <code>refreshInterval</code> is the primary driver; <code>syncWindows</code> is a gate on top of it. To ensure no window occurrence is missed, set <code>refreshInterval</code> to a value shorter than the smallest <code>window.duration</code>.</p>
 <h2 id="features">Features</h2>
 <p>Individual features are described in the <a href="../../guides/introduction/">Guides section</a>:</p>
 <ul>
@@ -5206,6 +5366,16 @@ be transformed and saved as a <code>Kind=Secret</code>:</p>
 <span class="w">  </span><span class="c1"># May be set to zero to fetch and create it once</span>
 <span class="w">  </span><span class="nt">refreshInterval</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;1h0m0s&quot;</span>
 
+<span class="w">  </span><span class="c1"># SyncWindows optionally restricts when periodic refreshes may occur (UTC, Periodic policy only).</span>
+<span class="w">  </span><span class="c1"># kind: allow -- syncs are permitted only while at least one window is active.</span>
+<span class="w">  </span><span class="c1"># kind: deny  -- syncs are blocked while any window is active.</span>
+<span class="w">  </span><span class="c1"># Each window entry uses a standard 5-field cron schedule and a duration.</span>
+<span class="w">  </span><span class="nt">syncWindows</span><span class="p">:</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">allow</span>
+<span class="w">    </span><span class="nt">windows</span><span class="p">:</span>
+<span class="w">      </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">schedule</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;0</span><span class="nv"> </span><span class="s">9</span><span class="nv"> </span><span class="s">*</span><span class="nv"> </span><span class="s">*</span><span class="nv"> </span><span class="s">1-5&quot;</span><span class="w">  </span><span class="c1"># weekdays at 09:00 UTC</span>
+<span class="w">        </span><span class="nt">duration</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">8h</span><span class="w">              </span><span class="c1"># window open until 17:00 UTC</span>
+
 <span class="w">  </span><span class="c1"># the target describes the secret that shall be created</span>
 <span class="w">  </span><span class="c1"># there can only be one target per ExternalSecret</span>
 <span class="w">  </span><span class="nt">target</span><span class="p">:</span>

main/api/spec/index.html

@@ -8848,6 +8848,21 @@ May be set to &ldquo;0s&rdquo; to fetch and create it once. Defaults to 1h0m0s.<
 </tr>
 <tr>
 <td>
+<code>syncWindows</code></br>
+<em>
+<a href="#external-secrets.io/v1.ExternalSecretSyncWindows">
+ExternalSecretSyncWindows
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>SyncWindows optionally restricts when periodic refreshes may occur.
+Evaluated in UTC, only for Periodic refresh policy (or when refreshPolicy is unset).</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>data</code></br>
 <em>
 <a href="#external-secrets.io/v1.ExternalSecretData">
@@ -9883,6 +9898,21 @@ May be set to &ldquo;0s&rdquo; to fetch and create it once. Defaults to 1h0m0s.<
 </tr>
 <tr>
 <td>
+<code>syncWindows</code></br>
+<em>
+<a href="#external-secrets.io/v1.ExternalSecretSyncWindows">
+ExternalSecretSyncWindows
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>SyncWindows optionally restricts when periodic refreshes may occur.
+Evaluated in UTC, only for Periodic refresh policy (or when refreshPolicy is unset).</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>data</code></br>
 <em>
 <a href="#external-secrets.io/v1.ExternalSecretData">
@@ -10060,6 +10090,131 @@ Kubernetes meta/v1.Time
 </tr>
 </tbody>
 </table>
+<h3 id="external-secrets.io/v1.ExternalSecretSyncWindowEntry">ExternalSecretSyncWindowEntry
+</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#external-secrets.io/v1.ExternalSecretSyncWindows">ExternalSecretSyncWindows</a>)
+</p>
+<p>
+<p>ExternalSecretSyncWindowEntry defines a single cron-schedule + duration pair
+within a SyncWindows block.</p>
+</p>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>schedule</code></br>
+<em>
+string
+</em>
+</td>
+<td>
+<p>Schedule is a standard 5-field cron expression evaluated in UTC, or a
+named shorthand such as @daily or @every 1h. It marks the start time of
+each window occurrence.
+Example: &ldquo;0 22 * * 1-5&rdquo; opens a window every weekday at 22:00 UTC.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>duration</code></br>
+<em>
+<a href="https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration">
+Kubernetes meta/v1.Duration
+</a>
+</em>
+</td>
+<td>
+<p>Duration specifies how long the window stays open after each Schedule
+firing. Example: &ldquo;8h&rdquo;.</p>
+</td>
+</tr>
+</tbody>
+</table>
+<h3 id="external-secrets.io/v1.ExternalSecretSyncWindowKind">ExternalSecretSyncWindowKind
+(<code>string</code> alias)</p></h3>
+<p>
+(<em>Appears on:</em>
+<a href="#external-secrets.io/v1.ExternalSecretSyncWindows">ExternalSecretSyncWindows</a>)
+</p>
+<p>
+<p>ExternalSecretSyncWindowKind defines whether a SyncWindow permits or
+blocks periodic refreshes.</p>
+</p>
+<table>
+<thead>
+<tr>
+<th>Value</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr><td><p>&#34;allow&#34;</p></td>
+<td><p>SyncWindowAllow allows periodic refreshes only while at least one window
+in the list is active. Refreshes are blocked at all other times.</p>
+</td>
+</tr><tr><td><p>&#34;deny&#34;</p></td>
+<td><p>SyncWindowDeny blocks periodic refreshes while any window in the list is
+active. Refreshes proceed normally at all other times.</p>
+</td>
+</tr></tbody>
+</table>
+<h3 id="external-secrets.io/v1.ExternalSecretSyncWindows">ExternalSecretSyncWindows
+</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#external-secrets.io/v1.ExternalSecretSpec">ExternalSecretSpec</a>)
+</p>
+<p>
+<p>ExternalSecretSyncWindows optionally restricts when periodic syncs may occur.
+All windows in the list share the same Kind.</p>
+</p>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>kind</code></br>
+<em>
+<a href="#external-secrets.io/v1.ExternalSecretSyncWindowKind">
+ExternalSecretSyncWindowKind
+</a>
+</em>
+</td>
+<td>
+<p>Kind applies to every window in the list.
+&ldquo;allow&rdquo; &ndash; syncs are permitted only while at least one window is active;
+all other times are blocked.
+&ldquo;deny&rdquo;  &ndash; syncs are blocked while any window is active;
+all other times are permitted.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>windows</code></br>
+<em>
+<a href="#external-secrets.io/v1.ExternalSecretSyncWindowEntry">
+[]ExternalSecretSyncWindowEntry
+</a>
+</em>
+</td>
+<td>
+<p>Windows is the list of schedule+duration pairs.</p>
+</td>
+</tr>
+</tbody>
+</table>
 <h3 id="external-secrets.io/v1.ExternalSecretTarget">ExternalSecretTarget
 </h3>
 <p>

main/snippets/full-external-secret.yaml

@@ -29,6 +29,16 @@ spec:
   # May be set to zero to fetch and create it once
   refreshInterval: "1h0m0s"
 
+  # SyncWindows optionally restricts when periodic refreshes may occur (UTC, Periodic policy only).
+  # kind: allow -- syncs are permitted only while at least one window is active.
+  # kind: deny  -- syncs are blocked while any window is active.
+  # Each window entry uses a standard 5-field cron schedule and a duration.
+  syncWindows:
+    kind: allow
+    windows:
+      - schedule: "0 9 * * 1-5"  # weekdays at 09:00 UTC
+        duration: 8h              # window open until 17:00 UTC
+
   # the target describes the secret that shall be created
   # there can only be one target per ExternalSecret
   target: