Certificates

When using client certificate authentication, you can generate certificates manually through easyrsa, openssl or cfssl.

easyrsa

easyrsa can manually generate certificates for your cluster.

  1. Download, unpack, and initialize the patched version of easyrsa3.

    1. curl -LO https://storage.googleapis.com/kubernetes-release/easy-rsa/easy-rsa.tar.gz
    2. tar xzf easy-rsa.tar.gz
    3. cd easy-rsa-master/easyrsa3
    4. ./easyrsa init-pki

  2. Generate a new certificate authority (CA). --batch sets automatic mode; --req-cn specifies the Common Name (CN) for the CA’s new root certificate.

    1. ./easyrsa --batch "--req-cn=${MASTER_IP}@`date +%s`" build-ca nopass

  3. Generate server certificate and key. The argument --subject-alt-name sets the possible IPs and DNS names the API server will be accessed with. The MASTER_CLUSTER_IP is usually the first IP from the service CIDR that is specified as the --service-cluster-ip-range argument for both the API server and the controller manager component. The argument --days is used to set the number of days after which the certificate expires. The sample below also assumes that you are using cluster.local as the default DNS domain name.

    1. ./easyrsa --subject-alt-name="IP:${MASTER_IP},"\
    2. "IP:${MASTER_CLUSTER_IP},"\
    3. "DNS:kubernetes,"\
    4. "DNS:kubernetes.default,"\
    5. "DNS:kubernetes.default.svc,"\
    6. "DNS:kubernetes.default.svc.cluster,"\
    7. "DNS:kubernetes.default.svc.cluster.local" \
    8. --days=10000 \
    9. build-server-full server nopass

  4. Copy pki/ca.crt, pki/issued/server.crt, and pki/private/server.key to your directory.

  5. Fill in and add the following parameters into the API server start parameters:

    1. --client-ca-file=/yourdirectory/ca.crt
    2. --tls-cert-file=/yourdirectory/server.crt
    3. --tls-private-key-file=/yourdirectory/server.key

openssl

openssl can manually generate certificates for your cluster.

  1. Generate a ca.key with 2048bit:

    1. openssl genrsa -out ca.key 2048

  2. According to the ca.key generate a ca.crt (use -days to set the certificate effective time):

    1. openssl req -x509 -new -nodes -key ca.key -subj "/CN=${MASTER_IP}" -days 10000 -out ca.crt

  3. Generate a server.key with 2048bit:

    1. openssl genrsa -out server.key 2048

  4. Create a config file for generating a Certificate Signing Request (CSR). Be sure to substitute the values marked with angle brackets (e.g. <MASTER_IP>) with real values before saving this to a file (e.g. csr.conf). Note that the value for MASTER_CLUSTER_IP is the service cluster IP for the API server as described in previous subsection. The sample below also assumes that you are using cluster.local as the default DNS domain name.

    1. [ req ]
    2. default_bits = 2048
    3. prompt = no
    4. default_md = sha256
    5. req_extensions = req_ext
    6. distinguished_name = dn
    8. [ dn ]
    9. C = <country>
    10. ST = <state>
    11. L = <city>
    12. O = <organization>
    13. OU = <organization unit>
    14. CN = <MASTER_IP>
    16. [ req_ext ]
    17. subjectAltName = @alt_names
    19. [ alt_names ]
    20. DNS.1 = kubernetes
    21. DNS.2 = kubernetes.default
    22. DNS.3 = kubernetes.default.svc
    23. DNS.4 = kubernetes.default.svc.cluster
    24. DNS.5 = kubernetes.default.svc.cluster.local
    25. IP.1 = <MASTER_IP>
    26. IP.2 = <MASTER_CLUSTER_IP>
    28. [ v3_ext ]
    29. authorityKeyIdentifier=keyid,issuer:always
    30. basicConstraints=CA:FALSE
    31. keyUsage=keyEncipherment,dataEncipherment
    32. extendedKeyUsage=serverAuth,clientAuth
    33. subjectAltName=@alt_names

  5. Generate the certificate signing request based on the config file:

    1. openssl req -new -key server.key -out server.csr -config csr.conf

  6. Generate the server certificate using the ca.key, ca.crt and server.csr:

    1. openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
    2. -CAcreateserial -out server.crt -days 10000 \
    3. -extensions v3_ext -extfile csr.conf

  7. View the certificate:

    1. openssl x509  -noout -text -in ./server.crt

