Configure External Access through a NodePort Service

By default, the Helm chart deploys a NodePort Service that routes traffic to the external listener ports on the Redpanda brokers. To set up external access using this NodePort Service, you must configure the brokers to advertise addresses that resolve to the IP address of the worker node.

A client connects to a Pod through the NodePort Service

Prerequisites

One worker node for each Redpanda broker that you want to deploy.
Install rpk on your local machine so that you can test connections to your Redpanda cluster from outside Kubernetes.
Review Kubernetes Cluster Requirements and Recommendations.
Understand Kubernetes networking for Redpanda.
Ensure that your Kubernetes cluster is accessible through your desired node port range. For example, with AWS EKS you must edit your inbound firewall rules. And with Azure AKS, you must enable public IPs on nodes in your node pool.

If you want brokers to advertise a custom domain, you must have control over the DNS settings for that domain.

For internal testing, you can use any domain without owning that domain, as long as:

Your local DNS server is configured to resolve that domain to the correct IP address.
Your client systems are configured to use your DNS server for resolution.

For production, it’s best to buy a domain from a domain registrar. This way, your domain is resolvable without any additional client-side configuration.

Advertise custom domains

Advertising custom domains rather than IP addresses has several advantages, including:

Flexibility: IP addresses can change, especially in cloud environments where services can be moved around or scaled up and down. If you use domain names, you can update the DNS record when the IP address changes and the clients won’t need any configuration changes.
High Availability: If a server fails, you can quickly point the domain name to another IP address, which would not be possible if clients connect directly using IP addresses.
Security: If the IP address of a server changes, you won’t need to reissue TLS certificates if it’s bound to a domain name.

To configure your Redpanda brokers to advertise a custom domain, each broker must also have a hostname that points to the address of the broker’s worker node.

Your brokers can advertise one of the following hostnames:

The default Redpanda hostname

The default hostnames are redpanda-<ordinal-number>, where redpanda is the name of the Helm release and the <ordinal-number> placeholder is the Pod ordinal generated by the StatefulSet.
Custom hostnames

Custom hostnames override the default. For example, you can configure your brokers to advertise <hostname-for-broker-0>.<custom-domain>.

Advertise the default Redpanda hostnames

By default, the Helm chart gives each broker a hostname that consists of the Helm release and the Pod ordinal. For example, redpanda-0, where redpanda is the Helm release and 0 is the Pod ordinal. To configure brokers to these hostnames, you must configure the brokers with a custom domain.

Specify your domain and optional subdomains in the external.domain configuration.

Replace <custom-domain> with your domain.

Helm + Operator
Helm

redpanda-cluster.yaml

apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    external:
      enabled: true
      domain: <custom-domain>
      type: NodePort

kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

--values
--set

custom-domain.yaml

external:
  enabled: true
  domain: <custom-domain>
  type: NodePort

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values custom-domain.yaml --reuse-values --wait

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set external.enabled=true \
  --set external.type=NodePort \
  --set external.domain=<custom-domain> \
  --wait

Create DNS records for each of your broker’s FQDNs, relative to the zone.

Custom hostnames

You can give each Redpanda broker a custom hostname to advertise instead of the default hostnames. Custom hostnames can either be suffixed with the Pod ordinal or they can be fully custom.

Advertise custom hostnames suffixed with the Pod ordinal

Configure the chart name with your chosen hostname.

Replace <custom-domain> with your domain, and replace <custom-hostname> with your hostname.

Helm + Operator
Helm

redpanda-cluster.yaml

apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    fullnameOverride: <custom-hostname>
    external:
      enabled: true
      type: NodePort
      domain: <custom-domain>

kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

--values
--set

custom-hostname-ordinal.yaml

fullnameOverride: <custom-hostname>
external:
  enabled: true
  type: NodePort
  domain: <custom-domain>

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values custom-hostname-ordinal.yaml --reuse-values --wait

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set external.enabled=true \
  --set external.type=NodePort \
  --set external.domain=<custom-domain> \
  --set fullnameOverride=<custom-hostname> \
  --wait

This configuration renames your Pods to <hostname>-<pod-ordinal>. Your Redpanda brokers will advertise the <hostname>-<pod-ordinal>.<custom-domain> address.

Create DNS records for each of your broker’s FQDNs, relative to the zone.

