diff --git a/docs/api/api-tokens.md b/docs/api/api-tokens.md index a05cf03bcfc..2845b69eddc 100644 --- a/docs/api/api-tokens.md +++ b/docs/api/api-tokens.md @@ -6,6 +6,8 @@ title: Using API Tokens + + Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher/cli-with-rancher.md), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. diff --git a/docs/api/workflows/tokens.md b/docs/api/workflows/tokens.md index 87c11bdb3f3..d34ef7e6b97 100644 --- a/docs/api/workflows/tokens.md +++ b/docs/api/workflows/tokens.md @@ -6,6 +6,8 @@ title: Tokens + + ## Token Resource Rancher has an imperative API resource `tokens.ext.cattle.io` that allows you to generate tokens for authenticating with Rancher. diff --git a/docs/faq/deprecated-features.md b/docs/faq/deprecated-features.md index 4e452e77376..662f63bb19d 100644 --- a/docs/faq/deprecated-features.md +++ b/docs/faq/deprecated-features.md @@ -12,11 +12,8 @@ Rancher will publish deprecated features as part of the [release notes](https:// | Patch Version | Release Date | |---------------|---------------| -| [2.13.3](https://github.com/rancher/rancher/releases/tag/v2.13.3) | February 25, 2026 | -| [2.13.2](https://github.com/rancher/rancher/releases/tag/v2.13.2) | January 29, 2026 | -| [2.13.1](https://github.com/rancher/rancher/releases/tag/v2.13.1) | December 18, 2025 | -| [2.13.0](https://github.com/rancher/rancher/releases/tag/v2.13.0) | November 25, 2025 | +| [2.14.0](https://github.com/rancher/rancher/releases/tag/v2.14.0) | March 25, 2026 | ## What can I expect when a feature is marked for deprecation? -In the release where functionality is marked as "Deprecated", it will still be available and supported allowing upgrades to follow the usual procedure. Once upgraded, users/admins should start planning to move away from the deprecated functionality before upgrading to the release it marked as removed. The recommendation for new deployments is to not use the deprecated feature. +In the release where functionality is marked as "Deprecated", it will still be available and supported allowing upgrades to follow the usual procedure. Once upgraded, users/admins should start planning to move away from the deprecated functionality before upgrading to the release it marked as removed. The recommendation for new deployments is to not use the deprecated feature. \ No newline at end of file diff --git a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md index 0d9305f1144..7c9d5fd1e04 100644 --- a/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md +++ b/docs/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -28,7 +28,11 @@ Alternative steps need to be performed for rollbacks in the following scenarios: 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. +In Rancher v2.7.7 through v2.13.x, the app `rancher-provisioning-capi` was installed on the upstream (local) cluster automatically as a replacement for the embedded cluster-api controllers. Conflicts and unexpected errors would occur if the upstream cluster contained 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-v2.13.x to any previous version of Rancher v2.7.x. + +In Rancher v2.13.0, Rancher Turtles became the default manager for CAPI resources, replacing the previously embedded cluster-api controllers, and in Rancher v2.14.0 the embedded cluster-api was removed entirely. As a result, if you roll back from Rancher v2.14.0 and later to an earlier version of Rancher v2.13.x and do not intend to continue using Rancher Turtles to manage CAPI resources, additional manual steps may be required to use the embedded cluster-api controllers. From Rancher v2.14.0 onward, Rancher Turtles is the only supported manager for CAPI resources. + +In Rancher v2.14.0, the cluster-api module is upgraded from v1.10.6 to v1.12.2. The cluster-api v1.12.2, in turn, upgrades the apiVersions of its Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1beta1` to `cluster.x-k8s.io/v1beta2`. Rancher backup files include Cluster API CRDs. When restoring backup data from Rancher v2.13.x to a local cluster after upgrading to v2.14.0, the Rancher Backup application first restores the v1beta1 CRDs. This fails because the v1beta2 version cannot be removed from the CRDs while v1beta2 custom resources are present in the cluster. In Rancher v2.14.0, the cluster-api module is upgraded from v1.10.6 to v1.12.2. The cluster-api v1.12.2, in turn, upgrades the apiVersions of its Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1beta1` to `cluster.x-k8s.io/v1beta2`. Rancher backup files include Cluster API CRDs. When restoring backup data from Rancher v2.13.x to a local cluster after upgrading to v2.14.0, the Rancher Backup application first restores the v1beta1 CRDs. This fails because the v1beta2 version cannot be removed from the CRDs while v1beta2 custom resources are present in the cluster. diff --git a/docs/how-to-guides/advanced-user-guides/capi-infrastructure-providers.md b/docs/how-to-guides/advanced-user-guides/capi-infrastructure-providers.md new file mode 100644 index 00000000000..0334a783ca7 --- /dev/null +++ b/docs/how-to-guides/advanced-user-guides/capi-infrastructure-providers.md @@ -0,0 +1,459 @@ +--- +title: Configuring Native CAPI Infrastructure Providers to Provision RKE2 Clusters +--- + +:::caution + +**This is a technology preview and using native CAPI infrastructure providers is an experimental feature introduced in Rancher 2.14.0.** The purpose of this guide is for evaluation and **should not** be used for production clusters, and note some configuration fields are subject to change. Future versions of this feature may be incompatible with this version. + +::: + +## Overview + +Rancher 2.14.0 can provision RKE2 clusters using native CAPI infrastructure providers, such as [CAPA](https://cluster-api-aws.sigs.k8s.io/) (Cluster API Provider AWS) and [CAPV](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere) (Cluster API Provider vSphere). + +Standard RKE2 provisioning relies on Rancher’s internal bootstrap and control plane providers alongside Rancher Node Drivers (via `rancher/machine`) as the infrastructure provider. This new mode allows you to substitute Rancher Node Drivers with native CAPI infrastructure providers while retaining Rancher’s bootstrap and control plane logic. + +This guide provides simple examples for evaluating this provisioning mode using CAPA and CAPV. Refer to the documentation of each provider for more details on available options and adapt these examples to your needs. + +:::note +Provisioning with a native CAPI infrastructure provider and Rancher as a bootstrap and control plane provider is distinct from using [Rancher Turtles](https://turtles.docs.rancher.com/turtles/stable/en/index.html) and the [CAPRKE2](https://caprke2.docs.rancher.com/) provider to provision a RKE2 cluster and subsequently import it into Rancher. +::: + +### Limitations and requirements + +- Unsupported configurations: Windows worker nodes and IPv6 are currently not supported. +- UI constraints: Detailed cluster management via the UI is disabled; clusters must be created and modified by applying Kubernetes objects to the local cluster. However, the Cluster Explorer remains accessible. +- Kubernetes cloud provider requirements: A cloud-specific Kubernetes provider for the infrastructure where the downstream cluster runs is required (e.g., the [Kubernetes AWS Cloud Provider](https://cloud-provider-aws.sigs.k8s.io/) for CAPA or the `rancher-vsphere-cpi` chart for CAPV). + +## General steps + +For both CAPA and CAPV, the general steps are as follows: + +1. Install Rancher. +1. Install a CAPI infrastructure provider, either CAPA or CAPV. +1. Set-up an identity resource for the provider. +1. Create a CAPI infrastructure cluster resource. +1. Create one or more CAPI infrastructure machine template resources. +1. Create a Rancher `clusters.provisioning.cattle.io` resource that references the identity, infrastructure cluster and infrastructure machine template resources. + +After applying the `clusters.provisioning.cattle.io` resource, the cluster appears in the Rancher Cluster Management list (click on **☰ > Cluster Management**), however the detailed view for this type of cluster is currently unavailable. + +To view the progress of the provisioning process and troubleshoot, refer to the status of the various CAPI and Rancher provisioning resources in the local cluster: + +1. Click **☰**, then click on the icon for your local cluster. +1. Use the dropdown menu at the top to filter for **All Namespaces**. +1. From the sidebar, select **More Resources > Cluster Provisioning**. + +The logs for the infrastructure provider deployment (e.g. `capa-controller-manager`) also show useful information. + +## Installing the infrastructure provider + +Rancher allows installing the infrastructure provider declaratively by creating the Rancher Turtles [`CAPIProvider`](https://turtles.docs.rancher.com/turtles/stable/en/reference/capiprovider.html) resource. + +### Examples + +CAPA: + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: capa-system +--- +apiVersion: turtles-capi.cattle.io/v1alpha1 +kind: CAPIProvider +metadata: + name: aws + namespace: capa-system +spec: + type: infrastructure + variables: + # Global credentials for the provider are not needed + # as these examples define credentials for the AWSCluster. + AWS_B64ENCODED_CREDENTIALS: "" +``` + +CAPV: + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: capv-system +--- +apiVersion: turtles-capi.cattle.io/v1alpha1 +kind: CAPIProvider +metadata: + name: vsphere + namespace: capv-system +spec: + type: infrastructure + variables: + # Global credentials for the provider are not needed + # as these examples define credentials for the VsphereCluster. + VSPHERE_USERNAME: "" + VSPHERE_PASSWORD: "" +``` + +## Provisioning a cluster + +For these examples, a single machine pool with all roles (control plane, etcd and worker) are used, but the examples can be adapted by specifying more machine pools and separate roles. + +Create the resources in your upstream cluster, and replace values within `<>` brackets. + +:::caution + +Each machine pool defined in the `clusters.provisioning.cattle.io` resource should reference a different machine template. + +::: + +### CAPA + +First, configure IAM as required by CAPA. These roles are assumed by downstream nodes using instance profiles to enable the Kubernetes AWS cloud provider. + +To do this, CAPA provides the `clusterawsadm` tool to generate and apply the required objects. Refer to the CAPA manual for more [details](https://cluster-api-aws.sigs.k8s.io/topics/using-clusterawsadm-to-fulfill-prerequisites). + +Then, configure the provider identity in the upstream cluster so that the CAPA provider can create resources on AWS. Refer to the manual for all [options](https://cluster-api-aws.sigs.k8s.io/topics/multitenancy). + +In this example, we'll use `AWSClusterStaticIdentity`. + +Create a secret with your credentials: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: capa-lab-credentials + namespace: capa-system +type: Opaque +stringData: + AccessKeyID: + SecretAccessKey: + # You might have a session token depending on your credential type. + # SessionToken: +``` + +Then, create the identity object that references the secret: + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 +kind: AWSClusterStaticIdentity +metadata: + name: capa-lab-identity +spec: + secretRef: capa-lab-credentials + allowedNamespaces: + # The namespace of the AWSCluster resource that points + # to this identity for provisioning. + list: + - fleet-default +``` + +Now, create the `AWSCluster` [resource](https://cluster-api-aws.sigs.k8s.io/crd/#infrastructure.cluster.x-k8s.io%2fv1beta2). This object defines the infrastructure configuration common to all machine pools. + +CAPA creates VPCs, subnets, security groups and a load balancer in its default configuration, but additional rules must be configured to allow ports needed by Rancher and RKE2. For simplicity, this example defines additional security group rules that allow all traffic between the nodes, but more restrictive rules can be configured instead. + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 +kind: AWSCluster +metadata: + name: capa-lab + namespace: fleet-default +spec: + identityRef: + kind: AWSClusterStaticIdentity + name: capa-lab-identity + + controlPlaneLoadBalancer: + healthCheckProtocol: TCP + loadBalancerType: nlb + + region: + + # These two additional rules allow all incoming traffic + # from other nodes. + network: + additionalControlPlaneIngressRules: + - protocol: "-1" + sourceSecurityGroupRoles: + - controlplane + - node + additionalNodeIngressRules: + - protocol: "-1" + sourceSecurityGroupRoles: + - controlplane + - node +``` + +Next, create a machine template for the control plane machine pool. Create additional templates for every machine pool defined in the `clusters.provisioning.cattle.io` resource. + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 +kind: AWSMachineTemplate +metadata: + name: capa-lab-control-plane + namespace: fleet-default +spec: + template: + spec: + ami: + # The ami requires cloud-init. + id: + # This should correspond to the profile created through clusterawsadm. + # Worker or etcd-only nodes should use nodes.cluster-api-provider-aws.sigs.k8s.io. + iamInstanceProfile: control-plane.cluster-api-provider-aws.sigs.k8s.io + instanceType: t3.medium + # This refers to the name of an EC2 key pair. + sshKeyName: + rootVolume: + size: 16 + cloudInit: + insecureSkipSecretsManager: true +``` + +:::caution +The `insecureSkipSecretsManager` option is set to true to bypass the AWS secrets manager as a source of userdata for the provisioned instances. This source restricts the visibility of the userdata but requires a custom cloud-init datasource which is not currently compatible with the userdata generated by Rancher. For more information, see the [CAPA documentation](https://cluster-api-aws.sigs.k8s.io/topics/userdata-privacy). +::: + +Finally, create the Rancher `clusters.provisioning.cattle.io` resource and point to the CAPA cluster and machine template that were just created. + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +metadata: + name: capa-lab + namespace: fleet-default +spec: + kubernetesVersion: v1.35.1+rke2r1 + rkeConfig: + # This is the ref to the infra cluster defined above. + infrastructureRef: + kind: AWSCluster + name: capa-lab + namespace: fleet-default + apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 + machinePools: + - name: ctrl + controlPlaneRole: true + etcdRole: true + workerRole: true + quantity: 3 + machineConfigRef: + kind: AWSMachineTemplate + name: capa-lab-control-plane + namespace: fleet-default + apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 + machineGlobalConfig: + cni: calico + disable-kube-proxy: false + etcd-expose-metrics: false + ingress-controller: traefik + protect-kernel-defaults: false + cloud-provider-name: external + node-name-from-cloud-provider-metadata: true + # The AWS cloud controller definition. The controller uses the IAM instance profile for its AWS credentials. + additionalManifest: |- + apiVersion: helm.cattle.io/v1 + kind: HelmChart + metadata: + name: aws-cloud-controller-manager + namespace: kube-system + spec: + chart: aws-cloud-controller-manager + repo: https://kubernetes.github.io/cloud-provider-aws + targetNamespace: kube-system + bootstrap: true + valuesContent: |- + hostNetworking: true + nodeSelector: + node-role.kubernetes.io/control-plane: "true" + args: + - --configure-cloud-routes=false + - --v=5 + - --cloud-provider=aws +``` + +### CAPV + +First, configure the provider identity in the upstream cluster so that the CAPV provider can create resources on your vSphere server. Refer to the manual for all identity [options](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/v1.15.2/docs/identity_management.md), and for general vSphere [requirements](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/v1.15.2/docs/getting_started.md). + +In this example, we'll use `VSphereClusterIdentity`. + +Create a secret with your credentials: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: capv-lab-credentials + namespace: capv-system +type: Opaque +stringData: + username: + password: +``` + +Then, create the identity object that references the secret: + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 +kind: VSphereClusterIdentity +metadata: + name: capv-lab-identity +spec: + secretName: capv-lab-credentials + allowedNamespaces: + selector: + # The namespace of the VSphereCluster for which this identity + # is used when provisioning. + matchLabels: + kubernetes.io/metadata.name: fleet-default +``` + +Like for CAPA, it is also necessary to install the [cloud provider for vSphere](https://github.com/kubernetes/cloud-provider-vsphere) in the downstream cluster. + +To securely transfer the credentials for the CPI chart, you can enable the prebootstrap feature in Rancher. This can be done by [enabling](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md) the `provisioningprebootstrap` feature flag and causes Rancher to restart. + +Now, create the secret that is sent to the downstream cluster. If you use a different name to create the `clusters.provisioning.cattle.io` resource, make sure you update the `rke.cattle.io/object-authorized-for-clusters` annotation below. + +```yaml +# Credential secret synced to the downstream cluster for the vsphere CPI chart. +apiVersion: v1 +kind: Secret +metadata: + name: vsphere-cpi-creds + namespace: fleet-default + annotations: + # Can be a comma-separated list for multiple clusters, with no spaces. + rke.cattle.io/object-authorized-for-clusters: capv-lab + provisioning.cattle.io/sync-bootstrap: "true" + provisioning.cattle.io/sync-target-namespace: kube-system +type: Opaque +stringData: + # Change the prefix of the key to match your vCenter host. + .username: + .password: +``` + +Now, create the `VSphereCluster` resource. This resource defines the infrastructure configuration common to all machine pools. Refer to the CAPV documentation for more configuration options. + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 +kind: VSphereCluster +metadata: + name: capv-lab + namespace: fleet-default +spec: + identityRef: + kind: VSphereClusterIdentity + name: capv-lab-identity + server: +``` + +Next, create a machine template for the control plane machine pool. Create additional templates for every machine pool defined in the `clusters.provisioning.cattle.io` resource. + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 +kind: VSphereMachineTemplate +metadata: + name: capv-lab-control-plane + namespace: fleet-default +spec: + template: + spec: + datacenter: + datastore: + diskGiB: 20 + folder: + memoryMiB: 4096 + network: + devices: + - dhcp4: true + networkName: + numCPUs: 2 + os: Linux + resourcePool: + template: +``` + +Finally, create the Rancher `clusters.provisioning.cattle.io` resource and point to the CAPV cluster and machine template that were just created. Note that this example disables the CSI chart for simplicity. The CPI chart is required. + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +metadata: + name: capv-lab + namespace: fleet-default +spec: + kubernetesVersion: v1.35.1+rke2r1 + rkeConfig: + infrastructureRef: + kind: VSphereCluster + name: capv-lab + namespace: fleet-default + apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 + machinePools: + - name: ctrl + controlPlaneRole: true + etcdRole: true + workerRole: true + quantity: 3 + machineConfigRef: + kind: VSphereMachineTemplate + name: capv-lab-control-plane + namespace: fleet-default + apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 + machineGlobalConfig: + cni: calico + disable-kube-proxy: false + etcd-expose-metrics: false + ingress-controller: traefik + protect-kernel-defaults: false + disable: + - rancher-vsphere-csi + cloud-provider-name: rancher-vsphere + chartValues: + rancher-vsphere-cpi: + vCenter: + datacenters: + host: + # The credential secret is transferred by the prebootstrap mechanism, + # and the cpi chart expects the default name (vsphere-cpi-creds). + credentialsSecret: + generate: false +``` + +### Changing machine templates + +Machine templates for CAPI infrastructure providers, such as `AWSMachineTemplate` and `VSphereMachineTemplate` are usually immutable. To modify the configuration of the instances in a machine pool, create a new template with a different name, then edit the machine pool in `clusters.provisioning.cattle.io` to point to this new template. This causes all of the machines in that pool to be recreated with the new configuration. + +### Customizing userdata + +Custom user data can be defined for each machine pool in the `clusters.provisioning.cattle.io` resource. To do this, use the `.spec.rkeConfig.machinePools.userdata.inlineUserdata` as an inline yaml string in the plain cloud-config format. The contents of this field are merged with the userdata generated by Rancher to bootstrap the cluster nodes. + +:::caution +Do not include sensitive data in this field, as it is part of a resource other than a Secret. + +This field is experimental and subject to change. It is only valid for native CAPI providers described in this document, and has no effect on clusters provisioned by Rancher through the standard method with node drivers. +::: + +Modifying the userdata field causes all of the machines in the pool to be recreated. + +```yaml +# Only some fields of the provisioning cluster resource are shown here. +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +metadata: + name: capv-lab + namespace: fleet-default +spec: + kubernetesVersion: v1.35.1+rke2r1 + rkeConfig: + machinePools: + - name: ctrl + userdata: + inlineUserdata: | + runcmd: + - ["echo", "Hello!"] +``` diff --git a/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md b/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md index 9f85fd52168..c51518c9969 100644 --- a/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md +++ b/docs/how-to-guides/advanced-user-guides/configure-oidc-provider.md @@ -6,8 +6,13 @@ title: Configure Rancher as an OIDC provider -Rancher can function as a standard OpenID Connect (OIDC) provider, allowing external applications to use Rancher for authentication. -This can be used for enabling single sign-on (SSO) across Rancher Prime components. For example, see the [documentation](https://documentation.suse.com/cloudnative/suse-observability/latest/en/setup/security/authentication/oidc.html) for configuring the OIDC provider for SUSE Observability. +Rancher can act as an OpenID Connect (OIDC) Identity Provider (IdP) for other applications. This allows you to use Rancher's centralized authentication and role-based access control (RBAC) to manage access to external, third-party applications. This can be used for enabling single sign-on (SSO) across Rancher components. For example, see the [documentation](https://documentation.suse.com/cloudnative/suse-observability/latest/en/setup/security/authentication/oidc.html) for configuring the OIDC provider for SUSE Observability. + +:::note +Because OIDC is a superset of OAuth2, you can use Rancher as an OAuth2 server without requiring full OIDC. This ensures that clients utilizing the OAuth2 aspect, such as the `rancher-ai-mcp` server, are fully supported. +::: + +The Rancher OIDC Provider issues access tokens for OAuth2 and OIDC that can be used as standard Bearer tokens (per RFC6750) to authenticate with Rancher. Previously, only an ID token could be used to impersonate and authenticate a user. The OIDC provider can be enabled with the `oidc-provider` feature flag. When this flag is on the following endpoints are available: @@ -21,27 +26,51 @@ The OIDC provider can be enabled with the `oidc-provider` feature flag. When thi The OIDC provider supports the OIDC Authentication Code Flow with PKCE. -## Configure OIDCClient +## Configuring an OIDC Client -An `OIDCClient` represents an external application that will be authenticating against Rancher. +An `OIDCClient` represents an external application that will be authenticating against Rancher. To register a client application, you must create an `OIDCClient` custom resource. -### Programmatically +### Configuration Fields -Create an `OIDCClient`: +When defining your `OIDCClient` manifest, you must include specific fields to pass CRD validation: + +- `spec.tokenExpirationSeconds`: This field is strictly required and will cause a validation error if omitted. It defines the lifespan of the access token. +- `spec.refreshTokenExpirationSeconds`: This field is also strictly required and will cause a validation error if omitted. It defines the lifespan of the refresh token. +- `scopes` (Optional): This field allows you to restrict the scopes that a client can request. If not explicitly configured, the allowed scopes will default to `openid`, `profile`, and `offline_access`. + +### Example OIDC Client Manifest + +Below is an example of an `OIDCClient` configuration: + +:::note +You must include the expiration fields to successfully apply the resource. +::: ```yaml apiVersion: management.cattle.io/v3 kind: OIDCClient metadata: - name: oidc-client-test + name: example-client spec: - tokenExpirationSeconds: 600 # expiration of the id_token and access_token - refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token - redirectURIs: - - "https://myredirecturl.com" # replace with your redirect url + description: "Example OIDC Client" + redirectUris: + - "https://example-app.com/callback" + tokenExpirationSeconds: 3600 + refreshTokenExpirationSeconds: 86400 + # scopes: + # - openid + # - profile + # - offline_access + ``` -Rancher automatically generates a client ID and client secret for each `OIDCClient`. -Once the resource is created, Rancher populates the status field with the client id: + +Save this configuration to a file (e.g., `oidcclient.yaml`) and apply it to your Rancher local cluster: + +``` +kubectl apply -f oidcclient.yaml +``` + +Rancher automatically generates a client ID and client secret for each `OIDCClient`. Once the resource is created, Rancher populates the status field with the client id: ```yaml apiVersion: management.cattle.io/v3 @@ -53,6 +82,10 @@ spec: refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token redirectURIs: - "https://myredirecturl.com" # replace with your redirect url + scopes: # Optional: Restricts the scopes the client can request. Defaults to openid, profile, and offline_access if omitted. + - openid + - profile + - offline_access status: clientID: client-xxx clientSecrets: @@ -61,8 +94,7 @@ status: lastFiveCharacters: xxx ``` -Rancher automatically generates a Kubernetes `Secret` in the `cattle-oidc-client-secrets` namespace for each `OIDCClient` resource. The Secret's name matches the `OIDCClient` client ID. -Initially, the `Secret` contains a single client secret. +Rancher automatically generates a Kubernetes `Secret` in the `cattle-oidc-client-secrets` namespace for each `OIDCClient` resource. The Secret's name matches the `OIDCClient` client ID. Initially, the `Secret` contains a single client secret. To retrieve the client secret: diff --git a/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md b/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md index be7d1b5a57a..2fc11bb0d06 100644 --- a/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md +++ b/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md @@ -61,14 +61,12 @@ metadata: ``` In this example, if the project's quota does not include configMaps in its list of resources, then Rancher will ignore `configMaps` in this override. -Users are advised to create dedicated `ResourceQuota` objects in namespaces to configure additional custom limits for resources not defined on the project. -Resource quotas are native Kubernetes objects, and Rancher will ignore user-defined quotas in namespaces belonging to a project with a quota, -thus giving users more control. +Users are advised to either use the `extended` map to configure additional custom limits for resources not built into the project, for all namespaces in the project, or to create dedicated `ResourceQuota` objects in specific namespaces for the same, just for these namespaces. Resource quotas are native Kubernetes objects, and Rancher will ignore user-defined quotas in namespaces belonging to a project with a quota, thus giving users more control. The following table explains the key differences between the two quota types. | Rancher Resource Quotas | Kubernetes Resource Quotas | | ---------------------------------------------------------- | -------------------------------------------------------- | -| Applies to projects and namespace. | Applies to namespaces only. | -| Creates resource pool for all namespaces in project. | Applies static resource limits to individual namespaces. | +| Applies to projects and namespaces. | Applies to namespaces only. | +| Creates resource pool for all namespaces in a project. | Applies static resource limits to individual namespaces. | | Applies resource quotas to namespaces through propagation. | Applies only to the assigned namespace. diff --git a/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md b/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md index a0ed1060085..27554d9cb67 100644 --- a/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md +++ b/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md @@ -48,3 +48,17 @@ Edit resource quotas when: 1. Click **Create**. **Result:** The resource quota is applied to your project and namespaces. When you add more namespaces in the future, Rancher validates that the project can accommodate the namespace. If the project can't allocate the resources, you may still create namespaces, but they will be given a resource quota of 0. Subsequently, Rancher will not allow you to create any resources restricted by this quota. + +### Advanced: Beyond the basic Resource Quotas + +The set of resource quotas listed in the **Resource Type** dropdown of **Edit Config** is limited. For quotas outside of that set use **Edit Config** and **Add Resource** as already described, and select **Custom** as the resource type. This enables the edit field **Resource Identifier** for the entry of the necessary identifier. Some examples of identifiers are: + +- `requests.nvidia.com/gpu` +- `gold.storageclass.storage.k8s.io/requests.storage` +- `count/podtemplates` + +:::warning + +While it is possible to specify `Custom` which refer to quotas in the basic builtin set it is currently **strongly** recommended to use the builtin fields for them instead. Also, in case of conflicts, i.e. specifying a quota for a resource in both its builtin field and via `Custom`, the data found in the builtin field has priority and the data in `Custom` is ignored. + +::: diff --git a/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md b/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md index 9f6c8ca5655..08d55f9f1a9 100644 --- a/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md +++ b/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md @@ -8,7 +8,7 @@ title: Overriding the Default Limit for a Namespace Although the **Namespace Default Limit** propagates from the project to each namespace when created, in some cases, you may need to increase (or decrease) the quotas for a specific namespace. In this situation, you can override the default limits by editing the namespace. -In the diagram below, the Rancher administrator has a resource quota in effect for their project. However, the administrator wants to override the namespace limits for `Namespace 3` so that it has more resources available. Therefore, the administrator [raises the namespace limits](../../../new-user-guides/manage-clusters/projects-and-namespaces.md) for `Namespace 3` so that the namespace can access more resources. +In the diagram below, the Rancher administrator has a resource quota in effect for their project. However, the administrator wants to override the cpu limits for `Namespace 3` so that it has more resources available. Therefore, the administrator [raises the cpu limits](../../../new-user-guides/manage-clusters/projects-and-namespaces.md) for `Namespace 3` so that the namespace can access more resources. Namespace Default Limit Override diff --git a/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md b/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md index e789f5bf38b..b29a473ce92 100644 --- a/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md +++ b/docs/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md @@ -6,14 +6,20 @@ title: Resource Quota Type Reference -When you create a resource quota, you are configuring the pool of resources available to the project. You can set the following resource limits for the following resource types. +When you create a resource quota, you are configuring the pool of resources available to the project. Rancher supports the use of arbitrary resource references and their quotas. This allows you to utilize all upstream [Kubernetes `ResourceQuota`](https://kubernetes.io/docs/concepts/policy/resource-quotas/#types-of-resource-quota) types when managing project resource quotas. + +You can set resource limits for the following predefined resource types, where the `Custom` type enables specification of arbitrary resources and their quotas. + +:::note +Support for arbitrary resource references using the `Custom` type does not cover resources in the `ext.cattle.io` API group. +::: | Resource Type | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CPU Limit* | The maximum amount of CPU (in [millicores](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)) allocated to the project/namespace.1 | +| CPU Limit* | The maximum amount of CPU (in [millicores](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)) allocated to the project/namespace.1 | | CPU Reservation* | The minimum amount of CPU (in millicores) guaranteed to the project/namespace.1 | -| Memory Limit* | The maximum amount of memory (in bytes) allocated to the project/namespace.1 | -| Memory Reservation* | The minimum amount of memory (in bytes) guaranteed to the project/namespace.1 | +| Memory Limit* | The maximum amount of memory (in [bytes](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory)) allocated to the project/namespace.1 | +| Memory Reservation* | The minimum amount of memory (in bytes) guaranteed to the project/namespace.1 | | Storage Reservation | The minimum amount of storage (in gigabytes) guaranteed to the project/namespace. | | Services Load Balancers | The maximum number of load balancers services that can exist in the project/namespace. | | Services Node Ports | The maximum number of node port services that can exist in the project/namespace. | @@ -22,10 +28,23 @@ When you create a resource quota, you are configuring the pool of resources avai | ConfigMaps | The maximum number of ConfigMaps that can exist in the project/namespace. | | Persistent Volume Claims | The maximum number of persistent volume claims that can exist in the project/namespace. | | Replications Controllers | The maximum number of replication controllers that can exist in the project/namespace. | -| Secrets | The maximum number of secrets that can exist in the project/namespace. | +| Secrets | The maximum number of secrets that can exist in the project/namespace. | | +| Custom\*\* | The specification of arbitrary resources and their quotas, beyond the resource types built into projects, as listed above. | :::note ***** -When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. +When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project or namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. -::: \ No newline at end of file +::: + +:::note **\*\*** + +For example: + + - `requests.nvidia.com/gpu: 4` + - `gold.storageclass.storage.k8s.io/requests.storage: 500Gi` + - `count/podtemplates: 10` + +See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#quota-for-extended-resources) for many more examples. + +::: diff --git a/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md b/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md new file mode 100644 index 00000000000..68fce21e8ad --- /dev/null +++ b/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md @@ -0,0 +1,268 @@ +--- +title: Using an External Gateway with Rancher +--- + + + + + +## Using an External Gateway with Rancher + +When using the Gateway API network exposure type, Rancher can create and manage its own Gateway resource. However, if you have an existing Gateway that you manage independently (for example, a shared Gateway used by multiple applications), you will need to create your own HTTPRoute resources to route traffic to Rancher. + +This section covers how to create the required HTTPRoute resources manually when using an externally managed Gateway. + +### Prerequisites + +- An existing Gateway resource configured and operational in your cluster +- Knowledge of your Gateway's: + - Name and namespace + - Listener names (sectionName) for HTTP and/or HTTPS traffic +- Rancher installed with `networkExposure.type` set to something other than `gateway` (e.g., `none` or `ingress`) + +### Cross-Namespace Gateway Requirements + +If your Gateway is in a different namespace than Rancher (e.g., Gateway in `gateway-system`, Rancher in `cattle-system`), the Gateway must be configured to accept HTTPRoutes from the Rancher namespace. By default, Gateway API only allows routes from the same namespace as the Gateway. + +The Gateway owner must configure `allowedRoutes` on the relevant listeners. There are two options: + +**Option 1: Allow routes from all namespaces** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: shared-gateway + namespace: gateway-system +spec: + gatewayClassName: example + listeners: + - name: https + port: 443 + protocol: HTTPS + allowedRoutes: + namespaces: + from: All + - name: http + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: All +``` + +**Option 2: Allow routes from specific namespaces (more restrictive)** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: shared-gateway + namespace: gateway-system +spec: + gatewayClassName: example + listeners: + - name: https + port: 443 + protocol: HTTPS + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + shared-gateway-access: "true" + - name: http + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + shared-gateway-access: "true" +``` + +When using the selector approach, ensure the Rancher namespace has the required label: + +```bash +kubectl label namespace cattle-system shared-gateway-access=true +``` + +> **Note:** If the Gateway and Rancher are in the same namespace, no additional configuration is needed—the default `allowedRoutes` setting (`from: Same`) will permit the HTTPRoute attachment. + +### Determining Your Rancher Service Values + +Before creating HTTPRoute resources, identify the following values from your Rancher installation: + +| Value | How to Determine | Example | +|-------|------------------|---------| +| **Release Name** | The name used in `helm install ` | `rancher` | +| **Namespace** | The namespace where Rancher is installed | `cattle-system` | +| **Hostname** | The `hostname` value from your Helm values | `rancher.example.com` | +| **TLS Mode** | The `tls` value from your Helm values | `ingress`, `external`, or `secret` | +| **Service HTTP Disabled** | The `service.disableHTTP` value | `true` or `false` | + +The Rancher service name follows the pattern: `-rancher` (or just `` if the release name already contains "rancher"). + +### HTTPRoute Configuration + +#### Primary HTTPRoute + +Create an HTTPRoute to direct traffic from your Gateway to the Rancher service. The configuration depends on your TLS setup: + +**When TLS terminates at the Gateway or within Kubernetes (`tls: ingress`, `tls: secret`, or `tls: letsEncrypt`):** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher + namespace: cattle-system # Must match Rancher's namespace +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTPS listener + hostnames: + - # e.g., rancher.example.com + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher # Your Rancher service name + port: 80 # Use 443 if service.disableHTTP=true +``` + +**When TLS terminates externally (`tls: external`):** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher + namespace: cattle-system +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTP listener + hostnames: + - + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher + port: 80 +``` + +#### HTTP to HTTPS Redirect Route (Optional) + +If TLS terminates at or within Kubernetes (not externally), you may want to redirect HTTP traffic to HTTPS. Create an additional HTTPRoute: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher-http-redirect + namespace: cattle-system +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTP listener + hostnames: + - + rules: + - filters: + - type: RequestRedirect + requestRedirect: + scheme: https + statusCode: 301 +``` + +### Using extraObjects + +You can include these HTTPRoute resources directly in your Rancher Helm installation using the `extraObjects` value. This keeps all resources managed together: + +```yaml +# values.yaml +hostname: rancher.example.com +tls: ingress + +extraObjects: + - apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: rancher + spec: + parentRefs: + - name: my-shared-gateway + namespace: gateway-system + sectionName: https + hostnames: + - rancher.example.com + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher + port: 80 + + - apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: rancher-http-redirect + spec: + parentRefs: + - name: my-shared-gateway + namespace: gateway-system + sectionName: http + hostnames: + - rancher.example.com + rules: + - filters: + - type: RequestRedirect + requestRedirect: + scheme: https + statusCode: 301 +``` + +### Backend Port Selection + +The port in `backendRefs` depends on your `service.disableHTTP` setting: + +| `service.disableHTTP` | Backend Port | +|-----------------------|--------------| +| `false` (default) | `80` | +| `true` | `443` | + +### Listener Selection Summary + +| TLS Configuration | Primary Route Listener | Redirect Route | +|-------------------|------------------------|----------------| +| `tls: external` | HTTP listener | Not needed | +| `tls: ingress` | HTTPS listener | HTTP listener (optional) | +| `tls: secret` | HTTPS listener | HTTP listener (optional) | +| `tls: letsEncrypt`| HTTPS listener | HTTP listener (optional) | + +### Troubleshooting + +**HTTPRoute not being accepted:** +- Verify the Gateway name and namespace are correct +- Ensure the `sectionName` matches an existing listener on your Gateway +- Check that the listener allows routes from the Rancher namespace (see Gateway's `allowedRoutes` configuration) + +**Connection refused or timeouts:** +- Confirm the Rancher service exists and has endpoints: `kubectl get endpoints rancher -n cattle-system` +- Verify the backend port matches your `service.disableHTTP` setting + +**Certificate errors:** +- If using `tls: ingress` or `tls: secret`, ensure your Gateway's HTTPS listener has the appropriate certificate configured +- Verify the certificate covers your Rancher hostname diff --git a/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md b/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md new file mode 100644 index 00000000000..3204dced2e4 --- /dev/null +++ b/docs/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md @@ -0,0 +1,10 @@ +--- +title: Rancher Deployment Guides +--- + + + + + +- [Using an External Gateway with Rancher](configure-with-existing-gateway.md) + diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md index cf4937b0037..ef6c1bbdfbb 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md @@ -53,6 +53,10 @@ if the user has not yet logged in to Rancher. However, if the user has previousl | Client Secret | The generated Secret of your Amazon Cognito App Client. | | Issuer | The Issuer URL of your Amazon Cognito App Client. It follows the format `https://cognito-idp.{region}.amazonaws.com/{userPoolId}`, and can be found in the App Client settings page. Rancher uses the Issuer URL to fetch all of the required URLs. | +## OIDC Support for PKCE Extension + + + ## Configuring OIDC Single Logout (SLO) diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md index 8ec61010eda..4226c885c26 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md @@ -139,6 +139,10 @@ For example, if your IdP sends `groups` in a claim called `custom_roles`, enter | Custom Email Claim | `email` | The name of the claim in the OIDC token that contains the user's email address. | | Custom Groups Claim | `groups` | The name of the claim in the OIDC token that contains the user's group memberships (used for RBAC). | +## OIDC Support for PKCE Extension + + + ## Configuring OIDC Single Logout (SLO) diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md index 0d406be4273..cf06bbc57ff 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md @@ -168,6 +168,10 @@ After configuration is completed, Rancher user permissions need to be reapplied ::: +## OIDC Support for PKCE Extension + + + ## Configuring OIDC Single Logout (SLO) diff --git a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md index 0c049f2076b..5a719447819 100644 --- a/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md +++ b/docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md @@ -1,14 +1,28 @@ --- -title: Notification Center +title: Notifications --- +The Rancher dashboard delivers dynamic notifications and system alerts to ensure that you stay informed about the latest updates, lifecycle events, and statuses relevant to your deployment. + +## Dynamic Content + +Rancher fetches dynamic content, including notifications about new releases, End of Maintenance (EOM) or End of Life (EOL) statuses, and other important announcements. + +Dynamic content is delivered to users through three areas in the Rancher dashboard. + +* **Home page notification banner**: A dynamic banner displayed at the top of the home page for high-priority announcements. +* **Home page section below the Links**: A dedicated area on the home page, located beneath the **Links** section, that displays relevant updates and resources. +* **[Notification center](#what-is-the-notification-center)**: A centralized hub for all notifications, including system alerts, resources and announcements. + +To interact with these notifications, click **Learn More** on the listed resource. You can also dismiss the notification. + ## What is the Notification Center? -The Notification Center, located in the upper-right corner of your Rancher dashboard and marked by a bell icon, is your central hub for staying informed about various events within Rancher. +The notification center acts as a central repository for both system-generated alerts and dynamic announcements. You can access it by clicking the bell icon in the top right corner of the Rancher dashboard. Notifications are categorized by severity and type: diff --git a/docs/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md b/docs/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md index 939522101ea..d2db2329e53 100644 --- a/docs/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md +++ b/docs/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md @@ -19,10 +19,7 @@ In order to deploy and run the adapter successfully, you need to ensure its vers | Rancher Version | Adapter Version | |-----------------|------------------| -| v2.13.3 | 108.0.0+up8.0.0 | -| v2.13.2 | 108.0.0+up8.0.0 | -| v2.13.1 | 108.0.0+up8.0.0 | -| v2.13.0 | 108.0.0+up8.0.0 | +| v2.14.0 | 109.0.0+up9.0.0 | ### 1. Gain Access to the Local Cluster diff --git a/docs/integrations-in-rancher/cluster-api/overview.md b/docs/integrations-in-rancher/cluster-api/overview.md index e2e4a661ce0..65b24f655ed 100644 --- a/docs/integrations-in-rancher/cluster-api/overview.md +++ b/docs/integrations-in-rancher/cluster-api/overview.md @@ -20,51 +20,13 @@ Rancher Turtles meets [SLSA Level 3](https://slsa.dev/spec/v1.0/levels#build-l3) ## Prerequisites -Before installing Rancher Turtles in your Rancher environment, you must disable Rancher's `embedded-cluster-api` functionality. This also includes cleaning up Rancher-specific webhooks that otherwise would conflict with CAPI ones. +:::important -To simplify setting up Rancher for installing Rancher Turtles, the official Rancher Turtles Helm chart includes a `pre-install` hook that removes the following: +Starting with Rancher v2.14.0, the built-in `embedded-cluster-api` functionality (also known as the `rancher-provisioning-capi` chart) has been removed. [Rancher Turtles](https://turtles.docs.rancher.com/) is now the only supported method for Cluster API integration with Rancher. -- Disables the `embedded-cluster-api` feature in Rancher. -- Deletes the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks, as they are no longer needed. +If you are upgrading from a previous version of Rancher (v2.13.x or earlier), you no longer need to manually disable the `embedded-cluster-api` feature flag or clean up related webhooks before installing Rancher Turtles. -These webhooks can be removed through the Rancher UI as well: - -1. In the upper left corner, click **☰** > **Cluster Management**. -1. Select your local cluster. -1. In the left-hand navigation menu, select **More Resources** > **Admission**. -1. From the dropdown, select the Resource pages for `MutatingWebhookConfiguration` and `ValidatingWebhookConfiguration`. -1. On the respective Resource pages, click the **⋮** that are attached to the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks and select the **Delete** option. - -The webhooks can also be accessed by entering the names of the webhooks into the **Resource Search** field. - -The following `kubectl` commands can manually remove the necessary webhooks: - -```console -kubectl delete mutatingwebhookconfiguration.admissionregistration.k8s.io mutating-webhook-configuration -``` - -```console -kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io validating-webhook-configuration -``` - -Use the following example to disable the `embedded-cluster-api` feature from the console: - -1. Create a `feature.yaml` file, with `embedded-cluster-api` set to false: - -```yaml title="feature.yaml" -apiVersion: management.cattle.io/v3 -kind: Feature -metadata: - name: embedded-cluster-api -spec: - value: false -``` - -2. Use `kubectl` to apply the `feature.yaml` file to the cluster: - -```bash -kubectl apply -f feature.yaml -``` +::: ## Installing the Rancher Turtles Operator @@ -240,21 +202,3 @@ Remember that, if you use a different name for the installation or a different n ::: -After Rancher Turtles is uninstalled, Rancher's `embedded-cluster-api` feature must be re-enabled: - -1. Create a `feature.yaml` file, with `embedded-cluster-api` set to true: - -```yaml title="feature.yaml" -apiVersion: management.cattle.io/v3 -kind: Feature -metadata: - name: embedded-cluster-api -spec: - value: true -``` - -2. Use `kubectl` to apply the `feature.yaml` file to the cluster: - -```bash -kubectl apply -f feature.yaml -``` diff --git a/docs/reference-guides/rancher-webhook.md b/docs/reference-guides/rancher-webhook.md index 9b8206fb9dc..90e2348fa63 100644 --- a/docs/reference-guides/rancher-webhook.md +++ b/docs/reference-guides/rancher-webhook.md @@ -20,10 +20,7 @@ Each Rancher version is designed to be compatible with a single version of the w | Rancher Version | Webhook Version | Availability in Prime | Availability in Community | |-----------------|-----------------|-----------------------|---------------------------| -| v2.13.3 | v0.9.3 | ✓ | ✓ | -| v2.13.2 | v0.9.2 | ✓ | ✓ | -| v2.13.1 | v0.9.1 | ✓ | ✓ | -| v2.13.0 | v0.9.0 | ✗ | ✓ | +| v2.14.0 | v0.10.0 | ✗ | ✓ | ## Why Do We Need It? diff --git a/docs/reference-guides/user-settings/api-keys.md b/docs/reference-guides/user-settings/api-keys.md index 634a7396d33..939e871e145 100644 --- a/docs/reference-guides/user-settings/api-keys.md +++ b/docs/reference-guides/user-settings/api-keys.md @@ -6,6 +6,8 @@ title: API Keys + + ## API Keys and User Authentication If you want to access your Rancher clusters, projects, or other objects using external applications, you can do so using the Rancher API. However, before your application can access the API, you must provide the app with a key used to authenticate with Rancher. You can obtain a key using the Rancher UI. diff --git a/docusaurus.config.js b/docusaurus.config.js index 7961bf04e81..2a6a8abecb2 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -185,9 +185,9 @@ module.exports = { label: "Latest", }, "2.14": { - label: 'v2.14 (Preview)', + label: 'v2.14', path: 'v2.14', - banner: 'unreleased' + banner: 'none' }, "2.13": { label: "v2.13", diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/api/api-tokens.md b/i18n/zh/docusaurus-plugin-content-docs/current/api/api-tokens.md index eb5aedcc002..e1b164f7742 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/api/api-tokens.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/api/api-tokens.md @@ -2,6 +2,8 @@ title: API 令牌 --- + + 默认情况下，某些集群级别的 API 令牌是使用无限期 TTL（`ttl=0`）生成的。换言之，除非你让令牌失效，否则 `ttl=0` 的 API 令牌永远不会过期。令牌不会因为更改密码而失效。 要停用 API 令牌，你可以删除令牌或停用用户账号。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/faq/deprecated-features.md b/i18n/zh/docusaurus-plugin-content-docs/current/faq/deprecated-features.md index dde3efc7051..5ff1ca57005 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/faq/deprecated-features.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/faq/deprecated-features.md @@ -12,10 +12,7 @@ Rancher 将在 GitHub 上发布的 Rancher 的[发版说明](https://github.com/ | Patch 版本 | 发布时间 | | ----------------------------------------------------------------- | ------------------ | -| [2.13.3](https://github.com/rancher/rancher/releases/tag/v2.13.3) | 2026 年 02 月 25 日 | -| [2.13.2](https://github.com/rancher/rancher/releases/tag/v2.13.2) | 2026 年 01 月 29 日 | -| [2.13.1](https://github.com/rancher/rancher/releases/tag/v2.13.1) | 2025 年 12 月 18 日 | -| [2.13.0](https://github.com/rancher/rancher/releases/tag/v2.13.0) | 2025 年 11 月 25 日 | +| [2.14.0](https://github.com/rancher/rancher/releases/tag/v2.14.0) | 2026 年 03 月 25 日 | ## 当一个功能被标记为弃用我可以得到什么样的预期？ diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md index b0873befd7a..a84688dd7f4 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md @@ -2,13 +2,19 @@ title: 资源配额类型参考 --- -创建资源配额相当于配置项目可用的资源池。你可以为以下资源类型设置资源配额： +When you create a resource quota, you are configuring the pool of resources available to the project. Rancher supports the use of arbitrary resource references and their quotas. This allows you to utilize all upstream [Kubernetes `ResourceQuota`](https://kubernetes.io/docs/concepts/policy/resource-quotas/#types-of-resource-quota) types when managing project resource quotas. + +You can set resource limits for the following predefined resource types, where the `Custom` type enables specification of arbitrary resources and their quotas. + +:::note +Support for arbitrary resource references using the `Custom` type does not cover resources in the `ext.cattle.io` API group. +::: | 资源类型 | 描述 | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CPU 限制\* | 分配给项目/命名空间的最大 CPU 量（以[毫核](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)为单位）1 | | CPU 预留\* | 预留给项目/命名空间的最小 CPU 量（以毫核为单位）1 | -| 内存限制\* | 分配给项目/命名空间的最大内存量（以字节为单位）1 | +| 内存限制\* | 分配给项目/命名空间的最大内存量（[以字节为单位](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory)）1 | | 内存预留\* | 预留给项目/命名空间的最小内存量（以字节为单位）1 | | 存储预留 | 预留给项目/命名空间的最小存储量（以千兆字节为单位） | | 服务负载均衡器 | 项目/命名空间中可以存在的负载均衡器服务的最大数量 | @@ -19,9 +25,22 @@ title: 资源配额类型参考 | 持久卷声明 | 项目/命名空间中可以存在的持久卷声明的最大数量 | | ReplicationController | 项目/命名空间中可以存在的最大 ReplicationController 数量 | | 密文 | 项目/命名空间中可以存在的最大密文数量 | +| Custom\*\* | The specification of arbitrary resources and their quotas, beyond the resource types built into projects, as listed above. | :::note ***** 在设置资源配额时，如果你在项目或命名空间上设置了任何与 CPU 或内存相关的内容（即限制或预留），所有容器都需要在创建期间设置各自的 CPU 或内存字段。你可以同时设置容器的默认资源限制，以避免为每个工作负载显式设置这些限制。详情请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits)。 -::: \ No newline at end of file +::: + +:::note **\*\*** + +For example: + + - `requests.nvidia.com/gpu: 4` + - `gold.storageclass.storage.k8s.io/requests.storage: 500Gi` + - `count/podtemplates: 10` + +See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#quota-for-extended-resources) for many more examples. + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md b/i18n/zh/docusaurus-plugin-content-docs/current/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md index cac167bf73b..41cc3f28ab6 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md @@ -15,10 +15,7 @@ title: 安装 Adapter | Rancher 版本 | Adapter 版本 | |-----------------|------------------| -| v2.13.3 | 108.0.0+up8.0.0 | -| v2.13.2 | 108.0.0+up8.0.0 | -| v2.13.1 | 108.0.0+up8.0.0 | -| v2.13.0 | 108.0.0+up8.0.0 | +| v2.14.0 | 109.0.0+up9.0.0 | ## 1. 获取对 Local 集群的访问权限 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference-guides/rancher-webhook.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference-guides/rancher-webhook.md index 4d811b5a23c..97831f63979 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/reference-guides/rancher-webhook.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/reference-guides/rancher-webhook.md @@ -20,10 +20,7 @@ Rancher 将 Rancher-Webhook 作为单独的 deployment 和服务部署在 local | Rancher Version | Webhook Version | Availability in Prime | Availability in Community | |-----------------|-----------------|-----------------------|---------------------------| -| v2.13.3 | v0.9.3 | ✓ | ✓ | -| v2.13.2 | v0.9.2 | ✓ | ✓ | -| v2.13.1 | v0.9.1 | ✓ | ✓ | -| v2.13.0 | v0.9.0 | ✗ | ✓ | +| v2.14.0 | v0.10.0 | ✗ | ✓ | ## 为什么我们需要它？ diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference-guides/user-settings/api-keys.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference-guides/user-settings/api-keys.md index c5e3e8b9e4a..894052f554d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/reference-guides/user-settings/api-keys.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/reference-guides/user-settings/api-keys.md @@ -2,6 +2,8 @@ title: API 密钥 --- + + ## API 密钥和用户身份验证 如果你想通过外部应用程序来访问 Rancher 集群、项目或其他对象，你可以使用 Rancher API。但是，在你的应用程序可以访问 API 之前，你必须为应用程序提供用于向 Rancher 进行身份验证的密钥。你可以通过 Rancher UI 获取密钥。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/api-tokens.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/api-tokens.md index eb5aedcc002..e1b164f7742 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/api-tokens.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/api/api-tokens.md @@ -2,6 +2,8 @@ title: API 令牌 --- + + 默认情况下，某些集群级别的 API 令牌是使用无限期 TTL（`ttl=0`）生成的。换言之，除非你让令牌失效，否则 `ttl=0` 的 API 令牌永远不会过期。令牌不会因为更改密码而失效。 要停用 API 令牌，你可以删除令牌或停用用户账号。 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/deprecated-features.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/deprecated-features.md index dde3efc7051..5ff1ca57005 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/deprecated-features.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/faq/deprecated-features.md @@ -12,10 +12,7 @@ Rancher 将在 GitHub 上发布的 Rancher 的[发版说明](https://github.com/ | Patch 版本 | 发布时间 | | ----------------------------------------------------------------- | ------------------ | -| [2.13.3](https://github.com/rancher/rancher/releases/tag/v2.13.3) | 2026 年 02 月 25 日 | -| [2.13.2](https://github.com/rancher/rancher/releases/tag/v2.13.2) | 2026 年 01 月 29 日 | -| [2.13.1](https://github.com/rancher/rancher/releases/tag/v2.13.1) | 2025 年 12 月 18 日 | -| [2.13.0](https://github.com/rancher/rancher/releases/tag/v2.13.0) | 2025 年 11 月 25 日 | +| [2.14.0](https://github.com/rancher/rancher/releases/tag/v2.14.0) | 2026 年 03 月 25 日 | ## 当一个功能被标记为弃用我可以得到什么样的预期？ diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md index b0873befd7a..a84688dd7f4 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md @@ -2,13 +2,19 @@ title: 资源配额类型参考 --- -创建资源配额相当于配置项目可用的资源池。你可以为以下资源类型设置资源配额： +When you create a resource quota, you are configuring the pool of resources available to the project. Rancher supports the use of arbitrary resource references and their quotas. This allows you to utilize all upstream [Kubernetes `ResourceQuota`](https://kubernetes.io/docs/concepts/policy/resource-quotas/#types-of-resource-quota) types when managing project resource quotas. + +You can set resource limits for the following predefined resource types, where the `Custom` type enables specification of arbitrary resources and their quotas. + +:::note +Support for arbitrary resource references using the `Custom` type does not cover resources in the `ext.cattle.io` API group. +::: | 资源类型 | 描述 | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CPU 限制\* | 分配给项目/命名空间的最大 CPU 量（以[毫核](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)为单位）1 | | CPU 预留\* | 预留给项目/命名空间的最小 CPU 量（以毫核为单位）1 | -| 内存限制\* | 分配给项目/命名空间的最大内存量（以字节为单位）1 | +| 内存限制\* | 分配给项目/命名空间的最大内存量（[以字节为单位](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory)）1 | | 内存预留\* | 预留给项目/命名空间的最小内存量（以字节为单位）1 | | 存储预留 | 预留给项目/命名空间的最小存储量（以千兆字节为单位） | | 服务负载均衡器 | 项目/命名空间中可以存在的负载均衡器服务的最大数量 | @@ -19,9 +25,22 @@ title: 资源配额类型参考 | 持久卷声明 | 项目/命名空间中可以存在的持久卷声明的最大数量 | | ReplicationController | 项目/命名空间中可以存在的最大 ReplicationController 数量 | | 密文 | 项目/命名空间中可以存在的最大密文数量 | +| Custom\*\* | The specification of arbitrary resources and their quotas, beyond the resource types built into projects, as listed above. | :::note ***** 在设置资源配额时，如果你在项目或命名空间上设置了任何与 CPU 或内存相关的内容（即限制或预留），所有容器都需要在创建期间设置各自的 CPU 或内存字段。你可以同时设置容器的默认资源限制，以避免为每个工作负载显式设置这些限制。详情请参阅 [Kubernetes 文档](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits)。 -::: \ No newline at end of file +::: + +:::note **\*\*** + +For example: + + - `requests.nvidia.com/gpu: 4` + - `gold.storageclass.storage.k8s.io/requests.storage: 500Gi` + - `count/podtemplates: 10` + +See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#quota-for-extended-resources) for many more examples. + +::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md index cac167bf73b..41cc3f28ab6 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md @@ -15,10 +15,7 @@ title: 安装 Adapter | Rancher 版本 | Adapter 版本 | |-----------------|------------------| -| v2.13.3 | 108.0.0+up8.0.0 | -| v2.13.2 | 108.0.0+up8.0.0 | -| v2.13.1 | 108.0.0+up8.0.0 | -| v2.13.0 | 108.0.0+up8.0.0 | +| v2.14.0 | 109.0.0+up9.0.0 | ## 1. 获取对 Local 集群的访问权限 diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-webhook.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-webhook.md index 4d811b5a23c..97831f63979 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-webhook.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/rancher-webhook.md @@ -20,10 +20,7 @@ Rancher 将 Rancher-Webhook 作为单独的 deployment 和服务部署在 local | Rancher Version | Webhook Version | Availability in Prime | Availability in Community | |-----------------|-----------------|-----------------------|---------------------------| -| v2.13.3 | v0.9.3 | ✓ | ✓ | -| v2.13.2 | v0.9.2 | ✓ | ✓ | -| v2.13.1 | v0.9.1 | ✓ | ✓ | -| v2.13.0 | v0.9.0 | ✗ | ✓ | +| v2.14.0 | v0.10.0 | ✗ | ✓ | ## 为什么我们需要它？ diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/api-keys.md b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/api-keys.md index c5e3e8b9e4a..894052f554d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/api-keys.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.14/reference-guides/user-settings/api-keys.md @@ -2,6 +2,8 @@ title: API 密钥 --- + + ## API 密钥和用户身份验证 如果你想通过外部应用程序来访问 Rancher 集群、项目或其他对象，你可以使用 Rancher API。但是，在你的应用程序可以访问 API 之前，你必须为应用程序提供用于向 Rancher 进行身份验证的密钥。你可以通过 Rancher UI 获取密钥。 diff --git a/shared-files/_cni-popularity.md b/shared-files/_cni-popularity.md index 2242dd7f500..cd262563ad0 100644 --- a/shared-files/_cni-popularity.md +++ b/shared-files/_cni-popularity.md @@ -4,7 +4,7 @@ The following table summarizes different GitHub metrics to give you an idea of e | Provider | Project | Stars | Forks | Contributors | | ---- | ---- | ---- | ---- | ---- | | Canal | https://github.com/projectcalico/canal | 720 | 97 | 20 | -| Flannel | https://github.com/flannel-io/flannel | 9.4k | 2.9k | 243 | -| Calico | https://github.com/projectcalico/calico | 6.9k | 1.5k | 400 | -| Weave | https://github.com/weaveworks/weave | 6.6k | 677 | 83 | -| Cilium | https://github.com/cilium/cilium | 23.5k | 3.6k | 1022 | +| Flannel | https://github.com/flannel-io/flannel | 9.4k | 2.9k | 247 | +| Calico | https://github.com/projectcalico/calico | 7.1k | 1.5k | 411 | +| Weave | https://github.com/weaveworks/weave | 6.6k | 675 | 82 | +| Cilium | https://github.com/cilium/cilium | 24k | 3.7k | 1049 | diff --git a/shared-files/_oidc-pkce-support.md b/shared-files/_oidc-pkce-support.md new file mode 100644 index 00000000000..6a835385a05 --- /dev/null +++ b/shared-files/_oidc-pkce-support.md @@ -0,0 +1,3 @@ +Rancher supports the Proof Key for Code Exchange (PKCE) extension (RFC 7636) for OIDC authentication providers. SHA-256 (`S256`) is the only supported PKCE verification method. To enable this feature, your authentication provider must use PKCE with `S256` for authorization requests. + +You can enable this feature by selecting **Enable PKCE (S256)** in your authentication provider configuration in Rancher. Enabling `S256` PKCE token verification allows you to mitigate authorization code interception attacks during OIDC authentication flows. diff --git a/shared-files/_v3-api-tokens-deprecation-warning.md b/shared-files/_v3-api-tokens-deprecation-warning.md new file mode 100644 index 00000000000..a5e018aa41f --- /dev/null +++ b/shared-files/_v3-api-tokens-deprecation-warning.md @@ -0,0 +1,8 @@ +:::warning Deprecation of v3 API tokens +Rancher v2.13 introduced a new token resource in the `ext.cattle.io` API group to serve as the public API for tokens, which was only accessible through `kubectl`. + +Starting with Rancher v2.14.0: + +- Legacy v3 API tokens (`tokens.management.cattle.io`) are being phased out and scheduled for removal in a future release. If you currently rely on legacy tokens for automation or API access, transition to the new `tokens.ext.cattle.io` tokens to ensure continued compatibility. +- The Rancher dashboard provides basic support for `tokens.ext.cattle.io` (create, view or list, and delete). +::: diff --git a/sidebars.js b/sidebars.js index 42d8eea20e0..a12f48a0f38 100644 --- a/sidebars.js +++ b/sidebars.js @@ -649,6 +649,17 @@ const sidebars = { id: "how-to-guides/advanced-user-guides/advanced-user-guides", }, items: [ + { + type: "category", + label: "Rancher Deployment Guides", + link: { + type: "doc", + id: "how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides", + }, + items: [ + "how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway", + ], + }, { type: "category", label: "Project Administration", @@ -784,7 +795,8 @@ const sidebars = { "how-to-guides/advanced-user-guides/enable-cluster-agent-scheduling-customization", "how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer", "how-to-guides/advanced-user-guides/configure-oidc-provider", - "how-to-guides/advanced-user-guides/ui-server-side-pagination" + "how-to-guides/advanced-user-guides/ui-server-side-pagination", + "how-to-guides/advanced-user-guides/capi-infrastructure-providers" ], }, ], diff --git a/src/pages/versions.md b/src/pages/versions.md index 482a4ce5986..331b7c8bbfb 100644 --- a/src/pages/versions.md +++ b/src/pages/versions.md @@ -5,6 +5,27 @@ title: Rancher Documentation Versions ### Current Versions +Here you can find links to supporting documentation for the current released version of Rancher v2.14, and its availability for [Rancher Prime](/v2.14/getting-started/quick-start-guides/deploy-rancher-manager/prime) and the Community version of Rancher: + + + + + + + + + + + + + + + + + + +
VersionDocumentationRelease NotesSupport MatrixPrimeCommunity
v2.14.0DocumentationRelease Notes
N/A
N/A
✓
+ Here you can find links to supporting documentation for the current released version of Rancher v2.13, and its availability for [Rancher Prime](/v2.13/getting-started/quick-start-guides/deploy-rancher-manager/prime) and the Community version of Rancher: diff --git a/src/theme/MDXComponents.js b/src/theme/MDXComponents.js index 871d566aa20..e815dfca195 100644 --- a/src/theme/MDXComponents.js +++ b/src/theme/MDXComponents.js @@ -16,6 +16,9 @@ import ConfigureSLOOidc from '/shared-files/_configure-slo-oidc.md'; import EOLRKE1Warning from '/shared-files/_eol-rke1-warning.md'; import PermissionsWarning from '/shared-files/_permissions-warning.md'; import SamlOpenLDAPGroupPermissions from '/shared-files/_saml-openldap-group-permissions.md'; +import v3APITokensDeprecationWarning from '/shared-files/_v3-api-tokens-deprecation-warning.md'; +import OIDCPKCESupport from '/shared-files/_oidc-pkce-support.md'; + export default { // Re-use the default mapping @@ -37,4 +40,6 @@ export default { EOLRKE1Warning, PermissionsWarning, SamlOpenLDAPGroupPermissions, + v3APITokensDeprecationWarning, + OIDCPKCESupport, }; diff --git a/versioned_docs/version-2.13/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md b/versioned_docs/version-2.13/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md index 0c049f2076b..5a719447819 100644 --- a/versioned_docs/version-2.13/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md +++ b/versioned_docs/version-2.13/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md @@ -1,14 +1,28 @@ --- -title: Notification Center +title: Notifications --- +The Rancher dashboard delivers dynamic notifications and system alerts to ensure that you stay informed about the latest updates, lifecycle events, and statuses relevant to your deployment. + +## Dynamic Content + +Rancher fetches dynamic content, including notifications about new releases, End of Maintenance (EOM) or End of Life (EOL) statuses, and other important announcements. + +Dynamic content is delivered to users through three areas in the Rancher dashboard. + +* **Home page notification banner**: A dynamic banner displayed at the top of the home page for high-priority announcements. +* **Home page section below the Links**: A dedicated area on the home page, located beneath the **Links** section, that displays relevant updates and resources. +* **[Notification center](#what-is-the-notification-center)**: A centralized hub for all notifications, including system alerts, resources and announcements. + +To interact with these notifications, click **Learn More** on the listed resource. You can also dismiss the notification. + ## What is the Notification Center? -The Notification Center, located in the upper-right corner of your Rancher dashboard and marked by a bell icon, is your central hub for staying informed about various events within Rancher. +The notification center acts as a central repository for both system-generated alerts and dynamic announcements. You can access it by clicking the bell icon in the top right corner of the Rancher dashboard. Notifications are categorized by severity and type: diff --git a/versioned_docs/version-2.14/api/api-tokens.md b/versioned_docs/version-2.14/api/api-tokens.md index a05cf03bcfc..2845b69eddc 100644 --- a/versioned_docs/version-2.14/api/api-tokens.md +++ b/versioned_docs/version-2.14/api/api-tokens.md @@ -6,6 +6,8 @@ title: Using API Tokens + + Rancher v2.8.0 introduced the [Rancher Kubernetes API](./api-reference.mdx) which can be used to manage Rancher resources through `kubectl`. This page covers information on API tokens used with the [Rancher CLI](../reference-guides/cli-with-rancher/cli-with-rancher.md), [kubeconfig files](../how-to-guides/new-user-guides/manage-clusters/access-clusters/authorized-cluster-endpoint.md#about-the-kubeconfig-file), Terraform and the [v3 API browser](./v3-rancher-api-guide.md#enable-view-in-api). By default, some cluster-level API tokens are generated with infinite time-to-live (`ttl=0`). In other words, API tokens with `ttl=0` never expire unless you invalidate them. Tokens are not invalidated by changing a password. diff --git a/versioned_docs/version-2.14/api/workflows/tokens.md b/versioned_docs/version-2.14/api/workflows/tokens.md index 87c11bdb3f3..d34ef7e6b97 100644 --- a/versioned_docs/version-2.14/api/workflows/tokens.md +++ b/versioned_docs/version-2.14/api/workflows/tokens.md @@ -6,6 +6,8 @@ title: Tokens + + ## Token Resource Rancher has an imperative API resource `tokens.ext.cattle.io` that allows you to generate tokens for authenticating with Rancher. diff --git a/versioned_docs/version-2.14/faq/deprecated-features.md b/versioned_docs/version-2.14/faq/deprecated-features.md index 4e452e77376..0d47ff92206 100644 --- a/versioned_docs/version-2.14/faq/deprecated-features.md +++ b/versioned_docs/version-2.14/faq/deprecated-features.md @@ -12,10 +12,7 @@ Rancher will publish deprecated features as part of the [release notes](https:// | Patch Version | Release Date | |---------------|---------------| -| [2.13.3](https://github.com/rancher/rancher/releases/tag/v2.13.3) | February 25, 2026 | -| [2.13.2](https://github.com/rancher/rancher/releases/tag/v2.13.2) | January 29, 2026 | -| [2.13.1](https://github.com/rancher/rancher/releases/tag/v2.13.1) | December 18, 2025 | -| [2.13.0](https://github.com/rancher/rancher/releases/tag/v2.13.0) | November 25, 2025 | +| [2.14.0](https://github.com/rancher/rancher/releases/tag/v2.14.0) | March 25, 2026 | ## What can I expect when a feature is marked for deprecation? diff --git a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md index 0d9305f1144..7c9d5fd1e04 100644 --- a/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md +++ b/versioned_docs/version-2.14/getting-started/installation-and-upgrade/install-upgrade-on-a-kubernetes-cluster/rollbacks.md @@ -28,7 +28,11 @@ Alternative steps need to be performed for rollbacks in the following scenarios: 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. +In Rancher v2.7.7 through v2.13.x, the app `rancher-provisioning-capi` was installed on the upstream (local) cluster automatically as a replacement for the embedded cluster-api controllers. Conflicts and unexpected errors would occur if the upstream cluster contained 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-v2.13.x to any previous version of Rancher v2.7.x. + +In Rancher v2.13.0, Rancher Turtles became the default manager for CAPI resources, replacing the previously embedded cluster-api controllers, and in Rancher v2.14.0 the embedded cluster-api was removed entirely. As a result, if you roll back from Rancher v2.14.0 and later to an earlier version of Rancher v2.13.x and do not intend to continue using Rancher Turtles to manage CAPI resources, additional manual steps may be required to use the embedded cluster-api controllers. From Rancher v2.14.0 onward, Rancher Turtles is the only supported manager for CAPI resources. + +In Rancher v2.14.0, the cluster-api module is upgraded from v1.10.6 to v1.12.2. The cluster-api v1.12.2, in turn, upgrades the apiVersions of its Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1beta1` to `cluster.x-k8s.io/v1beta2`. Rancher backup files include Cluster API CRDs. When restoring backup data from Rancher v2.13.x to a local cluster after upgrading to v2.14.0, the Rancher Backup application first restores the v1beta1 CRDs. This fails because the v1beta2 version cannot be removed from the CRDs while v1beta2 custom resources are present in the cluster. In Rancher v2.14.0, the cluster-api module is upgraded from v1.10.6 to v1.12.2. The cluster-api v1.12.2, in turn, upgrades the apiVersions of its Custom Resource Definitions (CRDs) from `cluster.x-k8s.io/v1beta1` to `cluster.x-k8s.io/v1beta2`. Rancher backup files include Cluster API CRDs. When restoring backup data from Rancher v2.13.x to a local cluster after upgrading to v2.14.0, the Rancher Backup application first restores the v1beta1 CRDs. This fails because the v1beta2 version cannot be removed from the CRDs while v1beta2 custom resources are present in the cluster. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/capi-infrastructure-providers.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/capi-infrastructure-providers.md new file mode 100644 index 00000000000..0334a783ca7 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/capi-infrastructure-providers.md @@ -0,0 +1,459 @@ +--- +title: Configuring Native CAPI Infrastructure Providers to Provision RKE2 Clusters +--- + +:::caution + +**This is a technology preview and using native CAPI infrastructure providers is an experimental feature introduced in Rancher 2.14.0.** The purpose of this guide is for evaluation and **should not** be used for production clusters, and note some configuration fields are subject to change. Future versions of this feature may be incompatible with this version. + +::: + +## Overview + +Rancher 2.14.0 can provision RKE2 clusters using native CAPI infrastructure providers, such as [CAPA](https://cluster-api-aws.sigs.k8s.io/) (Cluster API Provider AWS) and [CAPV](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere) (Cluster API Provider vSphere). + +Standard RKE2 provisioning relies on Rancher’s internal bootstrap and control plane providers alongside Rancher Node Drivers (via `rancher/machine`) as the infrastructure provider. This new mode allows you to substitute Rancher Node Drivers with native CAPI infrastructure providers while retaining Rancher’s bootstrap and control plane logic. + +This guide provides simple examples for evaluating this provisioning mode using CAPA and CAPV. Refer to the documentation of each provider for more details on available options and adapt these examples to your needs. + +:::note +Provisioning with a native CAPI infrastructure provider and Rancher as a bootstrap and control plane provider is distinct from using [Rancher Turtles](https://turtles.docs.rancher.com/turtles/stable/en/index.html) and the [CAPRKE2](https://caprke2.docs.rancher.com/) provider to provision a RKE2 cluster and subsequently import it into Rancher. +::: + +### Limitations and requirements + +- Unsupported configurations: Windows worker nodes and IPv6 are currently not supported. +- UI constraints: Detailed cluster management via the UI is disabled; clusters must be created and modified by applying Kubernetes objects to the local cluster. However, the Cluster Explorer remains accessible. +- Kubernetes cloud provider requirements: A cloud-specific Kubernetes provider for the infrastructure where the downstream cluster runs is required (e.g., the [Kubernetes AWS Cloud Provider](https://cloud-provider-aws.sigs.k8s.io/) for CAPA or the `rancher-vsphere-cpi` chart for CAPV). + +## General steps + +For both CAPA and CAPV, the general steps are as follows: + +1. Install Rancher. +1. Install a CAPI infrastructure provider, either CAPA or CAPV. +1. Set-up an identity resource for the provider. +1. Create a CAPI infrastructure cluster resource. +1. Create one or more CAPI infrastructure machine template resources. +1. Create a Rancher `clusters.provisioning.cattle.io` resource that references the identity, infrastructure cluster and infrastructure machine template resources. + +After applying the `clusters.provisioning.cattle.io` resource, the cluster appears in the Rancher Cluster Management list (click on **☰ > Cluster Management**), however the detailed view for this type of cluster is currently unavailable. + +To view the progress of the provisioning process and troubleshoot, refer to the status of the various CAPI and Rancher provisioning resources in the local cluster: + +1. Click **☰**, then click on the icon for your local cluster. +1. Use the dropdown menu at the top to filter for **All Namespaces**. +1. From the sidebar, select **More Resources > Cluster Provisioning**. + +The logs for the infrastructure provider deployment (e.g. `capa-controller-manager`) also show useful information. + +## Installing the infrastructure provider + +Rancher allows installing the infrastructure provider declaratively by creating the Rancher Turtles [`CAPIProvider`](https://turtles.docs.rancher.com/turtles/stable/en/reference/capiprovider.html) resource. + +### Examples + +CAPA: + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: capa-system +--- +apiVersion: turtles-capi.cattle.io/v1alpha1 +kind: CAPIProvider +metadata: + name: aws + namespace: capa-system +spec: + type: infrastructure + variables: + # Global credentials for the provider are not needed + # as these examples define credentials for the AWSCluster. + AWS_B64ENCODED_CREDENTIALS: "" +``` + +CAPV: + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + name: capv-system +--- +apiVersion: turtles-capi.cattle.io/v1alpha1 +kind: CAPIProvider +metadata: + name: vsphere + namespace: capv-system +spec: + type: infrastructure + variables: + # Global credentials for the provider are not needed + # as these examples define credentials for the VsphereCluster. + VSPHERE_USERNAME: "" + VSPHERE_PASSWORD: "" +``` + +## Provisioning a cluster + +For these examples, a single machine pool with all roles (control plane, etcd and worker) are used, but the examples can be adapted by specifying more machine pools and separate roles. + +Create the resources in your upstream cluster, and replace values within `<>` brackets. + +:::caution + +Each machine pool defined in the `clusters.provisioning.cattle.io` resource should reference a different machine template. + +::: + +### CAPA + +First, configure IAM as required by CAPA. These roles are assumed by downstream nodes using instance profiles to enable the Kubernetes AWS cloud provider. + +To do this, CAPA provides the `clusterawsadm` tool to generate and apply the required objects. Refer to the CAPA manual for more [details](https://cluster-api-aws.sigs.k8s.io/topics/using-clusterawsadm-to-fulfill-prerequisites). + +Then, configure the provider identity in the upstream cluster so that the CAPA provider can create resources on AWS. Refer to the manual for all [options](https://cluster-api-aws.sigs.k8s.io/topics/multitenancy). + +In this example, we'll use `AWSClusterStaticIdentity`. + +Create a secret with your credentials: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: capa-lab-credentials + namespace: capa-system +type: Opaque +stringData: + AccessKeyID: + SecretAccessKey: + # You might have a session token depending on your credential type. + # SessionToken: +``` + +Then, create the identity object that references the secret: + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 +kind: AWSClusterStaticIdentity +metadata: + name: capa-lab-identity +spec: + secretRef: capa-lab-credentials + allowedNamespaces: + # The namespace of the AWSCluster resource that points + # to this identity for provisioning. + list: + - fleet-default +``` + +Now, create the `AWSCluster` [resource](https://cluster-api-aws.sigs.k8s.io/crd/#infrastructure.cluster.x-k8s.io%2fv1beta2). This object defines the infrastructure configuration common to all machine pools. + +CAPA creates VPCs, subnets, security groups and a load balancer in its default configuration, but additional rules must be configured to allow ports needed by Rancher and RKE2. For simplicity, this example defines additional security group rules that allow all traffic between the nodes, but more restrictive rules can be configured instead. + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 +kind: AWSCluster +metadata: + name: capa-lab + namespace: fleet-default +spec: + identityRef: + kind: AWSClusterStaticIdentity + name: capa-lab-identity + + controlPlaneLoadBalancer: + healthCheckProtocol: TCP + loadBalancerType: nlb + + region: + + # These two additional rules allow all incoming traffic + # from other nodes. + network: + additionalControlPlaneIngressRules: + - protocol: "-1" + sourceSecurityGroupRoles: + - controlplane + - node + additionalNodeIngressRules: + - protocol: "-1" + sourceSecurityGroupRoles: + - controlplane + - node +``` + +Next, create a machine template for the control plane machine pool. Create additional templates for every machine pool defined in the `clusters.provisioning.cattle.io` resource. + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 +kind: AWSMachineTemplate +metadata: + name: capa-lab-control-plane + namespace: fleet-default +spec: + template: + spec: + ami: + # The ami requires cloud-init. + id: + # This should correspond to the profile created through clusterawsadm. + # Worker or etcd-only nodes should use nodes.cluster-api-provider-aws.sigs.k8s.io. + iamInstanceProfile: control-plane.cluster-api-provider-aws.sigs.k8s.io + instanceType: t3.medium + # This refers to the name of an EC2 key pair. + sshKeyName: + rootVolume: + size: 16 + cloudInit: + insecureSkipSecretsManager: true +``` + +:::caution +The `insecureSkipSecretsManager` option is set to true to bypass the AWS secrets manager as a source of userdata for the provisioned instances. This source restricts the visibility of the userdata but requires a custom cloud-init datasource which is not currently compatible with the userdata generated by Rancher. For more information, see the [CAPA documentation](https://cluster-api-aws.sigs.k8s.io/topics/userdata-privacy). +::: + +Finally, create the Rancher `clusters.provisioning.cattle.io` resource and point to the CAPA cluster and machine template that were just created. + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +metadata: + name: capa-lab + namespace: fleet-default +spec: + kubernetesVersion: v1.35.1+rke2r1 + rkeConfig: + # This is the ref to the infra cluster defined above. + infrastructureRef: + kind: AWSCluster + name: capa-lab + namespace: fleet-default + apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 + machinePools: + - name: ctrl + controlPlaneRole: true + etcdRole: true + workerRole: true + quantity: 3 + machineConfigRef: + kind: AWSMachineTemplate + name: capa-lab-control-plane + namespace: fleet-default + apiVersion: infrastructure.cluster.x-k8s.io/v1beta2 + machineGlobalConfig: + cni: calico + disable-kube-proxy: false + etcd-expose-metrics: false + ingress-controller: traefik + protect-kernel-defaults: false + cloud-provider-name: external + node-name-from-cloud-provider-metadata: true + # The AWS cloud controller definition. The controller uses the IAM instance profile for its AWS credentials. + additionalManifest: |- + apiVersion: helm.cattle.io/v1 + kind: HelmChart + metadata: + name: aws-cloud-controller-manager + namespace: kube-system + spec: + chart: aws-cloud-controller-manager + repo: https://kubernetes.github.io/cloud-provider-aws + targetNamespace: kube-system + bootstrap: true + valuesContent: |- + hostNetworking: true + nodeSelector: + node-role.kubernetes.io/control-plane: "true" + args: + - --configure-cloud-routes=false + - --v=5 + - --cloud-provider=aws +``` + +### CAPV + +First, configure the provider identity in the upstream cluster so that the CAPV provider can create resources on your vSphere server. Refer to the manual for all identity [options](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/v1.15.2/docs/identity_management.md), and for general vSphere [requirements](https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/v1.15.2/docs/getting_started.md). + +In this example, we'll use `VSphereClusterIdentity`. + +Create a secret with your credentials: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: capv-lab-credentials + namespace: capv-system +type: Opaque +stringData: + username: + password: +``` + +Then, create the identity object that references the secret: + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 +kind: VSphereClusterIdentity +metadata: + name: capv-lab-identity +spec: + secretName: capv-lab-credentials + allowedNamespaces: + selector: + # The namespace of the VSphereCluster for which this identity + # is used when provisioning. + matchLabels: + kubernetes.io/metadata.name: fleet-default +``` + +Like for CAPA, it is also necessary to install the [cloud provider for vSphere](https://github.com/kubernetes/cloud-provider-vsphere) in the downstream cluster. + +To securely transfer the credentials for the CPI chart, you can enable the prebootstrap feature in Rancher. This can be done by [enabling](../../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md) the `provisioningprebootstrap` feature flag and causes Rancher to restart. + +Now, create the secret that is sent to the downstream cluster. If you use a different name to create the `clusters.provisioning.cattle.io` resource, make sure you update the `rke.cattle.io/object-authorized-for-clusters` annotation below. + +```yaml +# Credential secret synced to the downstream cluster for the vsphere CPI chart. +apiVersion: v1 +kind: Secret +metadata: + name: vsphere-cpi-creds + namespace: fleet-default + annotations: + # Can be a comma-separated list for multiple clusters, with no spaces. + rke.cattle.io/object-authorized-for-clusters: capv-lab + provisioning.cattle.io/sync-bootstrap: "true" + provisioning.cattle.io/sync-target-namespace: kube-system +type: Opaque +stringData: + # Change the prefix of the key to match your vCenter host. + .username: + .password: +``` + +Now, create the `VSphereCluster` resource. This resource defines the infrastructure configuration common to all machine pools. Refer to the CAPV documentation for more configuration options. + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 +kind: VSphereCluster +metadata: + name: capv-lab + namespace: fleet-default +spec: + identityRef: + kind: VSphereClusterIdentity + name: capv-lab-identity + server: +``` + +Next, create a machine template for the control plane machine pool. Create additional templates for every machine pool defined in the `clusters.provisioning.cattle.io` resource. + +```yaml +apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 +kind: VSphereMachineTemplate +metadata: + name: capv-lab-control-plane + namespace: fleet-default +spec: + template: + spec: + datacenter: + datastore: + diskGiB: 20 + folder: + memoryMiB: 4096 + network: + devices: + - dhcp4: true + networkName: + numCPUs: 2 + os: Linux + resourcePool: + template: +``` + +Finally, create the Rancher `clusters.provisioning.cattle.io` resource and point to the CAPV cluster and machine template that were just created. Note that this example disables the CSI chart for simplicity. The CPI chart is required. + +```yaml +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +metadata: + name: capv-lab + namespace: fleet-default +spec: + kubernetesVersion: v1.35.1+rke2r1 + rkeConfig: + infrastructureRef: + kind: VSphereCluster + name: capv-lab + namespace: fleet-default + apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 + machinePools: + - name: ctrl + controlPlaneRole: true + etcdRole: true + workerRole: true + quantity: 3 + machineConfigRef: + kind: VSphereMachineTemplate + name: capv-lab-control-plane + namespace: fleet-default + apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 + machineGlobalConfig: + cni: calico + disable-kube-proxy: false + etcd-expose-metrics: false + ingress-controller: traefik + protect-kernel-defaults: false + disable: + - rancher-vsphere-csi + cloud-provider-name: rancher-vsphere + chartValues: + rancher-vsphere-cpi: + vCenter: + datacenters: + host: + # The credential secret is transferred by the prebootstrap mechanism, + # and the cpi chart expects the default name (vsphere-cpi-creds). + credentialsSecret: + generate: false +``` + +### Changing machine templates + +Machine templates for CAPI infrastructure providers, such as `AWSMachineTemplate` and `VSphereMachineTemplate` are usually immutable. To modify the configuration of the instances in a machine pool, create a new template with a different name, then edit the machine pool in `clusters.provisioning.cattle.io` to point to this new template. This causes all of the machines in that pool to be recreated with the new configuration. + +### Customizing userdata + +Custom user data can be defined for each machine pool in the `clusters.provisioning.cattle.io` resource. To do this, use the `.spec.rkeConfig.machinePools.userdata.inlineUserdata` as an inline yaml string in the plain cloud-config format. The contents of this field are merged with the userdata generated by Rancher to bootstrap the cluster nodes. + +:::caution +Do not include sensitive data in this field, as it is part of a resource other than a Secret. + +This field is experimental and subject to change. It is only valid for native CAPI providers described in this document, and has no effect on clusters provisioned by Rancher through the standard method with node drivers. +::: + +Modifying the userdata field causes all of the machines in the pool to be recreated. + +```yaml +# Only some fields of the provisioning cluster resource are shown here. +apiVersion: provisioning.cattle.io/v1 +kind: Cluster +metadata: + name: capv-lab + namespace: fleet-default +spec: + kubernetesVersion: v1.35.1+rke2r1 + rkeConfig: + machinePools: + - name: ctrl + userdata: + inlineUserdata: | + runcmd: + - ["echo", "Hello!"] +``` diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/configure-oidc-provider.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/configure-oidc-provider.md index 9f85fd52168..c51518c9969 100644 --- a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/configure-oidc-provider.md +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/configure-oidc-provider.md @@ -6,8 +6,13 @@ title: Configure Rancher as an OIDC provider -Rancher can function as a standard OpenID Connect (OIDC) provider, allowing external applications to use Rancher for authentication. -This can be used for enabling single sign-on (SSO) across Rancher Prime components. For example, see the [documentation](https://documentation.suse.com/cloudnative/suse-observability/latest/en/setup/security/authentication/oidc.html) for configuring the OIDC provider for SUSE Observability. +Rancher can act as an OpenID Connect (OIDC) Identity Provider (IdP) for other applications. This allows you to use Rancher's centralized authentication and role-based access control (RBAC) to manage access to external, third-party applications. This can be used for enabling single sign-on (SSO) across Rancher components. For example, see the [documentation](https://documentation.suse.com/cloudnative/suse-observability/latest/en/setup/security/authentication/oidc.html) for configuring the OIDC provider for SUSE Observability. + +:::note +Because OIDC is a superset of OAuth2, you can use Rancher as an OAuth2 server without requiring full OIDC. This ensures that clients utilizing the OAuth2 aspect, such as the `rancher-ai-mcp` server, are fully supported. +::: + +The Rancher OIDC Provider issues access tokens for OAuth2 and OIDC that can be used as standard Bearer tokens (per RFC6750) to authenticate with Rancher. Previously, only an ID token could be used to impersonate and authenticate a user. The OIDC provider can be enabled with the `oidc-provider` feature flag. When this flag is on the following endpoints are available: @@ -21,27 +26,51 @@ The OIDC provider can be enabled with the `oidc-provider` feature flag. When thi The OIDC provider supports the OIDC Authentication Code Flow with PKCE. -## Configure OIDCClient +## Configuring an OIDC Client -An `OIDCClient` represents an external application that will be authenticating against Rancher. +An `OIDCClient` represents an external application that will be authenticating against Rancher. To register a client application, you must create an `OIDCClient` custom resource. -### Programmatically +### Configuration Fields -Create an `OIDCClient`: +When defining your `OIDCClient` manifest, you must include specific fields to pass CRD validation: + +- `spec.tokenExpirationSeconds`: This field is strictly required and will cause a validation error if omitted. It defines the lifespan of the access token. +- `spec.refreshTokenExpirationSeconds`: This field is also strictly required and will cause a validation error if omitted. It defines the lifespan of the refresh token. +- `scopes` (Optional): This field allows you to restrict the scopes that a client can request. If not explicitly configured, the allowed scopes will default to `openid`, `profile`, and `offline_access`. + +### Example OIDC Client Manifest + +Below is an example of an `OIDCClient` configuration: + +:::note +You must include the expiration fields to successfully apply the resource. +::: ```yaml apiVersion: management.cattle.io/v3 kind: OIDCClient metadata: - name: oidc-client-test + name: example-client spec: - tokenExpirationSeconds: 600 # expiration of the id_token and access_token - refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token - redirectURIs: - - "https://myredirecturl.com" # replace with your redirect url + description: "Example OIDC Client" + redirectUris: + - "https://example-app.com/callback" + tokenExpirationSeconds: 3600 + refreshTokenExpirationSeconds: 86400 + # scopes: + # - openid + # - profile + # - offline_access + ``` -Rancher automatically generates a client ID and client secret for each `OIDCClient`. -Once the resource is created, Rancher populates the status field with the client id: + +Save this configuration to a file (e.g., `oidcclient.yaml`) and apply it to your Rancher local cluster: + +``` +kubectl apply -f oidcclient.yaml +``` + +Rancher automatically generates a client ID and client secret for each `OIDCClient`. Once the resource is created, Rancher populates the status field with the client id: ```yaml apiVersion: management.cattle.io/v3 @@ -53,6 +82,10 @@ spec: refreshTokenExpirationSeconds: 3600 # expiration of the refresh_token redirectURIs: - "https://myredirecturl.com" # replace with your redirect url + scopes: # Optional: Restricts the scopes the client can request. Defaults to openid, profile, and offline_access if omitted. + - openid + - profile + - offline_access status: clientID: client-xxx clientSecrets: @@ -61,8 +94,7 @@ status: lastFiveCharacters: xxx ``` -Rancher automatically generates a Kubernetes `Secret` in the `cattle-oidc-client-secrets` namespace for each `OIDCClient` resource. The Secret's name matches the `OIDCClient` client ID. -Initially, the `Secret` contains a single client secret. +Rancher automatically generates a Kubernetes `Secret` in the `cattle-oidc-client-secrets` namespace for each `OIDCClient` resource. The Secret's name matches the `OIDCClient` client ID. Initially, the `Secret` contains a single client secret. To retrieve the client secret: diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md index be7d1b5a57a..2fc11bb0d06 100644 --- a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/about-project-resource-quotas.md @@ -61,14 +61,12 @@ metadata: ``` In this example, if the project's quota does not include configMaps in its list of resources, then Rancher will ignore `configMaps` in this override. -Users are advised to create dedicated `ResourceQuota` objects in namespaces to configure additional custom limits for resources not defined on the project. -Resource quotas are native Kubernetes objects, and Rancher will ignore user-defined quotas in namespaces belonging to a project with a quota, -thus giving users more control. +Users are advised to either use the `extended` map to configure additional custom limits for resources not built into the project, for all namespaces in the project, or to create dedicated `ResourceQuota` objects in specific namespaces for the same, just for these namespaces. Resource quotas are native Kubernetes objects, and Rancher will ignore user-defined quotas in namespaces belonging to a project with a quota, thus giving users more control. The following table explains the key differences between the two quota types. | Rancher Resource Quotas | Kubernetes Resource Quotas | | ---------------------------------------------------------- | -------------------------------------------------------- | -| Applies to projects and namespace. | Applies to namespaces only. | -| Creates resource pool for all namespaces in project. | Applies static resource limits to individual namespaces. | +| Applies to projects and namespaces. | Applies to namespaces only. | +| Creates resource pool for all namespaces in a project. | Applies static resource limits to individual namespaces. | | Applies resource quotas to namespaces through propagation. | Applies only to the assigned namespace. diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md index a0ed1060085..27554d9cb67 100644 --- a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/manage-project-resource-quotas.md @@ -48,3 +48,17 @@ Edit resource quotas when: 1. Click **Create**. **Result:** The resource quota is applied to your project and namespaces. When you add more namespaces in the future, Rancher validates that the project can accommodate the namespace. If the project can't allocate the resources, you may still create namespaces, but they will be given a resource quota of 0. Subsequently, Rancher will not allow you to create any resources restricted by this quota. + +### Advanced: Beyond the basic Resource Quotas + +The set of resource quotas listed in the **Resource Type** dropdown of **Edit Config** is limited. For quotas outside of that set use **Edit Config** and **Add Resource** as already described, and select **Custom** as the resource type. This enables the edit field **Resource Identifier** for the entry of the necessary identifier. Some examples of identifiers are: + +- `requests.nvidia.com/gpu` +- `gold.storageclass.storage.k8s.io/requests.storage` +- `count/podtemplates` + +:::warning + +While it is possible to specify `Custom` which refer to quotas in the basic builtin set it is currently **strongly** recommended to use the builtin fields for them instead. Also, in case of conflicts, i.e. specifying a quota for a resource in both its builtin field and via `Custom`, the data found in the builtin field has priority and the data in `Custom` is ignored. + +::: diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md index 9f6c8ca5655..08d55f9f1a9 100644 --- a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/override-default-limit-in-namespaces.md @@ -8,7 +8,7 @@ title: Overriding the Default Limit for a Namespace Although the **Namespace Default Limit** propagates from the project to each namespace when created, in some cases, you may need to increase (or decrease) the quotas for a specific namespace. In this situation, you can override the default limits by editing the namespace. -In the diagram below, the Rancher administrator has a resource quota in effect for their project. However, the administrator wants to override the namespace limits for `Namespace 3` so that it has more resources available. Therefore, the administrator [raises the namespace limits](../../../new-user-guides/manage-clusters/projects-and-namespaces.md) for `Namespace 3` so that the namespace can access more resources. +In the diagram below, the Rancher administrator has a resource quota in effect for their project. However, the administrator wants to override the cpu limits for `Namespace 3` so that it has more resources available. Therefore, the administrator [raises the cpu limits](../../../new-user-guides/manage-clusters/projects-and-namespaces.md) for `Namespace 3` so that the namespace can access more resources. Namespace Default Limit Override diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md index e789f5bf38b..b29a473ce92 100644 --- a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/manage-projects/manage-project-resource-quotas/resource-quota-types.md @@ -6,14 +6,20 @@ title: Resource Quota Type Reference -When you create a resource quota, you are configuring the pool of resources available to the project. You can set the following resource limits for the following resource types. +When you create a resource quota, you are configuring the pool of resources available to the project. Rancher supports the use of arbitrary resource references and their quotas. This allows you to utilize all upstream [Kubernetes `ResourceQuota`](https://kubernetes.io/docs/concepts/policy/resource-quotas/#types-of-resource-quota) types when managing project resource quotas. + +You can set resource limits for the following predefined resource types, where the `Custom` type enables specification of arbitrary resources and their quotas. + +:::note +Support for arbitrary resource references using the `Custom` type does not cover resources in the `ext.cattle.io` API group. +::: | Resource Type | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| CPU Limit* | The maximum amount of CPU (in [millicores](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)) allocated to the project/namespace.1 | +| CPU Limit* | The maximum amount of CPU (in [millicores](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu)) allocated to the project/namespace.1 | | CPU Reservation* | The minimum amount of CPU (in millicores) guaranteed to the project/namespace.1 | -| Memory Limit* | The maximum amount of memory (in bytes) allocated to the project/namespace.1 | -| Memory Reservation* | The minimum amount of memory (in bytes) guaranteed to the project/namespace.1 | +| Memory Limit* | The maximum amount of memory (in [bytes](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory)) allocated to the project/namespace.1 | +| Memory Reservation* | The minimum amount of memory (in bytes) guaranteed to the project/namespace.1 | | Storage Reservation | The minimum amount of storage (in gigabytes) guaranteed to the project/namespace. | | Services Load Balancers | The maximum number of load balancers services that can exist in the project/namespace. | | Services Node Ports | The maximum number of node port services that can exist in the project/namespace. | @@ -22,10 +28,23 @@ When you create a resource quota, you are configuring the pool of resources avai | ConfigMaps | The maximum number of ConfigMaps that can exist in the project/namespace. | | Persistent Volume Claims | The maximum number of persistent volume claims that can exist in the project/namespace. | | Replications Controllers | The maximum number of replication controllers that can exist in the project/namespace. | -| Secrets | The maximum number of secrets that can exist in the project/namespace. | +| Secrets | The maximum number of secrets that can exist in the project/namespace. | | +| Custom\*\* | The specification of arbitrary resources and their quotas, beyond the resource types built into projects, as listed above. | :::note ***** -When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project / namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. +When setting resource quotas, if you set anything related to CPU or Memory (i.e. limits or reservations) on a project or namespace, all containers will require a respective CPU or Memory field set during creation. A container default resource limit can be set at the same time to avoid the need to explicitly set these limits for every workload. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#requests-vs-limits) for more details on why this is required. -::: \ No newline at end of file +::: + +:::note **\*\*** + +For example: + + - `requests.nvidia.com/gpu: 4` + - `gold.storageclass.storage.k8s.io/requests.storage: 500Gi` + - `count/podtemplates: 10` + +See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/policy/resource-quotas/#quota-for-extended-resources) for many more examples. + +::: diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md new file mode 100644 index 00000000000..68fce21e8ad --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway.md @@ -0,0 +1,268 @@ +--- +title: Using an External Gateway with Rancher +--- + + + + + +## Using an External Gateway with Rancher + +When using the Gateway API network exposure type, Rancher can create and manage its own Gateway resource. However, if you have an existing Gateway that you manage independently (for example, a shared Gateway used by multiple applications), you will need to create your own HTTPRoute resources to route traffic to Rancher. + +This section covers how to create the required HTTPRoute resources manually when using an externally managed Gateway. + +### Prerequisites + +- An existing Gateway resource configured and operational in your cluster +- Knowledge of your Gateway's: + - Name and namespace + - Listener names (sectionName) for HTTP and/or HTTPS traffic +- Rancher installed with `networkExposure.type` set to something other than `gateway` (e.g., `none` or `ingress`) + +### Cross-Namespace Gateway Requirements + +If your Gateway is in a different namespace than Rancher (e.g., Gateway in `gateway-system`, Rancher in `cattle-system`), the Gateway must be configured to accept HTTPRoutes from the Rancher namespace. By default, Gateway API only allows routes from the same namespace as the Gateway. + +The Gateway owner must configure `allowedRoutes` on the relevant listeners. There are two options: + +**Option 1: Allow routes from all namespaces** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: shared-gateway + namespace: gateway-system +spec: + gatewayClassName: example + listeners: + - name: https + port: 443 + protocol: HTTPS + allowedRoutes: + namespaces: + from: All + - name: http + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: All +``` + +**Option 2: Allow routes from specific namespaces (more restrictive)** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: Gateway +metadata: + name: shared-gateway + namespace: gateway-system +spec: + gatewayClassName: example + listeners: + - name: https + port: 443 + protocol: HTTPS + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + shared-gateway-access: "true" + - name: http + port: 80 + protocol: HTTP + allowedRoutes: + namespaces: + from: Selector + selector: + matchLabels: + shared-gateway-access: "true" +``` + +When using the selector approach, ensure the Rancher namespace has the required label: + +```bash +kubectl label namespace cattle-system shared-gateway-access=true +``` + +> **Note:** If the Gateway and Rancher are in the same namespace, no additional configuration is needed—the default `allowedRoutes` setting (`from: Same`) will permit the HTTPRoute attachment. + +### Determining Your Rancher Service Values + +Before creating HTTPRoute resources, identify the following values from your Rancher installation: + +| Value | How to Determine | Example | +|-------|------------------|---------| +| **Release Name** | The name used in `helm install ` | `rancher` | +| **Namespace** | The namespace where Rancher is installed | `cattle-system` | +| **Hostname** | The `hostname` value from your Helm values | `rancher.example.com` | +| **TLS Mode** | The `tls` value from your Helm values | `ingress`, `external`, or `secret` | +| **Service HTTP Disabled** | The `service.disableHTTP` value | `true` or `false` | + +The Rancher service name follows the pattern: `-rancher` (or just `` if the release name already contains "rancher"). + +### HTTPRoute Configuration + +#### Primary HTTPRoute + +Create an HTTPRoute to direct traffic from your Gateway to the Rancher service. The configuration depends on your TLS setup: + +**When TLS terminates at the Gateway or within Kubernetes (`tls: ingress`, `tls: secret`, or `tls: letsEncrypt`):** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher + namespace: cattle-system # Must match Rancher's namespace +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTPS listener + hostnames: + - # e.g., rancher.example.com + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher # Your Rancher service name + port: 80 # Use 443 if service.disableHTTP=true +``` + +**When TLS terminates externally (`tls: external`):** + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher + namespace: cattle-system +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTP listener + hostnames: + - + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher + port: 80 +``` + +#### HTTP to HTTPS Redirect Route (Optional) + +If TLS terminates at or within Kubernetes (not externally), you may want to redirect HTTP traffic to HTTPS. Create an additional HTTPRoute: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: rancher-http-redirect + namespace: cattle-system +spec: + parentRefs: + - name: + namespace: + sectionName: # Your Gateway's HTTP listener + hostnames: + - + rules: + - filters: + - type: RequestRedirect + requestRedirect: + scheme: https + statusCode: 301 +``` + +### Using extraObjects + +You can include these HTTPRoute resources directly in your Rancher Helm installation using the `extraObjects` value. This keeps all resources managed together: + +```yaml +# values.yaml +hostname: rancher.example.com +tls: ingress + +extraObjects: + - apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: rancher + spec: + parentRefs: + - name: my-shared-gateway + namespace: gateway-system + sectionName: https + hostnames: + - rancher.example.com + rules: + - matches: + - path: + type: PathPrefix + value: / + backendRefs: + - name: rancher + port: 80 + + - apiVersion: gateway.networking.k8s.io/v1 + kind: HTTPRoute + metadata: + name: rancher-http-redirect + spec: + parentRefs: + - name: my-shared-gateway + namespace: gateway-system + sectionName: http + hostnames: + - rancher.example.com + rules: + - filters: + - type: RequestRedirect + requestRedirect: + scheme: https + statusCode: 301 +``` + +### Backend Port Selection + +The port in `backendRefs` depends on your `service.disableHTTP` setting: + +| `service.disableHTTP` | Backend Port | +|-----------------------|--------------| +| `false` (default) | `80` | +| `true` | `443` | + +### Listener Selection Summary + +| TLS Configuration | Primary Route Listener | Redirect Route | +|-------------------|------------------------|----------------| +| `tls: external` | HTTP listener | Not needed | +| `tls: ingress` | HTTPS listener | HTTP listener (optional) | +| `tls: secret` | HTTPS listener | HTTP listener (optional) | +| `tls: letsEncrypt`| HTTPS listener | HTTP listener (optional) | + +### Troubleshooting + +**HTTPRoute not being accepted:** +- Verify the Gateway name and namespace are correct +- Ensure the `sectionName` matches an existing listener on your Gateway +- Check that the listener allows routes from the Rancher namespace (see Gateway's `allowedRoutes` configuration) + +**Connection refused or timeouts:** +- Confirm the Rancher service exists and has endpoints: `kubectl get endpoints rancher -n cattle-system` +- Verify the backend port matches your `service.disableHTTP` setting + +**Certificate errors:** +- If using `tls: ingress` or `tls: secret`, ensure your Gateway's HTTPS listener has the appropriate certificate configured +- Verify the certificate covers your Rancher hostname diff --git a/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md new file mode 100644 index 00000000000..3204dced2e4 --- /dev/null +++ b/versioned_docs/version-2.14/how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides.md @@ -0,0 +1,10 @@ +--- +title: Rancher Deployment Guides +--- + + + + + +- [Using an External Gateway with Rancher](configure-with-existing-gateway.md) + diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md index cf4937b0037..ef6c1bbdfbb 100644 --- a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-amazon-cognito.md @@ -53,6 +53,10 @@ if the user has not yet logged in to Rancher. However, if the user has previousl | Client Secret | The generated Secret of your Amazon Cognito App Client. | | Issuer | The Issuer URL of your Amazon Cognito App Client. It follows the format `https://cognito-idp.{region}.amazonaws.com/{userPoolId}`, and can be found in the App Client settings page. Rancher uses the Issuer URL to fetch all of the required URLs. | +## OIDC Support for PKCE Extension + + + ## Configuring OIDC Single Logout (SLO) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md index 8ec61010eda..4226c885c26 100644 --- a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-generic-oidc.md @@ -139,6 +139,10 @@ For example, if your IdP sends `groups` in a claim called `custom_roles`, enter | Custom Email Claim | `email` | The name of the claim in the OIDC token that contains the user's email address. | | Custom Groups Claim | `groups` | The name of the claim in the OIDC token that contains the user's group memberships (used for RBAC). | +## OIDC Support for PKCE Extension + + + ## Configuring OIDC Single Logout (SLO) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md index 0d406be4273..cf06bbc57ff 100644 --- a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-oidc.md @@ -168,6 +168,10 @@ After configuration is completed, Rancher user permissions need to be reapplied ::: +## OIDC Support for PKCE Extension + + + ## Configuring OIDC Single Logout (SLO) diff --git a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md index 0c049f2076b..5a719447819 100644 --- a/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md +++ b/versioned_docs/version-2.14/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/notification-center.md @@ -1,14 +1,28 @@ --- -title: Notification Center +title: Notifications --- +The Rancher dashboard delivers dynamic notifications and system alerts to ensure that you stay informed about the latest updates, lifecycle events, and statuses relevant to your deployment. + +## Dynamic Content + +Rancher fetches dynamic content, including notifications about new releases, End of Maintenance (EOM) or End of Life (EOL) statuses, and other important announcements. + +Dynamic content is delivered to users through three areas in the Rancher dashboard. + +* **Home page notification banner**: A dynamic banner displayed at the top of the home page for high-priority announcements. +* **Home page section below the Links**: A dedicated area on the home page, located beneath the **Links** section, that displays relevant updates and resources. +* **[Notification center](#what-is-the-notification-center)**: A centralized hub for all notifications, including system alerts, resources and announcements. + +To interact with these notifications, click **Learn More** on the listed resource. You can also dismiss the notification. + ## What is the Notification Center? -The Notification Center, located in the upper-right corner of your Rancher dashboard and marked by a bell icon, is your central hub for staying informed about various events within Rancher. +The notification center acts as a central repository for both system-generated alerts and dynamic announcements. You can access it by clicking the bell icon in the top right corner of the Rancher dashboard. Notifications are categorized by severity and type: diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md index 939522101ea..d2db2329e53 100644 --- a/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md +++ b/versioned_docs/version-2.14/integrations-in-rancher/cloud-marketplace/aws-cloud-marketplace/install-adapter.md @@ -19,10 +19,7 @@ In order to deploy and run the adapter successfully, you need to ensure its vers | Rancher Version | Adapter Version | |-----------------|------------------| -| v2.13.3 | 108.0.0+up8.0.0 | -| v2.13.2 | 108.0.0+up8.0.0 | -| v2.13.1 | 108.0.0+up8.0.0 | -| v2.13.0 | 108.0.0+up8.0.0 | +| v2.14.0 | 109.0.0+up9.0.0 | ### 1. Gain Access to the Local Cluster diff --git a/versioned_docs/version-2.14/integrations-in-rancher/cluster-api/overview.md b/versioned_docs/version-2.14/integrations-in-rancher/cluster-api/overview.md index e2e4a661ce0..65b24f655ed 100644 --- a/versioned_docs/version-2.14/integrations-in-rancher/cluster-api/overview.md +++ b/versioned_docs/version-2.14/integrations-in-rancher/cluster-api/overview.md @@ -20,51 +20,13 @@ Rancher Turtles meets [SLSA Level 3](https://slsa.dev/spec/v1.0/levels#build-l3) ## Prerequisites -Before installing Rancher Turtles in your Rancher environment, you must disable Rancher's `embedded-cluster-api` functionality. This also includes cleaning up Rancher-specific webhooks that otherwise would conflict with CAPI ones. +:::important -To simplify setting up Rancher for installing Rancher Turtles, the official Rancher Turtles Helm chart includes a `pre-install` hook that removes the following: +Starting with Rancher v2.14.0, the built-in `embedded-cluster-api` functionality (also known as the `rancher-provisioning-capi` chart) has been removed. [Rancher Turtles](https://turtles.docs.rancher.com/) is now the only supported method for Cluster API integration with Rancher. -- Disables the `embedded-cluster-api` feature in Rancher. -- Deletes the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks, as they are no longer needed. +If you are upgrading from a previous version of Rancher (v2.13.x or earlier), you no longer need to manually disable the `embedded-cluster-api` feature flag or clean up related webhooks before installing Rancher Turtles. -These webhooks can be removed through the Rancher UI as well: - -1. In the upper left corner, click **☰** > **Cluster Management**. -1. Select your local cluster. -1. In the left-hand navigation menu, select **More Resources** > **Admission**. -1. From the dropdown, select the Resource pages for `MutatingWebhookConfiguration` and `ValidatingWebhookConfiguration`. -1. On the respective Resource pages, click the **⋮** that are attached to the `mutating-webhook-configuration` and `validating-webhook-configuration` webhooks and select the **Delete** option. - -The webhooks can also be accessed by entering the names of the webhooks into the **Resource Search** field. - -The following `kubectl` commands can manually remove the necessary webhooks: - -```console -kubectl delete mutatingwebhookconfiguration.admissionregistration.k8s.io mutating-webhook-configuration -``` - -```console -kubectl delete validatingwebhookconfigurations.admissionregistration.k8s.io validating-webhook-configuration -``` - -Use the following example to disable the `embedded-cluster-api` feature from the console: - -1. Create a `feature.yaml` file, with `embedded-cluster-api` set to false: - -```yaml title="feature.yaml" -apiVersion: management.cattle.io/v3 -kind: Feature -metadata: - name: embedded-cluster-api -spec: - value: false -``` - -2. Use `kubectl` to apply the `feature.yaml` file to the cluster: - -```bash -kubectl apply -f feature.yaml -``` +::: ## Installing the Rancher Turtles Operator @@ -240,21 +202,3 @@ Remember that, if you use a different name for the installation or a different n ::: -After Rancher Turtles is uninstalled, Rancher's `embedded-cluster-api` feature must be re-enabled: - -1. Create a `feature.yaml` file, with `embedded-cluster-api` set to true: - -```yaml title="feature.yaml" -apiVersion: management.cattle.io/v3 -kind: Feature -metadata: - name: embedded-cluster-api -spec: - value: true -``` - -2. Use `kubectl` to apply the `feature.yaml` file to the cluster: - -```bash -kubectl apply -f feature.yaml -``` diff --git a/versioned_docs/version-2.14/reference-guides/rancher-webhook.md b/versioned_docs/version-2.14/reference-guides/rancher-webhook.md index 9b8206fb9dc..90e2348fa63 100644 --- a/versioned_docs/version-2.14/reference-guides/rancher-webhook.md +++ b/versioned_docs/version-2.14/reference-guides/rancher-webhook.md @@ -20,10 +20,7 @@ Each Rancher version is designed to be compatible with a single version of the w | Rancher Version | Webhook Version | Availability in Prime | Availability in Community | |-----------------|-----------------|-----------------------|---------------------------| -| v2.13.3 | v0.9.3 | ✓ | ✓ | -| v2.13.2 | v0.9.2 | ✓ | ✓ | -| v2.13.1 | v0.9.1 | ✓ | ✓ | -| v2.13.0 | v0.9.0 | ✗ | ✓ | +| v2.14.0 | v0.10.0 | ✗ | ✓ | ## Why Do We Need It? diff --git a/versioned_docs/version-2.14/reference-guides/user-settings/api-keys.md b/versioned_docs/version-2.14/reference-guides/user-settings/api-keys.md index 634a7396d33..939e871e145 100644 --- a/versioned_docs/version-2.14/reference-guides/user-settings/api-keys.md +++ b/versioned_docs/version-2.14/reference-guides/user-settings/api-keys.md @@ -6,6 +6,8 @@ title: API Keys + + ## API Keys and User Authentication If you want to access your Rancher clusters, projects, or other objects using external applications, you can do so using the Rancher API. However, before your application can access the API, you must provide the app with a key used to authenticate with Rancher. You can obtain a key using the Rancher UI. diff --git a/versioned_sidebars/version-2.14-sidebars.json b/versioned_sidebars/version-2.14-sidebars.json index 98ea9022fde..411a51c68d6 100644 --- a/versioned_sidebars/version-2.14-sidebars.json +++ b/versioned_sidebars/version-2.14-sidebars.json @@ -616,6 +616,17 @@ "id": "how-to-guides/advanced-user-guides/advanced-user-guides" }, "items": [ + { + "type": "category", + "label": "Rancher Deployment Guides", + "link": { + "type": "doc", + "id": "how-to-guides/advanced-user-guides/rancher-deployment-guides/rancher-deployment-guides" + }, + "items": [ + "how-to-guides/advanced-user-guides/rancher-deployment-guides/configure-with-existing-gateway" + ] + }, { "type": "category", "label": "Project Administration", @@ -751,7 +762,8 @@ "how-to-guides/advanced-user-guides/enable-cluster-agent-scheduling-customization", "how-to-guides/advanced-user-guides/configure-layer-7-nginx-load-balancer", "how-to-guides/advanced-user-guides/configure-oidc-provider", - "how-to-guides/advanced-user-guides/ui-server-side-pagination" + "how-to-guides/advanced-user-guides/ui-server-side-pagination", + "how-to-guides/advanced-user-guides/capi-infrastructure-providers" ] } ]