Finally, add the same parameters into the API server start parameters.

cfssl

cfssl is another tool for certificate generation.

  1. Download, unpack and prepare the command line tools as shown below. Note that you may need to adapt the sample commands based on the hardware architecture and cfssl version you are using.

    1. curl -L https://github.com/cloudflare/cfssl/releases/download/v1.5.0/cfssl_1.5.0_linux_amd64 -o cfssl
    2. chmod +x cfssl
    3. curl -L https://github.com/cloudflare/cfssl/releases/download/v1.5.0/cfssljson_1.5.0_linux_amd64 -o cfssljson
    4. chmod +x cfssljson
    5. curl -L https://github.com/cloudflare/cfssl/releases/download/v1.5.0/cfssl-certinfo_1.5.0_linux_amd64 -o cfssl-certinfo
    6. chmod +x cfssl-certinfo

  2. Create a directory to hold the artifacts and initialize cfssl:

    1. mkdir cert
    2. cd cert
    3. ../cfssl print-defaults config > config.json
    4. ../cfssl print-defaults csr > csr.json

  3. Create a JSON config file for generating the CA file, for example, ca-config.json:

    1. {
    2.   "signing": {
    3.     "default": {
    4.       "expiry": "8760h"
    5.     },
    6.     "profiles": {
    7.       "kubernetes": {
    8.         "usages": [
    9.           "signing",
    10.           "key encipherment",
    11.           "server auth",
    12.           "client auth"
    13.         ],
    14.         "expiry": "8760h"
    15.       }
    16.     }
    17.   }
    18. }

  4. Create a JSON config file for CA certificate signing request (CSR), for example, ca-csr.json. Be sure to replace the values marked with angle brackets with real values you want to use.

    1. {
    2.   "CN": "kubernetes",
    3.   "key": {
    4.     "algo": "rsa",
    5.     "size": 2048
    6.   },
    7.   "names":[{
    8.     "C": "<country>",
    9.     "ST": "<state>",
    10.     "L": "<city>",
    11.     "O": "<organization>",
    12.     "OU": "<organization unit>"
    13.   }]
    14. }

  5. Generate CA key (ca-key.pem) and certificate (ca.pem):

    1. ../cfssl gencert -initca ca-csr.json | ../cfssljson -bare ca

  6. Create a JSON config file for generating keys and certificates for the API server, for example, server-csr.json. Be sure to replace the values in angle brackets with real values you want to use. The MASTER_CLUSTER_IP is the service cluster IP for the API server as described in previous subsection. The sample below also assumes that you are using cluster.local as the default DNS domain name.

    1. {
    2.   "CN": "kubernetes",
    3.   "hosts": [
    4.     "127.0.0.1",
    5.     "<MASTER_IP>",
    6.     "<MASTER_CLUSTER_IP>",
    7.     "kubernetes",
    8.     "kubernetes.default",
    9.     "kubernetes.default.svc",
    10.     "kubernetes.default.svc.cluster",
    11.     "kubernetes.default.svc.cluster.local"
    12.   ],
    13.   "key": {
    14.     "algo": "rsa",
    15.     "size": 2048
    16.   },
    17.   "names": [{
    18.     "C": "<country>",
    19.     "ST": "<state>",
    20.     "L": "<city>",
    21.     "O": "<organization>",
    22.     "OU": "<organization unit>"
    23.   }]
    24. }

  7. Generate the key and certificate for the API server, which are by default saved into file server-key.pem and server.pem respectively:

    1. ../cfssl gencert -ca=ca.pem -ca-key=ca-key.pem \
    2. --config=ca-config.json -profile=kubernetes \
    3. server-csr.json | ../cfssljson -bare server

Distributing Self-Signed CA Certificate

A client node may refuse to recognize a self-signed CA certificate as valid. For a non-production deployment, or for a deployment that runs behind a company firewall, you can distribute a self-signed CA certificate to all clients and refresh the local list for valid certificates.

On each client, perform the following operations:

  1. sudo cp ca.crt /usr/local/share/ca-certificates/kubernetes.crt
  2. sudo update-ca-certificates
  1. Updating certificates in /etc/ssl/certs...
  2. 1 added, 0 removed; done.
  3. Running hooks in /etc/ca-certificates/update.d....
  4. done.

Certificates API

You can use the certificates.k8s.io API to provision x509 certificates to use for authentication as documented here.