Advertise fully custom hostnames

Add each hostname to the external.addresses setting.

Replace <custom-domain> with your domain, and replace the placeholders in the external.addresses setting with your own hostname in the order that you want them to be applied to the Redpanda brokers. The hostnames must be given to each Redpanda broker in order of the StatefulSet replicas. For example, the Redpanda broker running inside the redpanda-0 Pod advertises <hostname-for-broker-0>.<custom-domain>.

Helm + Operator
Helm

redpanda-cluster.yaml

apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    external:
      enabled: true
      type: NodePort
      domain: <custom-domain>
      addresses:
      - <hostname-for-broker-0>
      - <hostname-for-broker-1>
      - <hostname-for-broker-2>

kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

--values
--set

custom-hostname.yaml

external:
  enabled: true
  type: NodePort
  domain: <custom-domain>
  addresses:
  - <hostname-for-broker-0>
  - <hostname-for-broker-1>
  - <hostname-for-broker-2>

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values custom-hostname.yaml --reuse-values --wait

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set external.enabled=true \
  --set external.type=NodePort \
  --set external.domain=<custom-domain> \
  --set "external.addresses={<hostname-for-broker0>,<hostname-for-broker1>,<hostname-for-broker2>}" \
  --wait

Create DNS records for each of your broker’s FQDNs, relative to the zone.

Create DNS records

When your brokers are configured to advertise a custom domain, the next step is to create DNS records that point the FQDNs at the IP addresses of the worker nodes on which the brokers are running. You can:

Create the DNS records manually.
Use ExternalDNS to manage DNS records.

Manual

Find out on which worker nodes your Redpanda brokers are running.

kubectl get pod --namespace <namespace>  \
-o=custom-columns=NODE:.spec.nodeName,NAME:.metadata.name -l \
app.kubernetes.io/component=redpanda-statefulset

Find the IP address of each worker node.
```
kubectl get node -o wide
```
Update the A/AAAA records for your domain so that each FQDN points to the correct worker node’s IP address.

Hostname IP address

<fqdn-0>

<worker-node-ip-0>

<fqdn-1>

<worker-node-ip-1>

<fqdn-2>

<worker-node-ip-2>

IP addresses can change. If the IP addresses of your worker nodes change, you must reconfigure your DNS records with the new IP addresses.
Wait for your DNS changes to be propagated.
Use the FQDN to communicate with the Redpanda brokers from outside the Kubernetes cluster:
```
rpk cluster info -X brokers=<hostname-0>.<custom-domain>:31092
```

Hostname	IP address
`<fqdn-0>`	`<worker-node-ip-0>`
`<fqdn-1>`	`<worker-node-ip-1>`
`<fqdn-2>`	`<worker-node-ip-2>`

ExternalDNS

ExternalDNS is a tool for Kubernetes that manages DNS records. Whenever you add, change, or remove Kubernetes Services or Ingresses, ExternalDNS automatically makes the same updates to the DNS records by communicating with DNS providers through their public APIs. This communication keeps your DNS records up to date with your Kubernetes Services.

Ensure that you have a DNS zone available where ExternalDNS can create DNS records. See the supported DNS providers in the ExternalDNS documentation.

Deploy ExternalDNS in your Kubernetes cluster. For an example manifest, see the ExternalDNS documentation.

Set the --provider flag to your DNS provider.

The txtOwnerId and interval flags are recommended. The txtOwnerId flag prevents DNS record conflicts between different instances of ExternalDNS. The interval flag controls the sync period with the DNS provider.

Annotate the headless ClusterIP Service to use ExternalDNS:

Helm + Operator
Helm

redpanda-cluster.yaml

apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    service:
      internal:
        annotations:
          "external-dns.alpha.kubernetes.io/hostname": <custom-domain>
          "external-dns.alpha.kubernetes.io/endpoints-type": <type>

kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

--values
--set

external-dns.yaml

service:
  internal:
    annotations:
      "external-dns.alpha.kubernetes.io/hostname": <custom-domain>
      "external-dns.alpha.kubernetes.io/endpoints-type": <type>

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values external-dns.yaml --reuse-values --wait

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set "service.internal.annotations.external-dns\.alpha\.kubernetes\.io/hostname=<custom-domain>" \
  --set "service.internal.annotations.external-dns\.alpha\.kubernetes\.io/endpoints-type=<type>" \
  --wait

