Run a standalone Pulsar cluster in Kubernetes

Network perimeter security required

A Pulsar cluster is not intended to be exposed on the public internet. The security considerations in the current design expect network perimeter security. This requirement can be met by deploying Pulsar in private networks and restricting access to trusted clients and services.

This section guides you through every step of installing and running Apache Pulsar with Helm on Kubernetes quickly.

For deploying a Pulsar cluster for production usage, read the documentation on how to configure and install a Pulsar Helm chart.

Security Notice

This quickstart guide uses default configurations suitable for development and testing only. The default Helm chart configuration does not meet production security requirements. For production deployments, you must review and customize security settings including authentication, authorization, TLS encryption, and network policies.

Prerequisites

• Kubernetes server 1.25.0+ (latest stable version recommended)
• kubectl version that is compatible with your k8s server version (+/- 1 minor release version)
• Helm 3.12+ (choose a helm version that is compatible with your k8s server version)
• At least 8GB of available RAM in your Kubernetes cluster
• At least 20GB of persistent storage available

tip

For the following steps, step 2 and step 3 are for developers and step 4 is for administrators.

To run Pulsar with Helm on Kubernetes, follow the steps below.

Step 0: Prepare a Kubernetes cluster

Before installing a Pulsar Helm chart, you have to create a Kubernetes cluster. You can follow the instructions to prepare a Kubernetes cluster.

We use Minikube in this quick start guide. To prepare a Kubernetes cluster, follow these steps:

1. Create a Kubernetes cluster on Minikube.

   minikube start --memory=8192 --cpus=4

2. Set kubectl to use Minikube.

   kubectl config use-context minikube

3. To use the Kubernetes Dashboard with the local Kubernetes cluster on Minikube, enter the command below:

   minikube dashboard

   The command automatically triggers opening a webpage in your browser.

Step 1: Install Pulsar Helm chart

1. Add Pulsar charts repo.

   helm repo add apachepulsar https://pulsar.apache.org/charts

   helm repo update

2. Clone the Pulsar Helm chart repository.

   git clone https://github.com/apache/pulsar-helm-chart
   cd pulsar-helm-chart

3. Run the script prepare_helm_release.sh to create the secrets required for installing the Apache Pulsar Helm chart. The username pulsar and password pulsar are used for logging into the Grafana dashboard.

   note

   When running the script, you can use -n to specify the Kubernetes namespace where the Pulsar Helm chart is installed, -k to define the Pulsar Helm release name, and -c to create the Kubernetes namespace. For more information about the script, run ./scripts/pulsar/prepare_helm_release.sh --help.

   ./scripts/pulsar/prepare_helm_release.sh \
       -n pulsar \
       -k pulsar-mini \
       -c

4. Use the Pulsar Helm chart to install a Pulsar cluster to Kubernetes.

   The --set overrides below pin every Pulsar component to the apachepulsar/pulsar:5.0.0-M2 image (matching this documentation version), use Oxia as the metadata store instead of ZooKeeper — the recommended option for new Pulsar clusters — and scale Oxia down to a single replica to fit the minikube footprint. You can also set these values in a values file instead of on the command line.

   helm install \
       --values examples/values-minikube.yaml \
       --set defaultPulsarImageRepository=apachepulsar/pulsar \
       --set defaultPulsarImageTag=5.0.0-M2 \
       --set components.zookeeper=false \
       --set components.oxia=true \
       --set oxia.server.replicas=1 \
       --set oxia.replicationFactor=1 \
       --set oxia.initialShardCount=1 \
       --namespace pulsar \
       pulsar-mini apachepulsar/pulsar

