-
Notifications
You must be signed in to change notification settings - Fork 14.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
4 changed files
with
260 additions
and
75 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,256 @@ | ||
| --- | ||
| title: Certificates | ||
| --- | ||
|
|
||
| * TOC | ||
| {:toc} | ||
|
|
||
| ## Creating Certificates | ||
|
|
||
| When using client certificate authentication, you can generate certificates | ||
| using an existing deployment script or manually through `easyrsa` or `openssl.` | ||
|
|
||
| ### Using an Existing Deployment Script | ||
|
|
||
| **Using an existing deployment script** is implemented at | ||
| `cluster/saltbase/salt/generate-cert/make-ca-cert.sh`. | ||
|
|
||
| Execute this script with two parameters. The first is the IP address | ||
| of API server. The second is a list of subject alternate names in the form `IP:<ip-address> or DNS:<dns-name>`. | ||
|
|
||
| The script will generate three files: `ca.crt`, `server.crt`, and `server.key`. | ||
|
|
||
| Finally, add the following parameters into API server start parameters: | ||
|
|
||
| - `--client-ca-file=/srv/kubernetes/ca.crt` | ||
| - `--tls-cert-file=/srv/kubernetes/server.crt` | ||
| - `--tls-private-key-file=/srv/kubernetes/server.key` | ||
|
|
||
| ### easyrsa | ||
|
|
||
| **easyrsa** can be used to manually generate certificates for your cluster. | ||
|
|
||
| 1. Download, unpack, and initialize the patched version of easyrsa3. | ||
|
|
||
| curl -L -O https://storage.googleapis.com/kubernetes-release/easy-rsa/easy-rsa.tar.gz | ||
| tar xzf easy-rsa.tar.gz | ||
| cd easy-rsa-master/easyrsa3 | ||
| ./easyrsa init-pki | ||
| 1. Generate a CA. (`--batch` set automatic mode. `--req-cn` default CN to use.) | ||
|
|
||
| ./easyrsa --batch "--req-cn=${MASTER_IP}@`date +%s`" build-ca nopass | ||
| 1. 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 will expire. | ||
| The sample below also assume that you are using `cluster.local` as the default | ||
| DNS domain name. | ||
|
|
||
| ./easyrsa --subject-alt-name="IP:${MASTER_IP}"\ | ||
| "IP:${MASTER_CLUSTER_IP},"\ | ||
| "DNS:kubernetes,"\ | ||
| "DNS:kubernetes.default,"\ | ||
| "DNS:kubernetes.default.svc,"\ | ||
| "DNS:kubernetes.default.svc.cluster,"\ | ||
| "DNS:kubernetes.default.svc.cluster.local" \ | ||
| --days=10000 \ | ||
| build-server-full server nopass | ||
| 1. Copy `pki/ca.crt`, `pki/issued/server.crt`, and `pki/private/server.key` to your directory. | ||
| 1. Fill in and add the following parameters into the API server start parameters: | ||
|
|
||
| --client-ca-file=/yourdirectory/ca.crt | ||
| --tls-cert-file=/yourdirectory/server.crt | ||
| --tls-private-key-file=/yourdirectory/server.key | ||
|
|
||
| ### openssl | ||
|
|
||
| **openssl** can also be used to manually generate certificates for your cluster. | ||
|
|
||
| 1. Generate a ca.key with 2048bit: | ||
|
|
||
| openssl genrsa -out ca.key 2048 | ||
| 1. According to the ca.key generate a ca.crt (use -days to set the certificate effective time): | ||
|
|
||
| openssl req -x509 -new -nodes -key ca.key -subj "/CN=${MASTER_IP}" -days 10000 -out ca.crt | ||
| 1. Generate a server.key with 2048bit: | ||
|
|
||
| openssl genrsa -out server.key 2048 | ||
| 1. 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 assume that you are using `cluster.local` as the default | ||
| DNS domain name. | ||
|
|
||
| [ req ] | ||
| default_bits = 2048 | ||
| prompt = no | ||
| default_md = sha256 | ||
| req_extensions = req_ext | ||
| distinguished_name = dn | ||
| [ dn ] | ||
| C = <country> | ||
| ST = <state> | ||
| L = <city> | ||
| O = <organization> | ||
| OU = <organization unit> | ||
| CN = <MASTER_IP> | ||
| [ req_ext ] | ||
| subjectAltName = @alt_names | ||
| [ alt_names ] | ||
| DNS.1 = kubernetes | ||
| DNS.2 = kubernetes.default | ||
| DNS.3 = kubernetes.default.svc | ||
| DNS.4 = kubernetes.default.svc.cluster | ||
| DNS.5 = kubernetes.default.svc.cluster.local | ||
| IP.1 = <MASTER_IP> | ||
| IP.2 = <MASTER_CLUSTER_IP> | ||
| [ v3_ext ] | ||
| authorityKeyIdentifier=keyid,issuer:always | ||
| basicConstraints=CA:FALSE | ||
| keyUsage=keyEncipherment,dataEncipherment | ||
| extendedKeyUsage=serverAuth,clientAuth | ||
| subjectAltName=@alt_names | ||
| 1. Generate the certificate signing request based on the config file: | ||
|
|
||
| openssl req -new -key server.key -out server.csr -config csr.conf | ||
| 1. Generate the server certificate using the ca.key, ca.crt and server.csr: | ||
|
|
||
| openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 10000 | ||
| 1. View the certificate: | ||
|
|
||
| openssl x509 -noout -text -in ./server.crt | ||
|
|
||
| Finally, do not forget to fill out and add the same parameters into the API server start parameters. | ||
|
|
||
| ### cfssl | ||
|
|
||
| **cfssl** is another tool that can be used 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. | ||
|
|
||
| curl -LO https://pkg.cfssl.org/R1.2/cfssl_linux-amd64 -o cfssl | ||
| chmod +x cfssl | ||
| curl -LO https://pkg.cfssl.org/R1.2/cfssljson_linux-amd64 -o cfssljson | ||
| chmod +x cfssljson | ||
| curl -LO https://pkg.cfssl.org/R1.2/cfssl-certinfo_linux-amd64 -o cfssl-certinfo | ||
| chmod +x cfssl-certinfo | ||
| 1. Create a directory to hold the artifacts and initialize cfssl: | ||
|
|
||
| mkdir cert | ||
| cd cert | ||
| ../cfssl print-defaults config > config.json | ||
| ../cfssl print-defaults csr > csr.json | ||
| 1. Create a JSON config file for generating the CA file, for example, `ca-config.json`: | ||
|
|
||
| { | ||
| "signing": { | ||
| "default": { | ||
| "expiry": "8760h" | ||
| }, | ||
| "profiles": { | ||
| "kubernetes": { | ||
| "usages": [ | ||
| "signing", | ||
| "key encipherment", | ||
| "server auth", | ||
| "client auth", | ||
| ], | ||
| "expiry": "8760h" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| 1. Create a JSON config file for CA certificate signing request (CSR), for example, | ||
| `ca-csr.json`. Be sure the replace the values marked with angle brackets with | ||
| real values you want to use. | ||
|
|
||
| { | ||
| "CN": "kubernetes", | ||
| "key": { | ||
| "algo": "rsa", | ||
| "size": 2048 | ||
| }, | ||
| "names":[{ | ||
| "C": "<country>", | ||
| "ST": "<state>", | ||
| "L": "<city>", | ||
| "O": "<organization>", | ||
| "OU": "<organization unit>", | ||
| }] | ||
| } | ||
| 1. Generate CA key (`ca-key.pem`) and certificate (`ca.pem`): | ||
|
|
||
| ../cfssl gencert -initca ca-csr.json | ../cfssljson -bare ca | ||
| 1. Create a JSON config file for generating keys and certificates for the API | ||
| server as shown below. 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 assume that you are using `cluster.local` as the default | ||
| DNS domain name. | ||
|
|
||
| { | ||
| "CN": "kubernetes", | ||
| "hosts": [ | ||
| "127.0.0.1", | ||
| "<MASTER_IP>", | ||
| "<MASTER_CLUSTER_IP>", | ||
| "kubernetes", | ||
| "kubernetes.default", | ||
| "kubernetes.default.svc", | ||
| "kubernetes.default.svc.cluster", | ||
| "kubernetes.default.svc.cluster.local" | ||
| ], | ||
| "key": { | ||
| "algo": "rsa", | ||
| "size": 2048 | ||
| }, | ||
| "names": [{ | ||
| "C": "<country>", | ||
| "ST": "<state>", | ||
| "L": "<city>", | ||
| "O": "<organization>", | ||
| "OU": "<organization unit>" | ||
| }] | ||
| } | ||
| 1. Generate the key and certificate for the API server, which are by default | ||
| saved into file `server-key.pem` and `server.pem` respectively: | ||
|
|
||
| ../cfssl gencert -ca=ca.pem -ca-key=ca-key.pem \ | ||
| --config=ca-config.json -profile=kubernetes \ | ||
| server-csr.json | ../cfssljson -bare server | ||
|
|
||
|
|
||
| ## Distributing Self-Signed CA Certificate | ||
|
|
||
| When using self-signed CA certificates rather than one signed by public third-party | ||
| CA authorities like VeriSign, a client node may refuse to recognize it as a valid | ||
| CA certificate. For a non-production deployment or one that runs behind a company | ||
| firewall, you can distribute the CA certificate to all clients and refresh the | ||
| local list for valid certificates. | ||
|
|
||
| On each client, perform the following operations: | ||
|
|
||
| ```bash | ||
| $ sudo cp ca.crt /usr/local/share/ca-certificates/kubernetes.crt | ||
| $ sudo update-ca-certificates | ||
| pdating certificates in /etc/ssl/certs... | ||
| 1 added, 0 removed; done. | ||
| Running hooks in /etc/ca-certificates/update.d.... | ||
| done. | ||
| ``` | ||
|
|
||
| ## Certificates API | ||
|
|
||
| You can use the `certificates.k8s.io` API to provision | ||
| x509 certificates to use for authentication as documented | ||
| [here](/docs/tasks/tls/managing-tls-in-a-cluster). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters