Skip to content

Commit a9478b4

Browse files
neolit123neolit123
committed
kubeadm: introduce documentation changes for super-admin.conf
- Update most pages where the kubeadm generated admin.conf is discussed. Include information about the new file "super-admin.conf".
1 parent 1d1366e commit a9478b4

File tree

9 files changed

+318
-33
lines changed

9 files changed

+318
-33
lines changed

‎content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_certs_renew_super-admin.conf.md

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
11+
12+
13+
Renew the certificate embedded in the kubeconfig file for the super-admin
14+
15+
### Synopsis
16+
17+
18+
Renew the certificate embedded in the kubeconfig file for the super-admin.
19+
20+
Renewals run unconditionally, regardless of certificate expiration date; extra attributes such as SANs will be based on the existing file/certificates, there is no need to resupply them.
21+
22+
Renewal by default tries to use the certificate authority in the local PKI managed by kubeadm; as alternative it is possible to use K8s certificate API for certificate renewal, or as a last option, to generate a CSR request.
23+
24+
After renewal, in order to make changes effective, is required to restart control-plane components and eventually re-distribute the renewed certificate in case the file is used elsewhere.
25+
26+
```
27+
kubeadm certs renew super-admin.conf [flags]
28+
```
29+
30+
### Options
31+
32+
<table style="width: 100%; table-layout: fixed;">
33+
<colgroup>
34+
<col span="1" style="width: 10px;" />
35+
<col span="1" />
36+
colgroup>
37+
<tbody>
38+
39+
<tr>
40+
<td colspan="2">--cert-dir string&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Default: "/etc/kubernetes/pki"td>
41+
tr>
42+
<tr>
43+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>The path where to save the certificatesp>td>
44+
tr>
45+
46+
<tr>
47+
<td colspan="2">--config stringtd>
48+
tr>
49+
<tr>
50+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>Path to a kubeadm configuration file.p>td>
51+
tr>
52+
53+
<tr>
54+
<td colspan="2">-h, --helptd>
55+
tr>
56+
<tr>
57+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>help for admin.confp>td>
58+
tr>
59+
60+
<tr>
61+
<td colspan="2">--kubeconfig string&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Default: "/etc/kubernetes/admin.conf"td>
62+
tr>
63+
<tr>
64+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>The kubeconfig file to use when talking to the cluster. If the flag is not set, a set of standard locations can be searched for an existing kubeconfig file.p>td>
65+
tr>
66+
67+
tbody>
68+
table>
69+
70+
71+
72+
### Options inherited from parent commands
73+
74+
<table style="width: 100%; table-layout: fixed;">
75+
<colgroup>
76+
<col span="1" style="width: 10px;" />
77+
<col span="1" />
78+
colgroup>
79+
<tbody>
80+
81+
<tr>
82+
<td colspan="2">--rootfs stringtd>
83+
tr>
84+
<tr>
85+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>[EXPERIMENTAL] The path to the 'real' host root filesystem.p>td>
86+
tr>
87+
88+
tbody>
89+
table>
90+
91+
92+

