public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-04-14 02:15:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add v2.14 preview docs (#2212)

Browse Source
This commit is contained in:
Lucas Saintarbor
2026-03-05 12:30:57 -08:00
committed by GitHub
parent 4a0d71b3f3
commit 2dcfa6f6b8
874 changed files with 92618 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
versioned_docs/version-2.14/api/api-reference.mdx Normal file
View File

@@ -0,0 +1,18 @@
---
title: API Reference
hide_table_of_contents: true
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/api-reference"/>
</head>
:::note
At this time, not all Rancher resources are available through the Rancher Kubernetes API.
:::
import ApiDocMdx from '@theme/ApiDocMdx';
<ApiDocMdx id="rancher-api-v2-13" />

90
versioned_docs/version-2.14/api/api-tokens.md Normal file
View File

@@ -0,0 +1,90 @@
---
title: Using API Tokens
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/api-tokens"/>
</head>
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.
You can deactivate API tokens by deleting them or by deactivating the user account.
## Deleting Tokens
To delete a token:
1. Go to the list of all tokens in the Rancher API view at `https://<Rancher-Server-IP>/v3/tokens`.
1. Access the token you want to delete by its ID. For example, `https://<Rancher-Server-IP>/v3/tokens/kubectl-shell-user-vqkqt`
1. Click **Delete**.
The following is a complete list of tokens generated with `ttl=0`:
| Token | Description |
| ----------------- | -------------------------------------------------------------------------------------- |
| `kubectl-shell-*` | Access to `kubectl` shell in the browser |
| `agent-*` | Token for agent deployment |
| `compose-token-*` | Token for compose |
| `helm-token-*` | Token for Helm chart deployment |
| `drain-node-*` | Token for drain (Rancher uses `kubectl` for drain because there is no native Kubernetes API). |
## Setting TTL on Kubeconfig Tokens
Admins can set a global time-to-live (TTL) on Kubeconfig tokens. Changing the default kubeconfig TTL can be done by navigating to global settings and setting [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) to the desired duration in minutes. As of Rancher v2.8, the default value of [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) is `43200`, which means that tokens expire in 30 days.
:::note
This setting is used by all kubeconfig tokens except those created by the CLI to [generate kubeconfig tokens](#disable-tokens-in-generated-kubeconfigs).
:::
## Disable Tokens in Generated Kubeconfigs
Set the `kubeconfig-generate-token` setting to `false`. This setting instructs Rancher to no longer automatically generate a token when a user clicks on download a kubeconfig file. When this setting is deactivated, a generated kubeconfig references the [Rancher CLI](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl) to retrieve a short-lived token for the cluster. When this kubeconfig is used in a client, such as `kubectl`, the Rancher CLI needs to be installed to complete the log in request.
## Token Hashing
You can [enable token hashing](../how-to-guides/advanced-user-guides/enable-experimental-features/enable-experimental-features.md), where tokens undergo a one-way hash using the SHA256 algorithm. This is a non-reversible process: once enabled, this feature cannot be disabled. You should first evaluate this setting in a test environment, and/or take backups before enabling.
This feature affects all tokens which include, but are not limited to, the following:
- Kubeconfig tokens
- Bearer tokens API keys/calls
- Tokens used by internal operations
## Token Settings
These global settings affect Rancher token behavior.
| Setting | Description |
| ------- | ----------- |
| [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) | TTL in minutes on a user auth session token. |
| [`auth-user-session-idle-ttl-minutes`](#auth-user-session-idle-ttl-minutes) | TTL in minutes on a user auth session token, without user activity. |
| [`kubeconfig-default-token-ttl-minutes`](#kubeconfig-default-token-ttl-minutes) | Default TTL applied to all kubeconfig tokens except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). |
| [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes) | Max TTL for all tokens except those controlled by [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes). |
| [`kubeconfig-generate-token`](#kubeconfig-generate-token) | If true, automatically generate tokens when a user downloads a kubeconfig. |
### auth-user-session-ttl-minutes
Time to live (TTL) duration in minutes, used to determine when a user auth session token expires. When expired, the user must log in and obtain a new token. This setting is not affected by [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). Session tokens are created when a user logs into Rancher.
### auth-user-session-idle-ttl-minutes
Time to live (TTL) without user activity for login sessions tokens, in minutes.
By default, `auth-user-session-idle-ttl-minutes` is set to the same value as [`auth-user-session-ttl-minutes`](#auth-user-session-ttl-minutes) (for backward compatibility). It must never exceed the value of `auth-user-session-ttl-minutes`.
### kubeconfig-default-token-ttl-minutes
Time to live (TTL) duration in minutes, used to determine when a kubeconfig token expires. When the token is expired, the API rejects the token. This setting can't be larger than [`auth-token-max-ttl-minutes`](#auth-token-max-ttl-minutes). This setting applies to tokens generated in a requested kubeconfig file, except for tokens [generated by Rancher CLI](#disable-tokens-in-generated-kubeconfigs). As of Rancher v2.8, the default duration is `43200`, which means that tokens expire in 30 days.
### auth-token-max-ttl-minutes
Maximum Time to Live (TTL) in minutes allowed for auth tokens. If a user attempts to create a token with a TTL greater than `auth-token-max-ttl-minutes`, Rancher sets the token TTL to the value of `auth-token-max-ttl-minutes`. Applies to all kubeconfig tokens and API tokens. As of Rancher v2.8, the default duration is `129600`, which means that tokens expire in 90 days.
### kubeconfig-generate-token
When true, kubeconfigs requested through the UI contain a valid token. When false, kubeconfigs contain a command that uses the Rancher CLI to prompt the user to log in. [The CLI then retrieves and caches a token for the user](../reference-guides/cli-with-rancher/kubectl-utility.md#authentication-with-kubectl-and-kubeconfig-tokens-with-ttl).

20
versioned_docs/version-2.14/api/extension-apiserver.md Normal file
View File

@@ -0,0 +1,20 @@
---
title: Extension API Server
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/extension-apiserver"/>
</head>
Rancher extends Kubernetes with additional APIs by registering an extension API server using the [Kubernetes API Aggregation Layer](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/).
## Aggregation Layer is Required
The API aggregation layer must be configured on the local Kubernetes cluster for the `v1.ext.cattle.io` `APIService` to work correctly. If the `APIService` does not receive a registration request after the Rancher server starts, the pod will crash with a log entry indicating the error. If your pods are consistently failing to detect registration despite having a correctly configured cluster, you can increase the timeout by setting the `.Values.aggregationRegistrationTimeout` in Helm.
All versions of Kubernetes supported in this Rancher versions K8s distributions (RKE2/K3s) will have the aggregation layer configured and enabled by default. However, if you suspect that your cluster configuration is incorrect, refer to the [Kubernetes Aggregation Layer documentation](https://kubernetes.io/docs/tasks/extend-kubernetes/configure-aggregation-layer/) for information on configuring the aggregation layer.
:::note
If the underlying Kubernetes distribution does not support the aggregation layer, you must migrate to a Kubernetes distribution that does before upgrading.
:::

152
versioned_docs/version-2.14/api/quickstart.md Normal file
View File

@@ -0,0 +1,152 @@
---
title: RK-API Quick Start Guide
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/quickstart"/>
</head>
You can access Rancher's resources through the Kubernetes API. This guide helps you get started on using this API as a Rancher user.
1. In the upper left corner, click **☰ > Global Settings**.
2. Find and copy the address in the `server-url` field.
3. [Create](../reference-guides/user-settings/api-keys.md#creating-an-api-key) a Rancher API key with no scope.
:::danger
A Rancher API key with no scope grants unrestricted access to all resources that the user can access. To prevent unauthorized use, this key should be stored securely and rotated frequently.
:::
4. Create a `kubeconfig.yaml` file. Replace `$SERVER_URL` with the server url and `$API_KEY` with your Rancher API key:
```yaml
apiVersion: v1
kind: Config
clusters:
- name: "rancher"
cluster:
server: "$SERVER_URL"
users:
- name: "rancher"
user:
token: "$API_KEY"
contexts:
- name: "rancher"
context:
user: "rancher"
cluster: "rancher"
current-context: "rancher"
```
You can use this file with any compatible tool, such as kubectl or [client-go](https://github.com/kubernetes/client-go). For a quick demo, see the [kubectl example](#api-kubectl-example).
For more information on handling more complex certificate setups, see [Specifying CA Certs](#specifying-ca-certs).
For more information on available kubeconfig options, see the [upstream documentation](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/).
## API kubectl Example
In this example, we'll show how to use kubectl to create a project, followed by deleting it. For a list of other Rancher resources available, refer to the [API Reference](./api-reference.mdx) page.
:::note
At this time, not all Rancher resources are available through the Rancher Kubernetes API.
:::
1. Set your KUBECONFIG environment variable to the kubeconfig file you just created:
```bash
export KUBECONFIG=$(pwd)/kubeconfig.yaml
```
2. Use `kubectl explain` to view the available fields for projects, or complex sub-fields of resources:
```bash
kubectl explain projects
kubectl explain projects.spec
```
Not all resources may have detailed output.
3. Add the following content to a file named `project.yaml`:
```yaml
apiVersion: management.cattle.io/v3
kind: Project
metadata:
# name should be unique across all projects in every cluster
name: p-abc123
# generateName can be used instead of `name` to randomly generate a name.
# generateName: p-
# namespace should match spec.ClusterName.
namespace: local
spec:
# clusterName should match `metadata.Name` of the target cluster.
clusterName: local
description: Example Project
# displayName is the human-readable name and is visible from the UI.
displayName: Example
```
4. Create the project:
```bash
kubectl create -f project.yaml
```
5. Delete the project:
How you delete the project depends on how you created the project name.
**A. If you used `name` when creating the project**:
```bash
kubectl delete -f project.yaml
```
**B. If you used `generateName`**:
Replace `$PROJECT_NAME` with the randomly generated name of the project displayed by Kubectl after you created the project.
```bash
kubectl delete project $PROJECT_NAME -n local
```
## Specifying CA Certs
To ensure that your tools can recognize Rancher's CA certificates, most setups require additional modifications to the above template.
1. In the upper left corner, click **☰ > Global Settings**.
2. Find and copy the value in the `ca-certs` field.
3. Save the value in a file named `rancher.crt`.
:::note
If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated in step 5.
:::
4. The following commands convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finish by removing the `rancher.crt` file:
```bash
export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG
kubectl config set clusters.rancher.certificate-authority-data $(cat rancher.crt | base64 -i - | tr -d '\n')
rm rancher.crt
```
5. (Optional) If you use self-signed certificatess that aren't trusted by your system, you can set the insecure option in your kubeconfig with kubectl:
:::danger
This option shouldn't be used in production as it is a security risk.
:::
```bash
export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG
kubectl config set clusters.rancher.insecure-skip-tls-verify true
```
If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated above.

94
versioned_docs/version-2.14/api/v3-rancher-api-guide.md Normal file
View File

@@ -0,0 +1,94 @@
---
title: Previous v3 Rancher API Guide
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/v3-rancher-api-guide"/>
</head>
Rancher v2.8.0 introduced the Rancher Kubernetes API (RK-API). The previous v3 Rancher API is still available. This page describes the v3 API. For more information on RK-API, see the [RK-API quickstart](./quickstart.md) and [reference guide](./api-reference.mdx).
## How to Use the API
The previous v3 API has its own user interface accessible from a [web browser](#enable-view-in-api). This is an easy way to see resources, perform actions, and see the equivalent `curl` or HTTP request & response. To access it:
<Tabs>
<TabItem value="Rancher v2.6.4+">
1. Click your user avatar in the upper right corner.
1. Click **Account & API Keys**.
1. Under the **API Keys** section, find the **API Endpoint** field and click the link. The link looks something like `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
</TabItem>
<TabItem value="Rancher before v2.6.4">
Go to the URL endpoint at `https://<RANCHER_FQDN>/v3`, where `<RANCHER_FQDN>` is the fully qualified domain name of your Rancher deployment.
</TabItem>
</Tabs>
## Authentication
API requests must include authentication information. Authentication is done with HTTP basic authentication using [API keys](../reference-guides/user-settings/api-keys.md). API keys can create new clusters and have access to multiple clusters via `/v3/clusters/`. [Cluster and project roles](../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md) apply to these keys and restrict what clusters and projects the account can see and what actions they can take.
By default, certain 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. For details on how to invalidate them, refer to the [API tokens page](api-tokens.md).
## Making Requests
The API is generally RESTful but has several features to make the definition of everything discoverable by a client so that generic clients can be written instead of having to write specific code for every type of resource. For detailed info about the generic API spec, [see further documentation](https://github.com/rancher/api-spec/blob/master/specification.md).
- Every type has a Schema which describes:
- The URL to get to the collection of this type of resource.
- Every field the resource can have, along with their type, basic validation rules, whether they are required or optional, etc.
- Every action that is possible on this type of resource, with their inputs and outputs (also as schemas).
- Every field that allows filtering.
- What HTTP verb methods are available for the collection itself, or for individual resources in the collection.
The design allows you to load just the list of schemas and access everything about the API. The UI for the API contains no code specific to Rancher itself. The URL to get Schemas is sent in every HTTP response as a `X-Api-Schemas` header. From there you can follow the `collection` link on each schema to know where to list resources, and follow other `links` inside of the returned resources to get any other information.
In practice, you may just want to construct URL strings. We highly suggest limiting this to the top-level to list a collection (`/v3/<type>`) or get a specific resource (`/v3/<type>/<id>`). Anything deeper than that is subject to change in future releases.
Resources have relationships between each other called links. Each resource includes a map of `links` with the name of the link and the URL where you can retrieve that information. Again, you should `GET` the resource and then follow the URL in the `links` map, not construct these strings yourself.
Most resources have actions, which do something or change the state of the resource. To use them, send a HTTP `POST` to the URL in the `actions` map of the action you want. Certain actions require input or produce output. See the individual documentation for each type or the schemas for specific information.
To edit a resource, send a HTTP `PUT` to the `links.update` link on the resource with the fields that you want to change. If the link is missing then you don't have permission to update the resource. Unknown fields and ones that are not editable are ignored.
To delete a resource, send a HTTP `DELETE` to the `links.remove` link on the resource. If the link is missing then you don't have permission to update the resource.
To create a new resource, HTTP `POST` to the collection URL in the schema (which is `/v3/<type>`).
## Filtering
Most collections can be filtered on the server-side by common fields using HTTP query parameters. The `filters` map shows you what fields can be filtered on and what the filtered values were for the request you made. The API UI has controls to setup filtering and show you the appropriate request. For simple "equals" matches it's just `field=value`. Modifiers can be added to the field name, for example, `field_gt=42` for "field is greater than 42." See the [API spec](https://github.com/rancher/api-spec/blob/master/specification.md#filtering) for full details.
## Sorting
Most collections can be sorted on the server-side by common fields using HTTP query parameters. The `sortLinks` map shows you what sorts are available, along with the URL to get the collection sorted by that. It also includes info about what the current response was sorted by, if specified.
## Pagination
API responses are paginated with a limit of 100 resources per page by default. This can be changed with the `limit` query parameter, up to a maximum of 1000, for example, `/v3/pods?limit=1000`. The `pagination` map in collection responses tells you whether or not you have the full result set and has a link to the next page if you do not.
## Capturing v3 API Calls
You can use browser developer tools to capture how the v3 API is called. For example, you could follow these steps to use the Chrome developer tools to get the API call for provisioning a Rancher Kubernetes distribution cluster:
1. In the Rancher UI, go to **Cluster Management** and click **Create.**
1. Click one of the cluster types. This example uses Digital Ocean.
1. Fill out the form with a cluster name and node template, but don't click **Create**.
1. You need to open the developer tools before the cluster creation to see the API call being recorded. To open the tools, right-click the Rancher UI and click **Inspect.**
1. In the developer tools, click the **Network** tab.
1. On the **Network** tab, make sure **Fetch/XHR** is selected.
1. In the Rancher UI, click **Create**. In the developer tools, you should see a new network request with the name `cluster?_replace=true`.
1. Right-click `cluster?_replace=true` and click **Copy > Copy as cURL.**
1. Paste the result into any text editor. You can see the POST request, including the URL it was sent to, all headers, and the full body of the request. This command can be used to create a cluster from the command line. Note: the request should be stored in a safe place because it contains credentials.
### Enable View in API
You can also view captured v3 API calls for your respective clusters and resources. This feature is not enabled by default. To enable it:
1. Click your **User Tile** in the top right corner of the UI and select **Preferences** from the drop-down menu.
2. Under the **Advanced Features** section, click **Enable "View in API"**
Once checked, the **View in API** link is displayed under the **⋮** sub-menu on resource pages in the UI.

197
versioned_docs/version-2.14/api/workflows/kubeconfigs.md Normal file
View File

@@ -0,0 +1,197 @@
---
title: Kubeconfigs
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/workflows/kubeconfigs"/>
</head>
## Kubeconfig Resource
Kubeconfig is a Rancher resource `kubeconfigs.ext.cattle.io` that allows generating `v1.Config` kubeconfig files for interacting with Rancher and clusters managed by Rancher.
```sh
kubectl api-resources --api-group=ext.cattle.io
```
To get a description of the fields and structure of the Kubeconfig resource, run:
```sh
kubectl explain kubeconfigs.ext.cattle.io
```
## Creating a Kubeconfig
Only a **valid and active** Rancher user can create a Kubeconfig. For example, trying to create a Kubeconfig using a `system:admin` service account will lead to an error:
```bash
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Kubeconfig
EOF
Error from server (Forbidden): error when creating "STDIN": kubeconfigs.ext.cattle.io is forbidden: user system:admin is not a Rancher user
```
:::warning Important
The kubeconfig content is generated and returned in the `.status.value` field **only once** when the Kubeconfig is successfully created because it contains secret values for created tokens. Therefore it has to be captured by using an appropriate output option, such as `-o jsonpath='{.status.value}'`, or `-o yaml`.
:::
A kubeconfig can be created for more than one cluster at a time by specifying a list of cluster names in the `spec.clusters` field. You can look up cluster names by listing `clusters.management.cattle.io` resources.
```sh
kubectl get clusters.management.cattle.io -o=jsonpath="{.items[*]['metadata.name', 'spec.displayName']}{'\n'}"
local local
c-m-p66cdvlj downstream1
```
The `metadata.name` and `metadata.generateName` fields are ignored, and the name of the new Kubeconfig is automatically generated using the prefix `kubeconfig-`.
You can use the `spec.currentContext` field to set the cluster name, and it is used to set the current context in the kubeconfig. If you do not set the `spec.currentContext` field, then the first cluster in the `spec.clusters` list will be used as the current context. For ACE-enabled clusters that don't have an FQDN set, the first control plane node will be used as the current context.
For ACE-enabled clusters, if the FQDN is set, then that will be used as a cluster entry in the kubeconfig; otherwise, entries for all control plane nodes will be created.
```bash
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Kubeconfig
spec:
clusters: [c-m-p66cdvlj, c-m-fcd3g5h]
description: My Kubeconfig
currentContext: c-m-p66cdvlj
EOF
```
If `"*"` is specified as the first item in the `spec.clusters` field, the kubeconfig will be created for all clusters that the user has access to, if any.
```bash
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Kubeconfig
spec:
clusters: ["*"]
description: My Kubeconfig
EOF
```
If `spec.ttl` is not specified, the Kubeconfig's tokens will be created with the expiration time defined in the `kubeconfig-default-token-ttl-minutes` setting, which is 30 days by default. If `spec.ttl` is specified, it should be greater than 0 and less than or equal to the value of the `kubeconfig-default-token-ttl-minutes` setting expressed in seconds.
```bash
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Kubeconfig
spec:
clusters: [c-m-p66cdvlj] # Downstream cluster
ttl: 7200 # 2 hours
EOF
```
## Listing Kubeconfigs
Listing previously generated Kubeconfigs can be useful for cleaning up backing tokens if the Kubeconfig is no longer needed (e.g., it was issued temporarily). Admins can list all Kubeconfigs, while regular users can only view their own.
```sh
kubectl get kubeconfig
NAME TTL TOKENS STATUS AGE
kubeconfig-zp786 30d 2/2 Complete 18d
kubeconfig-7zvzp 30d 1/1 Complete 12d
kubeconfig-jznml 30d 1/1 Complete 12d
```
Use `-o wide` to get more details:
```sh
kubectl get kubeconfig -o wide
NAME TTL TOKENS STATUS AGE USER CLUSTERS DESCRIPTION
kubeconfig-zp786 30d 2/2 Complete 18d user-w5gcf * all clusters
kubeconfig-7zvzp 30d 1/1 Complete 12d u-w7drc *
kubeconfig-jznml 30d 1/1 Complete 12d u-w7drc *
```
## Viewing a Kubeconfig
Admins can get any Kubeconfig, while regular users can only get their own.
```sh
kubectl get kubeconfig kubeconfig-zp786
NAME TTL TOKENS STATUS AGE
kubeconfig-zp786 30d 2/2 Complete 18d
```
Use `-o wide` to get more details:
```sh
kubectl get kubeconfig kubeconfig-zp786 -o wide
NAME TTL TOKENS STATUS AGE USER CLUSTERS DESCRIPTION
kubeconfig-zp786 30d 2/2 Complete 18d user-w5gcf * all clusters
```
## Deleting a Kubeconfig
Admins can delete any Kubeconfig, while regular users can only delete their own. When a Kubeconfig is deleted, the kubeconfig tokens are also deleted.
```sh
kubectl delete kubeconfig kubeconfig-zp786
kubeconfig.ext.cattle.io "kubeconfig-zp786" deleted
```
To delete a Kubeconfig using preconditions:
```sh
cat <<EOF | k delete --raw /apis/ext.cattle.io/v1/kubeconfigs/kubeconfig-zp786 -f -
{
"apiVersion": "v1",
"kind": "DeleteOptions",
"preconditions": {
"uid": "52183e05-d382-47d2-b4b9-d0735823ce90",
"resourceVersion": "31331505"
}
}
EOF
```
## Deleting a Collection of Kubeconfigs
Admins can delete any Kubeconfig, while regular users can only delete their own.
To delete all Kubeconfigs:
```sh
kubectl delete --raw /apis/ext.cattle.io/v1/kubeconfigs
```
To delete a collection of Kubeconfigs by label:
```sh
kubectl delete --raw /apis/ext.cattle.io/v1/kubeconfigs?labelSelector=foo%3Dbar
```
## Updating a Kubeconfig
Only the `metadata`, e.g. adding a label or an annotation, and the `spec.description` field can be updated. All other `spec` fields are immutable.
To edit a Kubeconfig:
```sh
kubectl edit kubeconfig kubeconfig-zp786
```
To patch a Kubeconfig and update its description:
```sh
kubectl patch kubeconfig kubeconfig-zp786 -type merge -p '{"spec":{"description":"Updated description"}}'
kubeconfig.ext.cattle.io/kubeconfig-zp786 patched
kubectl get kubeconfig kubeconfig-fdcpl -o jsonpath='{.spec.description}'
Updated description
```
To patch a Kubeconfig and add a label:
```sh
kubectl patch kubeconfig kubeconfig-zp786 -type merge -p '{"metadata":{"labels":{"foo":"bar"}}}'
kubeconfig.ext.cattle.io/kubeconfig-zp786 patched
kubectl get kubeconfig kubeconfig-zp786 -o jsonpath='{.metadata.labels.foo}'
bar
```

219
versioned_docs/version-2.14/api/workflows/projects.md Normal file
View File

@@ -0,0 +1,219 @@
---
title: Projects
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/workflows/projects"/>
</head>
## Creating a Project
Project resources may only be created on the management cluster. See below for [creating namespaces under projects in a managed cluster](#creating-a-namespace-in-a-project).
### Creating a Basic Project
```bash
kubectl create -f - <<EOF
apiVersion: management.cattle.io/v3
kind: Project
metadata:
generateName: p-
namespace: c-m-abcde
spec:
clusterName: c-m-abcde
displayName: myproject
EOF
```
When creating a new project, you have two primary options for setting the name:
- **Automatic Generation:** Use `metadata.generateName` to ensure a unique project ID. However, note that you must use `kubectl create` (instead of `kubectl apply`) with this option, as `kubectl apply` does not support it.
- **Manual Naming:** You can explicitly set the project ID using `metadata.name`. If a project with that exact name already exists, the name request is denied.
The display name seen in the UI is set by `spec.displayName`. If `spec.displayName` is not provided, the field `metadata.name` is used instead.
Set `metadata.namespace` and `spec.clusterName` to the ID for the cluster the project belongs to.
If you create a project through a cluster member account and want that account to be able to access the project, you must include the annotation `field.cattle.io/creatorId`, and set it to the cluster member account's user ID.
```bash
kubectl create -f - <<EOF
apiVersion: management.cattle.io/v3
kind: Project
metadata:
annotations:
field.cattle.io/creatorId: user-id
generateName: p-
namespace: c-m-abcde
spec:
clusterName: c-m-abcde
displayName: myproject
EOF
```
Setting the `field.cattle.io/creatorId` field creates a `ProjectRoleTemplateBinding` that grants the specified user the ability to see project resources with the `get` command and view the project in the Rancher UI. Cluster owner and admin accounts don't need to set this annotation to perform these tasks.
Setting the `field.cattle.io/creator-principal-name` annotation to the user's principal preserves it in a projectroletemplatebinding automatically created for the project owner.
If you don't want the creator to be added as the owner member (e.g. if the creator is a cluster administrator) to the project you may set the `field.cattle.io/no-creator-rbac` annotation to `true`, which will prevent the corresponding projectroletemplatebinding from being created.
### Creating a Project With a Resource Quota
Refer to [Kubernetes Resource Quota](https://kubernetes.io/docs/concepts/policy/resource-quotas/).
```bash
kubectl create -f - <<EOF
apiVersion: management.cattle.io/v3
kind: Project
metadata:
generateName: p-
namespace: c-m-abcde
spec:
clusterName: c-m-abcde
displayName: myproject
resourceQuota:
limit:
limitsCpu: 1000m
namespaceDefaultResourceQuota:
limit:
limitsCpu: 50m
EOF
```
### Creating a Project With Container Limit Ranges
Refer to [Kubernetes Limit Ranges](https://kubernetes.io/docs/concepts/policy/limit-range/).
```bash
kubectl create -f - <<EOF
apiVersion: management.cattle.io/v3
kind: Project
metadata:
generateName: p-
namespace: c-m-abcde
spec:
clusterName: c-m-abcde
displayName: myproject
containerDefaultResourceLimit:
limitsCpu: 100m
limitsMemory: 100Mi
requestsCpu: 50m
requestsMemory: 50Mi
EOF
```
### Backing Namespace
After creating the project, the field `status.backingNamespace` gets populated. This represents the namespace in the management cluster that is created to manage project related resources. Examples of resources stored in the backing namespace are [project scoped secrets](../../how-to-guides/new-user-guides/kubernetes-resources-setup/secrets.md#creating-secrets-in-projects) and [project role template bindings](../../how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/manage-role-based-access-control-rbac/cluster-and-project-roles.md#project-roles).
## Adding a Member to a Project
Look up the project's [backing namespace](#backing-namespace) to specify the `metadata.namespace` field value and look up the project's ID to specify the `projectName` field value.
```bash
kubectl --namespace c-m-abcde get projects
```
Look up the role template ID to specify the `roleTemplateName` field value (e.g. `project-member` or `project-owner`).
```bash
kubectl get roletemplates
```
When adding a user member specify the `userPrincipalName` field:
```bash
kubectl create -f - <<EOF
apiVersion: management.cattle.io/v3
kind: ProjectRoleTemplateBinding
metadata:
generateName: prtb-
namespace: c-m-abcde-p-vwxyz
projectName: c-m-abcde:p-vwxyz
roleTemplateName: project-member
userPrincipalName: keycloak_user://user
EOF
```
When adding a group member specify the `groupPrincipalName` field instead:
```bash
kubectl create -f - <<EOF
apiVersion: management.cattle.io/v3
kind: ProjectRoleTemplateBinding
metadata:
generateName: prtb-
namespace: p-vwxyz
projectName: c-m-abcde:p-vwxyz
roleTemplateName: project-member
groupPrincipalName: keycloak_group://group
EOF
```
Create a projectroletemplatebinding for each role you want to assign to the project member.
## Listing Project Members
Look up the project backing namespace:
```bash
kubectl --namespace c-m-abcde get projects
```
To list projectroletemplatebindings in the project's backing namespace:
```bash
kubectl --namespace c-m-abcde-p-vwxyz get projectroletemplatebindings
```
## Deleting a Member From a Project
Lookup the projectroletemplatebinding IDs containing the member in the project's namespace as decribed in the [Listing Project Members](#listing-project-members) section.
Delete the projectroletemplatebinding from the project's namespace:
```bash
kubectl --namespace c-m-abcde-p-vwxyz delete projectroletemplatebindings prtb-qx874 prtb-7zw7s
```
## Creating a Namespace in a Project
The Project resource resides in the management cluster, even if the Project is for a managed cluster. The namespaces under the project reside in the managed cluster.
On the management cluster, look up the project ID for the cluster you are administrating if generated using `metadata.generateName`:
```bash
kubectl --namespace c-m-abcde get projects
```
On the managed cluster, create a namespace with a project annotation:
```bash
kubectl apply -f - <<EOF
apiVersion: v1
kind: Namespace
metadata:
name: mynamespace
annotations:
field.cattle.io/projectId: c-m-abcde:p-vwxyz
EOF
```
Note the format, `<cluster ID>:<project ID>`.
## Deleting a Project
Look up the project to delete in the cluster namespace:
```bash
kubectl --namespace c-m-abcde get projects
```
Delete the project under the cluster namespace:
```bash
kubectl --namespace c-m-abcde delete project p-vwxyz
```
Note that this command doesn't delete the namespaces and resources that formerly belonged to the project.
It does delete all project role template bindings for the projects, so recreating the project will not restore members added to the project, and you have to add users as members again.

126
versioned_docs/version-2.14/api/workflows/tokens.md Normal file
View File

@@ -0,0 +1,126 @@
---
title: Tokens
---
<head>
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/workflows/tokens"/>
</head>
## Token Resource
Rancher has an imperative API resource `tokens.ext.cattle.io` that allows you to generate tokens for authenticating with Rancher.
```sh
kubectl api-resources --api-group=ext.cattle.io
```
To get a description of the fields and structure of the Token resource, run:
```sh
kubectl explain tokens.ext.cattle.io
```
## Creating a Token
:::caution
The Token value is only returned once in the `status.value` field.
:::
Since Rancher v2.13.0 the `status.bearerToken` now contains a fully formed and ready-to-use Bearer token that can be used to authenticate to [Rancher API](../v3-rancher-api-guide.md).
Only a **valid and active** Rancher user can create a Token. Otherwise, you will get an error displayed (`Error from server (Forbidden)...`) when attempting to create a Token.
```bash
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Token
EOF
Error from server (Forbidden): error when creating "STDIN": tokens.ext.cattle.io is forbidden: user system:admin is not a Rancher user
```
A Token is always created for the user making the request. Attempting to create a Token for a different user, by specifying a different `spec.userID`, is forbidden and will fail.
- The `spec.description` field can be set to an arbitrary human-readable description of the Token's purpose. The default value is empty.
- The `spec.kind` field can be set to the kind of Token. The value `session` indicates a login Token. All other values, including the default empty string, indicate a kind of derived Token.
- The `metadata.name` and `metadata.generateName` fields are ignored, and the name of the new Token is automatically generated using the prefix `token-`.
```bash
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Token
spec:
description: My Token
EOF
```
- If the `spec.ttl` is not specified, the Token is created with the expiration time defined in the `auth-token-max-ttl-minutes` setting. The default expiration time is 90 days. If `spec.ttl` is specified, it should be greater than 0 and less than or equal to the value of the `auth-token-max-ttl-minutes` setting expressed in milliseconds.
```bash
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: Token
spec:
ttl: 7200000 # 2 hours
EOF
```
## Listing Tokens
Listing previously generated Tokens can help clean up tokens that are no longer needed (e.g., they were issued temporarily). Admins can list all Tokens, while regular users can only see their own.
```sh
kubectl get tokens.ext.cattle.io
NAME KIND TTL AGE
token-chjc9 90d 18s
token-6fzgj 90d 16s
token-8nbrm 90d 14s
```
Use `-o wide` to get more details:
```sh
kubectl get tokens.ext.cattle.io -o wide
NAME USER KIND TTL AGE DESCRIPTION
token-chjc9 user-jtghh 90d 24s example
token-6fzgj user-jtghh 90d 22s box
token-8nbrm user-jtghh 90d 20s jinx
```
## Viewing a Token
Admins can get any Token, while regular users can only get their own.
```sh
kubectl get tokens.ext.cattle.io token-chjc9
NAME KIND TTL AGE
token-chjc9 90d 18s
```
Use `-o wide` to get more details:
```sh
kubectl get tokens.ext.cattle.io token-chjc9 -o wide
NAME USER KIND TTL AGE DESCRIPTION
token-chjc9 user-jtghh 90d 24s example
```
## Deleting a Token
Admins can delete any Token, while regular users can only delete their own.
```sh
kubectl delete tokens.ext.cattle.io token-chjc9
token.ext.cattle.io "token-chjc9" deleted
```
## Updating a Token
Only the metadata fields `spec.description`, `spec.ttl`, and `spec.enabled` can be updated. All other `spec` fields are immutable. Admins can extend the `spec.ttl` field, while regular users can only reduce the value.
An example `kubectl` command to edit a Token:
```sh
kubectl edit tokens.ext.cattle.io token-zp786
```

187
versioned_docs/version-2.14/api/workflows/users.md Normal file
View File

@@ -0,0 +1,187 @@
---
title: Users
---
## User Resource
The `User` resource (users.management.cattle.io) represents a user account in Rancher.
To get a description of the fields and structure of the `User` resource, run:
```sh
kubectl explain users.management.cattle.io
```
## Creating a User
Creating a local user is a two-step process: you must create the `User` resource, then provide a password via a Kubernetes `Secret`.
Only a user with sufficient permissions can create a `User` resource.
```bash
kubectl create -f -<<EOF
apiVersion: management.cattle.io/v3
kind: User
metadata:
name: testuser
displayName: "Test User"
username: "testuser"
EOF
```
The user's password must be provided in a `Secret` object within the `cattle-local-user-passwords` namespace. The Rancher webhook will automatically hash the password and update the `Secret`.
:::important
Important: The `Secret` must have the same name as the metadata.name (and username) of the `User` resource.
:::
```bash
kubectl create -f -<<EOF
apiVersion: v1
kind: Secret
metadata:
name: testuser
namespace: cattle-local-user-passwords
type: Opaque
stringData:
password: Pass1234567!
EOF
```
After the plaintext password is submitted, the Rancher-Webhook automatically hashes it, replacing the content of the `Secret`, ensuring that the plaintext password is never stored:
```yaml
apiVersion: v1
data:
password: 1c1Y4CdjlehGWFz26F414x2qoj4gch5L5OXsx35MAa8=
salt: m8Co+CfMDo5XwVl0FqYzGcRIOTgRrwFSqW8yurh5DcE=
kind: Secret
metadata:
annotations:
cattle.io/password-hash: pbkdf2sha3512
name: testuser
namespace: cattle-local-user-passwords
ownerReferences:
- apiVersion: management.cattle.io/v3
kind: User
name: testuser
uid: 663ffb4f-8178-46c8-85a3-337f4d5cbc2e
uid: bade9f0a-b06f-4a77-9a39-4284dc2349c5
type: Opaque
```
## Updating User's Password
To change a user's password, use the `PasswordChangeRequest` resource, which handles secure password updates.
```yaml
kubectl create -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: PasswordChangeRequest
spec:
userID: "testuser"
currentPassword: "Pass1234567!"
newPassword: "NewPass1234567!"
EOF
```
## Listing Users
List all `User` resources in the cluster:
```sh
kubectl get users
NAME AGE
testuser 3m54s
user-4n5ws 12m
```
## Viewing a User
View a specific `User` resource by name:
```sh
kubectl get user testuser
NAME AGE
testuser 3m54s
```
## Deleting a User
Deleting a user will automatically delete the corresponding password `Secret`.
```sh
kubectl delete user testuser
user.management.cattle.io "testuser" deleted
```
## Get a Current User's Information
A client uses the `SelfUser` resource to retrieve information about the currently authenticated user without knowing their ID. The user ID is returned in the `.status.userID` field.
```bash
kubectl create -o jsonpath='{.status.userID}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: SelfUser
EOF
testuser
```
## Refreshing a User's Group Membership
Updates to user group memberships are triggered by the `GroupMembershipRefreshRequest` resource.
:::note
Group membership is only supported for external authentication providers.
:::
### For a Single User
```bash
kubectl create -o jsonpath='{.status}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: GroupMembershipRefreshRequest
spec:
userId: testuser
EOF
{
"conditions": [
{
"lastTransitionTime": "2025-11-10T12:01:03Z",
"message": "",
"reason": "",
"status": "True",
"type": "UserRefreshInitiated"
}
],
"summary": "Completed"
}
```
### For All Users
```bash
kubectl create -o jsonpath='{.status}' -f -<<EOF
apiVersion: ext.cattle.io/v1
kind: GroupMembershipRefreshRequest
spec:
userId: "*"
EOF
{
"conditions": [
{
"lastTransitionTime": "2025-11-10T12:01:59Z",
"message": "",
"reason": "",
"status": "True",
"type": "UserRefreshInitiated"
}
],
"summary": "Completed"
}
```