diff --git a/README.md b/README.md index b16cc92..86ad683 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,189 @@ This is the officially supported Helm Chart for installing Apache Pulsar on Kube Read [Deploying Pulsar on Kubernetes](http://pulsar.apache.org/docs/en/deploy-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](https://www.jetstack.io/)'s [cert-manager](https://cert-manager.io/docs/) + - [x] self-signed + - [x] [Let's Encrypt](https://letsencrypt.org/) + - [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](https://kubernetes.io/docs/tasks/tools/install-kubectl/#before-you-begin)) +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](http://pulsar.apache.org/docs/en/helm-tools/). + +## Add to local Helm repository + +To add this chart to your local Helm repository: + +```bash +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. + +```bash +helm install --set initialize=true 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. + + ```bash + git clone https://github.com/apache/pulsar-helm-chart + ``` + ```bash + 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. + + ```bash + ./scripts/pulsar/prepare_helm_release.sh -n -k -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 apache/pulsar + ``` + +5. 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: + + ```bash + kubectl get service -n + ``` + +For more information, please follow our detailed +[quick start guide](http://pulsar.apache.org/docs/en/kubernetes-helm/). + +## Customize the deployment + +We provide a [detailed guideline](http://pulsar.apache.org/docs/en/helm-deploy/) for you to customize +the Helm Chart for a production-ready deployment. + +You can also checkout out the example values file for different deployments. + +- [Deploy ZooKeeper only](examples/values-cs.yaml) +- [Deploy a Pulsar cluster with an external configuration store](examples/values-cs.yaml) +- [Deploy a Pulsar cluster with local persistent volume](examples/values-local-pv.yaml) +- [Deploy a Pulsar cluster to Minikube](examples/values-minikube.yaml) +- [Deploy a Pulsar cluster with no persistence](examples/values-no-persistence.yaml) +- [Deploy a Pulsar cluster with TLS encryption](examples/values-tls.yaml) +- [Deploy a Pulsar cluster with JWT authentication using symmetric key](examples/values-jwt-symmetric.yaml) +- [Deploy a Pulsar cluster with JWT authentication using asymmetric key](examples/values-jwt-asymmetric.yaml) + +## Upgrading + +Once your Pulsar Chart is installed, configuration changes and chart +updates should be done using `helm upgrade`. + +```bash +helm repo add apache https://pulsar.apache.org/charts +helm repo update +helm get values > pulsar.yaml +helm upgrade -f pulsar.yaml \ + apache/pulsar +``` + +For more detailed information, see our [Upgrading](http://pulsar.apache.org/docs/en/helm-upgrade/) guide. + +## Uninstall + +To uninstall the Pulsar Chart, run the following command: + +```bash +helm delete +``` + +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](https://github.com/apache/pulsar-helm-chart/blob/master/scripts/pulsar/prepare_helm_release.sh). They contain secret keys, tokens, etc. You can use [cleanup release script](https://github.com/apache/pulsar-helm-chart/blob/master/scripts/pulsar/cleanup_helm_release.sh) 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](https://github.com/apache/pulsar-helm-chart/issues/new/choose), and feel free to add to them by raising a [Pull Request](https://github.com/apache/pulsar-helm-chart/compare)! + ## Release Process 1. Bump the version in [charts/pulsar/Chart.yaml](https://github.com/apache/pulsar-helm-chart/blob/master/charts/pulsar/Chart.yaml#L24).