‎content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm_init_phase_kubeconfig_super-admin.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
11+
12+
13+
Generate a kubeconfig file for the super-admin
14+
15+
### Synopsis
16+
17+
18+
Generate a kubeconfig file for the super-admin.
19+
20+
```
21+
kubeadm init phase kubeconfig super-admin [flags]
22+
```
23+
24+
### Options
25+
26+
<table style="width: 100%; table-layout: fixed;">
27+
<colgroup>
28+
<col span="1" style="width: 10px;" />
29+
<col span="1" />
30+
colgroup>
31+
<tbody>
32+
33+
<tr>
34+
<td colspan="2">--apiserver-advertise-address stringtd>
35+
tr>
36+
<tr>
37+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>The IP address the API Server will advertise it's listening on. If not set the default network interface will be used.p>td>
38+
tr>
39+
40+
<tr>
41+
<td colspan="2">--apiserver-bind-port int32&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Default: 6443td>
42+
tr>
43+
<tr>
44+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>Port for the API Server to bind to.p>td>
45+
tr>
46+
47+
<tr>
48+
<td colspan="2">--cert-dir string&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Default: "/etc/kubernetes/pki"td>
49+
tr>
50+
<tr>
51+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>The path where to save and store the certificates.p>td>
52+
tr>
53+
54+
<tr>
55+
<td colspan="2">--config stringtd>
56+
tr>
57+
<tr>
58+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>Path to a kubeadm configuration file.p>td>
59+
tr>
60+
61+
<tr>
62+
<td colspan="2">--control-plane-endpoint stringtd>
63+
tr>
64+
<tr>
65+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>Specify a stable IP address or DNS name for the control plane.p>td>
66+
tr>
67+
68+
<tr>
69+
<td colspan="2">--dry-runtd>
70+
tr>
71+
<tr>
72+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>Don't apply any changes; just output what would be done.p>td>
73+
tr>
74+
75+
<tr>
76+
<td colspan="2">-h, --helptd>
77+
tr>
78+
<tr>
79+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>help for adminp>td>
80+
tr>
81+
82+
<tr>
83+
<td colspan="2">--kubeconfig-dir string&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Default: "/etc/kubernetes"td>
84+
tr>
85+
<tr>
86+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>The path where to save the kubeconfig file.p>td>
87+
tr>
88+
89+
<tr>
90+
<td colspan="2">--kubernetes-version string&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Default: "stable-1"td>
91+
tr>
92+
<tr>
93+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>Choose a specific Kubernetes version for the control plane.p>td>
94+
tr>
95+
96+
tbody>
97+
table>
98+
99+
100+
101+
### Options inherited from parent commands
102+
103+
<table style="width: 100%; table-layout: fixed;">
104+
<colgroup>
105+
<col span="1" style="width: 10px;" />
106+
<col span="1" />
107+
colgroup>
108+
<tbody>
109+
110+
<tr>
111+
<td colspan="2">--rootfs stringtd>
112+
tr>
113+
<tr>
114+
<td>td><td style="line-height: 130%; word-wrap: break-word;"><p>[EXPERIMENTAL] The path to the 'real' host root filesystem.p>td>
115+
tr>
116+
117+
tbody>
118+
table>
119+
120+
121+

‎content/en/docs/reference/setup-tools/kubeadm/implementation-details.md

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ in a majority of cases, and the most intuitive location; other constants paths a
6464
- `controller-manager.conf`
6565
- `scheduler.conf`
6666
- `admin.conf` for the cluster admin and kubeadm itself
67+
- `super-admin.conf` for the cluster super-admin that can bypass RBAC
6768

6869
- Names of certificates and key files :
6970

