XTesting/kubespray/docs/cert_manager.md

   1 # Installation Guide
   2
   3 - [Installation Guide](#installation-guide)
   4   - [Kubernetes TLS Root CA Certificate/Key Secret](#kubernetes-tls-root-ca-certificatekey-secret)
   5   - [Securing Ingress Resources](#securing-ingress-resources)
   6     - [Create New TLS Root CA Certificate and Key](#create-new-tls-root-ca-certificate-and-key)
   7       - [Install Cloudflare PKI/TLS `cfssl` Toolkit.](#install-cloudflare-pkitls-cfssl-toolkit)
   8       - [Create Root Certificate Authority (CA) Configuration File](#create-root-certificate-authority-ca-configuration-file)
   9       - [Create Certficate Signing Request (CSR) Configuration File](#create-certficate-signing-request-csr-configuration-file)
  10       - [Create TLS Root CA Certificate and Key](#create-tls-root-ca-certificate-and-key)
  11
  12 Cert-Manager is a native Kubernetes certificate management controller. It can help with issuing certificates from a variety of sources, such as Let’s Encrypt, HashiCorp Vault, Venafi, a simple signing key pair, or self signed. It will ensure certificates are valid and up to date, and attempt to renew certificates at a configured time before expiry.
  13
  14 ## Kubernetes TLS Root CA Certificate/Key Secret
  15
  16 If you're planning to secure your ingress resources using TLS client certificates, you'll need to create and deploy the Kubernetes `ca-key-pair` secret consisting of the Root CA certificate and key to your K8s cluster.
  17
  18 For further information, read the official [Cert-Manager CA Configuration](https://cert-manager.io/docs/configuration/ca/) doc.
  19
  20 `cert-manager` can now be enabled by editing your K8s cluster addons inventory e.g. `inventory\sample\group_vars\k8s_cluster\addons.yml` and setting `cert_manager_enabled` to true.
  21
  22 ```ini
  23 # Cert manager deployment
  24 cert_manager_enabled: true
  25 ```
  26
  27 If you don't have a TLS Root CA certificate and key available, you can create these by following the steps outlined in section [Create New TLS Root CA Certificate and Key](#create-new-tls-root-ca-certificate-and-key) using the Cloudflare PKI/TLS `cfssl` toolkit. TLS Root CA certificates and keys can also be created using `ssh-keygen` and OpenSSL, if `cfssl` is not available.
  28
  29 ## Securing Ingress Resources
  30
  31 A common use-case for cert-manager is requesting TLS signed certificates to secure your ingress resources. This can be done by simply adding annotations to your Ingress resources and cert-manager will facilitate creating the Certificate resource for you. A small sub-component of cert-manager, ingress-shim, is responsible for this.
  32
  33 To enable the Nginx Ingress controller as part of your Kubespray deployment, simply edit your K8s cluster addons inventory e.g. `inventory\sample\group_vars\k8s_cluster\addons.yml` and set `ingress_nginx_enabled` to true.
  34
  35 ```ini
  36 # Nginx ingress controller deployment
  37 ingress_nginx_enabled: true
  38 ```
  39
  40 For example, if you're using the Nginx ingress controller, you can secure the Prometheus ingress by adding the annotation `cert-manager.io/cluster-issuer: ca-issuer` and the `spec.tls` section to the `Ingress` resource definition.
  41
  42 ```yaml
  43 apiVersion: networking.k8s.io/v1
  44 kind: Ingress
  45 metadata:
  46   name: prometheus-k8s
  47   namespace: monitoring
  48   labels:
  49     prometheus: k8s
  50   annotations:
  51     kubernetes.io/ingress.class: "nginx"
  52     cert-manager.io/cluster-issuer: ca-issuer
  53 spec:
  54   tls:
  55   - hosts:
  56     - prometheus.example.com
  57     secretName: prometheus-dashboard-certs
  58   rules:
  59   - host: prometheus.example.com
  60     http:
  61       paths:
  62       - path: /
  63         pathType: ImplementationSpecific
  64         backend:
  65           service:
  66             name: prometheus-k8s
  67             port:
  68               name: web
  69 ```
  70
  71 Once deployed to your K8s cluster, every 3 months cert-manager will automatically rotate the Prometheus `prometheus.example.com` TLS client certificate and key, and store these as the Kubernetes `prometheus-dashboard-certs` secret.
  72
  73 Please consult the official upstream documentation:
  74
  75 - [cert-manager Ingress Usage](https://cert-manager.io/v1.5-docs/usage/ingress/)
  76 - [cert-manager Ingress Tutorial](https://cert-manager.io/v1.5-docs/tutorials/acme/ingress/#step-3-assign-a-dns-name)
  77
  78 ### ACME
  79
  80 The ACME Issuer type represents a single account registered with the Automated Certificate Management Environment (ACME) Certificate Authority server. When you create a new ACME Issuer, cert-manager will generate a private key which is used to identify you with the ACME server.
  81
  82 Certificates issued by public ACME servers are typically trusted by client’s computers by default. This means that, for example, visiting a website that is backed by an ACME certificate issued for that URL, will be trusted by default by most client’s web browsers. ACME certificates are typically free.
  83
  84 - [ACME Configuration](https://cert-manager.io/v1.5-docs/configuration/acme/)
  85 - [ACME HTTP Validation](https://cert-manager.io/v1.5-docs/tutorials/acme/http-validation/)
  86   - [HTTP01 Challenges](https://cert-manager.io/v1.5-docs/configuration/acme/http01/)
  87 - [ACME DNS Validation](https://cert-manager.io/v1.5-docs/tutorials/acme/dns-validation/)
  88   - [DNS01 Challenges](https://cert-manager.io/v1.5-docs/configuration/acme/dns01/)
  89 - [ACME FAQ](https://cert-manager.io/v1.5-docs/faq/acme/)
  90
  91 #### ACME With An Internal Certificate Authority
  92
  93 The ACME Issuer with an internal certificate authority requires cert-manager to trust the certificate authority. This trust must be done at the cert-manager deployment level.
  94 To add a trusted certificate authority to cert-manager, add it's certificate to `group_vars/k8s-cluster/addons.yml`:
  95
  96 ```yaml
  97 cert_manager_trusted_internal_ca: |
  98   -----BEGIN CERTIFICATE-----
  99   [REPLACE with your CA certificate]
 100   -----END CERTIFICATE-----
 101 ```
 102
 103 Once the CA is trusted, you can define your issuer normally.
 104
 105 ### Create New TLS Root CA Certificate and Key
 106
 107 #### Install Cloudflare PKI/TLS `cfssl` Toolkit
 108
 109 e.g. For Ubuntu/Debian distributions, the toolkit is part of the `golang-cfssl` package.
 110
 111 ```shell
 112 sudo apt-get install -y golang-cfssl
 113 ```
 114
 115 #### Create Root Certificate Authority (CA) Configuration File
 116
 117 The default TLS certificate expiry time period is `8760h` which is 5 years from the date the certificate is created.
 118
 119 ```shell
 120 $ cat > ca-config.json <<EOF
 121 {
 122   "signing": {
 123     "default": {
 124       "expiry": "8760h"
 125     },
 126     "profiles": {
 127       "kubernetes": {
 128         "usages": ["signing", "key encipherment", "server auth", "client auth"],
 129         "expiry": "8760h"
 130       }
 131     }
 132   }
 133 }
 134 EOF
 135 ```
 136
 137 #### Create Certficate Signing Request (CSR) Configuration File
 138
 139 The TLS certificate `names` details can be updated to your own specific requirements.
 140
 141 ```shell
 142 $ cat > ca-csr.json <<EOF
 143 {
 144   "CN": "Kubernetes",
 145   "key": {
 146     "algo": "rsa",
 147     "size": 2048
 148   },
 149   "names": [
 150     {
 151       "C": "US",
 152       "L": "Portland",
 153       "O": "Kubernetes",
 154       "OU": "CA",
 155       "ST": "Oregon"
 156     }
 157   ]
 158 }
 159 EOF
 160 ```
 161
 162 #### Create TLS Root CA Certificate and Key
 163
 164 ```shell
 165 $ cfssl gencert -initca ca-csr.json | cfssljson -bare ca
 166 ca.pem
 167 ca-key.pem
 168 ```
 169
 170 Check the TLS Root CA certificate has the correct `Not Before` and `Not After` dates, and ensure it is indeed a valid Certificate Authority with the X509v3 extension `CA:TRUE`.
 171
 172 ```shell
 173 $ openssl x509 -text -noout -in ca.pem
 174
 175 Certificate:
 176     Data:
 177         Version: 3 (0x2)
 178         Serial Number:
 179             6a:d4:d8:48:7f:98:4f:54:68:9a:e1:73:02:fa:d0:41:79:25:08:49
 180         Signature Algorithm: sha256WithRSAEncryption
 181         Issuer: C = US, ST = Oregon, L = Portland, O = Kubernetes, OU = CA, CN = Kubernetes
 182         Validity
 183             Not Before: Jul 10 15:21:00 2020 GMT
 184             Not After : Jul  9 15:21:00 2025 GMT
 185         Subject: C = US, ST = Oregon, L = Portland, O = Kubernetes, OU = CA, CN = Kubernetes
 186         Subject Public Key Info:
 187         ...
 188         X509v3 extensions:
 189             X509v3 Key Usage: critical
 190                 Certificate Sign, CRL Sign
 191             X509v3 Basic Constraints: critical
 192                 CA:TRUE
 193             X509v3 Subject Key Identifier:
 194                 D4:38:B5:E2:26:49:5E:0D:E3:DC:D9:70:73:3B:C4:19:6A:43:4A:F2
 195                 ...
 196 ```