deploy: 95604bb338

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.d66e0677.css">
-<link rel="preload" href="/assets/js/runtime~main.291dd07c.js" as="script">
-<link rel="preload" href="/assets/js/main.81d33ff5.js" as="script">
+<link rel="preload" href="/assets/js/runtime~main.5d35b92a.js" as="script">
+<link rel="preload" href="/assets/js/main.aa01575b.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>
@@ -28,7 +28,7 @@ Rancher deploys Rancher-Webhook as a separate deployment and service in both loc
 Rancher relies on the Rancher-Webhook as an integral part of its functionality. Without the webhook, Rancher would not be a complete product.
 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="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 <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. Users can change this using the Helm commands below on the affected clusters.</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 repo </span><span class="token function" style="color:rgb(130, 170, 255)">add</span><span class="token plain"> rancher-charts https://charts.rancher.io </span><br></span><span class="token-line" style="color:#bfc7d5"><span class="token plain">helm upgrade --reuse-values rancher-webhook rancher-charts/rancher-webhook  -n cattle-system --set global.hostNetwork</span><span class="token operator" style="color:rgb(137, 221, 255)">=</span><span class="token plain">true</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> Helm uses secrets by default. This is a datatype that some webhook versions validate to store information. In these cases, directly update the deployment with the hostNetwork=true value using kubectl, then run the Helm commands listed above to prevent drift between the Helm configuration and the actual state of the cluster.</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 plane to communicate with the Rancher-Webhook on port 9443. Please refer to the <a href="https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules" target="_blank" rel="noopener noreferrer">GKE documentation</a> for detailed information and steps on updating the firewall rules.</p><h3 class="anchor anchorWithStickyNavbar_LWe7" id="application-fails-to-deploy-due-to-rancher-webhook-blocking-access">Application Fails to Deploy Due to rancher-webhook Blocking Access<a href="#application-fails-to-deploy-due-to-rancher-webhook-blocking-access" class="hash-link" aria-label="Direct link to Application Fails to Deploy Due to rancher-webhook Blocking Access" title="Direct link to Application Fails to Deploy Due to rancher-webhook Blocking Access">Line truncated
-<script src="/assets/js/runtime~main.291dd07c.js"></script>
-<script src="/assets/js/main.81d33ff5.js"></script>
+<script src="/assets/js/runtime~main.5d35b92a.js"></script>
+<script src="/assets/js/main.aa01575b.js"></script>
 </body>
 </html>