public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-26 04:58:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into landing-page-longhorn

Browse Source
This commit is contained in:
Billy Tat
2023-10-19 11:00:10 -07:00
committed by GitHub
parent 78c1a71864 3c40971c1d
commit 6491999059
58 changed files with 3133 additions and 2428 deletions
Download Patch File Download Diff File Expand all files Collapse all files
versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rancher-psact.yaml
+3 -1
View File
@@ -17,6 +17,7 @@ plugins:
- cattle-system
- cattle-epinio-system
- cattle-fleet-system
- cattle-fleet-local-system
- longhorn-system
- cattle-neuvector-system
- cattle-monitoring-system
@@ -32,6 +33,7 @@ plugins:
- cattle-sriov-system
- cattle-ui-plugin-system
- tigera-operator
- cattle-provisioning-capi-system
kind: PodSecurityConfiguration
name: PodSecurity
path: ""
path: ""
versioned_docs/version-2.7/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md
+43 -18
View File
@@ -6,29 +6,54 @@ title: Rollbacks
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks"/>
</head>
## Additional Steps for Rollbacks with Rancher v2.6.4+
This page outlines how to rollback Rancher to a previous version after an upgrade.
Rancher v2.6.4 upgrades the cluster-api module from v0.4.4 to v1.0.2. Version v1.0.2 of the cluster-api, in turn, upgrades the Cluster API's Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. The CRDs upgrade to v1beta1 causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x. This is because CRDs that use the older apiVersion (v1alpha4) are incompatible with v1beta1.
Follow the instructions from this page when:
- The running Rancher instance has been upgraded to a newer version after the backup was made.
- The upstream (local) cluster is the same as where the backup was made.
To avoid rollback failure, the following Rancher scripts should be run **before** you attempt a restore operation or rollback:
:::tip
* `verify.sh`: Checks for any Rancher-related resources in the cluster.
* `cleanup.sh`: Cleans up the cluster.
See the [rancher/rancher-cleanup repo](https://github.com/rancher/rancher-cleanup) for more details and source code.
:::caution
There will be downtime while `cleanup.sh` runs, since the script deletes resources created by Rancher.
* Follow these steps to [migrate Rancher](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md).
* If you need to restore Rancher to its previous state at the same Rancher version, see the [restore documentation]( ../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md).
:::
### Rolling back from v2.6.4+ to lower versions of v2.6.x
## Alternative Steps for Special Scenarios
1. Follow these [instructions](https://github.com/rancher/rancher-cleanup/blob/main/README.md) to run the scripts.
1. Follow these [instructions](../../../how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md) to install the rancher-backup Helm chart on the existing cluster and restore the previous state.
1. Omit Step 3.
1. When you reach Step 4, install the Rancher v2.6.x version on the local cluster you intend to roll back to.
Alternative steps need to be performed for rollbacks in the following scenarios:
- Rolling back from v2.6.4 and later to an earlier version of v2.6.x.
- Rolling back from v2.7.7 and later to an earlier version of v2.7.x.
In Rancher v2.6.4, the cluster-api module is upgraded from v0.4.4 to v1.0.2. The cluster-api v1.0.2, in turn, upgrades the apiVersions of its Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. Custom Resources (CRs) that use the older apiVersion (v1alpha4) are incompatible with v1beta1, which causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x.
In Rancher v2.7.7, the app `rancher-provisioning-capi` is installed on the upstream (local) cluster automatically as a replacement for the embedded cluster-api controllers. Conflicts and unexpected errors will occur if the upstream cluster contains both the app, and Rancher v2.7.6 and earlier. Therefore, alternative steps are needed if you attempt to move from Rancher v2.7.7 to any previous version of Rancher v2.7.x.
### Step 1: Clean Up the Upstream (Local) Cluster
To avoid rollback failure, follow these [instructions](https://github.com/rancher/rancher-cleanup/blob/main/README.md) to run the scripts **before** you attempt a restore operation or rollback:
* `cleanup.sh`: Cleans up the cluster.
* `verify.sh`: Checks for any Rancher-related resources in the cluster.
:::caution
There will be downtime while `cleanup.sh` runs, since the script deletes resources created by Rancher.
:::
**Result:** all Rancher-related resources should be cleaned up on the upstream (local) cluster.
See the [rancher/rancher-cleanup repo](https://github.com/rancher/rancher-cleanup) for more details and source code.
### Step 2: Restore the Backup and Bring Up Rancher
At this point, there should be no Rancher-related resources on the upstream cluster. Therefore, the next step will be the same as if you were migrating Rancher to a new cluster that contains no Rancher resources.
Follow these [instructions](./migrate-rancher-to-new-cluster.md) to install the Rancher-Backup Helm chart and restore Rancher to its previous state.
Please keep in mind that:
1. Step 3 can be skipped, because the Cert-Manager app should still exist on the upstream (local) cluster if it was installed before.
2. At Step 4, install the Rancher version you intend to roll back to.
## Rolling Back to Rancher v2.5.0+
@@ -46,7 +71,7 @@ A restore is performed by creating a Restore custom resource.
:::
### Create the Restore Custom Resource
### Step 1: Create the Restore Custom Resource
1. Click **☰ > Cluster Management**.
1. Go to the local cluster and click **Explore**.
@@ -95,7 +120,7 @@ kubectl get pods -n cattle-resources-system
kubectl logs -n cattle-resources-system -f
```
### Roll back to a previous Rancher version
### Step 2: Roll Back to a Previous Rancher Version
Rancher can be rolled back using the Helm CLI. To roll back to the previous version:
versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/air-gapped-helm-cli-install/publish-images.md
+2 -2
View File
@@ -71,7 +71,7 @@ In a Kubernetes Install, if you elect to use the Rancher default self-signed TLS
```plain
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm fetch jetstack/cert-manager --version v1.11.0
helm fetch jetstack/cert-manager
helm template ./cert-manager-<version>.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt
```
@@ -250,7 +250,7 @@ The workstation must have Docker 18.02+ in order to support manifests, which are
```plain
helm repo add jetstack https://charts.jetstack.io
helm repo update
helm fetch jetstack/cert-manager --version v1.11.0
helm fetch jetstack/cert-manager
helm template ./cert-manager-<version>.tgz | awk '$1 ~ /image:/ {print $2}' | sed s/\"//g >> ./rancher-images.txt
```
versioned_docs/version-2.7/getting-started/installation-and-upgrade/other-installation-methods/rancher-behind-an-http-proxy/install-rancher.md
+2 -2
View File
@@ -35,7 +35,7 @@ kubectl create namespace cert-manager
Install the CustomResourceDefinitions of cert-manager:
```
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.crds.yaml
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<VERSION>/cert-manager.crds.yaml
```
And install it with Helm. Note that cert-manager also needs your proxy configured in case it needs to communicate with Let's Encrypt or other external certificate issuers:
@@ -48,7 +48,7 @@ To see options on how to customize the cert-manager install (including for cases
```
helm upgrade --install cert-manager jetstack/cert-manager \
--namespace cert-manager --version v1.11.0 \
--namespace cert-manager \
--set http_proxy=http://${proxy_host} \
--set https_proxy=http://${proxy_host} \
--set no_proxy=127.0.0.0/8\\,10.0.0.0/8\\,cattle-system.svc\\,172.16.0.0/12\\,192.168.0.0/16\\,.svc\\,.cluster.local
versioned_docs/version-2.7/getting-started/installation-and-upgrade/resources/upgrade-cert-manager.md
+4 -3
View File
@@ -6,6 +6,8 @@ title: Upgrading Cert-Manager
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/getting-started/installation-and-upgrade/resources/upgrade-cert-manager"/>
</head>
Rancher is compatible with the API version cert-manager.io/v1 and was last tested with cert-manager version v1.13.1.
Rancher uses cert-manager to automatically generate and renew TLS certificates for HA deployments of Rancher. As of Fall 2019, three important changes to cert-manager are set to occur that you need to take action on if you have an HA deployment of Rancher:
1. [Let's Encrypt will be blocking cert-manager instances older than 0.8.0 starting November 1st 2019.](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753)
@@ -96,8 +98,7 @@ In order to upgrade cert-manager, follow these instructions:
```plain
helm install \
cert-manager jetstack/cert-manager \
--namespace cert-manager \
--version v1.11.0
--namespace cert-manager
```
1. [Restore back up resources](https://cert-manager.io/docs/tutorials/backup/#restoring-resources)
@@ -129,7 +130,7 @@ Before you can perform the upgrade, you must prepare your air gapped environment
1. Fetch the latest cert-manager chart available from the [Helm chart repository](https://artifacthub.io/packages/helm/cert-manager/cert-manager).
```plain
helm fetch jetstack/cert-manager --version v1.11.0
helm fetch jetstack/cert-manager
```
1. Render the cert manager template with the options you would like to use to install the chart. Remember to set the `image.repository` option to pull the image from your private registry. This will create a `cert-manager` directory with the Kubernetes manifest files.
versioned_docs/version-2.7/getting-started/quick-start-guides/deploy-rancher-manager/helm-cli.md
+3 -5
View File
@@ -108,7 +108,7 @@ helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
kubectl create namespace cattle-system
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.crds.yaml
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<VERSION>/cert-manager.crds.yaml
helm repo add jetstack https://charts.jetstack.io
@@ -116,14 +116,12 @@ helm repo update
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--version v1.11.0
--create-namespace
# Windows Powershell
helm install cert-manager jetstack/cert-manager `
--namespace cert-manager `
--create-namespace `
--version v1.11.0
--create-namespace
```
The final command to install Rancher is below. The command requires a domain name that forwards traffic to the Linux machine. For the sake of simplicity in this tutorial, you can use a fake domain name to create your proof-of-concept. An example of a fake domain name would be `<IP_OF_LINUX_NODE>.sslip.io`.
versioned_docs/version-2.7/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md
+4 -1
View File
@@ -85,12 +85,13 @@ Any user that is bound to the above permission will be able to change the restri
## Exempting Required Rancher Namespaces
When you run Rancher on a Kubernetes cluster that enforces a restrictive security policy by default, you'll need to [exempt the following namespaces](#exempting-namespaces), otherwise the policy might prevent Rancher system pods from running properly.
When you run Rancher on a Kubernetes cluster that enforces a restrictive security policy by default, you'll need to [exempt the following namespaces](#exempting-namespaces), otherwise the policy might prevent Rancher system pods from running properly.
- `calico-apiserver`
- `calico-system`
- `cattle-alerting`
- `cattle-csp-adapter-system`
- `cattle-elemental-system`
- `cattle-epinio-system`
- `cattle-externalip-system`
- `cattle-fleet-local-system`
@@ -106,6 +107,8 @@ When you run Rancher on a Kubernetes cluster that enforces a restrictive securit
- `cattle-monitoring-system`
- `cattle-neuvector-system`
- `cattle-prometheus`
- `cattle-provisioning-capi-system`
- `cattle-resources-system`
- `cattle-sriov-system`
- `cattle-system`
- `cattle-ui-plugin-system`
versioned_docs/version-2.7/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/restore-rancher.md
+13 -28
View File
@@ -8,39 +8,24 @@ title: Restoring Rancher
This page outlines how to perform a restore with Rancher.
:::note Important:
Follow the instructions from this page when:
- The running Rancher instance is at the same version as when the backup was made.
- The upstream (local) cluster is the same as where the backup was made.
* Follow the instructions from this page for restoring rancher on the same cluster where it was backed up from. In order to migrate rancher to a new cluster, follow the steps to [migrate rancher.](migrate-rancher-to-new-cluster.md)
* While restoring rancher on the same setup, the operator will scale down the rancher deployment when restore starts, and it will scale back up the deployment once restore completes. So Rancher will be unavailable during the restore.
* If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation.](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md)
:::note Important
While restoring Rancher on the same setup, the operator will scale down the Rancher deployment when restore starts, and it will scale back up the deployment once restore completes. Rancher will be unavailable during the restore.
:::
## Additional Steps for Rollbacks with Rancher v2.6.4+
:::tip
Rancher v2.6.4 upgrades the cluster-api module from v0.4.4 to v1.0.2. Version v1.0.2 of the cluster-api, in turn, upgrades the Cluster API's Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1alpha4` to `cluster.x-k8s.io/v1beta1`. The CRDs upgrade to v1beta1 causes rollbacks to fail when you attempt to move from Rancher v2.6.4 to any previous version of Rancher v2.6.x. This is because CRDs that use the older apiVersion (v1alpha4) are incompatible with v1beta1.
To avoid rollback failure, the following Rancher scripts should be run **before** you attempt a restore operation or rollback:
* `verify.sh`: Checks for any Rancher-related resources in the cluster.
* `cleanup.sh`: Cleans up the cluster.
See the [rancher/rancher-cleanup repo](https://github.com/rancher/rancher-cleanup) for more details and source code.
:::caution
There will be downtime while `cleanup.sh` runs, since the script deletes resources created by Rancher.
* Follow those steps to [migrate Rancher](migrate-rancher-to-new-cluster.md).
* If you need to restore Rancher to a previous version after an upgrade, see the [rollback documentation](../../../getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md).
:::
### Rolling back from v2.6.4+ to lower versions of v2.6.x
1. Follow these [instructions](https://github.com/rancher/rancher-cleanup/blob/main/README.md) to run the scripts.
1. Follow these [instructions](./migrate-rancher-to-new-cluster.md) to install the rancher-backup Helm chart on the existing cluster and restore the previous state.
1. Omit Step 3.
1. When you reach Step 4, install the Rancher v2.6.x version on the local cluster you intend to roll back to.
### Create the Restore Custom Resource
## Create the Restore Custom Resource
A restore is performed by creating a Restore custom resource.
@@ -79,7 +64,7 @@ A restore is performed by creating a Restore custom resource.
2. Cluster-scoped resources
3. Namespaced resources
### Logs
## Logs
To check how the restore is progressing, you can check the logs of the operator. Run this command to follow the logs:
@@ -87,11 +72,11 @@ To check how the restore is progressing, you can check the logs of the operator.
kubectl logs -n cattle-resources-system -l app.kubernetes.io/name=rancher-backup -f
```
### Cleanup
## Cleanup
If you created the restore resource with kubectl, remove the resource to prevent a naming conflict with future restores.
### Known Issues
## Known Issues
In some cases, after restoring the backup, Rancher logs will show errors similar to the following:
```
2021/10/05 21:30:45 [ERROR] error syncing 'c-89d82/m-4067aa68dd78': handler rke-worker-upgrader: clusters.management.cattle.io "c-89d82" not found, requeuing
versioned_docs/version-2.7/pages-for-subheaders/install-upgrade-on-a-kubernetes-cluster.md
+2 -3
View File
@@ -149,7 +149,7 @@ To see options on how to customize the cert-manager install (including for cases
```
# If you have installed the CRDs manually instead of with the `--set installCRDs=true` option added to your Helm install command, you should upgrade your CRD resources before upgrading the Helm chart:
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.0/cert-manager.crds.yaml
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/<VERSION>/cert-manager.crds.yaml
# Add the Jetstack Helm repository
helm repo add jetstack https://charts.jetstack.io
@@ -160,8 +160,7 @@ helm repo update
# Install the cert-manager Helm chart
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--version v1.11.0
--create-namespace
```
Once you’ve installed cert-manager, you can verify it is deployed correctly by checking the cert-manager namespace for running pods:
versioned_docs/version-2.7/pages-for-subheaders/installation-requirements.md
+4
View File
@@ -23,6 +23,10 @@ See our page on [best practices](../reference-guides/best-practices/rancher-serv
Rancher needs to be installed on a supported Kubernetes version. Consult the [Rancher support matrix](https://www.suse.com/suse-rancher/support-matrix/all-supported-versions) to ensure that your intended version of Kubernetes is supported.
### Install Rancher on a Hardened Kubernetes cluster
If you install Rancher on a hardened Kubernetes cluster, check the [Exempting Required Rancher Namespaces](../../../docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/psa-config-templates.md#exempting-required-rancher-namespaces) section for detailed requirements.
## Operating Systems and Container Runtime Requirements
All supported operating systems are 64-bit x86. Rancher should work with any modern Linux distribution.
versioned_docs/version-2.7/pages-for-subheaders/rke1-hardening-guide.md
+38 -35
View File
@@ -209,41 +209,44 @@ services:
exemptions:
usernames: []
runtimeClasses: []
namespaces: [ calico-apiserver,
calico-system,
cattle-alerting,
cattle-csp-adapter-system,
cattle-epinio-system,
cattle-externalip-system,
cattle-fleet-local-system,
cattle-fleet-system,
cattle-gatekeeper-system,
cattle-global-data,
cattle-global-nt,
cattle-impersonation-system,
cattle-istio,
cattle-istio-system,
cattle-logging,
cattle-logging-system,
cattle-monitoring-system,
cattle-neuvector-system,
cattle-prometheus,
cattle-sriov-system,
cattle-system,
cattle-ui-plugin-system,
cattle-windows-gmsa-system,
cert-manager,
cis-operator-system,
fleet-default,
ingress-nginx,
istio-system,
kube-node-lease,
kube-public,
kube-system,
longhorn-system,
rancher-alerting-drivers,
security-scan,
tigera-operator ]
namespaces: [calico-apiserver,
calico-system,
cattle-alerting,
cattle-csp-adapter-system,
cattle-elemental-system,
cattle-epinio-system,
cattle-externalip-system,
cattle-fleet-local-system,
cattle-fleet-system,
cattle-gatekeeper-system,
cattle-global-data,
cattle-global-nt,
cattle-impersonation-system,
cattle-istio,
cattle-istio-system,
cattle-logging,
cattle-logging-system,
cattle-monitoring-system,
cattle-neuvector-system,
cattle-prometheus,
cattle-provisioning-capi-system,
cattle-resources-system,
cattle-sriov-system,
cattle-system,
cattle-ui-plugin-system,
cattle-windows-gmsa-system,
cert-manager,
cis-operator-system,
fleet-default,
ingress-nginx,
istio-system,
kube-node-lease,
kube-public,
kube-system,
longhorn-system,
rancher-alerting-drivers,
security-scan,
tigera-operator]
kube-controller:
extra_args:
feature-gates: RotateKubeletServerCertificate=true
versioned_docs/version-2.7/reference-guides/rancher-security/psa-restricted-exemptions.md
+1
View File
@@ -46,6 +46,7 @@ plugins:
cattle-monitoring-system,
cattle-neuvector-system,
cattle-prometheus,
cattle-provisioning-capi-system,
cattle-resources-system,
cattle-sriov-system,
cattle-system,