Skip to content

Commit 72b28fd

Browse files
pmatseykanetspmatseykanets
committed
Add Kubeconfigs example workflows page
1 parent 4def8a4 commit 72b28fd

File tree

1 file changed

+160
-0
lines changed

1 file changed

+160
-0
lines changed

‎docs/api/workflows/kubeconfigs.md

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: Kubeconfigs
3+
---
4+
5+
<head>
6+
<link rel="canonical" href="https://ranchermanager.docs.rancher.com/api/workflows/kubeconfigs"/>
7+
</head>
8+
9+
## Feature Flag
10+
11+
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`.
12+
13+
```sh
14+
kubectl patch feature ext-kubeconfigs -p '{"spec":{"value":false}}'
15+
```
16+
17+
## Creating a Kubeconfig
18+
19+
Only a **valid and active** Rancher user can create a Kubeconfig.
20+
21+
```bash
22+
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
23+
apiVersion: ext.cattle.io/v1
24+
kind: Kubeconfig
25+
EOF
26+
Error from server (Forbidden): error when creating "STDIN": kubeconfigs.ext.cattle.io is forbidden: user system:admin is not a Rancher user
27+
```
28+
29+
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.
30+
Note: Cluster names can be retrieved by listing `clusters.management.cattle.io` resources.
31+
32+
The `spec.currentContext` field can be used to set the cluster name that will be set as the current context in the kubeconfig.
33+
If the `spec.currentContext` field is not set, 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.
34+
35+
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.
36+
37+
```bash
38+
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
39+
apiVersion: ext.cattle.io/v1
40+
kind: Kubeconfig
41+
spec:
42+
clusters: [c-m-p66cdvlj, c-m-fcd3g5h]
43+
description: My Kubeconfig
44+
currentContext: c-m-p66cdvlj
45+
EOF
46+
```
47+
48+
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.
49+
50+
```bash
51+
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
52+
apiVersion: ext.cattle.io/v1
53+
kind: Kubeconfig
54+
spec:
55+
clusters: ["*"]
56+
description: My Kubeconfig
57+
EOF
58+
```
59+
60+
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.
61+
62+
```bash
63+
kubectl create -o jsonpath='{.status.value}' -f -<<EOF
64+
apiVersion: ext.cattle.io/v1
65+
kind: Kubeconfig
66+
spec:
67+
clusters: [c-m-p66cdvlj] # Downstream cluster
68+
ttl: 7200 # 2 hours
69+
EOF
70+
```
71+
72+
## Listing Kubeconfigs
73+
74+
Listing previously generated Kubeconfigs can be useful in order to clean up backing tokens if the Kubeconfig is no longer needed (e.g., it was issued temporarily).
75+
Admins can list all Kubeconfigs, while regular users can only see theirs.
76+
77+
```sh
78+
kubectl get kubeconfig
79+
NAME TTL TOKENS STATUS AGE
80+
kubeconfig-zp786 30d 2/2 Complete 18d
81+
kubeconfig-7zvzp 30d 1/1 Complete 12d
82+
kubeconfig-jznml 30d 1/1 Complete 12d
83+
```
84+
Use `-o wide` to get more details:
85+
86+
```sh
87+
NAME TTL TOKENS STATUS AGE USER CLUSTERS DESCRIPTION
88+
kubeconfig-zp786 30d 2/2 Complete 18d user-w5gcf * all clusters
89+
kubeconfig-7zvzp 30d 1/1 Complete 12d u-w7drc *
90+
kubeconfig-jznml 30d 1/1 Complete 12d u-w7drc *
91+
```
92+
93+
#### Viewing a Kubeconfig
94+
95+
Admins can get any Kubeconfig, while regular users can only get theirs.
96+
97+
```sh
98+
kubectl get kubeconfig kubeconfig-zp786
99+
NAME TTL TOKENS STATUS AGE
100+
kubeconfig-zp786 30d 2/2 Complete 18d
101+
```
102+
103+
Use `-o wide` to get more details:
104+
105+
```sh
106+
kubectl get kubeconfig kubeconfig-zp786 -o wide
107+
NAME TTL TOKENS STATUS AGE USER CLUSTERS DESCRIPTION
108+
kubeconfig-zp786 30d 2/2 Complete 18d user-w5gcf * all clusters
109+
```
110+
111+
#### Deleting a Kubeconfig
112+
113+
Admins can delete any Kubeconfig, while regular users can only delete theirs.
114+
When a Kubeconfig is deleted, the kubeconfig tokens are also deleted.
115+
116+
```sh
117+
kubectl delete kubeconfig kubeconfig-zp786
118+
kubeconfig.ext.cattle.io "kubeconfig-zp786" deleted
119+
```
120+
121+
To delete a Kubeconfig using a precondition:
122+
```sh
123+
kubectl delete --raw /apis/ext.cattle.io/v1/kubeconfigs -f -<<EOF
124+
apiVersion: v1
125+
kind: DeleteOptions
126+
preconditions:
127+
uid: 52183e05-d382-47d2-b4b9-d0735823ce90
128+
EOF
129+
```
130+
131+
#### Deleting a Collection of Kubeconfigs
132+
133+
Admins can delete any Kubeconfig, while regular users can only delete theirs.
134+
135+
To delete all Kubeconfigs:
136+
```sh
137+
kubectl delete --raw /apis/ext.cattle.io/v1/kubeconfigs
138+
```
139+
140+
To delete a collection of Kubeconfigs by label:
141+
142+
```sh
143+
kubectl delete --raw /apis/ext.cattle.io/v1/kubeconfigs?labelSelector=foo%3Dbar
144+
```
145+
146+
#### Updating a Kubeconfig
147+
148+
Only the metadata and the `spec.description` field can be updated. All other `spec` fields are immutable.
149+
150+
To add a label to a Kubeconfig:
151+
152+
```sh
153+
kubectl patch kubeconfig kubeconfig-zp786 -p '{"metadata":{"labels":{"foo":"bar"}}}'
154+
```
155+
156+
To change the description of a Kubeconfig:
157+
158+
```sh
159+
kubectl patch kubeconfig kubeconfig-zp786 -p '{"spec":{"description":"Updated description"}}'
160+
```

0 commit comments

Comments
 (0)