Deploy Confluent for Kubernetes¶

The Confluent for Kubernetes (CFK) bundle contains Helm charts, templates, and scripts for deploying Confluent Platform to your Kubernetes cluster.

You can deploy CFK using one of the following methods:

Deploy Confluent for Kubernetes directly from Confluent’s Helm repo
Deploy Confluent for Kubernetes by downloading the Helm bundle

You can install the optional Confluent plugin for interacting with CFK using one of the following methods:

Install Confluent plugin from the CFK bundle
Install Confluent plugin using Krew

Deploy Confluent for Kubernetes from Confluent’s Helm repo¶

Add a Helm repo:

helm repo add confluentinc https://packages.confluent.io/helm

helm repo update

Install CFK using the default configuration:

helm upgrade --install confluent-operator \
  confluentinc/confluent-for-kubernetes \
  --namespace <namespace>

Deploy Confluent for Kubernetes using the download bundle¶

Download the CFK bundle using the following command, and unpack the downloaded bundle:

curl -O https://packages.confluent.io/bundle/cfk/confluent-for-kubernetes-2.3.4.tar.gz

From the helm sub-directory of where you downloaded the CFK bundle, install CFK:

helm upgrade --install confluent-operator \
  ./confluent-for-kubernetes \
  --namespace <namespace>

Deploy customized Confluent for Kubernetes¶

You can customize the configuration of CFK when you install or update it. Since CFK is installed and updated with helm, the methods for customing CFK configuration are as per helm, i.e. you can:

set configuration values in a YAML file which you can pass to helm commands via the --values or -f flag
set configuration values as key=value pairs directly in your helm commands via the --set, --set-string, and --set-file flags
combine the two above approaches, where you may set some configuration in a values file and others on the command line with the --set flags.

Refer to Helm documentation for more details on these flags.

To deploy customized Confluent for Kubernetes using the CFK values.yaml file:

Find the default values.yaml file:
- If you are using Helm repo to deploy CFK, pull the CFK Chart:
```
mkdir -p <CFK-home>

helm pull confluentinc/confluent-for-kubernetes \
  --untar \
  --untardir=<CFK-home> \
  --namespace <namespace>
```
  The values.yaml file is in the <CFK-home>/confluent-for-kubernetes directory.
- If you are using a download bundle to deploy CFK, the values.yaml file is in the helm/confluent-for-kubernetes directory under where you downloaded the bundle.
Create a copy of the values.yaml file to customize CFK configuration. Do not edit the default values.yaml file. Save your copy to any file location; we will refer to this location as <path-to-values-file>.

Install CFK using the customized configuration:

helm upgrade --install confluent-operator \
  confluentinc/confluent-for-kubernetes \
  --values <path-to-values-file> \
  --namespace <namespace>

To deploy customized Confluent for Kubernetes with the helm upgrade command:

Specify the configuration options using the --set flag:

helm upgrade --install confluent-operator \
  confluentinc/confluent-for-kubernetes \
  --set <setting1>=<value1> \
  --set <setting2>=<value2> \
  ...
  --namespace <namespace>

Configure CFK to manage Confluent Platform components across all namespaces¶

By default, CFK only deploys and manages Confluent Platform component clusters and resources in the same Kubernetes namespace where CFK itself is deployed. To enable CFK to manage Confluent Platform resources across all namespaces, set the namespaced configuration property to false in the install command:

helm upgrade --install confluent-operator \
  confluentinc/confluent-for-kubernetes \
  --set namespaced=false \
  --namespace <namespace>

Alternatively, you can update the values.yaml file as described above, and set the following property:

namespaced: false

Deploy Confluent for Kubernetes without creating roles and role bindings¶

By default, when you deploy CFK via helm, the helm installation will also create the Kubernetes role and role binding (or cluster role and cluster role binding) needed for CFK to function at the same time for convenience. However, as the user responsible for deploying CFK, you may not have the ability to manage Kubernetes RBAC permissions, so your helm installation would fail. The responsibility for managing Kubernetes RBAC permissions may only belong to your Kubernetes cluster administrator. In this situation, your Kubernetes cluster admin must have already created the requisite RBAC resources in advance (see Prepare Kubernetes Cluster for Confluent Platform). To instruct helm to skip trying to create RBAC resources again, add --set rbac=false to the install command:

helm upgrade --install confluent-operator \
  confluentinc/confluent-for-kubernetes \
  --set rbac=false \
  --namespace <namespace>

Alternatively, you can update the values.yaml file as described above, and set the following property:

rbac: false

Deploy Confluent for Kubernetes with custom service account¶

To provide a custom service account to manange CFK, add --set serviceAccount.create=false --set serviceAccount.name=<name> to the install command:

helm upgrade --install confluent-operator \
  confluentinc/confluent-for-kubernetes \
  --set serviceAccount.create=false \
  --set serviceAccount.name=<service-account-name> \
  --namespace <namespace>

Alternatively, you can update the values.yaml file as described above, and set the following property:

serviceAccount:
  create: false
  name: <service-account-name>

Note that if you use a custom service account and set rbac=false, meaning that the roles and role bindings were pre-created by your Kubernetes cluster admin, then you must ensure that your <service-account-name>> matches the subject name in the pre-created role binding.

Deploy Confluent for Kubernetes with cluster object deletion protection¶

Note

This feature is in Early Access and should be used only in development environments. The feature is not intended for production environments.

Confluent for Kubernetes (CFK) provides validating admission webhooks for deletion events of the Confluent Platform clusters.

CFK webhooks are disabled by default in this release of CFK.

CFK provides the following webhooks:

