nixos: nixos/doc/manual/configuration/kubernetes.xml to CommonMark
This commit is contained in:
parent
ee807a30cf
commit
f8bdee0054
|
@ -26,6 +26,6 @@
|
||||||
<xi:include href="../from_md/configuration/subversion.chapter.xml" />
|
<xi:include href="../from_md/configuration/subversion.chapter.xml" />
|
||||||
<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
|
<xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
|
||||||
<xi:include href="profiles.xml" />
|
<xi:include href="profiles.xml" />
|
||||||
<xi:include href="kubernetes.xml" />
|
<xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
|
||||||
<!-- Apache; libvirtd virtualisation -->
|
<!-- Apache; libvirtd virtualisation -->
|
||||||
</part>
|
</part>
|
||||||
|
|
104
nixos/doc/manual/configuration/kubernetes.chapter.md
Normal file
104
nixos/doc/manual/configuration/kubernetes.chapter.md
Normal file
|
@ -0,0 +1,104 @@
|
||||||
|
# Kubernetes {#sec-kubernetes}
|
||||||
|
|
||||||
|
The NixOS Kubernetes module is a collective term for a handful of
|
||||||
|
individual submodules implementing the Kubernetes cluster components.
|
||||||
|
|
||||||
|
There are generally two ways of enabling Kubernetes on NixOS. One way is
|
||||||
|
to enable and configure cluster components appropriately by hand:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.kubernetes = {
|
||||||
|
apiserver.enable = true;
|
||||||
|
controllerManager.enable = true;
|
||||||
|
scheduler.enable = true;
|
||||||
|
addonManager.enable = true;
|
||||||
|
proxy.enable = true;
|
||||||
|
flannel.enable = true;
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
Another way is to assign cluster roles (\"master\" and/or \"node\") to
|
||||||
|
the host. This enables apiserver, controllerManager, scheduler,
|
||||||
|
addonManager, kube-proxy and etcd:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.kubernetes.roles = [ "master" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
While this will enable the kubelet and kube-proxy only:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.kubernetes.roles = [ "node" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
Assigning both the master and node roles is usable if you want a single
|
||||||
|
node Kubernetes cluster for dev or testing purposes:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.kubernetes.roles = [ "master" "node" ];
|
||||||
|
```
|
||||||
|
|
||||||
|
Note: Assigning either role will also default both
|
||||||
|
[`services.kubernetes.flannel.enable`](options.html#opt-services.kubernetes.flannel.enable)
|
||||||
|
and [`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts)
|
||||||
|
to true. This sets up flannel as CNI and activates automatic PKI bootstrapping.
|
||||||
|
|
||||||
|
As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled
|
||||||
|
ports on kubernetes components. Thus, from NixOS 19.03 all plain HTTP
|
||||||
|
ports have been disabled by default. While opening insecure ports is
|
||||||
|
still possible, it is recommended not to bind these to other interfaces
|
||||||
|
than loopback. To re-enable the insecure port on the apiserver, see options:
|
||||||
|
[`services.kubernetes.apiserver.insecurePort`](options.html#opt-services.kubernetes.apiserver.insecurePort) and
|
||||||
|
[`services.kubernetes.apiserver.insecureBindAddress`](options.html#opt-services.kubernetes.apiserver.insecureBindAddress)
|
||||||
|
|
||||||
|
::: {.note}
|
||||||
|
As of NixOS 19.03, it is mandatory to configure:
|
||||||
|
[`services.kubernetes.masterAddress`](options.html#opt-services.kubernetes.masterAddress).
|
||||||
|
The masterAddress must be resolveable and routeable by all cluster nodes.
|
||||||
|
In single node clusters, this can be set to `localhost`.
|
||||||
|
:::
|
||||||
|
|
||||||
|
Role-based access control (RBAC) authorization mode is enabled by
|
||||||
|
default. This means that anonymous requests to the apiserver secure port
|
||||||
|
will expectedly cause a permission denied error. All cluster components
|
||||||
|
must therefore be configured with x509 certificates for two-way tls
|
||||||
|
communication. The x509 certificate subject section determines the roles
|
||||||
|
and permissions granted by the apiserver to perform clusterwide or
|
||||||
|
namespaced operations. See also: [ Using RBAC
|
||||||
|
Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
|
||||||
|
|
||||||
|
The NixOS kubernetes module provides an option for automatic certificate
|
||||||
|
bootstrapping and configuration,
|
||||||
|
[`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts).
|
||||||
|
The PKI bootstrapping process involves setting up a certificate authority (CA)
|
||||||
|
daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert
|
||||||
|
for the cluster, and uses the CA-cert for signing subordinate certs issued
|
||||||
|
to each of the cluster components. Subsequently, the certmgr daemon monitors
|
||||||
|
active certificates and renews them when needed. For single node Kubernetes
|
||||||
|
clusters, setting [`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts)
|
||||||
|
= true is sufficient and no further action is required. For joining extra node
|
||||||
|
machines to an existing cluster on the other hand, establishing initial
|
||||||
|
trust is mandatory.
|
||||||
|
|
||||||
|
To add new nodes to the cluster: On any (non-master) cluster node where
|
||||||
|
[`services.kubernetes.easyCerts`](options.html#opt-services.kubernetes.easyCerts)
|
||||||
|
is enabled, the helper script `nixos-kubernetes-node-join` is available on PATH.
|
||||||
|
Given a token on stdin, it will copy the token to the kubernetes secrets directory
|
||||||
|
and restart the certmgr service. As requested certificates are issued, the
|
||||||
|
script will restart kubernetes cluster components as needed for them to
|
||||||
|
pick up new keypairs.
|
||||||
|
|
||||||
|
::: {.note}
|
||||||
|
Multi-master (HA) clusters are not supported by the easyCerts module.
|
||||||
|
:::
|
||||||
|
|
||||||
|
In order to interact with an RBAC-enabled cluster as an administrator,
|
||||||
|
one needs to have cluster-admin privileges. By default, when easyCerts
|
||||||
|
is enabled, a cluster-admin kubeconfig file is generated and linked into
|
||||||
|
`/etc/kubernetes/cluster-admin.kubeconfig` as determined by
|
||||||
|
[`services.kubernetes.pki.etcClusterAdminKubeconfig`](options.html#opt-services.kubernetes.pki.etcClusterAdminKubeconfig).
|
||||||
|
`export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig` will make
|
||||||
|
kubectl use this kubeconfig to access and authenticate the cluster. The
|
||||||
|
cluster-admin kubeconfig references an auto-generated keypair owned by
|
||||||
|
root. Thus, only root on the kubernetes master may obtain cluster-admin
|
||||||
|
rights by means of this file.
|
|
@ -1,112 +0,0 @@
|
||||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
|
||||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
||||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
||||||
version="5.0"
|
|
||||||
xml:id="sec-kubernetes">
|
|
||||||
<title>Kubernetes</title>
|
|
||||||
<para>
|
|
||||||
The NixOS Kubernetes module is a collective term for a handful of individual
|
|
||||||
submodules implementing the Kubernetes cluster components.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
There are generally two ways of enabling Kubernetes on NixOS. One way is to
|
|
||||||
enable and configure cluster components appropriately by hand:
|
|
||||||
<programlisting>
|
|
||||||
services.kubernetes = {
|
|
||||||
apiserver.enable = true;
|
|
||||||
controllerManager.enable = true;
|
|
||||||
scheduler.enable = true;
|
|
||||||
addonManager.enable = true;
|
|
||||||
proxy.enable = true;
|
|
||||||
flannel.enable = true;
|
|
||||||
};
|
|
||||||
</programlisting>
|
|
||||||
Another way is to assign cluster roles ("master" and/or "node") to the host.
|
|
||||||
This enables apiserver, controllerManager, scheduler, addonManager,
|
|
||||||
kube-proxy and etcd:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-services.kubernetes.roles"/> = [ "master" ];
|
|
||||||
</programlisting>
|
|
||||||
While this will enable the kubelet and kube-proxy only:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-services.kubernetes.roles"/> = [ "node" ];
|
|
||||||
</programlisting>
|
|
||||||
Assigning both the master and node roles is usable if you want a single node
|
|
||||||
Kubernetes cluster for dev or testing purposes:
|
|
||||||
<programlisting>
|
|
||||||
<xref linkend="opt-services.kubernetes.roles"/> = [ "master" "node" ];
|
|
||||||
</programlisting>
|
|
||||||
Note: Assigning either role will also default both
|
|
||||||
<xref linkend="opt-services.kubernetes.flannel.enable"/> and
|
|
||||||
<xref linkend="opt-services.kubernetes.easyCerts"/> to true. This sets up
|
|
||||||
flannel as CNI and activates automatic PKI bootstrapping.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
As of kubernetes 1.10.X it has been deprecated to open non-tls-enabled ports
|
|
||||||
on kubernetes components. Thus, from NixOS 19.03 all plain HTTP ports have
|
|
||||||
been disabled by default. While opening insecure ports is still possible, it
|
|
||||||
is recommended not to bind these to other interfaces than loopback. To
|
|
||||||
re-enable the insecure port on the apiserver, see options:
|
|
||||||
<xref linkend="opt-services.kubernetes.apiserver.insecurePort"/> and
|
|
||||||
<xref linkend="opt-services.kubernetes.apiserver.insecureBindAddress"/>
|
|
||||||
</para>
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
As of NixOS 19.03, it is mandatory to configure:
|
|
||||||
<xref linkend="opt-services.kubernetes.masterAddress"/>. The masterAddress
|
|
||||||
must be resolveable and routeable by all cluster nodes. In single node
|
|
||||||
clusters, this can be set to <literal>localhost</literal>.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
<para>
|
|
||||||
Role-based access control (RBAC) authorization mode is enabled by default.
|
|
||||||
This means that anonymous requests to the apiserver secure port will
|
|
||||||
expectedly cause a permission denied error. All cluster components must
|
|
||||||
therefore be configured with x509 certificates for two-way tls communication.
|
|
||||||
The x509 certificate subject section determines the roles and permissions
|
|
||||||
granted by the apiserver to perform clusterwide or namespaced operations. See
|
|
||||||
also:
|
|
||||||
<link
|
|
||||||
xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/">
|
|
||||||
Using RBAC Authorization</link>.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
The NixOS kubernetes module provides an option for automatic certificate
|
|
||||||
bootstrapping and configuration,
|
|
||||||
<xref linkend="opt-services.kubernetes.easyCerts"/>. The PKI bootstrapping
|
|
||||||
process involves setting up a certificate authority (CA) daemon (cfssl) on
|
|
||||||
the kubernetes master node. cfssl generates a CA-cert for the cluster, and
|
|
||||||
uses the CA-cert for signing subordinate certs issued to each of the cluster
|
|
||||||
components. Subsequently, the certmgr daemon monitors active certificates and
|
|
||||||
renews them when needed. For single node Kubernetes clusters, setting
|
|
||||||
<xref linkend="opt-services.kubernetes.easyCerts"/> = true is sufficient and
|
|
||||||
no further action is required. For joining extra node machines to an existing
|
|
||||||
cluster on the other hand, establishing initial trust is mandatory.
|
|
||||||
</para>
|
|
||||||
<para>
|
|
||||||
To add new nodes to the cluster: On any (non-master) cluster node where
|
|
||||||
<xref linkend="opt-services.kubernetes.easyCerts"/> is enabled, the helper
|
|
||||||
script <literal>nixos-kubernetes-node-join</literal> is available on PATH.
|
|
||||||
Given a token on stdin, it will copy the token to the kubernetes secrets
|
|
||||||
directory and restart the certmgr service. As requested certificates are
|
|
||||||
issued, the script will restart kubernetes cluster components as needed for
|
|
||||||
them to pick up new keypairs.
|
|
||||||
</para>
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
Multi-master (HA) clusters are not supported by the easyCerts module.
|
|
||||||
</para>
|
|
||||||
</note>
|
|
||||||
<para>
|
|
||||||
In order to interact with an RBAC-enabled cluster as an administrator, one
|
|
||||||
needs to have cluster-admin privileges. By default, when easyCerts is
|
|
||||||
enabled, a cluster-admin kubeconfig file is generated and linked into
|
|
||||||
<literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as determined by
|
|
||||||
<xref linkend="opt-services.kubernetes.pki.etcClusterAdminKubeconfig"/>.
|
|
||||||
<literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal>
|
|
||||||
will make kubectl use this kubeconfig to access and authenticate the cluster.
|
|
||||||
The cluster-admin kubeconfig references an auto-generated keypair owned by
|
|
||||||
root. Thus, only root on the kubernetes master may obtain cluster-admin
|
|
||||||
rights by means of this file.
|
|
||||||
</para>
|
|
||||||
</chapter>
|
|
130
nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml
Normal file
130
nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml
Normal file
|
@ -0,0 +1,130 @@
|
||||||
|
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-kubernetes">
|
||||||
|
<title>Kubernetes</title>
|
||||||
|
<para>
|
||||||
|
The NixOS Kubernetes module is a collective term for a handful of
|
||||||
|
individual submodules implementing the Kubernetes cluster
|
||||||
|
components.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
There are generally two ways of enabling Kubernetes on NixOS. One
|
||||||
|
way is to enable and configure cluster components appropriately by
|
||||||
|
hand:
|
||||||
|
</para>
|
||||||
|
<programlisting language="bash">
|
||||||
|
services.kubernetes = {
|
||||||
|
apiserver.enable = true;
|
||||||
|
controllerManager.enable = true;
|
||||||
|
scheduler.enable = true;
|
||||||
|
addonManager.enable = true;
|
||||||
|
proxy.enable = true;
|
||||||
|
flannel.enable = true;
|
||||||
|
};
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
Another way is to assign cluster roles ("master" and/or
|
||||||
|
"node") to the host. This enables apiserver,
|
||||||
|
controllerManager, scheduler, addonManager, kube-proxy and etcd:
|
||||||
|
</para>
|
||||||
|
<programlisting language="bash">
|
||||||
|
services.kubernetes.roles = [ "master" ];
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
While this will enable the kubelet and kube-proxy only:
|
||||||
|
</para>
|
||||||
|
<programlisting language="bash">
|
||||||
|
services.kubernetes.roles = [ "node" ];
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
Assigning both the master and node roles is usable if you want a
|
||||||
|
single node Kubernetes cluster for dev or testing purposes:
|
||||||
|
</para>
|
||||||
|
<programlisting language="bash">
|
||||||
|
services.kubernetes.roles = [ "master" "node" ];
|
||||||
|
</programlisting>
|
||||||
|
<para>
|
||||||
|
Note: Assigning either role will also default both
|
||||||
|
<link xlink:href="options.html#opt-services.kubernetes.flannel.enable"><literal>services.kubernetes.flannel.enable</literal></link>
|
||||||
|
and
|
||||||
|
<link xlink:href="options.html#opt-services.kubernetes.easyCerts"><literal>services.kubernetes.easyCerts</literal></link>
|
||||||
|
to true. This sets up flannel as CNI and activates automatic PKI
|
||||||
|
bootstrapping.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
As of kubernetes 1.10.X it has been deprecated to open
|
||||||
|
non-tls-enabled ports on kubernetes components. Thus, from NixOS
|
||||||
|
19.03 all plain HTTP ports have been disabled by default. While
|
||||||
|
opening insecure ports is still possible, it is recommended not to
|
||||||
|
bind these to other interfaces than loopback. To re-enable the
|
||||||
|
insecure port on the apiserver, see options:
|
||||||
|
<link xlink:href="options.html#opt-services.kubernetes.apiserver.insecurePort"><literal>services.kubernetes.apiserver.insecurePort</literal></link>
|
||||||
|
and
|
||||||
|
<link xlink:href="options.html#opt-services.kubernetes.apiserver.insecureBindAddress"><literal>services.kubernetes.apiserver.insecureBindAddress</literal></link>
|
||||||
|
</para>
|
||||||
|
<note>
|
||||||
|
<para>
|
||||||
|
As of NixOS 19.03, it is mandatory to configure:
|
||||||
|
<link xlink:href="options.html#opt-services.kubernetes.masterAddress"><literal>services.kubernetes.masterAddress</literal></link>.
|
||||||
|
The masterAddress must be resolveable and routeable by all cluster
|
||||||
|
nodes. In single node clusters, this can be set to
|
||||||
|
<literal>localhost</literal>.
|
||||||
|
</para>
|
||||||
|
</note>
|
||||||
|
<para>
|
||||||
|
Role-based access control (RBAC) authorization mode is enabled by
|
||||||
|
default. This means that anonymous requests to the apiserver secure
|
||||||
|
port will expectedly cause a permission denied error. All cluster
|
||||||
|
components must therefore be configured with x509 certificates for
|
||||||
|
two-way tls communication. The x509 certificate subject section
|
||||||
|
determines the roles and permissions granted by the apiserver to
|
||||||
|
perform clusterwide or namespaced operations. See also:
|
||||||
|
<link xlink:href="https://kubernetes.io/docs/reference/access-authn-authz/rbac/">
|
||||||
|
Using RBAC Authorization</link>.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The NixOS kubernetes module provides an option for automatic
|
||||||
|
certificate bootstrapping and configuration,
|
||||||
|
<link xlink:href="options.html#opt-services.kubernetes.easyCerts"><literal>services.kubernetes.easyCerts</literal></link>.
|
||||||
|
The PKI bootstrapping process involves setting up a certificate
|
||||||
|
authority (CA) daemon (cfssl) on the kubernetes master node. cfssl
|
||||||
|
generates a CA-cert for the cluster, and uses the CA-cert for
|
||||||
|
signing subordinate certs issued to each of the cluster components.
|
||||||
|
Subsequently, the certmgr daemon monitors active certificates and
|
||||||
|
renews them when needed. For single node Kubernetes clusters,
|
||||||
|
setting
|
||||||
|
<link xlink:href="options.html#opt-services.kubernetes.easyCerts"><literal>services.kubernetes.easyCerts</literal></link>
|
||||||
|
= true is sufficient and no further action is required. For joining
|
||||||
|
extra node machines to an existing cluster on the other hand,
|
||||||
|
establishing initial trust is mandatory.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
To add new nodes to the cluster: On any (non-master) cluster node
|
||||||
|
where
|
||||||
|
<link xlink:href="options.html#opt-services.kubernetes.easyCerts"><literal>services.kubernetes.easyCerts</literal></link>
|
||||||
|
is enabled, the helper script
|
||||||
|
<literal>nixos-kubernetes-node-join</literal> is available on PATH.
|
||||||
|
Given a token on stdin, it will copy the token to the kubernetes
|
||||||
|
secrets directory and restart the certmgr service. As requested
|
||||||
|
certificates are issued, the script will restart kubernetes cluster
|
||||||
|
components as needed for them to pick up new keypairs.
|
||||||
|
</para>
|
||||||
|
<note>
|
||||||
|
<para>
|
||||||
|
Multi-master (HA) clusters are not supported by the easyCerts
|
||||||
|
module.
|
||||||
|
</para>
|
||||||
|
</note>
|
||||||
|
<para>
|
||||||
|
In order to interact with an RBAC-enabled cluster as an
|
||||||
|
administrator, one needs to have cluster-admin privileges. By
|
||||||
|
default, when easyCerts is enabled, a cluster-admin kubeconfig file
|
||||||
|
is generated and linked into
|
||||||
|
<literal>/etc/kubernetes/cluster-admin.kubeconfig</literal> as
|
||||||
|
determined by
|
||||||
|
<link xlink:href="options.html#opt-services.kubernetes.pki.etcClusterAdminKubeconfig"><literal>services.kubernetes.pki.etcClusterAdminKubeconfig</literal></link>.
|
||||||
|
<literal>export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig</literal>
|
||||||
|
will make kubectl use this kubeconfig to access and authenticate the
|
||||||
|
cluster. The cluster-admin kubeconfig references an auto-generated
|
||||||
|
keypair owned by root. Thus, only root on the kubernetes master may
|
||||||
|
obtain cluster-admin rights by means of this file.
|
||||||
|
</para>
|
||||||
|
</chapter>
|
Loading…
Reference in a new issue