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.
+
+