Skip to content

Commit b76e3ba

Browse files
skrthomasskrthomas
authored
Merge pull request #57834 from ShaunaDiaz/OSDOCS-5387
OSDOCS-5387: add kubeconfig management
2 parents 568f8d3 + d643b26 commit b76e3ba

9 files changed

+198
-42
lines changed

‎_topic_maps/_topic_map_ms.yml

Lines changed: 4 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,6 @@ Topics:
7474
- Name: Network APIs
7575
Dir: network_apis
7676
Topics:
77-
# FIXME: need to incorporate the supported k8s APIs
7877
- Name: Route [route.openshift.io/v1]
7978
File: route-route-openshift-io-v1
8079
- Name: Security APIs
@@ -106,14 +105,16 @@ Distros: microshift
106105
Topics:
107106
- Name: Using configuration tools
108107
File: microshift-using-config-tools
108+
- Name: Cluster access with kubeconfig
109+
File: microshift-cluster-access-kubeconfig
109110
---
110111
Name: Networking
111112
Dir: microshift_networking
112113
Distros: microshift
113114
Topics:
114-
- Name: Applying networking settings
115+
- Name: Networking settings
115116
File: microshift-networking
116-
- Name: Using a firewall
117+
- Name: Firewall configuration
117118
File: microshift-firewall
118119
---
119120
Name: Storage
@@ -132,14 +133,6 @@ Topics:
132133
File: expanding-persistent-volumes-microshift
133134
- Name: Dynamic storage using the LVMS plugin
134135
File: microshift-storage-plugin-overview
135-
#- Name: Using container storage interface (CSI) for MicroShift
136-
# Dir: container_storage_interface_microshift
137-
# Distros: microshift
138-
# Topics:
139-
# - Name: Configuring CSI volumes for MicroShift
140-
# File: microshift-persistent-storage-csi
141-
#- Name: Dynamic provisioning for MicroShift
142-
# File: dynamic-provisioning-microshift
143136
---
144137
Name: Running applications
145138
Dir: microshift_running_apps
@@ -151,37 +144,6 @@ Topics:
151144
File: microshift-operators
152145
- Name: Greenboot health check
153146
File: microshift-greenboot
154-
# ---
155-
# Name: Networking
156-
# Dir: networking
157-
# Distros: microshift
158-
# Topics:
159-
# - Name: Understanding the Ingress Operator
160-
# File: ingress-operator-microshift
161-
# - Name: Configuring a cluster-wide proxy during installation
162-
# File: configuring-cluster-wide-proxy
163-
# - Name: CIDR range definitions
164-
# File: cidr-range-definitions
165-
# - Name: Network policy
166-
# Dir: network_policy
167-
# Topics:
168-
# - Name: About network policy
169-
# File: about-network-policy
170-
# - Name: Creating a network policy
171-
# File: creating-network-policy
172-
# - Name: Viewing a network policy
173-
# File: viewing-network-policy
174-
# - Name: Deleting a network policy
175-
# File: deleting-network-policy
176-
# - Name: Configuring multitenant isolation with network policy
177-
# File: multitenant-network-policy
178-
# ---
179-
# Name: Updating clusters
180-
# Dir: updating
181-
# Distros: microshift
182-
# Topics:
183-
# - Name: Updating MicroShift Clusters
184-
# File: TBD
185147
---
186148
Name: Troubleshooting
187149
Dir: microshift_troubleshooting

‎microshift_configuring/microshift-cluster-access-kubeconfig.adoc

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
:_content-type: ASSEMBLY
2+
[id="microshift-kubeconfig"]
3+
= Cluster access with kubeconfig
4+
include::_attributes/attributes-microshift.adoc[]
5+
:context: microshift-kubeconfig
6+
7+
toc::[]
8+
9+
Learn about how `kubeconfig` files are used with {product-title} deployments. CLI tools use `kubeconfig` files to communicate with the API server of a cluster. These files provide cluster details, IP addresses, and other information needed for authentication.
10+
11+
include::modules/microshift-kubeconfig-overview.adoc[leveloffset=+1]
12+
13+
include::modules/microshift-kubeconfig-local-access.adoc[leveloffset=+1]
14+
15+
include::modules/microshift-accessing-cluster-locally.adoc[leveloffset=+2]
16+
17+
include::modules/microshift-kubeconfig-remote-con.adoc[leveloffset=+1]
18+
19+
include::modules/microshift-kubeconfig-generating-remote-kcfiles.adoc[leveloffset=+1]
20+
21+
include::modules/microshift-accessing-cluster-open-firewall.adoc[leveloffset=+2]
22+
23+
include::modules/microshift-accessing-cluster-remotely.adoc[leveloffset=+2]

