deploy: 485b3c0c5d

reference-guides/rancher-webhook.html

@@ -15,8 +15,8 @@
 
 <script src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js" charset="UTF-8" data-domain-script="0f98beb0-fc4c-417d-a42e-564e2cae42d2" async></script>
 <script src="/scripts/optanonwrapper.js" async></script><link rel="stylesheet" href="/assets/css/styles.cd075367.css">
-<link rel="preload" href="/assets/js/runtime~main.49ba3b4c.js" as="script">
-<link rel="preload" href="/assets/js/main.7eedd2c2.js" as="script">
+<link rel="preload" href="/assets/js/runtime~main.62e46203.js" as="script">
+<link rel="preload" href="/assets/js/main.2a09f4a6.js" as="script">
 </head>
 <body class="navigation-with-keyboard">
 <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-57KS2MW" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
@@ -29,7 +29,7 @@ Rancher relies on the Rancher-Webhook as an integral part of its functionality.
 It provides essential protection for Rancher-managed clusters, preventing security vulnerabilities and ensuring the consistency and stability of the cluster.</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="what-resources-does-the-webhook-validate">What Resources Does the Webhook Validate?<a href="#what-resources-does-the-webhook-validate" class="hash-link" aria-label="Direct link to What Resources Does the Webhook Validate?" title="Direct link to What Resources Does the Webhook Validate?">​</a></h2><p>You can find an in-progress list of the resources that the webhook validates in the <a href="https://github.com/rancher/webhook/blob/release/v0.4/docs.md" target="_blank" rel="noopener noreferrer">webhook&#x27;s repo</a>. These docs are organized by group/version and resource (top-level header is group/version, next level header is resource). Checks specific to one version can be found by viewing the <code>docs.md</code> file associated with a particular tag (note that webhook versions prior to <code>v0.3.6</code> won&#x27;t have this file).</p><h2 class="anchor anchorWithStickyNavbar_LWe7" id="bypassing-the-webhook">Bypassing the Webhook<a href="#bypassing-the-webhook" class="hash-link" aria-label="Direct link to Bypassing the Webhook" title="Direct link to Bypassing the Webhook">​</a></h2><p>Sometimes, you must bypass Rancher&#x27;s webhook validation to perform emergency restore operations or fix other critical issues. The bypass operation is exhaustive, meaning no webhook validations or mutations apply when you use it. It is not possible to bypass some validations or mutations and have others still apply - they are either all bypassed or all active.</p><div class="theme-admonition theme-admonition-danger alert alert--danger admonition_LlT9"><div class="admonitionHeading_tbUL"><span class="admonitionIcon_kALy"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>danger</div><div class="admonitionContent_S0QG"><p>Rancher&#x27;s webhook provides critical security protections. Bypassing the webhook should only be done by administrators in specific scenarios, after all other options have been exhausted. In addition, permission to bypass the webhook should be carefully controlled, and never given to users who are not admins.</p></div></div><p>To bypass the webhook, impersonate both the <code>rancher-webhook-sudo</code> service account and the <code>system:masters</code> group (both are required):</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">kubectl create -f example.yaml --as</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">system:serviceaccount:cattle-system:rancher-webhook-sudo --as-group</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">system:masters</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h2 class="anchor anchorWithStickyNavbar_LWe7" id="customizing-rancher-webhook-configuration">Customizing Rancher-Webhook Configuration<a href="#customizing-rancher-webhook-configuration" class="hash-link" aria-label="Direct link to Customizing Rancher-Webhook Configuration" title="Direct link to Customizing Rancher-Webhook Configuration">​</a></h2><p>You can add custom Helm values when you install Rancher-Webhook via Helm. During a Helm install of the Rancher-Webhook chart, Rancher checks for custom Helm values. These custom values must be defined in a ConfigMap named <code>rancher-config</code>, in the <code>cattle-system</code> namespace, under the data key, <code>rancher-webhook</code>. The value of this key must be valid YAML.</p><div class="language-yaml codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-backgrouLine truncated
 These values are synced to the <code>rancher-config</code> ConfigMap during installation.</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm </span><span class="token function" style="color:rgb(130, 170, 255)">install</span><span class="token plain"> rancher rancher-</span><span class="token operator" style="color:rgb(137, 221, 255)">&lt;</span><span class="token plain">CHART_REPO</span><span class="token operator" style="color:rgb(137, 221, 255)">&gt;</span><span class="token plain">/rancher </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  --namespace cattle-system </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  </span><span class="token punctuation" style="color:rgb(199, 146, 234)">..</span><span class="token plain">. </span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  --set webhook.port</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token number" style="color:rgb(247, 140, 108)">9553</span><span class="token plain"> </span><span class="token punctuation" style="color:rgb(199, 146, 234)">\</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  --set webhook.priorityClassName</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token string" style="color:rgb(195, 232, 141)">&quot;system-node-critical&quot;</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h2 class="anchor anchorWithStickyNavbar_LWe7" id="common-issues">Common Issues<a href="#common-issues" class="hash-link" aria-label="Direct link to Common Issues" title="Direct link to Common Issues">​</a></h2><h3 class="anchor anchorWithStickyNavbar_LWe7" id="eks-cluster-with-calico-cni">EKS Cluster with Calico CNI<a href="#eks-cluster-with-calico-cni" class="hash-link" aria-label="Direct link to EKS Cluster with Calico CNI" title="Direct link to EKS Cluster with Calico CNI">​</a></h3><p>Users running an EKS cluster with Calico CNI may run into errors when the Kubernetes API server attempts to contact the Rancher-Webhook.
 One workaround for this issue, as <a href="https://docs.tigera.io/calico/latest/getting-started/kubernetes/managed-public-cloud/eks#install-eks-with-calico-networking" target="_blank" rel="noopener noreferrer">documented by Calico</a> involves setting <code>hostNetwork=true</code> for the webhook deployment. You can change this value by adding the Helm value <code>global.hostNetwork=true</code> to the <code>rancher-config</code> ConfigMap. See <a href="#customizing-rancher-webhook-configuration">Customizing Rancher-Webhook Configuration</a> for more info.</p><div class="language-bash codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-bash codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">apiVersion: v1</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">kind: ConfigMap</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">metadata:</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  name: rancher-config</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  namespace: cattle-system</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  labels:</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">    app.kubernetes.io/part-of: </span><span class="token string" style="color:rgb(195, 232, 141)">&quot;rancher&quot;</span><span class="token plain"></span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">data:</span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">  rancher-webhook: </span><span class="token string" style="color:rgb(195, 232, 141)">&#x27;{&quot;global&quot;: {&quot;hostNetwork&quot;: true}}&#x27;</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p><strong>Note:</strong> This temporary workaround may violate an environment&#x27;s security policy. This workaround also requires that port 9443 is unused on the host network.</p><p><strong>Note:</strong> By default, Helm stores information as secrets. Secrets are a resource that some webhook versions validate. In these cases, directly update the deployment with the <code>hostNetwork=true</code> value using kubectl, then update the webhook configuration as specified above.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="private-gke-cluster">Private GKE Cluster<a href="#private-gke-cluster" class="hash-link" aria-label="Direct link to Private GKE Cluster" title="Direct link to Private GKE Cluster">​</a></h3><p>When using a private GKE cluster, errors may occur that prevent the Kubernetes API server from communicating with the webhook. The following error message may appear:</p><div class="codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><div class="codeBlockContent_biex"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#bfc7d5"><span class="token plain">Internal error occurred: failed calling webhook &quot;rancher.cattle.io.namespaces.create-non-kubesystem&quot;: failed to call webhook: Post &quot;https://rancher-webhook.cattle-system.svc:443/v1/webhook/validation/namespaces?timeout=10s&quot;: context deadline exceeded</span><br></span></code></pre><div class="buttonGroup__atx"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_eSgA" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y97N"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_LjdS"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>This issue occurs because firewall rules restrict communication between the API server and the private cluster. To resolve this communication problem, users must add firewall rules to allow the GKE control Line truncated
-<script src="/assets/js/runtime~main.49ba3b4c.js"></script>
-<script src="/assets/js/main.7eedd2c2.js"></script>
+<script src="/assets/js/runtime~main.62e46203.js"></script>
+<script src="/assets/js/main.2a09f4a6.js"></script>
 </body>
 </html>