@@ -209,12 +210,21 @@ Kubeadm generates kubeconfig files with identities for control plane components:
209210
This client cert should have the CN `system:kube-scheduler`, as defined by default
210211
[RBAC core components roles](/docs/reference/access-authn-authz/rbac/#core-component-roles)
211212

212-
Additionally, a kubeconfig file for kubeadm itself and the admin is generated and saved into the
213-
`/etc/kubernetes/admin.conf` file. The "admin" here is defined as the actual person(s) that is
214-
administering the cluster and wants to have full control (**root**) over the cluster. The
215-
embedded client certificate for admin should be in the `system:masters` organization, as defined
216-
by default [RBAC user facing role bindings](/docs/reference/access-authn-authz/rbac/#user-facing-roles).
217-
It should also include a CN. Kubeadm uses the `kubernetes-admin` CN.
213+
Additionally, a kubeconfig file for kubeadm as an administrative entity is generated and stored
214+
in `/etc/kubernetes/admin.conf`. This file includes a certificate with
215+
`Subject: O = kubeadm:cluster-admins, CN = kubernetes-admin`. `kubeadm:cluster-admins`
216+
is a group managed by kubeadm. It is bound to the `cluster-admin` ClusterRole during `kubeadm init`,
217+
by using the `super-admin.conf` file, which does not require RBAC.
218+
This `admin.conf` file must remain on control plane nodes and not be shared with additional users.
219+
220+
During `kubeadm init` another kubeconfig file is generated and stored in `/etc/kubernetes/super-admin.conf`.
221+
This file includes a certificate with `Subject: O = system:masters, CN = kubernetes-super-admin`.
222+
`system:masters` is a super user group that bypasses RBAC and makes `super-admin.conf` useful in case
223+
of an emergency where a cluster is locked due to RBAC misconfiguration.
224+
The `super-admin.conf` file can be stored in a safe location and not shared with additional users.
225+
226+
See [RBAC user facing role bindings](/docs/reference/access-authn-authz/rbac/#user-facing-roles)
227+
for additional information RBAC and built-in ClusterRoles and groups.
218228

219229
Please note that:
220230

‎content/en/docs/reference/setup-tools/kubeadm/kubeadm-certs.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ For more details see [Manual certificate renewal](/docs/tasks/administer-cluster
3434
{{< tab name="etcd-server" include="generated/kubeadm_certs_renew_etcd-server.md" />}}
3535
{{< tab name="front-proxy-client" include="generated/kubeadm_certs_renew_front-proxy-client.md" />}}
3636
{{< tab name="scheduler.conf" include="generated/kubeadm_certs_renew_scheduler.conf.md" />}}
37+
{{< tab name="super-admin.conf" include="generated/kubeadm_certs_renew_super-admin.conf.md" />}}
3738
{{< /tabs >}}
3839

3940
## kubeadm certs certificate-key {#cmd-certs-certificate-key}

‎content/en/docs/reference/setup-tools/kubeadm/kubeadm-init-phase.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ You can create all required kubeconfig files by calling the `all` subcommand or
5858
{{< tab name="kubelet" include="generated/kubeadm_init_phase_kubeconfig_kubelet.md" />}}
5959
{{< tab name="controller-manager" include="generated/kubeadm_init_phase_kubeconfig_controller-manager.md" />}}
6060
{{< tab name="scheduler" include="generated/kubeadm_init_phase_kubeconfig_scheduler.md" />}}
61+
{{< tab name="super-admin" include="generated/kubeadm_init_phase_kubeconfig_super-admin.md" />}}
6162
{{< /tabs >}}
6263

6364
## kubeadm init phase control-plane {#cmd-phase-control-plane}

‎content/en/docs/reference/setup-tools/kubeadm/kubeadm-init.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,9 @@ following steps:
3232
arguments, lowercased if necessary.
3333

3434
1. Writes kubeconfig files in `/etc/kubernetes/` for the kubelet, the controller-manager and the
35-
scheduler to use to connect to the API server, each with its own identity, as well as an
36-
additional kubeconfig file for administration named `admin.conf`.
35+
scheduler to use to connect to the API server, each with its own identity. Also
36+
additional kubeconfig files are written, for kubeadm as administrative entity (`admin.conf`)
37+
and for a super admin user that can bypass RBAC (`super-admin.conf`).
3738

3839
1. Generates static Pod manifests for the API server,
3940
controller-manager and scheduler. In case an external etcd is not provided,
@@ -186,7 +187,7 @@ as a learner and promoted to a voting member only after the etcd data are fully
186187
List of deprecated feature gates:
187188

188189
{{< table caption="kubeadm deprecated feature gates" >}}
189-
Feature | Default
190+
Feature | Default
190191
:-------|:--------
191192
`UpgradeAddonsBeforeControlPlane` | `false`
192193
{{< /table >}}
@@ -291,7 +292,7 @@ for etcd and CoreDNS.
291292

292293
#### Custom sandbox (pause) images {#custom-pause-image}
293294

294-
To set a custom image for these you need to configure this in your
295+
To set a custom image for these you need to configure this in your
295296
{{< glossary_tooltip text="container runtime" term_id="container-runtime" >}}
296297
to use the image.
297298
Consult the documentation for your container runtime to find out how to change this setting;
@@ -386,8 +387,9 @@ DNS name or an address of a load balancer.
386387
kubeadm certs certificate-key
387388
```
388389

389-
Once the cluster is up, you can grab the admin credentials from the control-plane node
390-
at `/etc/kubernetes/admin.conf` and use that to talk to the cluster.
390+
Once the cluster is up, you can use the `/etc/kubernetes/admin.conf` file from
391+
a control-plane node to talk to the cluster with administrator credentials or
392+
[Generating kubeconfig files for additional users](/docs/tasks/administer-cluster/kubeadm/kubeadm-certs#kubeconfig-additional-users).
391393

392394
Note that this style of bootstrap has some relaxed security guarantees because
393395
it does not allow the root CA hash to be validated with

‎content/en/docs/setup/best-practices/certificates.md

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -184,19 +184,36 @@ you need to provide if you are generating all of your own keys and certificates:
184184

185185
You must manually configure these administrator account and service accounts:
186186

187-
| filename | credential name | Default CN | O (in Subject) |
188-
|-------------------------|----------------------------|-------------------------------------|----------------|
189-
| admin.conf | default-admin | kubernetes-admin | system:masters |
190-
| kubelet.conf | default-auth | system:node:`` (see note) | system:nodes |
191-
| controller-manager.conf | default-controller-manager | system:kube-controller-manager | |
192-
| scheduler.conf | default-scheduler | system:kube-scheduler | |
187+
| filename | credential name | Default CN | O (in Subject) |
188+
|-------------------------|----------------------------|-------------------------------------|------------------------|
189+
| admin.conf | default-admin | kubernetes-admin | `` |
190+
| super-admin.conf | default-super-admin | kubernetes-super-admin | system:masters |
191+
| kubelet.conf | default-auth | system:node:`` (see note) | system:nodes |
192+
| controller-manager.conf | default-controller-manager | system:kube-controller-manager | |
193+
| scheduler.conf | default-scheduler | system:kube-scheduler | |
193194

194195
{{< note >}}
195196
The value of `` for `kubelet.conf` **must** match precisely the value of the node name
196197
provided by the kubelet as it registers with the apiserver. For further details, read the
197198
[Node Authorization](/docs/reference/access-authn-authz/node/).
198199
{{< /note >}}
199200

201+
{{< note >}}
202+
In the above example `` is implementation specific. Some tools sign the
203+
certificate in the default `admin.conf` to be part of the `system:masters` group.
204+
`system:masters` is a break-glass, super user group can bypass the authorization
205+
layer of Kubernetes, such as RBAC. Also some tools do not generate a separate
206+
`super-admin.conf` with a certificate bound to this super user group.
207+
208+
kubeadm generates two separate administrator certificates in kubeconfig files.
209+
One is in `admin.conf` and has `Subject: O = kubeadm:cluster-admins, CN = kubernetes-admin`.
210+
`kubeadm:cluster-admins` is a custom group bound to the `cluster-admin` ClusterRole.
211+
This file is generated on all kubeadm managed control plane machines.
212+
213+
Another is in `super-admin.conf` that has `Subject: O = system:masters, CN = kubernetes-super-admin`.
214+
This file is generated only on the node where `kubeadm init` was called.
215+
{{< /note >}}
216+
200217
1. For each config, generate an x509 cert/key pair with the given CN and O.
201218

202219
1. Run `kubectl` as follows for each config:
@@ -213,6 +230,7 @@ These files are used as follows:
213230
| filename | command | comment |
214231
|-------------------------|-------------------------|-----------------------------------------------------------------------|
215232
| admin.conf | kubectl | Configures administrator user for the cluster |
233+
| super-admin.conf | kubectl | Configures super administrator user for the cluster |
216234
| kubelet.conf | kubelet | One required for each node in the cluster. |
217235
| controller-manager.conf | kube-controller-manager | Must be added to manifest in `manifests/kube-controller-manager.yaml` |
218236
| scheduler.conf | kube-scheduler | Must be added to manifest in `manifests/kube-scheduler.yaml` |
@@ -221,6 +239,7 @@ The following files illustrate full paths to the files listed in the previous ta
221239

222240
```
223241
/etc/kubernetes/admin.conf
242+
/etc/kubernetes/super-admin.conf
224243
/etc/kubernetes/kubelet.conf
225244
/etc/kubernetes/controller-manager.conf
226245
/etc/kubernetes/scheduler.conf

‎content/en/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -211,11 +211,19 @@ export KUBECONFIG=/etc/kubernetes/admin.conf
211211
```
212212

213213
{{< warning >}}
214-
Kubeadm signs the certificate in the `admin.conf` to have `Subject: O = system:masters, CN = kubernetes-admin`.
215-
`system:masters` is a break-glass, super user group that bypasses the authorization layer (e.g. RBAC).
216-
Do not share the `admin.conf` file with anyone and instead grant users custom permissions by generating
217-
them a kubeconfig file using the `kubeadm kubeconfig user` command. For more details see
218-
[Generating kubeconfig files for additional users](/docs/tasks/administer-cluster/kubeadm/kubeadm-certs#kubeconfig-additional-users).
214+
The kubeconfig file `admin.conf` that `kubeadm init` generates contains a certificate with
215+
`Subject: O = kubeadm:cluster-admins, CN = kubernetes-admin`. The group `kubeadm:cluster-admins`
216+
is bound to the built-in `cluster-admin` ClusterRole.
217+
Do not share the `admin.conf` file with anyone.
218+
219+
`kubeadm init` generates another kubeconfig file `super-admin.conf` that contains a certificate with
220+
`Subject: O = system:masters, CN = kubernetes-super-admin`.
221+
`system:masters` is a break-glass, super user group that bypasses the authorization layer (for example RBAC).
222+
Do not share the `super-admin.conf` file with anyone. It is recommended to move the file to a safe location.
223+
224+
See
225+
[Generating kubeconfig files for additional users](/docs/tasks/administer-cluster/kubeadm/kubeadm-certs#kubeconfig-additional-users)
226+
on how to use `kubeadm kubeconfig user` to generate kubeconfig files for additional users.
219227
{{< /warning >}}
220228

221229
Make a record of the `kubeadm join` command that `kubeadm init` outputs. You

0 commit comments

Comments
 (0)