‎modules/microshift-accessing-cluster-locally.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
//
33
// microshift/microshift_install/microshift-install-rpm.adoc
44
// microshift/microshift_install/microshift-embed-in-rpm-ostree.adoc
5+
// microshift/microshift_configuring/microshift-cluster-access-kubeconfig.adoc
56

67
:_content-type: PROCEDURE
78
[id="accessing-microshift-cluster-locally_{context}"]

‎modules/microshift-accessing-cluster-open-firewall.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
//
33
// microshift/microshift_install/microshift-install-rpm.adoc
44
// microshift/microshift_install/microshift-embed-in-rpm-ostree.adoc
5+
// microshift/microshift_configuring/microshift-cluster-access-kubeconfig.adoc
56

67
:_content-type: PROCEDURE
78
[id="microshift-accessing-cluster-open-firewall_{context}"]

‎modules/microshift-accessing-cluster-remotely.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
//
33
// microshift/microshift_install/microshift-install-rpm.adoc
44
// microshift/microshift_install/microshift-embed-in-rpm-ostree.adoc
5+
// microshift/microshift_configuring/microshift-cluster-access-kubeconfig.adoc
56

67
:_content-type: PROCEDURE
78
[id="accessing-microshift-cluster-remotely_{context}"]

‎modules/microshift-kubeconfig-generating-remote-kcfiles.adoc

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/microshift_configuring/microshift-cluster-access-kubeconfig.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="generating-additional-kubeconfig-files_{context}"]
7+
= Generating additional kubeconfig files for remote access
8+
9+
You can generate additional `kubeconfig` files to use if you need more host names or IP addresses than the default remote access file provides.
10+
11+
[IMPORTANT]
12+
====
13+
You must restart {product-title} for configuration changes to be implemented.
14+
====
15+
16+
.Prerequisites
17+
18+
* You have created a `config.yaml` for {product-title}.
19+
20+
.Procedure
21+
22+
. (Optional) You can show the contents of the `config.yaml` by running the following command:
23+
+
24+
[source,terminal]
25+
----
26+
$ cat /etc/microshift/config.yaml
27+
----
28+
29+
. (Optional) You can show the contents of the remote-access `kubeconfig` file, by running the following command:
30+
+
31+
[source,terminal]
32+
----
33+
$ cat /var/lib/microshift/resources/kubeadmin/<hostname>/kubeconfig
34+
----
35+
+
36+
[IMPORTANT]
37+
====
38+
Additional remote access `kubeconfig` files must include one of the server names listed in the {product-title} `config.yaml` file. Additional `kubeconfig` files must also use the same CA for validation.
39+
====
40+
41+
. To generate additional `kubeconfig` files for additional DNS names SANs or external IP addresses, add the entries you need to the `apiServer.subjectAltNames` field. In the following example, the DNS name used is `alt-name-1` and the IP address is `1.2.3.4`.
42+
+
43+
.Example `config.yaml` with additional authentication values
44+
[source,yaml]
45+
----
46+
dns:
47+
baseDomain: example.com
48+
node:
49+
hostnameOverride: "microshift-rhel9" <1>
50+
nodeIP: 10.0.0.1
51+
apiServer:
52+
subjectAltNames:
53+
- alt-name-1 <2>
54+
- 1.2.3.4 <3>
55+
----
56+
<1> Hostname
57+
<2> DNS name
58+
<3> IP address or range
59+
60+
. Restart {product-title} to apply configuration changes and auto-generate the `kubeconfig` files you need by running the following command:
61+
+
62+
[source,terminal]
63+
----
64+
$ sudo systemctl restart microshift
65+
----
66+
67+
. To check the contents of additional remote-access `kubeconfig` files, insert the name or IP address as listed in the `config.yaml` into the `cat` command. For example, `alt-name-1` is used in the following example command:
68+
+
69+
[source,terminal]
70+
----
71+
$ cat /var/lib/microshift/resources/kubeadmin/alt-name-1/kubeconfig
72+
----
73+
74+
. Choose the `kubeconfig` file to use that contains the SAN or IP address you want to use to connect your cluster. In this example, the `kubeconfig` containing`alt-name-1` in the `cluster.server` field is the correct file.
75+
+
76+
.Example contents of an additional `kubeconfig` file
77+
[source,yaml]
78+
----
79+
clusters:
80+
- cluster:
81+
certificate-authority-data: <base64 CA>
82+
server: https://alt-name-1:6443 <1>
83+
----
84+
<1> The `/var/lib/microshift/resources/kubeadmin/alt-name-1/kubeconfig` file values are from the `apiServer.subjectAltNames` configuration values.
85+
86+
[NOTE]
87+
====
88+
All of these parameters are included as common names (CN) and subject alternative names (SAN) in the external serving certificates for the API server.
89+
====

