Add instructions for Individual and Wildcard certificate (#933)

* Describes individual and wildcard TLS certificate Signed-off-by: JenTing Hsiao <jenting.hsiao@suse.com> * Updated wording for certificates explanation Co-authored-by: Markus Napp <mnapp@suse.com>
SUSE · Jul 23, 2020 · 81ee343 · 81ee343
1 parent 9d13363
commit 81ee343
Showing 1 changed file with 95 additions and 97 deletions.
diff --git a/adoc/admin-monitoring-stack.adoc b/adoc/admin-monitoring-stack.adoc
@@ -40,48 +40,6 @@ Grafana is an open-source system for querying, analysing and visualizing metrics
 +
 Please refer to <<nginx-ingress>> on how to configure ingress in your cluster. Deploying NGINX Ingress Controller also allows us to provide TLS termination to our services and to provide basic authentication to the Prometheus Expression browser/API.
 
-. Create DNS entries
-+
-.Subdomains VS. Subpaths
-[IMPORTANT]
-====
-There will be two different ways of using ingress for accessing the monitoring system.
-One will be using `subdomains` such as `+prometheus.example.com+`, `+prometheus-alertmanager.example.com+`, and `+grafana.example.com+`.
-Another deployment will be using `subpaths` for accessing monitoring system such as `example.com/prometheus`, `example.com/alertmanager`, and `example.com/grafana`.
-====
-+
-In this example, we will use a master node with IP `10.86.4.158` in the case of NodePort service of the Ingress Controller.
-+
-.. Installation example of `subdomains`
-+
-NOTE: You should configure proper DNS names in any production environment.
-These values are only for example purposes.
-+
-----
-monitoring.example.com                      IN  A       10.86.4.158
-prometheus.example.com                      IN  CNAME   monitoring.example.com
-prometheus-alertmanager.example.com         IN  CNAME   monitoring.example.com
-grafana.example.com                         IN  CNAME   monitoring.example.com
-----
-+
-Or add this entry to `/etc/hosts`
-+
-----
-10.86.4.158 prometheus.example.com prometheus-alertmanager.example.com grafana.example.com
-----
-+
-.. Installation example of `subpaths`
-+
-----
-example.com                      IN  A       10.86.4.158
-----
-+
-Or add this entry to `/etc/hosts`
-+
-----
-10.86.4.158 example.com
-----
-
 . Monitoring namespace
 +
 We will deploy our monitoring stack in its own namespace and therefore create one.
@@ -126,55 +84,6 @@ Create secret in {kube} cluster
 kubectl create secret generic -n monitoring prometheus-basic-auth --from-file=auth
 ----
 
-. TLS
-+
-You must configure your certificates for the components as secrets in the {kube} cluster.
-Get certificates from your local certificate authority.
-In this example we are using a single certificate shared by the components `prometheus.example.com`, `prometheus-alertmanager.example.com` and `grafana.example.com`.
-+
-.Create Individual Secrets For Components
-[NOTE]
-====
-Should you choose to secure each service with an individual certificate, you must repeat the step below for each component and adjust the name for the individual secret each time.
-
-In this example the name is `monitoring-tls`.
-====
-+
-.Note Down Secret Names For Configuration
-[IMPORTANT]
-====
-You need to make sure the TLS secret you created came from a certificate that contains a Common Name (CN),
-also known as a Fully Qualified Domain Name (FQDN) for example.com.
-
-Please note down the names of the secrets you have created.
-Later configuration steps require secret names to be specified.
-====
-+
-.. Trusted Certificates
-+
-Please refer to <<trusted-server-certificate>> on how to sign the trusted certificate.
-The `server.conf` for DNS.1 is `prometheus.example.com`, DNS.2 is `prometheus-alertmanager.example.com` and DNS.3 `grafana.example.com`.
-+
-Then, import your trusted certificate into the {kube} cluster.
-In this example, trusted certificates are `monitoring.key` and `monitoring.crt`.
-+
-.. Self-signed Certificates (optional)
-+
-Please refer to <<self-signed-server-certificate>> on how to sign the self-signed certificate.
-The `server.conf` for DNS.1 is `+prometheus.example.com+`, DNS.2 is `+prometheus-alertmanager.example.com+` and DNS.3 `+grafana.example.com+`.
-+
-Then, import your self-signed certificate into the {kube} cluster.
-In this example, self-signed certificates are `monitoring.key` and `monitoring.crt`.
-+
-.. Add TLS secret to {kube} cluster from trusted Certificates or self-signed Certificates
-+
-[source,bash]
-----
-kubectl create -n monitoring secret tls monitoring-tls  \
---key  ./monitoring.key \
---cert ./monitoring.crt
-----
-
 == Installation
 
 There will be two different ways of using ingress for accessing the monitoring system.
@@ -186,10 +95,7 @@ There will be two different ways of using ingress for accessing the monitoring s
 [#installation-for-subdomains]
 === Installation For Subdomains
 
-[NOTE]
-====
 This installation example shows how to install and configure Prometheus and Grafana using subdomains such as `prometheus.example.com`, `prometheus-alertmanager.example.com`, and `grafana.example.com`.
-====
 
 [IMPORTANT]
 ====
@@ -198,6 +104,63 @@ In order to provide additional security by using TLS certificates, please make s
 If you don't need TLS, you may use other methods for exposing these web services as native `LBaaS` in OpenStack, haproxy service or k8s native methods as port-forwarding or NodePort but this is out of scope of this document.
 ====
 
+=== Create DNS entries
+
+In this example, we will use a master node with IP `10.86.4.158` in the case of NodePort service of the Ingress Controller.
+
+[NOTE]
+====
+You should configure proper DNS names in any production environment.
+These values are only for example purposes.
+====
+
+. Configure the DNS server
++
+----
+monitoring.example.com                      IN  A       10.86.4.158
+prometheus.example.com                      IN  CNAME   monitoring.example.com
+prometheus-alertmanager.example.com         IN  CNAME   monitoring.example.com
+grafana.example.com                         IN  CNAME   monitoring.example.com
+----
+
+. Configure the management workstation `/etc/hosts` (optional)
++
+----
+10.86.4.158 prometheus.example.com prometheus-alertmanager.example.com grafana.example.com
+----
+
+==== TLS Certificate
+
+You must configure your certificates for the components as secrets in the {kube} cluster.
+Get certificates from your certificate authority.
+
+. Individual certificate
++
+Single-name TLS certificate protects a single sub-domain, and it means each sub-domain owns its private key. From the security perspective, it is recommended to use individual certificates. However, you have to manage the private key and the certificate rotation separately.
++
+.Note Down Secret Names For Configuration
+[IMPORTANT]
+====
+When you choose to secure each service with an individual certificate, you must repeat the step below for each component and adjust the name for the individual secret each time. Please note down the names of the secrets you have created.
+
+In this example, the secret name is `monitoring-tls`.
+====
+
+. Wildcard certificate
++
+Wildcard TLS allows you to secure multiple sub-domains with one certificate and it means multiple sub-domains share the same private key. You can then add more sub-domains without having to redeploy the certificate and moreover, save the additional certificate costs.
+
+Refer to <<trusted-server-certificate>> on how to sign the trusted certificate or refer to <<self-signed-server-certificate>> on how to sign the self-signed certificate. The `server.conf` for DNS.1 is `+prometheus.example.com+` and `+prometheus-alertmanager.example.com+` `+grafana.example.com+` for individual certificates separately. The `server.conf` for DNS.1 is `+*.example.com+` for a wildcard certificate.
+
+Then, import your certificate and key pair into the {kube} cluster secret name `monitoring-tls`. In this example, the certificate and key are `monitoring.crt` and `monitoring.key`.
+
+[source,bash]
+----
+kubectl create -n monitoring secret tls monitoring-tls  \
+--key  ./monitoring.key \
+--cert ./monitoring.crt
+----
+
 ==== Prometheus
 
 . Create a configuration file `prometheus-config-values.yaml`
@@ -780,16 +743,51 @@ kubectl apply -f grafana-dashboards-caasp-cluster.yaml
 [#installation-for-subpaths]
 === Installation For Subpaths
 
-[NOTE]
-====
 This installation example shows how to install and configure Prometheus and Grafana using subpaths such as example.com/prometheus, example.com/alertmanager, and example.com/grafana.
-====
 
 [IMPORTANT]
 ====
 Overlapped instructions from subdomains will be omitted. Refer to the instruction from subdomains.
 ====
 
+=== Create DNS entries
+
+In this example, we will use a master node with IP `10.86.4.158` in the case of NodePort service of the Ingress Controller.
+
+[NOTE]
+====
+You should configure proper DNS names in any production environment.
+These values are only for example purposes.
+====
+
+. Configure the DNS server
++
+----
+example.com                      IN  A       10.86.4.158
+----
+
+. Configure the management workstation `/etc/hosts` (optional)
++
+----
+10.86.4.158 example.com
+----
+
+==== TLS Certificate
+
+You must configure your certificates for the components as secrets in the {kube} cluster.
+Get certificates from your certificate authority.
+
+Refer to <<trusted-server-certificate>> on how to sign the trusted certificate or refer to <<self-signed-server-certificate>> on how to sign the self-signed certificate. The `server.conf` for DNS.1 is `+example.com+`.
+
+Then, import your certificate and key pair into the {kube} cluster secret name `monitoring-tls`. In this example, the certificate and key are `monitoring.crt` and `monitoring.key`.
+
+[source,bash]
+----
+kubectl create -n monitoring secret tls monitoring-tls  \
+--key  ./monitoring.key \
+--cert ./monitoring.crt
+----
+
 ==== Prometheus
 
 . Create a configuration file `prometheus-config-values.yaml`