5. Check the status of all pods.

   kubectl get pods -n pulsar

   If all pods start up successfully, you can see that the STATUS is changed to Running or Completed.

   Output

   NAME                                            READY   STATUS      RESTARTS   AGE
   pulsar-mini-bookie-0                            1/1     Running     0          9m27s
   pulsar-mini-bookie-init-5gphs                   0/1     Completed   0          9m27s
   pulsar-mini-broker-0                            1/1     Running     0          9m27s
   pulsar-mini-grafana-6b7bcc64c7-4tkxd            1/1     Running     0          9m27s
   pulsar-mini-oxia-coordinator-7c9d8f5b6c-q4xtz   1/1     Running     0          9m27s
   pulsar-mini-oxia-server-0                       1/1     Running     0          9m27s
   pulsar-mini-prometheus-5fcf5dd84c-w8mgz         1/1     Running     0          9m27s
   pulsar-mini-proxy-0                             1/1     Running     0          9m27s
   pulsar-mini-pulsar-init-t7cqt                   0/1     Completed   0          9m27s
   pulsar-mini-toolset-0                           1/1     Running     0          9m27s

6. Check the status of all services in the namespace pulsar.

   kubectl get services -n pulsar

   Output

   NAME                           TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                       AGE
   pulsar-mini-bookie             ClusterIP      None             <none>        3181/TCP,8000/TCP             11m
   pulsar-mini-broker             ClusterIP      None             <none>        8080/TCP,6650/TCP             11m
   pulsar-mini-grafana            LoadBalancer   10.106.141.246   <pending>     3000:31905/TCP                11m
   pulsar-mini-oxia               ClusterIP      10.103.0.51      <none>        6648/TCP,6649/TCP,8080/TCP    11m
   pulsar-mini-oxia-coordinator   ClusterIP      10.103.0.77      <none>        6649/TCP,8080/TCP             11m
   pulsar-mini-oxia-svc           ClusterIP      None             <none>        6648/TCP,6649/TCP,8080/TCP    11m
   pulsar-mini-prometheus         ClusterIP      None             <none>        9090/TCP                      11m
   pulsar-mini-proxy              LoadBalancer   10.97.240.109    <pending>     80:32305/TCP,6650:31816/TCP   11m
   pulsar-mini-toolset            ClusterIP      None             <none>        <none>                        11m

Step 2: Use pulsar-admin to create Pulsar tenants/namespaces/topics

pulsar-admin is the CLI (Command-Line Interface) tool for Pulsar. In this step, you can use pulsar-admin to create resources, including tenants, namespaces, and topics.

1. Enter the toolset container.

   kubectl exec -it -n pulsar pulsar-mini-toolset-0 -- /bin/bash

   tip

   To perform a health check, you can use the bin/pulsar-admin brokers healthcheck command. For more information, see Pulsar admin docs.

2. In the toolset container, create a tenant named apache.

   bin/pulsar-admin tenants create apache

   Then you can list the tenants to see if the tenant is created successfully.

   bin/pulsar-admin tenants list

   You should see a similar output as below. The tenant apache has been successfully created.

   "apache"
   "public"
   "pulsar"

3. In the toolset container, create a namespace named pulsar in the tenant apache.

   bin/pulsar-admin namespaces create apache/pulsar

   Then you can list the namespaces of tenant apache to see if the namespace is created successfully.

   bin/pulsar-admin namespaces list apache

   You should see a similar output as below. The namespace apache/pulsar has been successfully created.

   "apache/pulsar"

4. In the toolset container, create a topic test-topic with 4 partitions in the namespace apache/pulsar.

   bin/pulsar-admin topics create-partitioned-topic apache/pulsar/test-topic -p 4

5. In the toolset container, list all the partitioned topics in the namespace apache/pulsar.

   bin/pulsar-admin topics list-partitioned-topics apache/pulsar

   Then you can see all the partitioned topics in the namespace apache/pulsar.

   "persistent://apache/pulsar/test-topic"

Step 3: Use Pulsar client to produce and consume messages

You can use the Pulsar client to create producers and consumers to produce and consume messages.

By default, the Pulsar Helm chart exposes the Pulsar cluster through a Kubernetes LoadBalancer. In Minikube, you can use the following command to check the proxy service.