‎modules/microshift-kubeconfig-local-access.adoc

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/microshift_configuring/microshift-cluster-access-kubeconfig.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="microshift-kubeconfig-local-access_{context}"]
7+
= Local access kubeconfig file
8+
9+
The local access `kubeconfig` file is written to`/var/lib/microshift/resources/kubeadmin/kubeconfig`. This `kubeconfig` file provides access to the API server using `localhost`. Choose this file when you are connecting the cluster locally.
10+
11+
.Example contents of `kubeconfig` for local access
12+
[source,yaml]
13+
----
14+
clusters:
15+
- cluster:
16+
certificate-authority-data: <base64 CA>
17+
server: https://localhost:6443
18+
----
19+
20+
The `localhost` `kubeconfig` file can only be used from a client connecting to the API server from the same host. The certificates in the file do not work for remote connections.

‎modules/microshift-kubeconfig-overview.adoc

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/microshift_configuring/microshift-cluster-access-kubeconfig.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="kubeconfig-files-overview_{context}"]
7+
= Kubeconfig files for configuring cluster access
8+
9+
The two categories of `kubeconfig` files used in {product-title} are local access and remote access. Every time {product-title} starts, a set of `kubeconfig` files for local and remote access to the API server are generated. These files are generated in the `/var/lib/microshift/resources/kubeadmin/` directory using preexisting configuration information.
10+
11+
Each access type requires a different authentication certificate signed by different Certificate Authorities (CAs). The generation of multiple `kubeconfig` files accommodates this need.
12+
13+
You can use the appropriate `kubeconfig` file for the access type needed in each case to provide authentication details. The contents of {product-title} `kubeconfig` files are determined by either default built-in values or a `config.yaml` file.
14+
15+
[NOTE]
16+
====
17+
A `kubeconfig` file must exist for the cluster to be accessible. The values are applied from built-in default values or a `config.yaml`, if one was created.
18+
====
19+
20+
.Example contents of the kubeconfig files
21+
[source,terminal]
22+
----
23+
/var/lib/microshift/resources/kubeadmin/
24+
├── kubeconfig <1>
25+
├── alt-name-1 <2>
26+
│ └── kubeconfig
27+
├── 1.2.3.4 <3>
28+
│ └── kubeconfig
29+
└── microshift-rhel9 <4>
30+
└── kubeconfig
31+
----
32+
<1> Local host name. The main IP address of the host is always the default.
33+
<2> Subject Alternative Names for API server certificates.
34+
<3> DNS name.
35+
<4> {product-title} host name.

‎modules/microshift-kubeconfig-remote-con.adoc

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * microshift/microshift_configuring/microshift-cluster-access-kubeconfig.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="remote-access-con_{context}"]
7+
= Remote access kubeconfig files
8+
9+
When a {product-title} cluster connects to the API server from an external source, a certificate with all of the alternative names in the SAN field is used for validation. {product-title} generates a default `kubeconfig` for external access using the `hostname` value. The defaults are set in the `<node.hostnameOverride>`, `<node.nodeIP>` and `api.<dns.baseDomain>` parameter values of the default `kubeconfig` file.
10+
11+
The `/var/lib/microshift/resources/kubeadmin/<hostname>/kubeconfig` file uses the `hostname` of the machine, or `node.hostnameOverride` if that option is set, to reach the API server. The CA of the `kubeconfig` file is able to validate certificates when accessed externally.
12+
13+
.Example contents of a default `kubeconfig` file for remote access
14+
[source,yaml]
15+
----
16+
clusters:
17+
- cluster:
18+
certificate-authority-data: <base64 CA>
19+
server: https://microshift-rhel9:6443
20+
----
21+
22+
[id="remote-access-customization_{context}"]
23+
== Remote access customization
24+
Multiple remote access `kubeconfig` file values can be generated for accessing the cluster with different IP addresses or host names. An additional `kubeconfig` file generates for each entry in the `apiServer.subjectAltNames` parameter. You can copy remote access `kubeconfig` files from the host during times of IP connectivity and then use them to access the API server from other workstations.

0 commit comments

Comments
 (0)