diff --git a/docs/reference-guides/rancher-webhook.md b/docs/reference-guides/rancher-webhook.md index cabce834237..016ac60cddb 100644 --- a/docs/reference-guides/rancher-webhook.md +++ b/docs/reference-guides/rancher-webhook.md @@ -140,74 +140,3 @@ The webhook provides extra validations on [namespaces](https://github.com/ranche If you roll back to Rancher v2.7.5 or earlier, you may see webhook versions that are too recent to be compatible with downstream clusters running pre-v2.7.5 version of Rancher. This may cause various incompatibility issues. For example, project members may be unable to create namespaces. In addition, when you roll back to versions before the webhook was installed in downstream clusters, the webhook may remain installed, which can result in similar incompatibility issues. 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. - -### Project Users Can't Create Namespaces - -**Note:** The following affects Rancher v2.7.2 - v2.7.4. - -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. - -### Pinning the Webhook - -:::note - -When the `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 v2.8.3 and v2.8.4. The solution is to pin the appropriate version. The following table shows which webhook version to pin 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 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 -``` - -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. - -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: - - name: CATTLE_RANCHER_WEBHOOK_VERSION - value: 103.0.2+up0.4.3 -``` - -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 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 \ - --env CATTLE_RANCHER_WEBHOOK_VERSION=103.0.4+up0.4.5 rancher/rancher:v2.8.4 -``` 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 04975dedabd..f399f5349bd 100644 --- a/versioned_docs/version-2.8/reference-guides/rancher-webhook.md +++ b/versioned_docs/version-2.8/reference-guides/rancher-webhook.md @@ -147,6 +147,8 @@ To help alleviate these issues, you can run the [adjust-downstream-webhook](http The following affects Rancher v2.8.3 and v2.8.4. +::: + When the `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 v2.8.3 and v2.8.4. The solution is to pin the appropriate version. The following table shows which webhook version to pin for each respective version of Rancher: