You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by si...@apache.org on 2020/07/02 08:38:10 UTC
[pulsar-helm-chart] branch master updated: Update Pulsar Helm Chart
README (#35)
This is an automated email from the ASF dual-hosted git repository.
sijie pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar-helm-chart.git
The following commit(s) were added to refs/heads/master by this push:
new e6a2766 Update Pulsar Helm Chart README (#35)
e6a2766 is described below
commit e6a2766e7846ee187a8ac8372abff25b9bcfae75
Author: Sijie Guo <si...@apache.org>
AuthorDate: Thu Jul 2 01:38:03 2020 -0700
Update Pulsar Helm Chart README (#35)
---
README.md | 183 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 183 insertions(+)
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 <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.
+
+ ```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 <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
+ ```
+
+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 <k8s-namespace>
+ ```
+
+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-release-name> > pulsar.yaml
+helm upgrade -f pulsar.yaml \
+ <pulsar-release-name> 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 <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](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).