From d5977164c0b210b166924fc7d781336fcd395f55 Mon Sep 17 00:00:00 2001 From: Kevin Joiner Date: Wed, 24 May 2023 08:40:18 -0400 Subject: [PATCH 1/4] Add docs page for rancher-webhook --- docs/reference-guides/rancher-webhook.md | 36 ++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/reference-guides/rancher-webhook.md diff --git a/docs/reference-guides/rancher-webhook.md b/docs/reference-guides/rancher-webhook.md new file mode 100644 index 00000000000..4ad343957fd --- /dev/null +++ b/docs/reference-guides/rancher-webhook.md @@ -0,0 +1,36 @@ +--- +title: Rancher Webhook +--- + +Rancher-Webhook is an essential component of Rancher that works in conjunction with Kubernetes to enhance security and enable critical features for Rancher-managed clusters. + +It integrates with Kubernetes' extensible admission controllers, as described in the [Kubernetes documentation](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/), which allows Rancher-Webhook to inspect specific requests sent to the Kubernetes API server, and add custom, Rancher-specific validation and mutations to the requests that are specific to Rancher. Rancher-Webhook manages the resources to be validated using the `rancher.cattle.io` `ValidatingWebhookConfiguration` and the `rancher.cattle.io` `MutatingWebhookConfiguration`, and will override any manual edits. +Rancher deploys Rancher-Webhook as a separate deployment and service in both local and downstream clusters. Rancher manages Rancher-Webhook using Helm. It's important to note that Rancher may override modifications made by users to the Helm release. + +## Why do we need it? + +Rancher-Webhook is crucial for Rancher to protect clusters against malicious attacks and enable various features. +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. + +## Common Issues + +### EKS Cluster with Calico CNI + +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 [documented by calico](https://docs.tigera.io/calico/latest/getting-started/kubernetes/managed-public-cloud/eks#install-eks-with-calico-networking) involves setting `hostNetwork=true` for the webhook deployment. Users can change this using the Helm commands below on the affected clusters. + +``` bash +helm repo add rancher-charts https://charts.rancher.io +helm upgrade --reuse-values rancher-webhook rancher-chart/rancher-webhook -n cattle-system --set global.hostNetwork=true +``` +**Note:** This temporary workaround may violate an environment's security policy. This workaround also requires that port 9443 is unused on the host network. + +### Private GKE Cluster + +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: + +``` +Internal error occurred: failed calling webhook "rancher.cattle.io.namespaces.create-non-kubesystem": failed to call webhook: Post "https://rancher-webhook.cattle-system.svc:443/v1/webhook/validation/namespaces?timeout=10s": context deadline exceeded +``` +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 [GKE documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules) for detailed information and steps on updating the firewall rules. From 3c7b6b0e4f3626bbf6896ea4bb21c74722990035 Mon Sep 17 00:00:00 2001 From: Billy Tat Date: Thu, 22 Jun 2023 13:36:06 -0700 Subject: [PATCH 2/4] Fix typo --- docs/reference-guides/rancher-webhook.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference-guides/rancher-webhook.md b/docs/reference-guides/rancher-webhook.md index 4ad343957fd..42e3f11ec3c 100644 --- a/docs/reference-guides/rancher-webhook.md +++ b/docs/reference-guides/rancher-webhook.md @@ -18,7 +18,7 @@ It provides essential protection for Rancher-managed clusters, preventing securi ### EKS Cluster with Calico CNI 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 [documented by calico](https://docs.tigera.io/calico/latest/getting-started/kubernetes/managed-public-cloud/eks#install-eks-with-calico-networking) involves setting `hostNetwork=true` for the webhook deployment. Users can change this using the Helm commands below on the affected clusters. +One workaround for this issue [documented by Calico](https://docs.tigera.io/calico/latest/getting-started/kubernetes/managed-public-cloud/eks#install-eks-with-calico-networking) involves setting `hostNetwork=true` for the webhook deployment. Users can change this using the Helm commands below on the affected clusters. ``` bash helm repo add rancher-charts https://charts.rancher.io From 71a60643f25a73c47c7e2113a05a40026d1947d2 Mon Sep 17 00:00:00 2001 From: Billy Tat Date: Thu, 22 Jun 2023 17:09:55 -0700 Subject: [PATCH 3/4] Add to sidebar --- sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.js b/sidebars.js index d2e86d8095d..b7b11d28c92 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1040,6 +1040,7 @@ const sidebars = { "reference-guides/system-tools", "reference-guides/rke1-template-example-yaml", + "reference-guides/rancher-webhook", { type: 'category', label: 'Rancher Security', From 5e054fd4551fdc1f349e82672202444979bc2af0 Mon Sep 17 00:00:00 2001 From: martyav Date: Fri, 23 Jun 2023 17:35:57 -0400 Subject: [PATCH 4/4] added /v2.7 page and updated v2.7 sidebar --- docs/reference-guides/rancher-webhook.md | 4 ++ .../reference-guides/rancher-webhook.md | 40 +++++++++++++++++++ versioned_sidebars/version-2.7-sidebars.json | 1 + 3 files changed, 45 insertions(+) create mode 100644 versioned_docs/version-2.7/reference-guides/rancher-webhook.md diff --git a/docs/reference-guides/rancher-webhook.md b/docs/reference-guides/rancher-webhook.md index 42e3f11ec3c..41bd42226b3 100644 --- a/docs/reference-guides/rancher-webhook.md +++ b/docs/reference-guides/rancher-webhook.md @@ -2,6 +2,10 @@ title: Rancher Webhook --- + + + + Rancher-Webhook is an essential component of Rancher that works in conjunction with Kubernetes to enhance security and enable critical features for Rancher-managed clusters. It integrates with Kubernetes' extensible admission controllers, as described in the [Kubernetes documentation](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/), which allows Rancher-Webhook to inspect specific requests sent to the Kubernetes API server, and add custom, Rancher-specific validation and mutations to the requests that are specific to Rancher. Rancher-Webhook manages the resources to be validated using the `rancher.cattle.io` `ValidatingWebhookConfiguration` and the `rancher.cattle.io` `MutatingWebhookConfiguration`, and will override any manual edits. diff --git a/versioned_docs/version-2.7/reference-guides/rancher-webhook.md b/versioned_docs/version-2.7/reference-guides/rancher-webhook.md new file mode 100644 index 00000000000..41bd42226b3 --- /dev/null +++ b/versioned_docs/version-2.7/reference-guides/rancher-webhook.md @@ -0,0 +1,40 @@ +--- +title: Rancher Webhook +--- + + + + + +Rancher-Webhook is an essential component of Rancher that works in conjunction with Kubernetes to enhance security and enable critical features for Rancher-managed clusters. + +It integrates with Kubernetes' extensible admission controllers, as described in the [Kubernetes documentation](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/), which allows Rancher-Webhook to inspect specific requests sent to the Kubernetes API server, and add custom, Rancher-specific validation and mutations to the requests that are specific to Rancher. Rancher-Webhook manages the resources to be validated using the `rancher.cattle.io` `ValidatingWebhookConfiguration` and the `rancher.cattle.io` `MutatingWebhookConfiguration`, and will override any manual edits. +Rancher deploys Rancher-Webhook as a separate deployment and service in both local and downstream clusters. Rancher manages Rancher-Webhook using Helm. It's important to note that Rancher may override modifications made by users to the Helm release. + +## Why do we need it? + +Rancher-Webhook is crucial for Rancher to protect clusters against malicious attacks and enable various features. +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. + +## Common Issues + +### EKS Cluster with Calico CNI + +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 [documented by Calico](https://docs.tigera.io/calico/latest/getting-started/kubernetes/managed-public-cloud/eks#install-eks-with-calico-networking) involves setting `hostNetwork=true` for the webhook deployment. Users can change this using the Helm commands below on the affected clusters. + +``` bash +helm repo add rancher-charts https://charts.rancher.io +helm upgrade --reuse-values rancher-webhook rancher-chart/rancher-webhook -n cattle-system --set global.hostNetwork=true +``` +**Note:** This temporary workaround may violate an environment's security policy. This workaround also requires that port 9443 is unused on the host network. + +### Private GKE Cluster + +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: + +``` +Internal error occurred: failed calling webhook "rancher.cattle.io.namespaces.create-non-kubesystem": failed to call webhook: Post "https://rancher-webhook.cattle-system.svc:443/v1/webhook/validation/namespaces?timeout=10s": context deadline exceeded +``` +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 [GKE documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules) for detailed information and steps on updating the firewall rules. diff --git a/versioned_sidebars/version-2.7-sidebars.json b/versioned_sidebars/version-2.7-sidebars.json index 3d5b769d92f..4551749cd89 100644 --- a/versioned_sidebars/version-2.7-sidebars.json +++ b/versioned_sidebars/version-2.7-sidebars.json @@ -1001,6 +1001,7 @@ "reference-guides/rancher-project-tools", "reference-guides/system-tools", "reference-guides/rke1-template-example-yaml", + "reference-guides/rancher-webhook", { "type": "category", "label": "Rancher Security",