Custom Configuration in Kubernetes

Deprecated red

The Cluster and Console resources are deprecated. For details, see the deprecation notice. To migrate to the Redpanda resource, see Migrate from Cluster and Console Custom Resources

The Redpanda operator for Kubernetes creates clusters based on the Custom Resource Definition (CRD). After you install the Redpanda operator, you apply the CRD. The CRD has two main components: the basic configuration for the Redpanda cluster, which includes the cluster name and namespace, and the configuration for the APIs.

Configure the CRD

In addition to the cluster properties included in the CRD by default, you can specify other cluster-level and node-level properties in the additionalConfiguration section of the CRD. Node-level configuration properties are passed to the redpanda.yaml configuration file. The Redpanda operator uses the Admin API to update cluster-level properties.

The format of each property in the additionalConfiguration section of the CRD is:

<subsystem>.<property_name>: <value>

For example, the CRD might have the following additionalConfiguration section:

additionalConfiguration:
  redpanda.enable_idempotence: "true"
  redpanda.default_topic_partitions: "3"
  pandaproxy_client.retries: "10"
  schema_registry.schema_registry_replication_factor: "3"

This example references the following subsystems: redpanda, pandaproxy_client (the HTTP Proxy client), and schema_registry. Each subsystem is followed by a property name and a value for the property.

Any properties you specify in the additionalConfiguration section of the CRD must be supported by the Redpanda version that the cluster is running. Since the Redpanda operator does not check for version compatibility, make sure you verify the CRD after you make a change.

Modify the CRD

To modify properties, edit the CRD file, save it, and run:

kubectl apply -f <custom_resource.yaml>

If a change to the property requires a restart of the cluster, the operator performs the restart automatically.

To see whether a change to a property requires a restart, see Cluster-level properties.

You can change cluster-level configuration properties through the Admin API. However, if the CRD has a different value for that property, that value overwrites the value set through the Admin API. If the CRD does not contain that property, there is no conflict. To avoid the possibility of overwriting a property value set through the Admin API, Redpanda recommends that you set properties in the CRD.

Verify the CRD

Verify that your CRD is successfully applied to the cluster after you make a change to the configuration. You could have a typo in the CRD, or you might have tried to apply a new property that isn’t supported for the Redpanda version that’s running on your cluster.

For example, suppose you add the following additionalConfiguration section to the CRD:

additionalConfiguration:
  redpanda.cluster_idd: puma

In the example, the cluster_id property name has a typo (an additional d). After saving the file with the typo, run the kubectl apply command to apply the modified CRD.

To verify that the cluster was configured successfully:

kubectl get cluster -o yaml

If there’s an error, the status section of the output notifies you:

status:
  conditions:
  - lastTransitionTime: "2022-04-01T13:11Z"
    message: '{cluster_idd":"Unknown property"}'
    reason: Error
    status: "False"
    type: ClusterConfigured

The message says there’s an unknown property. There was an error, and the ClusterConfigured status is False. In this case, the cluster continues to run without making a change to the configuration, whether or not a change to the property would require a cluster restart.

After you fix the typo, the status section of the kubectl get cluster-o yaml output looks like the following:

status:
  conditions:
  - lastTransitionTime: "2022-04-01T13:11Z"
    status: "True"
    type: ClusterConfigured

CRD example

The following file is the one_node_cluster.yaml sample file from the redpanda-examples GitHub repository. In this example, the additionalConfiguration section, which is highlighted, is appended to the end of the file, and has one property defined.

apiVersion: redpanda.vectorized.io/v1alpha1
kind: Cluster
metadata:
  name: one-node-cluster
spec:
  image: "docker.redpanda.com/redpandadata/redpanda"
  version: "latest"
  replicas: 1
  resources:
    requests:
      cpu: 1
      memory: 1.2Gi
    limits:
      cpu: 1
      memory: 1.2Gi
  configuration:
    rpcServer:
      port: 33145
    kafkaApi:
    - port: 9092
    pandaproxyApi:
    - port: 8082
    schemaRegistry:
      port: 8081
    adminApi:
    - port: 9644
    developerMode: true

  additionalConfiguration:
    redpanda.cluster_id: puma

The additionalConfiguration section of the CRD example contains a cluster-level property: cluster_id.

In this example, the cluster ID is revised to panda. To change the cluster_id property in the CRD, edit the additionalConfiguration section so it looks like this:

additionalConfiguration:
  redpanda.cluster_id: panda

Save the file, and run the following command to apply the change:

kubectl apply -f one-node-cluster.yaml

To retrieve the cluster ID:

kubectl exec one-node-cluster-0 -- rpk cluster config get cluster_id

The command returns the updated cluster ID:

Defaulted container "redpanda" out of: redpanda, redpanda-configurator (init)
panda