public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-27 05:28:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1884 from rancher/main

Browse Source 
Sync v2.12.0 branch with main
This commit is contained in:
Billy Tat
2025-07-18 19:45:14 -07:00
committed by GitHub
parent 4f43b68474 e3eb6400c8
commit 9dab861b3f
367 changed files with 124 additions and 231470 deletions
Download Patch File Download Diff File Expand all files Collapse all files
versioned_docs/version-2.12/how-to-guides/advanced-user-guides/cis-scan-guides/install-rancher-cis-benchmark.md
-6
View File
@@ -13,9 +13,3 @@ title: Install Rancher CIS Benchmark
1. Click **Install**.
**Result:** The CIS scan application is deployed on the Kubernetes cluster.
:::note
If you are running Kubernetes v1.24 or earlier, and have a [Pod Security Policy](../../new-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.md) (PSP) hardened cluster, CIS Benchmark 4.0.0 and later disable PSPs by default. To install CIS Benchmark on a PSP-hardened cluster, set `global.psp.enabled` to `true` in the values before installing the chart. [Pod Security Admission](../../new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md) (PSA) hardened clusters aren't affected.
:::
versioned_docs/version-2.12/how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md
-1
View File
@@ -39,7 +39,6 @@ Values set from the Rancher API will override the value passed in through the co
When installing Rancher with a Helm chart, use the `--set` option. In the below example, two features are enabled by passing the feature flag names in a comma separated list:
For Kubernetes v1.25 or later, set `global.cattle.psp.enabled` to `false` when using Rancher v2.7.2-v2.7.4. This is not necessary for Rancher v2.7.5 and above, but you can still manually set the option if you choose.
```
helm install rancher rancher-latest/rancher \
versioned_docs/version-2.12/how-to-guides/advanced-user-guides/istio-setup-guide/enable-istio-in-cluster.md
-1
View File
@@ -17,7 +17,6 @@ Detailed information can be found in [this announcement](https://forums.suse.com
:::note Prerequisites:
- Only a user with the `cluster-admin` [Kubernetes default role](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) assigned can configure and install Istio in a Kubernetes cluster.
- If you have pod security policies, you will need to install Istio with the CNI enabled. For details, see [this section.](../../../integrations-in-rancher/istio/configuration-options/pod-security-policies.md)
- To install Istio on an RKE2 cluster, additional steps are required. For details, see [this section.](../../../integrations-in-rancher/istio/configuration-options/install-istio-on-rke2-cluster.md)
- To install Istio in a cluster where project network isolation is enabled, additional steps are required. For details, see [this section.](../../../integrations-in-rancher/istio/configuration-options/project-network-isolation.md)
versioned_docs/version-2.12/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies.md
-43
View File
@@ -1,43 +0,0 @@
---
title: Applying Pod Security Policies to Projects
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/advanced-user-guides/manage-projects/manage-pod-security-policies"/>
</head>
:::note
These cluster options are only available for [clusters in which Rancher has launched Kubernetes](../../new-user-guides/launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md).
:::
You can always assign a pod security policy (PSP) to an existing project if you didn't assign one during creation.
### Prerequisites
- Create a Pod Security Policy within Rancher. Before you can assign a default PSP to an existing project, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies](../../new-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.md).
- Assign a default Pod Security Policy to the project's cluster. You can't assign a PSP to a project until one is already applied to the cluster. For more information, see [the documentation about adding a pod security policy to a cluster](../../new-user-guides/manage-clusters/add-a-pod-security-policy.md).
### Applying a Pod Security Policy
1. In the upper left corner, click **☰ > Cluster Management**.
1. On the **Clusters** page, go to the cluster where you want to move a namespace and click **Explore**.
1. Click **Cluster > Projects/Namespaces**.
1. Find the project that you want to add a PSP to. From that project, select **⋮ > Edit Config**.
1. From the **Pod Security Policy** drop-down, select the PSP you want to apply to the project.
Assigning a PSP to a project will:
- Override the cluster's default PSP.
- Apply the PSP to the project.
- Apply the PSP to any namespaces you add to the project later.
1. Click **Save**.
**Result:** The PSP is applied to the project and any namespaces added to the project.
:::note
Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked to determine if they comply with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.
:::
versioned_docs/version-2.12/how-to-guides/advanced-user-guides/manage-projects/manage-projects.md
-1
View File
@@ -24,7 +24,6 @@ You can use projects to perform actions like:
- [Set resource quotas](manage-project-resource-quotas/manage-project-resource-quotas.md)
- [Manage namespaces](../../new-user-guides/manage-namespaces.md)
- [Configure tools](../../../reference-guides/rancher-project-tools.md)
- [Configure pod security policies](manage-pod-security-policies.md)
### Authorization
versioned_docs/version-2.12/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-permissions-and-global-configuration.md
-6
View File
@@ -38,12 +38,6 @@ The user retention feature is disabled by default.
For more information, see [Enabling User Retention](../../advanced-user-guides/enable-user-retention.md).
## Pod Security Policies
_Pod Security Policies_ (or PSPs) are objects that control security-sensitive aspects of pod specification, e.g. root privileges. If a pod does not meet the conditions specified in the PSP, Kubernetes will not allow it to start, and Rancher will display an error message.
For more information how to create and use PSPs, see [Pod Security Policies](create-pod-security-policies.md).
## Provisioning Drivers
Drivers in Rancher allow you to manage which providers can be used to provision [hosted Kubernetes clusters](../kubernetes-clusters-in-rancher-setup/set-up-clusters-from-hosted-kubernetes-providers/set-up-clusters-from-hosted-kubernetes-providers.md) or [nodes in an infrastructure provider](../launch-kubernetes-with-rancher/use-new-nodes-in-an-infra-provider/use-new-nodes-in-an-infra-provider.md) to allow Rancher to deploy and manage Kubernetes.
versioned_docs/version-2.12/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies.md
-82
View File
@@ -1,82 +0,0 @@
---
title: Creating Pod Security Policies
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/create-pod-security-policies"/>
</head>
:::caution
Pod Security Policies are only available in Kubernetes until v1.24. [Pod Security Standards](pod-security-standards.md) are the built-in alternative.
:::
[Pod Security Policies (PSPs)](https://kubernetes.io/docs/concepts/security/pod-security-policy/) are objects that control security-sensitive aspects of the pod specification (such as root privileges).
If a pod doesn't meet the conditions specified in the PSP, Kubernetes won't allow it to start, and Rancher will display the following error message: `Pod <NAME> is forbidden: unable to validate...`.
## How PSPs Work
You can assign PSPs at the cluster or project level.
PSPs work through inheritance:
- By default, PSPs assigned to a cluster are inherited by its projects, as well as any namespaces added to those projects.
- **Exception:** Namespaces that are not assigned to projects do not inherit PSPs, regardless of whether the PSP is assigned to a cluster or project. Because these namespaces have no PSPs, workload deployments to these namespaces will fail, which is the default Kubernetes behavior.
- You can override the default PSP by assigning a different PSP directly to the project.
Any workloads that are already running in a cluster or project before a PSP is assigned will not be checked if it complies with the PSP. Workloads would need to be cloned or upgraded to see if they pass the PSP.
Read more about Pod Security Policies in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/).
## Default PSPs
Rancher ships with three default Pod Security Policies (PSPs): the `restricted-noroot`, `restricted` and `unrestricted` policies.
### Restricted-NoRoot
This policy is based on the Kubernetes [example restricted policy](https://raw.githubusercontent.com/kubernetes/website/master/content/en/examples/policy/restricted-psp.yaml). It significantly restricts what types of pods can be deployed to a cluster or project. This policy:
- Prevents pods from running as a privileged user and prevents escalation of privileges.
- Validates that server-required security mechanisms are in place, such as restricting what volumes can be mounted to only the core volume types and preventing root supplemental groups from being added.
### Restricted
This policy is a relaxed version of the `restricted-noroot` policy, with almost all the restrictions in place, except for the fact that it allows running containers as a privileged user.
### Unrestricted
This policy is equivalent to running Kubernetes with the PSP controller disabled. It has no restrictions on what pods can be deployed into a cluster or project.
:::note important
When disabling PSPs, default PSPs are **not** automatically deleted from your cluster. You must manually delete them if they're no longer needed.
:::
## Creating PSPs
Using Rancher, you can create a Pod Security Policy using our GUI rather than creating a YAML file.
### Requirements
Rancher can only assign PSPs for clusters that are [launched using RKE](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md).
You must enable PSPs at the cluster level before you can assign them to a project. This can be configured by [editing the cluster](../../../reference-guides/cluster-configuration/cluster-configuration.md).
It is a best practice to set PSP at the cluster level.
We recommend adding PSPs during cluster and project creation instead of adding it to an existing one.
### Creating PSPs in the Rancher UI
1. In the upper left corner, click **☰ > Cluster Management**.
1. In the left navigation bar, click **Pod Security Policies**.
1. Click **Add Policy**.
1. Name the policy.
1. Complete each section of the form. Refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) for more information on what each policy does.
1. Click **Create**.
## Configuration
The Kubernetes documentation on PSPs is [here](https://kubernetes.io/docs/concepts/policy/pod-security-policy/).
versioned_docs/version-2.12/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/pod-security-standards.md
-57
View File
@@ -11,54 +11,6 @@ They became available and were turned on by default in Kubernetes v1.23, and rep
PSS define security levels for workloads. PSAs describe requirements for pod security contexts and related fields. PSAs reference PSS levels to define security restrictions.
## Upgrade to Pod Security Standards (PSS)
Ensure that you migrate all PSPs to another workload security mechanism. This includes mapping your current PSPs to Pod Security Standards for enforcement with the [PSA controller](https://kubernetes.io/docs/concepts/security/pod-security-admission/). If the PSA controller won't meet all of your organization's needs, we recommend that you use a policy engine, such as [Kubewarden](https://www.kubewarden.io/), [Kyverno](https://kyverno.io/), or [NeuVector](https://neuvector.com/). Refer to the documentation of your policy engine of choice for more information on how to migrate from PSPs.
:::caution
You must add your new policy enforcement mechanisms _before_ you remove the PodSecurityPolicy objects. If you don't, you may create an opportunity for privilege escalation attacks within the cluster.
:::
### Removing PodSecurityPolicies from Rancher-Maintained Apps & Marketplace Workloads
Rancher v2.7.2 offers a new major version of Rancher-maintained Helm charts. v102.x.y allows you to remove PSPs that were installed with previous versions of the chart. This new version replaces non-standard PSPs switches with the standardized `global.cattle.psp.enabled` switch, which is turned off by default.
You must perform the following steps _while still in Kubernetes v1.24_:
1. Configure the PSA controller to suit your needs. You can use one of Rancher's built-in [PSA Configuration Templates](#pod-security-admission-configuration-templates), or create a custom template and apply it to the clusters that you are migrating.
1. Map your active PSPs to Pod Security Standards:
1. See which PSPs are still active in your cluster:
:::caution
This strategy may miss workloads that aren't currently running, such as CronJobs, workloads currently scaled to zero, or workloads that haven't rolled out yet.
:::
```shell
kubectl get pods \
--all-namespaces \
--output jsonpath='{.items[*].metadata.annotations.kubernetes\.io\/psp}' \
| tr " " "\n" | sort -u
```
1. Follow the Kubernetes guide on [Mapping PSPs to Pod Security Standards](https://kubernetes.io/docs/reference/access-authn-authz/psp-to-pod-security-standards/) to apply PSSs to your workloads that were relying on PSPs. See [Migrate from PodSecurityPolicy to the Built-In PodSecurity Admission controller](https://kubernetes.io/docs/tasks/configure-pod-container/migrate-from-psp/) for more details.
1. To remove PSPs from Rancher charts, upgrade the charts to the latest v102.x.y version _before_ you upgrade to Kubernetes v1.25. Make sure that the **Enable PodSecurityPolicies** option is **disabled**. This will remove any PSPs that were installed with previous chart versions.
:::info important
If you want to upgrade your charts to v102.x.y, but don't plan on upgrading your clusters to Kubernetes v1.25 and moving away from PSPs, make sure that you select the option **Enable PodSecurityPolicies** for each chart that you are upgrading.
:::
### Cleaning Up Releases After a Kubernetes v1.25 Upgrade
If you experience problems while removing PSPs from your charts, or have charts that don't contain a built-in mechanism for removing PSPs, your chart upgrades or deletions might fail with an error message such as the following:
```console
Error: UPGRADE FAILED: resource mapping not found for name: "<object-name>" namespace: "<object-namespace>" from "": no matches for kind "PodSecurityPolicy" in version "policy/v1beta1"
ensure CRDs are installed first
```
This happens when Helm tries to query the cluster for objects that were stored in a previous release's data blob. To clean up these releases and avoid this error, use the `helm-mapkubeapis` Helm plugin. To learn more about `helm-mapkubeapis`, how it works, and how it can be fine-tuned for your use case, see the [official Helm documentation](https://github.com/helm/helm-mapkubeapis#readme).
Note that Helm plugin installation is local to the machine that you run the commands from. Therefore, make sure that you run both the installation and cleanup from the same machine.
#### Install `helm-mapkubeapis`
1. Open your terminal in the machine you intend to use `helm-mapkubeapis` from and install the plugin:
@@ -110,15 +62,6 @@ After you install the `helm-mapkubeapis` plugin, clean up the releases that beca
1. Finally, after reviewing the changes, perform a full run with `helm mapkubeapis <release-name> --namespace <release-namespace>`.
#### Upgrading Charts to a Version That Supports Kubernetes v1.25
You can proceed with your upgrade once any releases that had lingering PSPs are cleaned up. For Rancher-maintained workloads, follow the steps outlined in the [Removing PodSecurityPolicies from Rancher-maintained Apps & Marketplace workloads](#removing-podsecuritypolicies-from-rancher-maintained-apps--marketplace-workloads) section of this document.
For workloads not maintained by Rancher, refer to the vendor documentation.
:::caution
Do not skip this step. Applications incompatible with Kubernetes v1.25 aren't guaranteed to work after a cleanup.
:::
## Pod Security Admission Configuration Templates
Rancher offers PSA configuration templates. These are pre-defined security configurations that you can apply to a cluster. Rancher admins (or those with the right permissions) can [create, manage, and edit](./psa-config-templates.md) PSA templates.
versioned_docs/version-2.12/how-to-guides/new-user-guides/backup-restore-and-disaster-recovery/migrate-rancher-to-new-cluster.md
-1
View File
@@ -168,7 +168,6 @@ Follow the steps to [install cert-manager](../../../getting-started/installation
Use the same version of Helm to install Rancher, that was used on the first cluster.
For Kubernetes v1.25 or later, set `global.cattle.psp.enabled` to `false` when using Rancher v2.7.2-v2.7.4. This is not necessary for Rancher v2.7.5 and above, but you can still manually set the option if you choose.
```bash
helm install rancher rancher-latest/rancher \
versioned_docs/version-2.12/how-to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md
+1 -10
View File
@@ -269,15 +269,7 @@ Therefore, when Rancher registers a cluster, it assumes that several capabilitie
However, if the cluster has a certain capability, such as the ability to use a pod security policy, a user of that cluster might still want to select pod security policies for the cluster in the Rancher UI. In order to do that, the user will need to manually indicate to Rancher that pod security policies are enabled for the cluster.
By annotating a registered cluster, it is possible to indicate to Rancher that a cluster was given a pod security policy, or another capability, outside of Rancher.
This example annotation indicates that a pod security policy is enabled:
```json
"capabilities.cattle.io/pspEnabled": "true"
```
The following annotation indicates Ingress capabilities. Note that the values of non-primitive objects need to be JSON encoded, with quotations escaped.
By annotating a registered cluster, it is possible to indicate to Rancher that a cluster was given Ingress capabilities, or another capability, outside of Rancher. The following annotation indicates Ingress capabilities. Note that the values of non-primitive objects need to be JSON encoded, with quotations escaped.
```json
"capabilities.cattle.io/ingressCapabilities": "[
@@ -294,7 +286,6 @@ These capabilities can be annotated for the cluster:
- `loadBalancerCapabilities`
- `nodePoolScalingSupported`
- `nodePortRange`
- `pspEnabled`
- `taintSupport`
All the capabilities and their type definitions can be viewed in the Rancher API view, at `[Rancher Server URL]/v3/schemas/capabilities`.
versioned_docs/version-2.12/how-to-guides/new-user-guides/manage-clusters/add-a-pod-security-policy.md
-43
View File
@@ -1,43 +0,0 @@
---
title: Adding a Pod Security Policy
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/manage-clusters/add-a-pod-security-policy"/>
</head>
:::note Prerequisite:
The options below are available only for clusters that are [launched using RKE.](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md)
:::
When your cluster is running pods with security-sensitive configurations, assign it a [pod security policy](../authentication-permissions-and-global-configuration/create-pod-security-policies.md), which is a set of rules that monitors the conditions and settings in your pods. If a pod doesn't meet the rules specified in your policy, the policy stops it from running.
You can assign a pod security policy when you provision a cluster. However, if you need to relax or restrict security for your pods later, you can update the policy while editing your cluster.
1. Click **☰ > Cluster Management**.
1. Go to the cluster to which you want to apply a pod security policy and click **⋮ > Edit Config**.
1. From **Pod Security Policy Support**, select **Enabled**.
:::note
This option is only available for clusters [provisioned by RKE](../launch-kubernetes-with-rancher/launch-kubernetes-with-rancher.md).
:::
4. From the **Default Pod Security Policy** drop-down, select the policy you want to apply to the cluster.
Rancher ships with [policies](../authentication-permissions-and-global-configuration/create-pod-security-policies.md#default-psps) of `restricted` and `unrestricted`, although you can [create custom policies](../authentication-permissions-and-global-configuration/create-pod-security-policies.md#creating-psps) as well.
5. Click **Save**.
**Result:** The pod security policy is applied to the cluster and any projects within the cluster.
:::note
Workloads already running before assignment of a pod security policy are grandfathered in. Even if they don't meet your pod security policy, workloads running before assignment of the policy continue to run.
To check if a running workload passes your pod security policy, clone or upgrade it.
:::
versioned_docs/version-2.12/how-to-guides/new-user-guides/manage-clusters/assign-pod-security-policies.md
-29
View File
@@ -1,29 +0,0 @@
---
title: Assigning Pod Security Policies
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/manage-clusters/assign-pod-security-policies"/>
</head>
_Pod Security Policies_ are objects that control security-sensitive aspects of pod specification (like root privileges).
## Adding a Default Pod Security Policy
When you create a new cluster with RKE, you can configure it to apply a PSP immediately. As you create the cluster, use the **Cluster Options** to enable a PSP. The PSP assigned to the cluster will be the default PSP for projects within the cluster.
:::note Prerequisite:
Create a Pod Security Policy within Rancher. Before you can assign a default PSP to a new cluster, you must have a PSP available for assignment. For instruction, see [Creating Pod Security Policies](../authentication-permissions-and-global-configuration/create-pod-security-policies.md).
:::
:::note
For security purposes, we recommend assigning a PSP as you create your clusters.
:::
To enable a default Pod Security Policy, set the **Pod Security Policy Support** option to **Enabled**, and then make a selection from the **Default Pod Security Policy** drop-down.
When the cluster finishes provisioning, the PSP you selected is applied to all projects within the cluster.
versioned_docs/version-2.12/how-to-guides/new-user-guides/manage-clusters/projects-and-namespaces.md
+6 -17
View File
@@ -126,12 +126,11 @@ Rancher extends Kubernetes to allow the application of [Pod Security Policies](h
This section describes how to create a new project with a name and with optional pod security policy, members, and resource quotas.
1. [Name a new project.](#1-name-a-new-project)
2. [Optional: Select a pod security policy.](#2-optional-select-a-pod-security-policy)
3. [Recommended: Add project members.](#3-recommended-add-project-members)
4. [Optional: Add resource quotas.](#4-optional-add-resource-quotas)
1. [Name a new project.](#name-a-new-project)
1. [Recommended: Add project members.](#recommended-add-project-members)
1. [Optional: Add resource quotas.](#optional-add-resource-quotas)
### 1. Name a New Project
### Name a New Project
1. In the upper left corner, click **☰ > Cluster Management**.
1. On the **Clusters** page, go to the cluster you want to project in and click **Explore**.
@@ -139,17 +138,7 @@ This section describes how to create a new project with a name and with optional
1. Click **Create Project**.
1. Enter a **Project Name**.
### 2. Optional: Select a Pod Security Policy
This option is only available if you've already created a Pod Security Policy. For instruction, see [Creating Pod Security Policies](../authentication-permissions-and-global-configuration/create-pod-security-policies.md).
Assigning a PSP to a project will:
- Override the cluster's default PSP.
- Apply the PSP to the project.
- Apply the PSP to any namespaces you add to the project later.
### 3. Recommended: Add Project Members
### Recommended: Add Project Members
Use the **Members** section to provide other users with project access and roles.
@@ -179,7 +168,7 @@ To add members:
:::
1. In the **Project Permissions** section, choose a role. For more information, refer to the [documentation on project roles.](../authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md)
### 4. Optional: Add Resource Quotas
### Optional: Add Resource Quotas
Resource quotas limit the resources that a project (and its namespaces) can consume. For more information, see [Resource Quotas](../../advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md).