Webhook to prevent component deletion when its persistent volume (PV) reclaim policy is set to Delete

This webhook blocks deletion requests on CRs with PVs in ReclaimPolicy: Delete. Without this prevention, a CR deletion will result in the deletion of those PVs and data loss.

This webhook only applies to the components that have persistent volumes, namely, ZooKeeper, Kafka, ksqlDB, and Control Center.
Webhook to prevent CFK StatefulSet deletion

The proper way to delete Confluent Platform resources is to delete the component custom resource (CR) as CFK watches those deletion events and properly cleans everything up. Deletion of StatefulSets can result in unintended PV deletion and data loss.

This webhook blocks delete requests on CFK StatefulSets.

Prerequisites before deploying CFK¶

Before you deploy CFK with webhooks enabled, you need to create TLS certificates and add a label to your Kubernetes namespaces.

TLS certificates¶

To enable webhooks, you must provide TLS certificates to be used for secure communication between the webhook server and the Kubernetes API server:

Create signed TLS keys and certificates in the format as described in Provide TLS keys and certificates in PEM format. Provide the TLS Group 1 (ca.pem, server.pem, server-key.pem) or Group 3 (tls.crt, tls.key, ca.crt) certificates.

The certificate must have the Subject Alternative Name (SAN) of the form, confluent-operator.<namespace>.svc, which is the cluster-internal DNS name for the service in the namespace the CFK pod is getting deployed into.
Provide the above certificates to the CFK pod using one of the following:
- Add the certificates to a Kubernetes secret and put them in the namespace that the CFK pod is getting deployed in.
- Add the certificates in Vault. All certificates must be in the same directory.

Kubernetes metadata label¶

When deploying CFK on the Kubernetes version lower than 1.21, set the kubernetes.io/metadata.name label on all namespaces the webhooks should validate requests on.

This label is automatically set in Kubernetes 1.21 or later. For reference, see Automatic labeling.

Check labels on namespace Confluent Platform is getting deployed in:

kubectl get namespace <namespace> --show-labels

An example output:

NAME       STATUS   AGE   LABELS
operator   Active   48d   <none>

Set the kubernetes.io/metadata.name label to the name of namespace itself:

kubectl label namespace <namespace> kubernetes.io/metadata.name=<namespace>

Validate.

kubectl get namespace <namespace> --show-labels

Following is an sample output:

NAME       STATUS   AGE   LABELS
operator   Active   48d   kubernetes.io/metadata.name=operator

Enable webhooks and deploy CFK¶

Use the helm value to enable or disable the validating webhooks.

Update the values.yaml file as described above, and set the following properties:

webhooks:
  enabled: true                  --- [1]
  tls:                           --- [2]
    secretRef:
    directoryPathInContainer:

[1] Required to enable CFK webhooks.
[2] Specify secretRef or directoryPathInContainer value that you created in TLS certificates.

Disable webhooks¶

After you deploy CFK with webhooks enabled, you can disable CFK webhooks at the namespace or component level by applying the following labels for a namespace or for a component CR.

Disable all CFK validation webhooks:

confluent-operator.webhooks.platform.confluent.io/disable: "true"

Disable the webhook that validates StatefulSet deletion:
```
confluent-operator.webhooks.platform.confluent.io/allow-statefulset-deletion: "true"
```
This label is only applied at the CR level.

Disable the webhook that validates CR deletion for PV reclaim policy:

confluent-operator.webhooks.platform.confluent.io/allow-pv-deletion: "true"

For example, to allow Kafka CR deletion when PVs are in the Delete mode, apply the following label:

kubectl -n operator label kafka kafka \
  confluent-operator.webhooks.platform.confluent.io/allow-pv-deletion="true"

Install Confluent plugin¶

The Confluent for Kubernetes (CFK) bundle contains a Confluent plugin for interacting with Confluent for Kubernetes. It is supported for three environments: Linux, Windows, and Darwin. See Confluent plugin for more information about the tool.

If you deployed CFK using the Helm repo, download and unpack the CFK bundle as described in the first step in Deploy Confluent for Kubernetes using the download bundle.

If you used Deploy Confluent for Kubernetes using the download bundle, skip this step.
Unpack the kubectl plugin that matches your client environment, Linux, Windows or Mac OS (Darwin), into your client environment local executables directory. On Mac OS and Linux, this would be /usr/local/bin/. This will allow the standard CLI kubectl to find the plugin.
```
tar -xvf kubectl-plugin/kubectl-confluent-<environment>-amd64.tar.gz \
   -C <local directory for the plugin>
```
For example, on Mac OS:
```
tar -xvf kubectl-plugin/kubectl-confluent-darwin-amd64.tar.gz \
   -C /usr/local/bin/
```

Install Confluent plugin using Krew¶

Krew is the plugin manager for kubectl. Take the following steps if you want to use Krew to install the Confluent plugin.

Install Krew as described in Krew User Guide.
If you deployed CFK using the Helm repo, download and unpack the CFK bundle as described in the first step in Deploy Confluent for Kubernetes using the download bundle.

If you used Deploy Confluent for Kubernetes using the download bundle, skip this step.
Go to the kubectl-plugin sub-directory under the directory where you unpacked the CFK bundle.

Install the Confluent plugin using the following command:

kubectl krew install \
  --manifest=confluent-platform.yaml \
  --archive=kubectl-confluent-<environment>-amd64.tar.gz

For example, to install the plugin on MacOS:

kubectl krew  install \
  --manifest=confluent-platform.yaml \
  --archive=kubectl-confluent-darwin-amd64.tar.gz