Google Git
Sign in
apache / pulsar-helm-chart / 6c2edba8b1c3e56b8b2bdc2689004fe88637db28
commit6c2edba8b1c3e56b8b2bdc2689004fe88637db28[log] [tgz]
authorLari Hotari <lhotari@users.noreply.github.com>Mon Aug 31 08:05:49 2020 +0300
committerGitHub <noreply@github.com>Sun Aug 30 23:05:49 2020 -0600
tree3ad298202387844b28d7e9b91a5c2df5a6a2ff3b
parent4178c70d9093325b29a40441f613919c1b014ce8 [diff]
Get OS signals passed to container process by using shell built-in "exec" (#59)

### Changes 

- using "exec" to run a command replaces the shell process with the executed process
- this is required so that the process running in the container is able to receive OS signals
  - explained in https://docs.docker.com/develop/develop-images/dockerfile_best-practices/
    and https://docs.docker.com/engine/reference/builder/#entrypoint
- receiving SIGTERM signal is required for graceful shutdown. This is explained in https://pracucci.com/graceful-shutdown-of-kubernetes-pods.html 

This change might fix issues such as https://github.com/apache/pulsar/issues/6603 . One expectation of this fix is that graceful shutdown would allow Pulsar components such as a bookies to deregistered from Zookeeper properly before shutdown. 

### Motivation

Dockerfile best practices mention that "exec" should be used so that the process running in a container can receive OS signals. This is explained in https://docs.docker.com/develop/develop-images/dockerfile_best-practices/
    and https://docs.docker.com/engine/reference/builder/#entrypoint .  Kubernetes documention explains pod termination in https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-termination : "Typically, the container runtime sends a TERM signal to the main process in each container. Once the grace period has expired, the KILL signal is sent to any remaining processes, and the Pod is then deleted from the API Server ."
Currently some issues while running Pulsar are caused by the lack of graceful shutdown. Graceful shutdown isn't happening at all since the Pulsar processes never receive the TERM signal that would allow graceful shutdown. This PR fixes that.

This PR was inspired by https://github.com/kafkaesque-io/pulsar-helm-chart/pull/31
5 files changed
tree: 3ad298202387844b28d7e9b91a5c2df5a6a2ff3b
  1. .ci/
  2. .github/
  3. charts/
  4. examples/
  5. hack/
  6. scripts/
  7. .asf.yaml
  8. .gitignore
  9. license_test.go
  10. README.md
README.md

Official Apache Pulsar Helm Chart

This is the officially supported Helm Chart for installing Apache Pulsar on Kubernetes.

Read Deploying Pulsar on Kubernetes for more details.

Features

This Helm Chart includes all the components of Apache Pulsar for a complete experience.

  • [x] Pulsar core components:
    • [x] ZooKeeper
    • [x] Bookies
    • [x] Brokers
    • [x] Functions
    • [x] Proxies
  • [x] Management & monitoring components:
    • [x] Pulsar Manager
    • [x] Prometheus
    • [x] Grafana

It includes support for:

  • [x] Security
    • [x] Automatically provisioned TLS certs, using Jetstack's cert-manager
    • [x] TLS Encryption
      • [x] Proxy
      • [x] Broker
      • [x] Toolset
      • [x] Bookie
      • [x] ZooKeeper
    • [x] Authentication
      • [x] JWT
      • [ ] Mutal TLS
      • [ ] Kerberos
    • [x] Authorization
  • [x] Storage
    • [x] Non-persistence storage
    • [x] Persistence Volume
    • [x] Local Persistent Volumes
    • [ ] Tiered Storage
  • [x] Functions
    • [x] Kubernetes Runtime
    • [x] Process Runtime
    • [x] Thread Runtime
  • [x] Operations
    • [x] Independent Image Versions for all components, enabling controlled upgrades

Requirements

In order to use this chart to deploy Apache Pulsar on Kubernetes, the followings are required.

  1. kubectl 1.14 or higher, compatible with your cluster (+/- 1 minor release from your cluster)
  2. Helm v3 (3.0.2 or higher)
  3. A Kubernetes cluster, version 1.14 or higher.

Environment setup

Before proceeding to deploying Pulsar, you need to prepare your environment.

Tools

helm and kubectl need to be installed on your computer.

Add to local Helm repository

To add this chart to your local Helm repository:

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

To use the helm chart:

NOTE: Please specify --set initialize=true when installing a release at the first time. initialize=true will start initialize jobs to initialize the cluster metadata for both bookkeeper and pulsar clusters.

helm install --set initialize=true <release-name> apache/pulsar

Kubernetes cluster preparation

You need a Kubernetes cluster whose version is 1.14 or higher in order to use this chart, due to the usage of certain Kubernetes features.

We provide some instructions to guide you through the preparation: http://pulsar.apache.org/docs/en/helm-prepare/

Deploy Pulsar to Kubernetes

  1. Clone the Pulsar Helm charts repository.

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

    cd pulsar-helm-chart

  2. Run prepare_helm_release.sh to create required kubernetes resources for installing this Helm chart.

    • A k8s namespace for installing the Pulsar release (if -c is specified)
    • Create the JWT secret keys and tokens for three superusers: broker-admin, proxy-admin, and admin. By default, it generates asymmeric pubic/private key pair. You can choose to generate symmeric secret key by specifying --symmetric in the following command.
      • proxy-admin role is used for proxies to communicate to brokers.
      • broker-admin role is used for inter-broker communications.
      • admin role is used by the admin tools.
    ./scripts/pulsar/prepare_helm_release.sh -n <k8s-namespace> -k <pulsar-release-name> -c

  3. Use the Pulsar Helm charts to install Apache Pulsar.

NOTE: Please specify --set initialize=true when installing a release at the first time. initialize=true will start initialize jobs to initialize the cluster metadata for both bookkeeper and pulsar clusters.

This command installs and starts Apache Pulsar.

```bash 
$ helm install --set initialize=true <pulsar-release-name> apache/pulsar
```

  1. Access the Pulsar cluster

    The default values will create a ClusterIP for the proxy you can use to interact with the cluster. To find the IP address of proxy use:

    kubectl get service -n <k8s-namespace>

For more information, please follow our detailed quick start guide.

Customize the deployment

We provide a detailed guideline for you to customize the Helm Chart for a production-ready deployment.

You can also checkout out the example values file for different deployments.

Upgrading

Once your Pulsar Chart is installed, configuration changes and chart updates should be done using helm upgrade.

helm repo add apache https://pulsar.apache.org/charts
helm repo update
helm get values <pulsar-release-name> > pulsar.yaml
helm upgrade -f pulsar.yaml \
    <pulsar-release-name> apache/pulsar

For more detailed information, see our Upgrading guide.

Uninstall

To uninstall the Pulsar Chart, run the following command:

helm delete <pulsar-release-name>

For the purposes of continuity, these charts have some Kubernetes objects that are not removed when performing helm delete. These items we require you to conciously remove them, as they affect re-deployment should you choose to.

  • PVCs for stateful data, which you must consciously remove
    • ZooKeeper: This is your metadata.
    • BookKeeper: This is your data.
    • Prometheus: This is your metrics data, which can be safely removed.
  • Secrets, if generated by our prepare release script. They contain secret keys, tokens, etc. You can use cleanup release script to remove these secrets and tokens as needed.

Troubleshooting

We‘ve done our best to make these charts as seamless as possible, occasionally troubles do surface outside of our control. We’ve collected tips and tricks for troubleshooting common issues. Please examine these first before raising an issue, and feel free to add to them by raising a Pull Request!

Release Process

  1. Bump the version in charts/pulsar/Chart.yaml.

  2. Send a pull request for reviews.

  3. After the pull request is approved, merge it. The release workflow will be triggered automatically.

    • It creates a tag named pulsar-<version>.
    • Published the packaged helm chart to Github releases.
    • Update the charts/index.yaml in Pulsar website.

  4. Trigger the Pulsar website build to make the release available under https://pulsar.apache.org/charts.