mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-25 04:28:15 +00:00
Add v2.13 preview docs
This commit is contained in:
Billy Tat
@@ -0,0 +1,205 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
|
||||
## Feature Flag
|
||||
|
||||
The Kubeconfigs Public API is available since Rancher v2.12.0 and is enabled by default. It can be disabled by setting the `ext-kubeconfigs` feature flag to `false`.
|
||||
|
||||
```sh
|
||||
kubectl patch feature ext-kubeconfigs -p '{"spec":{"value":false}}'
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
@@ -0,0 +1,210 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
|
||||
Use `metadata.generateName` to ensure a unique project ID, but note that `kubectl apply` does not work with `metadata.generateName`, so `kubectl create` must be 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, 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 allows the cluster member account 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
|
||||
```
|
||||
|
||||
## Adding a Member to a Project
|
||||
|
||||
Look up the project ID to specify the `metadata.namespace` field and `projectName` field values.
|
||||
|
||||
```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: 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 ID:
|
||||
|
||||
```bash
|
||||
kubectl --namespace c-m-abcde get projects
|
||||
```
|
||||
|
||||
to list projectroletemplatebindings in the project's namespace:
|
||||
|
||||
```bash
|
||||
kubectl --namespace 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 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 since it 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.
|
||||
@@ -0,0 +1,132 @@
|
||||
---
|
||||
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
|
||||
```
|
||||
|
||||
## Feature Flag
|
||||
|
||||
The Tokens Public API is available for Rancher v2.12.0 and later, and is enabled by default. You can disable the Tokens Public API by setting the `ext-tokens` feature flag to `false` as shown in the example `kubectl` command below:
|
||||
|
||||
```sh
|
||||
kubectl patch feature ext-tokens -p '{"spec":{"value":false}}'
|
||||
```
|
||||
|
||||
## Creating a Token
|
||||
|
||||
:::caution
|
||||
The Token value is only returned once in the `status.value` field.
|
||||
:::
|
||||
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user