kubectl get services -n pulsar | grep pulsar-mini-proxy

You will see a similar output as below.

pulsar-mini-proxy            LoadBalancer   10.97.240.109    <pending>     80:32305/TCP,6650:31816/TCP   28m

This output tells what are the node ports that Pulsar cluster's binary port and HTTP port are mapped to. The port after 80: is the HTTP port while the port after 6650: is the binary port.

Then you can find the IP address and exposed ports of your Minikube server by running the following command.

minikube service pulsar-mini-proxy -n pulsar

Output

|-----------|-------------------|-------------|-------------------------|
| NAMESPACE |       NAME        | TARGET PORT |           URL           |
|-----------|-------------------|-------------|-------------------------|
| pulsar    | pulsar-mini-proxy | http/80     | http://172.17.0.4:32305 |
|           |                   | pulsar/6650 | http://172.17.0.4:31816 |
|-----------|-------------------|-------------|-------------------------|
🏃  Starting tunnel for service pulsar-mini-proxy.
|-----------|-------------------|-------------|------------------------|
| NAMESPACE |       NAME        | TARGET PORT |          URL           |
|-----------|-------------------|-------------|------------------------|
| pulsar    | pulsar-mini-proxy |             | http://127.0.0.1:61853 |
|           |                   |             | http://127.0.0.1:61854 |
|-----------|-------------------|-------------|------------------------|

At this point, you can get the service URLs to connect to your Pulsar client. Here are URL examples:

webServiceUrl=http://127.0.0.1:61853/
brokerServiceUrl=pulsar://127.0.0.1:61854/

Then you can proceed with the following steps:

1. Download the Apache Pulsar tarball from the downloads page.

2. Decompress the tarball based on your download file.

   tar -xf <file-name>.tar.gz

3. Expose PULSAR_HOME.

   (1) Enter the directory of the decompressed download file.

   (2) Expose PULSAR_HOME as the environment variable.

   export PULSAR_HOME=$(pwd)

4. Configure the Pulsar client.

   In the ${PULSAR_HOME}/conf/client.conf file, replace webServiceUrl and brokerServiceUrl with the service URLs you get from the above steps.

5. Create a subscription to consume messages from apache/pulsar/test-topic.

   bin/pulsar-client consume -s sub apache/pulsar/test-topic  -n 0

6. Open a new terminal. In the new terminal, create a producer and send 10 messages to the test-topic topic.

   bin/pulsar-client produce apache/pulsar/test-topic  -m "---------hello apache pulsar-------" -n 10

7. Verify the results.

   • From the producer side

     Output

     The messages have been produced successfully.

     18:15:15.489 [main] INFO  org.apache.pulsar.client.cli.PulsarClientTool - 10 messages successfully produced

   • From the consumer side

     Output

     At the same time, you can receive the messages as below.

     ----- got message -----
     ---------hello apache pulsar-------
     ----- got message -----
     ---------hello apache pulsar-------
     ----- got message -----
     ---------hello apache pulsar-------
     ----- got message -----
     ---------hello apache pulsar-------
     ----- got message -----
     ---------hello apache pulsar-------
     ----- got message -----
     ---------hello apache pulsar-------
     ----- got message -----
     ---------hello apache pulsar-------
     ----- got message -----
     ---------hello apache pulsar-------
     ----- got message -----
     ---------hello apache pulsar-------
     ----- got message -----
     ---------hello apache pulsar-------

Step 4: Use Prometheus and Grafana to monitor cluster

Grafana is an open-source visualization tool, which can be used for visualizing time series data into dashboards.

1. By default, the Grafana is exposed as a separate LoadBalancer. You can open the Grafana UI using the following command:

   minikube service pulsar-mini-grafana -n pulsar

2. The Grafana UI is open in your browser. You can use the username pulsar and password pulsar to log into the Grafana Dashboard.

3. You can view dashboards for different components of a Pulsar cluster.