Streaming

Use a Custom Service for External Access

By default, the Helm chart deploys a NodePort Service to provide external access to the Redpanda cluster. To use a custom Service, set external.service.enabled to false. Then, you can create your own Services to provide external access.

  • Operator

  • Helm

redpanda-cluster.yaml
apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    external:
      enabled: true
      service:
        enabled: false
      addresses:
      - <subdomain-or-ip-address-for-replica-0>
      - <subdomain-or-ip-address-for-replica-1>
      - <subdomain-or-ip-address-for-replica-2>
kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

  • --values

  • --set

disable-external-service.yaml
external:
  enabled: true
  service:
    enabled: false
  addresses:
  - <subdomain-or-ip-address-for-replica-0>
  - <subdomain-or-ip-address-for-replica-1>
  - <subdomain-or-ip-address-for-replica-2>
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values disable-external-service.yaml --reuse-values
helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set external.enabled=true \
  --set external.service.enabled=false \
  --set "external.addresses={<subdomain-or-ip-address-for-replica-0>,<subdomain-or-ip-address-for-replica-1>,<subdomain-or-ip-address-for-replica-2>}"

Make sure to configure external.addresses with addresses that point to the worker nodes on which each Redpanda broker is running. The addresses must be listed in order of the StatefulSet replicas. For example, the first address in the list is assigned to the first replica (redpanda-0 by default).

If you use a custom domain (external.domain), provide subdomains for each replica in external.addresses. This custom domain is appended to each subdomain (<subdomain-for-replica-0>.<custom-domain>).

The Helm chart includes the external.addresses list in the checksum that determines whether the StatefulSet’s Pods must restart. Because external.addresses is a static list, adding or removing a broker requires you to update the list, which changes the checksum and forces a rolling restart of every existing broker, not just the new one.

external.domain doesn’t have this problem. Each broker builds its own advertised address from its Pod name (<pod-name>.<domain>), so the address doesn’t depend on the number of brokers and doesn’t have to change when you scale. Scaling the cluster doesn’t restart any existing brokers.

For production clusters that you expect to scale, prefer external.domain. See Advertise custom domains or Advertise a custom domain.

If your brokers must advertise addresses that don’t follow the <pod-name>.<domain> pattern, you can still avoid the rolling restart. See Scale without restarting brokers.

If your custom Services follow the <fullname>-<pod-ordinal> naming pattern, you can omit external.addresses and configure only external.domain instead, as described in manage:kubernetes/networking/external/k-nodeport.adoc#advertise-custom-domains.

Make sure that your custom Service listens on the advertised ports that are configured for each listener. See Configure Listeners in Kubernetes.

Publish addresses of unready brokers

Set publishNotReadyAddresses: true in the spec of every custom Service that exposes Redpanda brokers:

apiVersion: v1
kind: Service
metadata:
  name: <custom-service-name>
spec:
  publishNotReadyAddresses: true

All Services that the Helm chart and Redpanda Operator create set this field so that broker addresses remain resolvable while brokers are starting up or temporarily failing readiness probes, such as during a rolling upgrade. If your custom Service does not set this field, Kubernetes removes unready brokers from the Service endpoints, so clients temporarily lose connectivity to those brokers' advertised addresses during startup and rolling restarts. If a custom Service also serves inter-broker addresses, the missing endpoints can prevent a restarting cluster from re-forming.

Next steps

Suggested reading