nixos/doc/manual/configuration/kubernetes.chapter.md

   1 # Kubernetes {#sec-kubernetes}
   2
   3 The NixOS Kubernetes module is a collective term for a handful of
   4 individual submodules implementing the Kubernetes cluster components.
   5
   6 There are generally two ways of enabling Kubernetes on NixOS. One way is
   7 to enable and configure cluster components appropriately by hand:
   8
   9 ```nix
  10 {
  11   services.kubernetes = {
  12     apiserver.enable = true;
  13     controllerManager.enable = true;
  14     scheduler.enable = true;
  15     addonManager.enable = true;
  16     proxy.enable = true;
  17     flannel.enable = true;
  18   };
  19 }
  20 ```
  21
  22 Another way is to assign cluster roles ("master" and/or "node") to
  23 the host. This enables apiserver, controllerManager, scheduler,
  24 addonManager, kube-proxy and etcd:
  25
  26 ```nix
  27 {
  28   services.kubernetes.roles = [ "master" ];
  29 }
  30 ```
  31
  32 While this will enable the kubelet and kube-proxy only:
  33
  34 ```nix
  35 {
  36   services.kubernetes.roles = [ "node" ];
  37 }
  38 ```
  39
  40 Assigning both the master and node roles is usable if you want a single
  41 node Kubernetes cluster for dev or testing purposes:
  42
  43 ```nix
  44 {
  45   services.kubernetes.roles = [ "master" "node" ];
  46 }
  47 ```
  48
  49 Note: Assigning either role will also default both
  50 [](#opt-services.kubernetes.flannel.enable)
  51 and [](#opt-services.kubernetes.easyCerts)
  52 to true. This sets up flannel as CNI and activates automatic PKI bootstrapping.
  53
  54 ::: {.note}
  55 As of NixOS 19.03, it is mandatory to configure:
  56 [](#opt-services.kubernetes.masterAddress).
  57 The masterAddress must be resolveable and routeable by all cluster nodes.
  58 In single node clusters, this can be set to `localhost`.
  59 :::
  60
  61 Role-based access control (RBAC) authorization mode is enabled by
  62 default. This means that anonymous requests to the apiserver secure port
  63 will expectedly cause a permission denied error. All cluster components
  64 must therefore be configured with x509 certificates for two-way tls
  65 communication. The x509 certificate subject section determines the roles
  66 and permissions granted by the apiserver to perform clusterwide or
  67 namespaced operations. See also: [ Using RBAC
  68 Authorization](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).
  69
  70 The NixOS kubernetes module provides an option for automatic certificate
  71 bootstrapping and configuration,
  72 [](#opt-services.kubernetes.easyCerts).
  73 The PKI bootstrapping process involves setting up a certificate authority (CA)
  74 daemon (cfssl) on the kubernetes master node. cfssl generates a CA-cert
  75 for the cluster, and uses the CA-cert for signing subordinate certs issued
  76 to each of the cluster components. Subsequently, the certmgr daemon monitors
  77 active certificates and renews them when needed. For single node Kubernetes
  78 clusters, setting [](#opt-services.kubernetes.easyCerts)
  79 = true is sufficient and no further action is required. For joining extra node
  80 machines to an existing cluster on the other hand, establishing initial
  81 trust is mandatory.
  82
  83 To add new nodes to the cluster: On any (non-master) cluster node where
  84 [](#opt-services.kubernetes.easyCerts)
  85 is enabled, the helper script `nixos-kubernetes-node-join` is available on PATH.
  86 Given a token on stdin, it will copy the token to the kubernetes secrets directory
  87 and restart the certmgr service. As requested certificates are issued, the
  88 script will restart kubernetes cluster components as needed for them to
  89 pick up new keypairs.
  90
  91 ::: {.note}
  92 Multi-master (HA) clusters are not supported by the easyCerts module.
  93 :::
  94
  95 In order to interact with an RBAC-enabled cluster as an administrator,
  96 one needs to have cluster-admin privileges. By default, when easyCerts
  97 is enabled, a cluster-admin kubeconfig file is generated and linked into
  98 `/etc/kubernetes/cluster-admin.kubeconfig` as determined by
  99 [](#opt-services.kubernetes.pki.etcClusterAdminKubeconfig).
 100 `export KUBECONFIG=/etc/kubernetes/cluster-admin.kubeconfig` will make
 101 kubectl use this kubeconfig to access and authenticate the cluster. The
 102 cluster-admin kubeconfig references an auto-generated keypair owned by
 103 root. Thus, only root on the kubernetes master may obtain cluster-admin
 104 rights by means of this file.