// Module included in the following assemblies:
//
// assembly-security.adoc

[id='installing-your-own-ca-certificates-{context}']
= Installing your own CA certificates

[role="_abstract"]
This procedure describes how to install your own CA certificates and keys instead of using the CA certificates and private keys generated by the Cluster Operator.

The Cluster Operator automatically generates and renews the following secrets:

`_CLUSTER-NAME_-cluster-ca`:: The cluster secret that contains the private key for the cluster CA.
`_CLUSTER-NAME_-cluster-ca-cert`:: The cluster secret that contains a cluster CA certificate. The certificate contains a public key to validate the identity of Kafka brokers.
`_CLUSTER-NAME_-clients-ca`:: The client secret that contains the private key for the client CA.
`_CLUSTER-NAME_-clients-ca-cert`:: The client secret that contains a client CA certificate. The certificate contains a public key to validate the identity of clients accessing the Kafka brokers.

Strimzi uses these secrets by default.

This procedure describes the steps to replace the secrets to use your own cluster or client CA certificates.

.Prerequisites

* The Cluster Operator is running.
* 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 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
2. One or more intermediate CAs
3. The root CA
+
** All CAs in the chain should be configured using the X509v3 Basic Constraints extension. Basic Constraints limit the path length of a certificate chain.
* The OpenSSL TLS management tool for converting certificates.

.Before you begin
The Cluster Operator generates the following files for the `_CLUSTER-NAME_-cluster-ca-cert` secret:

* `ca.crt` cluster certificate in PEM format
* `ca.p12` cluster certificate in PKCS #12 format
* `ca.password` to access the PKCS #12 file

Some applications cannot use PEM certificates and support only PKCS #12 certificates.
You can also add your own cluster certificate in PKCS #12 format.

If you don't have a cluster certificate in PKCS #12 format, use the OpenSSL TLS management tool to generate one from your `ca.crt` file.

.Example certificate generation command
[source,shell,subs="+quotes"]
openssl pkcs12 -export -in ca.crt --nokeys -out ca.p12 -password pass:__P12-PASSWORD__ -caname ca.crt

Replace _P12-PASSWORD_ with your own password.

You can do the same for the `_CLUSTER-NAME_-clients-ca-cert` secret, which also contains certificates in PEM and PKCS #12 format by default.

.Procedure

. Replace the CA certificate generated by the Cluster Operator.

.. Delete the existing secret.
+
[source,shell,subs="+quotes"]
kubectl delete secret _CA-CERTIFICATE-SECRET_
+
_CA-CERTIFICATE-SECRET_ is the name of the `Secret`:
+
--
* `_CLUSTER-NAME_-cluster-ca-cert` for the cluster CA certificate
* `_CLUSTER-NAME_-clients-ca-cert` for the clients CA certificate
--
+
Replace _CLUSTER-NAME_ with the name of your Kafka cluster.
+
Ignore any "Not Exists" errors.

.. Create the new secret.
+
.Client secret creation with a certificate in PEM format only
[source,shell,subs="+quotes"]
kubectl create secret generic _CLUSTER-NAME_-clients-ca-cert --from-file=ca.crt=ca.crt
+
.Cluster secret creation with certificates in PEM and PKCS #12 format
[source,shell,subs="+quotes"]
----
kubectl create secret generic _CLUSTER-NAME_-cluster-ca-cert \
  --from-file=ca.crt=ca.crt \
  --from-file=ca.p12=ca.p12 \
  --from-literal=ca.password=_P12-PASSWORD_
----

. Replace the private key generated by the Cluster Operator.
+
.. Delete the existing secret.
+
[source,shell,subs="+quotes"]
kubectl delete secret _CA-KEY-SECRET_
+
_CA-KEY-SECRET_ is the name of CA key:
+
* `_CLUSTER-NAME_-cluster-ca` for the cluster CA key
* `_CLUSTER-NAME_-clients-ca` for the clients CA key

.. Create the new secret.
+
[source,shell,subs="+quotes"]
kubectl create secret generic _CA-KEY-SECRET_ --from-file=ca.key=ca.key

. Label the secrets.
+
[source,shell,subs="+quotes"]
----
kubectl label secret _CA-CERTIFICATE-SECRET_ strimzi.io/kind=Kafka strimzi.io/cluster=_CLUSTER-NAME_
----
+
[source,shell,subs="+quotes"]
----
kubectl label secret _CA-KEY-SECRET_ strimzi.io/kind=Kafka strimzi.io/cluster=_CLUSTER-NAME_
----
+
* Label `strimzi.io/kind=Kafka` identifies the Kafka custom resource.
* Label `strimzi.io/cluster=_CLUSTER-NAME_` identifies the Kafka cluster.

. Annotate the secrets
+
[source,shell,subs="+quotes"]
----
kubectl annotate secret _CA-CERTIFICATE-SECRET_ strimzi.io/ca-cert-generation=_CA-CERTIFICATE-GENERATION_
----
+
[source,shell,subs="+quotes"]
----
kubectl annotate secret _CA-KEY-SECRET_ strimzi.io/ca-key-generation=_CA-KEY-GENERATION_
----
+
* Annotation `strimzi.io/ca-cert-generation=_CA-CERTIFICATE-GENERATION_` defines the generation of a new CA certificate.
* Annotation `strimzi.io/ca-key-generation=_CA-KEY-GENERATION_` defines the generation of a new CA key.
+
If you are replacing CA certificates automatically generated by the Cluster Operator, use the next higher incremental value from the existing annotation and follow the xref:proc-replacing-your-own-private-keys-{context}[replacing CA keys procedure].
If there are no CA certificates automatically generated by the Cluster Operator, start from 0 (zero) as the incremental value (`strimzi.io/ca-cert-generation=0`) for your own CA certificate. Set a higher incremental value when you renew the certificates.

. Create the `Kafka` resource for your cluster, configuring either the `Kafka.spec.clusterCa` or the `Kafka.spec.clientsCa` object to _not_ use generated CAs.
+
.Example fragment `Kafka` resource configuring the cluster CA to use certificates you supply for yourself
[source,yaml,subs="attributes"]
----
kind: Kafka
version: {KafkaApiVersion}
spec:
  # ...
  clusterCa:
    generateCertificateAuthority: false
----

[role="_additional-resources"]
.Additional resources

* To renew CA certificates you have previously installed, see xref:renewing-your-own-ca-certificates-{context}[].
* To replace the private keys of CA certificates you have previously installed, see xref:proc-replacing-your-own-private-keys-{context}[].
* xref:proc-installing-certs-per-listener-{context}[].
