diff --git a/docs/reference-guides/rancher-webhook.md b/docs/reference-guides/rancher-webhook.md index e09e20320d4..29dd1194660 100644 --- a/docs/reference-guides/rancher-webhook.md +++ b/docs/reference-guides/rancher-webhook.md @@ -146,9 +146,11 @@ Project users may not be able to create namespaces in projects. This includes pr To help alleviate these issues, you can run the [adjust-downstream-webhook](https://github.com/rancherlabs/support-tools/tree/master/adjust-downstream-webhook) shell script after roll back. This script selects and installs the proper webhook version (or removes the webhook entirely) for the corresponding Rancher version. -### Webhook is Unpinned +### Pinning the Webhook -**Note:** The following affects Rancher v2.8.3 - v2.8.4. +:::note + +The following affects Rancher v2.8.3 and v2.8.4. When a Rancher-Webhook deployment is unpinned, it can be automatically updated to a version that is incompatible with the current version of Rancher. This is a known issue for Rancher versions 2.8.3 and 2.8.4. The solution is to *pin* the appropriate version. The following table shows which webhook version to provide for each respective version of Rancher: @@ -161,7 +163,9 @@ When a Rancher-Webhook deployment is unpinned, it can be automatically updated t For example, if you are running Rancher v2.8.3, you need to pin Rancher-Webhook to version 103.0.2+up0.4.3. -Note that if you view the Local cluster in Rancher, and then bring up `Workloads | Deployments`, selecting at least `System Namespaces`, you should see a `rancher-webhook` workload in the `cattle-system` namespace. It will probably have an associated version, but this isn't sufficient to determine if the webhook is pinned to a specific version. To do this, bring up the Rancher kubectl shell, or switch to a terminal session, and run the command +Note that if you view the Local cluster in Rancher, and then bring up `Workloads | Deployments`, selecting at least `System Namespaces`, you should see a `rancher-webhook` workload in the `cattle-system` namespace. It will probably have an associated version, but this isn't sufficient to determine if the webhook is pinned to a specific version. + +To verify if the webhook is pinned, bring up the Rancher kubectl shell, or switch to a terminal session, and run: ```bash kubectl get settings rancher-webhook-version @@ -176,7 +180,7 @@ rancher-webhook-version 103.0.2+up0.4.3 If the webhook is unpinned, the `VALUE` column will be blank. -For helm installations, there are two ways to pin the webhook. If you're using a values file, you would add this block to a YAML file (often called `values.yaml`) to pin the webhook when using Rancher 2.8.3: +There are two ways to pin the webhook in Helm installations. If you're running Rancher v2.8.3 and using a "values" YAML file (typically called `values.yaml`), add this block to the file: ```yaml extraEnv: @@ -184,7 +188,7 @@ extraEnv: value: 103.0.2+up0.4.3 ``` -And then run the command +Then, run the command: ```bash helm upgrade --install rancher rancher-latest/rancher --namespace cattle-system --reuse-values --values PATH/TO/values.yaml @@ -200,7 +204,7 @@ helm upgrade --install rancher rancher-latest/rancher --namespace cattle-system After doing this, the webhook field in the UI should be the value specified in the `helm` command, and the above `kubectl get settings` command should have the same value in the `VALUE` column. -If you're running `rancher` via a `docker` installation, you need to stop and delete the `rancher/rancher` container, and then rerun the `docker run` command, adding the command-line options `--env CATTLE_RANCHER_WEBHOOK_VERSION=` somewhere before `rancher/rancher:`. For example: +If you're running Rancher via a Docker installation, you need to stop and delete the `rancher/rancher` container, and then rerun the `docker run` command, adding the command-line option `--env CATTLE_RANCHER_WEBHOOK_VERSION=` somewhere before `rancher/rancher:`. For example: ```bash docker run -d --restart=unless-stopped -p 8080:80 -p 8081:443 --name rancher --privileged \ diff --git a/versioned_docs/version-2.8/reference-guides/rancher-webhook.md b/versioned_docs/version-2.8/reference-guides/rancher-webhook.md index d454823c9d8..ed17739427f 100644 --- a/versioned_docs/version-2.8/reference-guides/rancher-webhook.md +++ b/versioned_docs/version-2.8/reference-guides/rancher-webhook.md @@ -141,9 +141,11 @@ Project users may not be able to create namespaces in projects. This includes pr To help alleviate these issues, you can run the [adjust-downstream-webhook](https://github.com/rancherlabs/support-tools/tree/master/adjust-downstream-webhook) shell script after roll back. This script selects and installs the proper webhook version (or removes the webhook entirely) for the corresponding Rancher version. -### Webhook is Unpinned +### Pinning the Webhook -**Note:** The following affects Rancher v2.8.3 - v2.8.4. +:::note + +The following affects Rancher v2.8.3 and v2.8.4. When a Rancher-Webhook deployment is unpinned, it can be automatically updated to a version that is incompatible with the current version of Rancher. This is a known issue for Rancher versions 2.8.3 and 2.8.4. The solution is to *pin* the appropriate version. The following table shows which webhook version to provide for each respective version of Rancher: @@ -156,7 +158,9 @@ When a Rancher-Webhook deployment is unpinned, it can be automatically updated t For example, if you are running Rancher v2.8.3, you need to pin Rancher-Webhook to version 103.0.2+up0.4.3. -Note that if you view the Local cluster in Rancher, and then bring up `Workloads | Deployments`, selecting at least `System Namespaces`, you should see a `rancher-webhook` workload in the `cattle-system` namespace. It will probably have an associated version, but this isn't sufficient to determine if the webhook is pinned to a specific version. To do this, bring up the Rancher kubectl shell, or switch to a terminal session, and run the command +Note that if you view the Local cluster in Rancher, and then bring up `Workloads | Deployments`, selecting at least `System Namespaces`, you should see a `rancher-webhook` workload in the `cattle-system` namespace. It will probably have an associated version, but this isn't sufficient to determine if the webhook is pinned to a specific version. + +To verify if the webhook is pinned, bring up the Rancher kubectl shell, or switch to a terminal session, and run: ```bash kubectl get settings rancher-webhook-version @@ -171,7 +175,7 @@ rancher-webhook-version 103.0.2+up0.4.3 If the webhook is unpinned, the `VALUE` column will be blank. -For helm installations, there are two ways to pin the webhook. If you're using a values file, you would add this block to a YAML file (often called `values.yaml`) to pin the webhook when using Rancher 2.8.3: +There are two ways to pin the webhook in Helm installations. If you're running Rancher v2.8.3 and using a "values" YAML file (typically called `values.yaml`), add this block to the file: ```yaml extraEnv: @@ -179,7 +183,7 @@ extraEnv: value: 103.0.2+up0.4.3 ``` -And then run the command +Then, run the command: ```bash helm upgrade --install rancher rancher-latest/rancher --namespace cattle-system --reuse-values --values PATH/TO/values.yaml @@ -195,7 +199,7 @@ helm upgrade --install rancher rancher-latest/rancher --namespace cattle-system After doing this, the webhook field in the UI should be the value specified in the `helm` command, and the above `kubectl get settings` command should have the same value in the `VALUE` column. -If you're running `rancher` via a `docker` installation, you need to stop and delete the `rancher/rancher` container, and then rerun the `docker run` command, adding the command-line options `--env CATTLE_RANCHER_WEBHOOK_VERSION=` somewhere before `rancher/rancher:`. For example: +If you're running Rancher via a Docker installation, you need to stop and delete the `rancher/rancher` container, and then rerun the `docker run` command, adding the command-line option `--env CATTLE_RANCHER_WEBHOOK_VERSION=` somewhere before `rancher/rancher:`. For example: ```bash docker run -d --restart=unless-stopped -p 8080:80 -p 8081:443 --name rancher --privileged \