From f8bdee0054668f1ac7b30679e5ce6f5b95f160ee Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Sat, 3 Jul 2021 19:41:27 +0800 Subject: nixos: nixos/doc/manual/configuration/kubernetes.xml to CommonMark --- nixos/doc/manual/configuration/configuration.xml | 2 +- .../doc/manual/configuration/kubernetes.chapter.md | 104 +++++++++++++++++ nixos/doc/manual/configuration/kubernetes.xml | 112 ------------------ .../from_md/configuration/kubernetes.chapter.xml | 130 +++++++++++++++++++++ 4 files changed, 235 insertions(+), 113 deletions(-) create mode 100644 nixos/doc/manual/configuration/kubernetes.chapter.md delete mode 100644 nixos/doc/manual/configuration/kubernetes.xml create mode 100644 nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml diff --git a/nixos/doc/manual/configuration/configuration.xml b/nixos/doc/manual/configuration/configuration.xml index a1d0d139aa5..2461a5de73a 100644 --- a/nixos/doc/manual/configuration/configuration.xml +++ b/nixos/doc/manual/configuration/configuration.xml @@ -26,6 +26,6 @@ - + diff --git a/nixos/doc/manual/configuration/kubernetes.chapter.md b/nixos/doc/manual/configuration/kubernetes.chapter.md new file mode 100644 index 00000000000..09a076a610b --- /dev/null +++ b/nixos/doc/manual/configuration/kubernetes.chapter.md @@ -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. diff --git a/nixos/doc/manual/configuration/kubernetes.xml b/nixos/doc/manual/configuration/kubernetes.xml deleted file mode 100644 index 54a100e4479..00000000000 --- a/nixos/doc/manual/configuration/kubernetes.xml +++ /dev/null @@ -1,112 +0,0 @@ - - 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: - -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: - - = [ "master" ]; - - While this will enable the kubelet and kube-proxy only: - - = [ "node" ]; - - Assigning both the master and node roles is usable if you want a single node - Kubernetes cluster for dev or testing purposes: - - = [ "master" "node" ]; - - Note: Assigning either role will also default both - and - 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: - and - - - - - As of NixOS 19.03, it is mandatory to configure: - . 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. - - - The NixOS kubernetes module provides an option for automatic certificate - bootstrapping and configuration, - . 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 - = 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 - 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. - - - - 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 - . - 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. - - diff --git a/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml b/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml new file mode 100644 index 00000000000..2707101ccf8 --- /dev/null +++ b/nixos/doc/manual/from_md/configuration/kubernetes.chapter.xml @@ -0,0 +1,130 @@ + + 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: + + +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: + + +services.kubernetes.roles = [ "master" ]; + + + While this will enable the kubelet and kube-proxy only: + + +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: + + +services.kubernetes.roles = [ "master" "node" ]; + + + Note: Assigning either role will also default both + services.kubernetes.flannel.enable + and + 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 + and + services.kubernetes.apiserver.insecureBindAddress + + + + As of NixOS 19.03, it is mandatory to configure: + 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. + + + The NixOS kubernetes module provides an option for automatic + certificate bootstrapping and configuration, + 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 + = 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 + 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. + + + + 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. + 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. + + -- cgit 1.4.1