From 7e452622736bd1c2cd3eff021429e69cbbd0fa65 Mon Sep 17 00:00:00 2001 From: Jakub Scholz Date: Thu, 7 Feb 2019 22:29:18 +0100 Subject: [PATCH 1/4] Try to improve the docs about custom CAs --- ...c-installing-your-own-ca-certificates.adoc | 59 +++++++++++-------- 1 file changed, 34 insertions(+), 25 deletions(-) diff --git a/documentation/book/proc-installing-your-own-ca-certificates.adoc b/documentation/book/proc-installing-your-own-ca-certificates.adoc index 19e11d7854..e061642cce 100644 --- a/documentation/book/proc-installing-your-own-ca-certificates.adoc +++ b/documentation/book/proc-installing-your-own-ca-certificates.adoc @@ -10,12 +10,17 @@ This procedure describes how to install your own CA certificates and private key .Prerequisites * The Cluster Operator is running. -* A `Kafka` resource within {ProductPlatformName} -* Your own X.509 certificates and keys in PEM format for the cluster CA or clients CA. For example, these could be generated by `openssl`, using a command such as: +* A Kafka cluster is not yet deployed +* Your own X.509 certificates and keys in PEM format for the cluster CA or clients CA. + -[source,shell,subs="+quotes"] -openssl req -x509 -new -days __ --nodes -out ca.crt -keyout ca.key - +** If you want to use cluster or clients CA which is not a Root CA, you have to include the whole chain in the certificate file. +The chain should be in the following order: ++ +1. The cluster or clients CA +2. One or more intermediate CAs +3. The root CA ++ +** All CAs in the chain should be marked as CA in the Basic Constraints extension. .Procedure @@ -29,11 +34,7 @@ On {KubernetesName}, run the following commands: # Delete any existing secret (ignore "Not Exists" errors) kubectl delete secret __ # Create and label the new one -kubectl create secret generic __ \ - --from-file=ca.crt=__ \ - && kubectl label secret __ \ - strimzi.io/kind=Kafka \ - strimzi.io/cluster=__ +kubectl create secret generic __ --from-file=ca.crt=__ ---- endif::Kubernetes[] + @@ -44,11 +45,7 @@ On {OpenShiftName}, run the following commands: # Delete any existing secret (ignore "Not Exists" errors) oc delete secret __ # Create the new one -oc create secret generic __ \ - --from-file=ca.crt=__ \ - && oc label secret __ \ - strimzi.io/kind=Kafka \ - strimzi.io/cluster=__ +oc create secret generic __ --from-file=ca.crt=__ ---- . Put your CA key in the corresponding `Secret` (`__-cluster-ca` for the cluster CA or `__-clients-ca` for the clients CA) @@ -61,11 +58,7 @@ On {KubernetesName}, run the following commands: # Delete the existing secret kubectl delete secret __ # Create the new one -kubectl create secret generic __ \ - --from-file=ca.key=__ \\ - && kubectl label secret __ \ - strimzi.io/kind=Kafka \ - strimzi.io/cluster=__ +kubectl create secret generic __ --from-file=ca.key=__ ---- endif::Kubernetes[] + @@ -76,11 +69,27 @@ On {OpenShiftName}, run the following commands: # Delete the existing secret oc delete secret __ # Create the new one -oc create secret generic __ \ - --from-file=ca.key=__ \ - && oc label secret __ \ - strimzi.io/kind=Kafka \ - strimzi.io/cluster=__ +oc create secret generic __ --from-file=ca.key=__ +---- + +. Label both `Secrets` with labels `strimzi.io/kind=Kafka` and `strimzi.io/cluster=__`: +ifdef::Kubernetes[] ++ +On {KubernetesName}, run the following commands: ++ +[source,shell,subs="+quotes"] +---- +kubectl label secret __ strimzi.io/kind=Kafka strimzi.io/cluster=__ +kubectl label secret __ strimzi.io/kind=Kafka strimzi.io/cluster=__ +---- +endif::Kubernetes[] ++ +On {OpenShiftName}, run the following commands: ++ +[source,shell,subs="+quotes"] +---- +oc label secret __ strimzi.io/kind=Kafka strimzi.io/cluster=__ +oc label secret __ strimzi.io/kind=Kafka strimzi.io/cluster=__ ---- . Create the `Kafka` resource for your cluster, configuring either the `Kafka.spec.clusterCa` or the `Kafka.spec.clientsCa` object to _not_ use generated CAs: From 4a3f5bd450a36ef49a2293ad722b0ccb3da6a15e Mon Sep 17 00:00:00 2001 From: Jakub Scholz Date: Fri, 8 Feb 2019 11:09:35 +0100 Subject: [PATCH 2/4] Review comments I --- .../book/proc-installing-your-own-ca-certificates.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/book/proc-installing-your-own-ca-certificates.adoc b/documentation/book/proc-installing-your-own-ca-certificates.adoc index e061642cce..81042e0721 100644 --- a/documentation/book/proc-installing-your-own-ca-certificates.adoc +++ b/documentation/book/proc-installing-your-own-ca-certificates.adoc @@ -20,7 +20,7 @@ The chain should be in the following order: 2. One or more intermediate CAs 3. The root CA + -** All CAs in the chain should be marked as CA in the Basic Constraints extension. +** All CAs in the chain should be configured as a CA in the X509v3 Basic Constraints. .Procedure From 490a7ea0d2dd38e6cf87c6fcfec305289ce47e09 Mon Sep 17 00:00:00 2001 From: "Nicole C. Baratta" Date: Fri, 8 Feb 2019 14:46:38 +0100 Subject: [PATCH 3/4] Update documentation/book/proc-installing-your-own-ca-certificates.adoc Co-Authored-By: scholzj --- .../book/proc-installing-your-own-ca-certificates.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/book/proc-installing-your-own-ca-certificates.adoc b/documentation/book/proc-installing-your-own-ca-certificates.adoc index 81042e0721..79169036aa 100644 --- a/documentation/book/proc-installing-your-own-ca-certificates.adoc +++ b/documentation/book/proc-installing-your-own-ca-certificates.adoc @@ -10,7 +10,7 @@ This procedure describes how to install your own CA certificates and private key .Prerequisites * The Cluster Operator is running. -* A Kafka cluster is not yet deployed +* A Kafka cluster is not yet deployed. * Your own X.509 certificates and keys in PEM format for the cluster CA or clients CA. + ** If you want to use cluster or clients CA which is not a Root CA, you have to include the whole chain in the certificate file. From d91e4f6a62bf26240e13f780bcd50bf58d5894ba Mon Sep 17 00:00:00 2001 From: "Nicole C. Baratta" Date: Fri, 8 Feb 2019 14:47:20 +0100 Subject: [PATCH 4/4] Update documentation/book/proc-installing-your-own-ca-certificates.adoc Co-Authored-By: scholzj --- .../book/proc-installing-your-own-ca-certificates.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/book/proc-installing-your-own-ca-certificates.adoc b/documentation/book/proc-installing-your-own-ca-certificates.adoc index 79169036aa..57698f9147 100644 --- a/documentation/book/proc-installing-your-own-ca-certificates.adoc +++ b/documentation/book/proc-installing-your-own-ca-certificates.adoc @@ -13,7 +13,7 @@ This procedure describes how to install your own CA certificates and private key * A Kafka cluster is not yet deployed. * Your own X.509 certificates and keys in PEM format for the cluster CA or clients CA. + -** If you want to use cluster or clients CA which is not a Root CA, you have to include the whole chain in the certificate file. +** If you want to use a cluster or clients CA which is not a Root CA, you have to include the whole chain in the certificate file. The chain should be in the following order: + 1. The cluster or clients CA