Doc how to find an unpinned webhook and pin it.

2026-09-25 04:28:15 +00:00 · 2024-07-23 11:52:44 -07:00
parent b9b6374efa
commit f6f6b8e000
1 changed files with 61 additions and 0 deletions
@@ -145,3 +145,64 @@ To help alleviate these issues, you can run the [adjust-downstream-webhook](http
 Project users may not be able to create namespaces in projects. This includes project owners. This issue is caused by Rancher automatically upgrading the webhook to a version compatible with a more recent version of Rancher than the one currently installed. 

 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
+
+**Note:** The following affects Rancher v2.8.3 - 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:
+
+
+| Rancher Version | Webhook Version |
+|-----------------|-----------------|
+| v2.8.3          | 103.0.2+up0.4.3 |
+| v2.8.4          | 103.0.4+up0.4.5 |
+
+
+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
+
+```bash
+kubectl get settings rancher-webhook-version
+```
+
+If the webhook is pinned, you'll see output with a `VALUE` field that matches the `Webhook Version` from the above table:
+
+```text
+NAME                       VALUE
+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:
+
+```yaml
+extraEnv:
+  - name: CATTLE_RANCHER_WEBHOOK_VERSION
+    value: 103.0.2+up0.4.3
+```
+
+And then run the command
+
+```bash
+helm upgrade --install rancher rancher-latest/rancher --namespace cattle-system --reuse-values --values PATH/TO/values.yaml
+```
+
+You can instead specify the webhook version directly on the command-line:
+
+```bash
+helm upgrade --install rancher rancher-latest/rancher --namespace cattle-system --reuse-values \
+    --set extraEnv[0].name=CATTLE_RANCHER_WEBHOOK_VERSION \
+    --set extraEnv[0].value=103.0.2+up0.4.3
+```
+
+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=<WEBHOOK-VERSION>` somewhere before `rancher/rancher:<VERSION>`.  For example:
+
+```bash
+docker run -d --restart=unless-stopped -p 8080:80 -p 8081:443 --name rancher --privileged \
+    --env CATTLE_RANCHER_WEBHOOK_VERSION=103.0.4+up0.4.5 rancher/rancher:v2.8.4
+```