For guidance, see Setting up ExternalDNS for Headless Services in the ExternalDNS documentation.

ExternalDNS will now automatically create DNS records for your Redpanda brokers, update the records if the IP addresses change, and delete them if you delete the ClusterIP Service.

Advertise IP addresses

You can configure each Redpanda broker to advertise the IP address of the worker node on which it’s running.

If your cluster has TLS enabled (default), you must Advertise custom domains. The Helm chart adds custom domains to the SAN list of TLS certificates and not IP addresses. Therefore, IP addresses assigned to LoadBalancer Services must be made resolvable by DNS names to ensure secure TLS access.

While adding entries to the /etc/hosts file may work for development purposes, it’s not a suitable approach for production environments. In production, you’ll need to update your organization’s DNS service to make the IP addresses resolvable by DNS names. Updating your organization’s DNS service ensures that users can access your services securely without encountering any SSL/TLS warnings or errors.

Deploy Redpanda with TLS disabled and enable the NodePort Service type:

Helm + Operator
Helm

redpanda-cluster.yaml

apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    external:
      enabled: true
      type: NodePort
    tls:
      enabled: false

kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

--values
--set

loadbalancer-tls-disabled.yaml

external:
  enabled: true
  type: NodePort
tls:
  enabled: false

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values loadbalancer-tls-disabled.yaml --reuse-values --wait

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set external.enabled=true \
  --set external.type=NodePort \
  --set tls.enabled=false \
  --wait

Find out on which worker nodes your Redpanda brokers are running.

kubectl get pod --namespace <namespace>  \
-o=custom-columns=NODE:.spec.nodeName,NAME:.metadata.name -l \
app.kubernetes.io/component=redpanda-statefulset

Find the IP address of each worker node.
```
kubectl get node -o wide
```

Add the IP addresses of each worker node to the external.addresses field in order. For example, the first IP address in the list is assigned to redpanda-0, the second is assigned to redpanda-1, and so on.

Helm + Operator
Helm

redpanda-cluster.yaml

apiVersion: cluster.redpanda.com/v1alpha2
kind: Redpanda
metadata:
  name: redpanda
spec:
  chartRef: {}
  clusterSpec:
    external:
      addresses:
      - <worker-node-ip-1>
      - <worker-node-ip-2>
      - <worker-node-ip-3>

kubectl apply -f redpanda-cluster.yaml --namespace <namespace>

--values
--set

external-access-ip-addresses.yaml

external:
  addresses:
  - <worker-node-ip-1>
  - <worker-node-ip-2>
  - <worker-node-ip-3>

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --values external-access-ip-addresses.yaml --reuse-values --wait

helm upgrade --install redpanda redpanda/redpanda --namespace <namespace> --create-namespace \
  --set external.enabled=true \
  --set external.type=NodePort \
  --set tls.enabled=false \
  --set external.domain=<custom-domain> \
  --set "external.addresses={<worker-node-ip1>,<worker-node-ip2>,<worker-node-ip3>}" \
  --wait

IP addresses can change. If the IP addresses of your worker nodes change, you must reconfigure the Redpanda brokers and all your external clients with the new IP addresses.

Use the IP addresses to communicate with the Redpanda cluster from outside the Kubernetes cluster:
```
rpk cluster info -X brokers=<worker-node-ip>:31092
```

Configure External Access through a NodePort Service

Prerequisites

Advertise custom domains

Advertise the default Redpanda hostnames

Custom hostnames

Advertise custom hostnames suffixed with the Pod ordinal

Advertise fully custom hostnames

Create DNS records

Manual

ExternalDNS

Advertise IP addresses

Next steps

Suggested reading

What do you like about this doc?

Let us know what we do well:

Let us contact you about your feedback:

What did you not like about this doc?

Let us know what we can improve:

Let us contact you about your feedback:

Configure External Access through a NodePort Service

Prerequisites

Advertise custom domains

Advertise the default Redpanda hostnames

Custom hostnames

Advertise custom hostnames suffixed with the Pod ordinal

Advertise fully custom hostnames

Create DNS records

Manual

ExternalDNS

Advertise IP addresses

Next steps

Suggested reading

Simple online edits

Contribution guide