nixos: nixos/doc/manual/configuration/kubernetes.xml to CommonMark

4 files changed, 235 insertions, 113 deletions

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 @@
  <xi:include href="../from_md/configuration/subversion.chapter.xml" />
  <xi:include href="../generated/modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
  <xi:include href="profiles.xml" />
- <xi:include href="kubernetes.xml" />
+ <xi:include href="../from_md/configuration/kubernetes.chapter.xml" />
 <!-- Apache; libvirtd virtualisation -->
 </part>
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 @@
-<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>
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 @@
+<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 (&quot;master&quot; and/or
+    &quot;node&quot;) to the host. This enables apiserver,
+    controllerManager, scheduler, addonManager, kube-proxy and etcd:
+  </para>
+  <programlisting language="bash">
+services.kubernetes.roles = [ &quot;master&quot; ];
+</programlisting>
+  <para>
+    While this will enable the kubelet and kube-proxy only:
+  </para>
+  <programlisting language="bash">
+services.kubernetes.roles = [ &quot;node&quot; ];
+</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 = [ &quot;master&quot; &quot;node&quot; ];
+</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>