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/05/18 21:23:32 UTC
[pulsar] branch master updated: Polish helm related docs (#6946)
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.git
The following commit(s) were added to refs/heads/master by this push:
new 1be8461 Polish helm related docs (#6946)
1be8461 is described below
commit 1be8461cebdd6d61f1b9d3b4a84a9442c377a0c2
Author: HuanliMeng <48...@users.noreply.github.com>
AuthorDate: Tue May 19 05:23:21 2020 +0800
Polish helm related docs (#6946)
---
site2/docs/deploy-kubernetes.md | 7 +-
site2/docs/getting-started-helm.md | 59 +++++++++--------
site2/docs/helm-deploy.md | 129 +++++++++++++++++--------------------
site2/docs/helm-install.md | 25 +++----
site2/docs/helm-overview.md | 44 +++++--------
site2/docs/helm-prepare.md | 47 ++++++++------
site2/docs/helm-tools.md | 12 ++--
site2/docs/helm-upgrade.md | 23 ++++---
8 files changed, 166 insertions(+), 180 deletions(-)
diff --git a/site2/docs/deploy-kubernetes.md b/site2/docs/deploy-kubernetes.md
index c16df09..264a863 100644
--- a/site2/docs/deploy-kubernetes.md
+++ b/site2/docs/deploy-kubernetes.md
@@ -1,11 +1,10 @@
---
id: deploy-kubernetes
-title: Deploying Pulsar on Kubernetes
+title: Deploy Pulsar on Kubernetes
sidebar_label: Kubernetes
---
-For those looking to get up and running with these charts as fast
-as possible, in a **non-production** use case, we provide
+To get up and running with these charts as fast as possible, in a **non-production** use case, we provide
a [quick start guide](getting-started-helm.md) for Proof of Concept (PoC) deployments.
-For those looking to configure and install a Pulsar cluster on Kubernetes for production usage, you should follow the complete [Installation Guide](helm-install.md).
\ No newline at end of file
+To configure and install a Pulsar cluster on Kubernetes for production usage, follow the complete [Installation Guide](helm-install.md).
\ No newline at end of file
diff --git a/site2/docs/getting-started-helm.md b/site2/docs/getting-started-helm.md
index e43b508..82f3f61 100644
--- a/site2/docs/getting-started-helm.md
+++ b/site2/docs/getting-started-helm.md
@@ -4,8 +4,7 @@ title: Get started in Kubernetes
sidebar_label: Run Pulsar in Kubernetes
---
-This section guides you through every step of installing and running
-Apache Pulsar with Helm on Kubernetes quickly, including
+This section guides you through every step of installing and running Apache Pulsar with Helm on Kubernetes quickly, including the following sections:
- Install the Apache Pulsar on Kubernetes using Helm
- Start and stop Apache Pulsar
@@ -13,7 +12,7 @@ Apache Pulsar with Helm on Kubernetes quickly, including
- Produce and consume messages using Pulsar clients
- Monitor Apache Pulsar status with Prometheus and Grafana
-For deploying a Pulsar cluster for production usage, please read the documentation on [how to configure and install a Pulsar Helm chart](helm-deploy.md).
+For deploying a Pulsar cluster for production usage, read the documentation on [how to configure and install a Pulsar Helm chart](helm-deploy.md).
## Prerequisite
@@ -21,22 +20,22 @@ For deploying a Pulsar cluster for production usage, please read the documentati
- kubectl 1.14.0+
- Helm 3.0+
-> Tip
-> For the following steps, step 2 and step 3 are for developers and step 4 and step 5 are for administrators.
+> #### Tip
+> For the following steps, step 2 and step 3 are for **developers** and step 4 and step 5 are for **administrators**.
## Step 0: Prepare a Kubernetes cluster
Before installing a Pulsar Helm chart, you have to create a Kubernetes cluster. You can follow [the instructions](helm-prepare.md) to prepare a Kubernetes cluster.
-We use [Minikube](https://kubernetes.io/docs/getting-started-guides/minikube/) in this quick start guide.
+We use [Minikube](https://kubernetes.io/docs/getting-started-guides/minikube/) in this quick start guide. To prepare a Kubernetes cluster, follow these steps:
-1. Create a kubernetes cluster on Minikube.
+1. Create a Kubernetes cluster on Minikube.
```bash
minikube start --memory=8192 --cpus=4 --kubernetes-version=<k8s-version>
```
- The `<k8s-version>` can be any [Kubernetes version supported by your minikube installation](https://minikube.sigs.k8s.io/docs/reference/configuration/kubernetes/). Example: `v1.16.1.
+ The `<k8s-version>` can be any [Kubernetes version supported by your Minikube installation](https://minikube.sigs.k8s.io/docs/reference/configuration/kubernetes/), such as `v1.16.1`.
2. Set `kubectl` to use Minikube.
@@ -44,14 +43,14 @@ We use [Minikube](https://kubernetes.io/docs/getting-started-guides/minikube/) i
kubectl config use-context minikube
```
-3. In order to use the [Kubernetes Dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/) with local Kubernetes cluster on Minikube, enter the command below:
+3. To use the [Kubernetes Dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/) with the local Kubernetes cluster on Minikube, enter the command below:
```bash
minikube dashboard
```
The command automatically triggers opening a webpage in your browser.
-## Step 1: Install Pulsar Helm Chart
+## Step 1: Install Pulsar Helm chart
1. Clone the Pulsar Helm chart repository.
@@ -60,7 +59,7 @@ We use [Minikube](https://kubernetes.io/docs/getting-started-guides/minikube/) i
cd deployment/kubernetes/helm/
```
-2. Run `prepare_helm_release.sh` to create secrets required for installing Apache Pulsar Helm chart. The username `pulsar` and password `pulsar` are used for logging into Grafana dashboard and Pulsar Manager.
+2. Run the script `prepare_helm_release.sh` to create secrets required for installing the Apache Pulsar Helm chart. The username `pulsar` and password `pulsar` are used for logging into the Grafana dashboard and Pulsar Manager.
```bash
./scripts/pulsar/prepare_helm_release.sh \
@@ -85,7 +84,7 @@ We use [Minikube](https://kubernetes.io/docs/getting-started-guides/minikube/) i
kubectl get pods -n pulsar
```
- If all pods start up successfully, you can see `STATUS` changes to `Running` or `Completed`.
+ If all pods start up successfully, you can see that the `STATUS` is changed to `Running` or `Completed`.
**Output**
@@ -125,7 +124,7 @@ We use [Minikube](https://kubernetes.io/docs/getting-started-guides/minikube/) i
## Step 2: Use pulsar-admin to create Pulsar tenants/namespaces/topics
-`pulsar-admin` is the CLI tool for Pulsar. In this step, you can use `pulsar-admin` to create resources including tenants, namespaces, and 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.
@@ -193,7 +192,7 @@ We use [Minikube](https://kubernetes.io/docs/getting-started-guides/minikube/) i
You can use the Pulsar client to create producers and consumers to produce and consume messages.
-By default the Helm chart expose the Pulsar cluster through a Kubernetes `LoadBalancer`. In Minikube, you can use the following command to get the IP address of the proxy service.
+By default, the Pulsar Helm chart exposes the Pulsar cluster through a Kubernetes `LoadBalancer`. In Minikube, you can use the following command to get the IP address of the proxy service.
```bash
kubectl get services -n pulsar | grep pulsar-mini-proxy
@@ -205,24 +204,24 @@ 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 exposed to. The port after `80:` is the http port while the port after `6650:` is the binary port.
+This output tells what are the node ports that Pulsar cluster's binary port and HTTP port are exposed 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 of your minikube server by running the following command.
+Then you can find the IP address of your Minikube server by running the following command.
```bash
minikube ip
```
-At this point, you will get the service urls to connect to your Pulsar client.
+At this point, you can get the service URLs to connect to your Pulsar client.
```
webServiceUrl=http://$(minikube ip):<exposed-http-port>/
brokerServiceUrl=pulsar://$(minikube ip):<exposed-binary-port>/
```
-Then proceed with the following steps:
+Then you can proceed with the following steps:
-1. Download the Apache Pulsar tarball from [downloads page](https://pulsar.apache.org/en/download/).
+1. Download the Apache Pulsar tarball from the [downloads page](https://pulsar.apache.org/en/download/).
2. Decompress the tarball based on your download file.
@@ -236,13 +235,13 @@ Then proceed with the following steps:
(2) Expose `PULSAR_HOME` as the environment variable.
- ```bash
- export PULSAR_HOME=$(pwd)
- ```
+ ```bash
+ 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.
+ 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`.
@@ -258,7 +257,7 @@ Then proceed with the following steps:
7. Verify the results.
- - From producer side
+ - From the producer side
**Output**
@@ -268,7 +267,7 @@ Then proceed with the following steps:
18:15:15.489 [main] INFO org.apache.pulsar.client.cli.PulsarClientTool - 10 messages successfully produced
```
- - From consumer side
+ - From the consumer side
**Output**
@@ -307,7 +306,7 @@ Then proceed with the following steps:
minikube service pulsar-mini-pulsar-manager
```
-2. The pulsar manager UI will be open in your browser. You can use username `pulsar` and password `pulsar` to log into Pulsar Manager.
+2. The Pulsar Manager UI will be open in your browser. You can use the username `pulsar` and password `pulsar` to log into Pulsar Manager.
3. In Pulsar Manager UI, you can create an environment.
@@ -316,9 +315,9 @@ Then proceed with the following steps:
- Type `http://pulsar-mini-broker:8080` for the field `Service URL` in the popup window.
- Click `Confirm` button in the popup window.
-4. After successfully created an environment, you will be redirected to the `tenants` page of that environment. Then you can create `tenants`, `namespaces` and `topics` using Pulsar Manager.
+4. After successfully created an environment, you are redirected to the `tenants` page of that environment. Then you can create `tenants`, `namespaces` and `topics` using the Pulsar Manager.
-## Step 5: Use Prometheus and Grafana to monitor the cluster
+## Step 5: 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.
@@ -328,6 +327,6 @@ Grafana is an open-source visualization tool, which can be used for visualizing
minikube service pulsar-mini-grafana -n pulsar
```
-2. The Grafana UI will be open in your browser. You can use username `pulsar` and password `pulsar` to log into Grafana Dashboard.
+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 will be able to view dashboards for different components of a Pulsar cluster.
+3. You can view dashboards for different components of a Pulsar cluster.
diff --git a/site2/docs/helm-deploy.md b/site2/docs/helm-deploy.md
index 7e045e5..b43734c 100644
--- a/site2/docs/helm-deploy.md
+++ b/site2/docs/helm-deploy.md
@@ -1,37 +1,37 @@
---
id: helm-deploy
-title: Deploying a Pulsar cluster using Helm
+title: Deploy Pulsar cluster using Helm
sidebar_label: Deployment
---
-Before running `helm install`, you need to make some decisions about how you will run Pulsar.
+Before running `helm install`, you need to decide how to run Pulsar.
Options can be specified using Helm's `--set option.name=value` command line option.
-## Selecting configuration options
+## Select configuration options
-In each section collect the options that will be combined to use with `helm install`.
+In each section, collect the options that are combined to use with the `helm install` command.
-### Kubernetes Namespace
+### Kubernetes namespace
-By default, the chart is installed to a namespace called `pulsar`.
+By default, the Pulsar Helm chart is installed to a namespace called `pulsar`.
```yaml
namespace: pulsar
```
-If you decide to install the chart into a different k8s namespace, you can include this option in your Helm install command:
+To install the Pulsar Helm chart into a different Kubernetes namespace, you can include this option in the `helm install` command.
```bash
--set namespace=<different-k8s-namespace>
```
-By default, the chart doesn't create the namespace.
+By default, the Pulsar Helm chart doesn't create the namespace.
```yaml
namespaceCreate: false
```
-If you want the chart to create the k8s namespace automatically, you can include this option in your Helm install command.
+To use the Pulsar Helm chart to create the Kubernetes namespace automatically, you can include this option in the `helm install` command.
```bash
--set namespaceCreate=true
@@ -39,7 +39,7 @@ If you want the chart to create the k8s namespace automatically, you can include
### Persistence
-By default the chart creates Volume Claims with the expectation that a dynamic provisioner will create the underlying Persistent Volumes.
+By default, the Pulsar Helm chart creates Volume Claims with the expectation that a dynamic provisioner creates the underlying Persistent Volumes.
```yaml
volumes:
@@ -49,16 +49,17 @@ volumes:
local_storage: false
```
-If you would like to use local persistent volumes as the persistent storage for your Helm release, you can install [local-storage-provisioner](#install-local-storage-provisioner) and include the following option in your Helm install command.
+To use local persistent volumes as the persistent storage for Helm release, you can install the [local storage provisioner](#install-local-storage-provisioner) and include the following option in the `helm install` command.
```bash
--set volumes.local_storage=true
```
-> **Important**: After initial installation, making changes to your storage settings requires manually editing Kubernetes objects,
-> so it's best to plan ahead before installing your production instance of Pulsar to avoid extra storage migration work.
+> #### Note
+>
+> Before installing the production instance of Pulsar, ensure to plan the storage settings to avoid extra storage migration work. Because after initial installation, you must edit Kubernetes objects manually if you want to change storage settings.
-This chart is designed for production use, To use this chart in a development environment (e.g. minikube), you can disable persistence by including this option in your Helm install command.
+The Pulsar Helm chart is designed for production use. To use the Pulsar Helm chart in a development environment (such as Minikube), you can disable persistence by including this option in your `helm install` command.
```bash
--set volumes.persistence=false
@@ -66,14 +67,14 @@ This chart is designed for production use, To use this chart in a development en
### Affinity
-By default `anti-affinity` is turned on to ensure pods of same component can run on different nodes.
+By default, `anti-affinity` is enabled to ensure pods of the same component can run on different nodes.
```yaml
affinity:
anti_affinity: true
```
-If you are planning to use this chart in a development environment (e.g. minikue), you can disable `anti-affinity` by including this option in your Helm install command.
+To use the Pulsar Helm chart in a development environment (such as Minikue), you can disable `anti-affinity` by including this option in your `helm install` command.
```bash
--set affinity.anti_affinity=false
@@ -81,9 +82,9 @@ If you are planning to use this chart in a development environment (e.g. minikue
### Components
-This chart is designed for production usage. It deploys a production-ready Pulsar cluster including Pulsar core components and monitoring components.
+The Pulsar Helm chart is designed for production usage. It deploys a production-ready Pulsar cluster, including Pulsar core components and monitoring components.
-You can customize the components to deploy by turning on/off individual components.
+You can customize the components to be deployed by turning on/off individual components.
```yaml
## Components
@@ -117,9 +118,9 @@ monitoring:
grafana: true
```
-### Docker Images
+### Docker images
-This chart is designed to enable controlled upgrades. So it provides the capability to configure independent image versions for components. You can customize the images by setting individual component.
+The Pulsar Helm chart is designed to enable controlled upgrades. So it can configure independent image versions for components. You can customize the images by setting individual component.
```yaml
## Images
@@ -166,18 +167,11 @@ images:
### TLS
-This Pulsar Chart can be configured to enable TLS to protect all the traffic between components. Before you enable TLS, you have to provision TLS certificates
-for the components you have configured to enable TLS.
+The Pulsar Helm chart can be configured to enable TLS (Transport Layer Security) to protect all the traffic between components. Before enabling TLS, you have to provision TLS certificates for the required components.
-- [Provision TLS certs using `cert-manager`](#provision-tls-certs-using-cert-manager)
+#### Provision TLS certificates using cert-manager
-#### Provision TLS certs using cert-manager
-
-In order to using `cert-manager` to provision the TLS certificates, you have to install
-[cert-manager](#install-cert-manager) before installing the Pulsar chart. After
-successfully install cert manager, you can then set `certs.internal_issuer.enabled`
-to `true`. So the Pulsar chart will use `cert-manager` to generate `selfsigning` TLS
-certs for the configured components.
+To use the `cert-manager` to provision the TLS certificates, you have to install the [cert-manager](#install-cert-manager) before installing the Pulsar Helm chart. After successfully installing the cert-manager, you can set `certs.internal_issuer.enabled` to `true`. Therefore, the Pulsar Helm chart can use the `cert-manager` to generate `selfsigning` TLS certificates for the configured components.
```yaml
certs:
@@ -205,14 +199,14 @@ tls:
#### Enable TLS
-After installing `cert-manager`, you can then set `tls.enabled` to `true` to enable TLS encryption for the entire cluster.
+After installing the `cert-manager`, you can set `tls.enabled` to `true` to enable TLS encryption for the entire cluster.
```yaml
tls:
enabled: false
```
-You can also control whether to enable TLS encryption for individual component.
+You can also configure whether to enable TLS encryption for individual component.
```yaml
tls:
@@ -242,8 +236,8 @@ tls:
### Authentication
-Authentication is disabled by default. You can set `auth.authentication.enabled` to `true` to turn on authentication.
-Currently this chart only supports JWT authentication provider. You can set `auth.authentication.provider` to `jwt` to use JWT authentication provider.
+By default, authentication is disabled. You can set `auth.authentication.enabled` to `true` to enable authentication.
+Currently, the Pulsar Helm chart only supports JWT authentication provider. You can set `auth.authentication.provider` to `jwt` to use the JWT authentication provider.
```yaml
# Enable or disable broker authentication and authorization.
@@ -265,7 +259,7 @@ auth:
client: "admin"
```
-If you decide to enable authentication, you can run [prepare helm release](#prepare-the-helm-release) to generate token secret keys and tokens for three super users specified in `auth.superUsers` field. The generated token keys and super user tokens are uploaded and stored as kubernetes secrets prefixed with `<pulsar-release-name>-token-`. You can use following command to find those secrets.
+To enable authentication, you can run [prepare helm release](#prepare-the-helm-release) to generate token secret keys and tokens for three super users specified in the `auth.superUsers` field. The generated token keys and super user tokens are uploaded and stored as Kubernetes secrets prefixed with `<pulsar-release-name>-token-`. You can use the following command to find those secrets.
```bash
kubectl get secrets -n <k8s-namespace>
@@ -273,8 +267,7 @@ kubectl get secrets -n <k8s-namespace>
### Authorization
-Authorization is disabled by default. Authorization can be enabled
-only if Authentication is enabled.
+By default, authorization is disabled. Authorization can be enabled only when authentication is enabled.
```yaml
auth:
@@ -282,7 +275,7 @@ auth:
enabled: false
```
-You can include this option to turn on authorization.
+To enable authorization, you can include this option in the `helm install` command.
```bash
--set auth.authorization.enabled=true
@@ -290,17 +283,15 @@ You can include this option to turn on authorization.
### CPU and RAM resource requirements
-The resource requests, and number of replicas for the Pulsar components in this Chart are set by default to be adequate for a small production deployment. If you are trying to deploy a non-production instance, you can reduce the defaults in order to fit into a smaller cluster.
+By default, the resource requests and the number of replicas for the Pulsar components in the Pulsar Helm chart are adequate for a small production deployment. If you deploy a non-production instance, you can reduce the defaults to fit into a smaller cluster.
-Once you have all of your configuration options collected, we need
-to install dependent charts before proceeding to install the Pulsar
-Chart.
+Once you have all of your configuration options collected, you can install dependent charts before installing the Pulsar Helm chart.
-## Install Dependent Charts
+## Install dependent charts
-### Install Local Storage Provisioner
+### Install local storage provisioner
-If you decide to use local persistent volumes as the persistent storage, you need to [install a storage provisioner for local persistent volumes](https://kubernetes.io/blog/2019/04/04/kubernetes-1.14-local-persistent-volumes-ga/).
+To use local persistent volumes as the persistent storage, you need to install a storage provisioner for [local persistent volumes](https://kubernetes.io/blog/2019/04/04/kubernetes-1.14-local-persistent-volumes-ga/).
One of the easiest way to get started is to use the local storage provisioner provided along with the Pulsar Helm chart.
@@ -310,13 +301,13 @@ helm repo update
helm install pulsar-storage-provisioner streamnative/local-storage-provisioner
```
-### Install Cert Manager
+### Install cert-manager
-The Pulsar Chart uses [cert-manager](https://github.com/jetstack/cert-manager) to automate provisioning and managing TLS certificates. If you decide to enable TLS encryption for brokers or proxies, you need to install cert-manager first.
+The Pulsar Helm chart uses the [cert-manager](https://github.com/jetstack/cert-manager) to provision and manage TLS certificates automatically. To enable TLS encryption for brokers or proxies, you need to install the cert-manager in advance.
-You can follow the [official instructions](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm) to install cert-manager.
+For details about how to install the cert-manager, follow the [official instructions](https://cert-manager.io/docs/installation/kubernetes/#installing-with-helm).
-Alternatively, we provide a bash script [install-cert-manager.sh](https://github.com/apache/pulsar/blob/master/deployment/kubernetes/helm/scripts/cert-manager/install-cert-manager.sh) to install a cert-manager release to namespace `cert-manager`.
+Alternatively, we provide a bash script [install-cert-manager.sh](https://github.com/apache/pulsar/blob/master/deployment/kubernetes/helm/scripts/cert-manager/install-cert-manager.sh) to install a cert-manager release to the namespace `cert-manager`.
```bash
git clone https://github.com/apache/pulsar
@@ -324,9 +315,9 @@ cd pulsar/deployment/kubernetes/helm
./scripts/cert-manager/install-cert-manager.sh
```
-## Prepare the Helm Release
+## Prepare Helm release
-Once you have install all the dependent charts and collected all of your configuration options, you can run [prepare_helm_release.sh](https://github.com/apache/pulsar/blob/master/deployment/kubernetes/helm/scripts/pulsar/prepare_helm_release.sh) to prepare the helm release.
+Once you have install all the dependent charts and collected all of your configuration options, you can run [prepare_helm_release.sh](https://github.com/apache/pulsar/blob/master/deployment/kubernetes/helm/scripts/pulsar/prepare_helm_release.sh) to prepare the Helm release.
```bash
git clone https://github.com/apache/pulsar
@@ -334,24 +325,24 @@ cd pulsar/deployment/kubernetes/helm
./scripts/pulsar/prepare_helm_release.sh -n <k8s-namespace> -k <helm-release-name>
```
-The `prepare_helm_release` creates following resources:
+The `prepare_helm_release` creates the following resources:
-- A k8s namespace for installing the Pulsar release
-- Create a secret for storing the username and password of control center administrator. The username and password can be passed to `prepare_helm_release.sh` through flags `--control-center-admin` and `--control-center-password`. The username and password is used for logging into Grafana dashboard and Pulsar Manager.
-- 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`.
+- A Kubernetes namespace for installing the Pulsar release
+- A secret for storing the username and password of the control center administrator. The username and password can be passed to `prepare_helm_release.sh` through flags `--control-center-admin` and `--control-center-password`. The username and password is used for logging into the Grafana dashboard and Pulsar Manager.
+- JWT secret keys and tokens for three super users: `broker-admin`, `proxy-admin`, and `admin`. By default, it generates an asymmetric pubic/private key pair. You can choose to generate a symmetric secret key by specifying `--symmetric`.
- `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.
-## Deploy using Helm
+## Deploy Pulsar cluster using Helm
-Once you have done the following three things, you can proceed to install a Helm release.
+Once you have finished the following three things, you can install a Helm release.
-- Collect all of your configuration options
-- Install dependent charts
-- Prepare the Helm release
+- Collect all of your configuration options.
+- Install dependent charts.
+- Prepare the Helm release.
-In this example, we've named our Helm release `pulsar`.
+In this example, we name our Helm release `pulsar`.
```bash
git clone https://github.com/apache/pulsar
@@ -361,23 +352,23 @@ helm upgrade --install pulsar pulsar \
--set [your configuration options]
```
-You can also use `--version <installation version>` option if you would like to install a specific version of Pulsar Helm chart.
+You can also use the `--version <installation version>` option if you want to install a specific version of Pulsar Helm chart.
-## Monitoring the Deployment
+## Monitor deployment
-This will output the list of resources installed once the deployment finishes which may take 5-10 minutes.
+A list of installed resources are output once the Pulsar cluster is deployed. This may take 5-10 minutes.
-The status of the deployment can be checked by running `helm status pulsar` which can also be done while the deployment is taking place if you run the command in another terminal.
+The status of the deployment can be checked by running the `helm status pulsar` command, which can also be done while the deployment is taking place if you run the command in another terminal.
-## Accessing the Pulsar Cluster
+## Access Pulsar cluster
-The default values will create a `ClusterIP` for the following resources you can use to interact with the cluster.
+The default values will create a `ClusterIP` for the following resources, which you can use to interact with the cluster.
- Proxy: You can use the IP address to produce and consume messages to the installed Pulsar cluster.
-- Pulsar Manager: You can access the pulsar manager UI at `http://<pulsar-manager-ip>:9527`.
+- Pulsar Manager: You can access the Pulsar Manager UI at `http://<pulsar-manager-ip>:9527`.
- Grafana Dashboard: You can access the Grafana dashboard at `http://<grafana-dashboard-ip>:3000`.
-To find the IP address of those components use:
+To find the IP addresses of those components, run the following command:
```bash
kubectl get service -n <k8s-namespace>
diff --git a/site2/docs/helm-install.md b/site2/docs/helm-install.md
index cce9b8f..3f93db2 100644
--- a/site2/docs/helm-install.md
+++ b/site2/docs/helm-install.md
@@ -8,32 +8,33 @@ Install Apache Pulsar on Kubernetes with the official Pulsar Helm chart.
## Requirements
-In order to deploy Apache Pulsar on Kubernetes, the following are required.
+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.
+- 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))
+- Helm v3 (3.0.2 or higher)
+- A Kubernetes cluster, version 1.14 or higher
## Environment setup
-Before proceeding to deploying Pulsar, you need to prepare your environment.
+Before deploying Pulsar, you need to prepare your environment.
### Tools
-`helm` and `kubectl` need to be [installed on your computer](helm-tools.md).
+Install [`helm`](helm-tools.md) and [`kubectl`](helm-tools.md) on your computer.
## Cloud cluster preparation
-> NOTE: Kubernetes 1.14 or higher is required, due to the usage of certain Kubernetes features.
+> #### Note
+> Kubernetes 1.14 or higher is required.
-Follow the instructions to create and connect to the Kubernetes cluster of your choice:
+To create and connect to the Kubernetes cluster, follow the instructions:
- [Google Kubernetes Engine](helm-prepare.md#google-kubernetes-engine)
-## Deploy Pulsar
+## Pulsar deployment
-With the environment set up and configuration generated, you can now proceed to the [deployment of Pulsar](helm-deploy.md).
+Once the environment is set up and configuration is generated, you can now proceed to the [deployment of Pulsar](helm-deploy.md).
-## Upgrade Pulsar
+## Pulsar upgrade
-If you are upgrading an existing Kubernetes installation, follow the [upgrade documentation](helm-upgrade.md) instead.
+To upgrade an existing Kubernetes installation, follow the [upgrade documentation](helm-upgrade.md).
diff --git a/site2/docs/helm-overview.md b/site2/docs/helm-overview.md
index efd6fa5..0f2660c 100644
--- a/site2/docs/helm-overview.md
+++ b/site2/docs/helm-overview.md
@@ -8,10 +8,9 @@ This is the official supported Helm chart to install Apache Pulsar on a cloud-na
## Introduction
-The Apache Pulsar Helm chart is one of the most convenient ways
-to operate Pulsar on Kubernetes. This chart contains all the required components to get started and can scale to large deployments.
+The Apache Pulsar Helm chart is one of the most convenient ways to operate Pulsar on Kubernetes. This Pulsar Helm chart contains all the required components to get started and can scale to large deployments.
-This chart includes all the components for a complete experience, but each part can be configured to install separately.
+This chart includes all the components for a complete experience, but each part can be configured to be installed separately.
- Pulsar core components:
- ZooKeeper
@@ -28,7 +27,7 @@ This chart includes all the components for a complete experience, but each part
It includes support for:
- Security
- - Automatically provisioned TLS certs, using [Jetstack](https://www.jetstack.io/)'s [cert-manager](https://cert-manager.io/docs/)
+ - Automatically provisioned TLS certificates, using [Jetstack](https://www.jetstack.io/)'s [cert-manager](https://cert-manager.io/docs/)
- self-signed
- [Let's Encrypt](https://letsencrypt.org/)
- TLS Encryption
@@ -42,46 +41,37 @@ It includes support for:
- Authorization
- Storage
- Non-persistence storage
- - Persistence Volume
- - Local Persistent Volumes
+ - Persistence volume
+ - Local persistent volumes
- Functions
- Kubernetes Runtime
- Process Runtime
- Thread Runtime
- Operations
- - Independent Image Versions for all components, enabling controlled upgrades
+ - Independent image versions for all components, enabling controlled upgrades
## Pulsar Helm chart quick start
-For those looking to get up and running with these charts as fast
-as possible, in a **non-production** use case, we provide
-a [quick start guide](getting-started-helm.md) for Proof of Concept (PoC) deployments.
+To get up and run with these charts as fast as possible, in a **non-production** use case, we provide a [quick start guide](getting-started-helm.md) for Proof of Concept (PoC) deployments.
-This guide walks the user through deploying these charts with default
-values & features, but *does not* meet production ready requirements.
-If you wish to deploy these charts into production under sustained load,
-you should follow the complete [Installation Guide](helm-install.md).
+This guide walks the user through deploying these charts with default values and features, but *does not* meet production ready requirements. To deploy these charts into production under sustained load, follow the complete [Installation Guide](helm-install.md).
## 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/issues/new/choose), and feel free to add to them by raising a [Pull Request](https://github.com/apache/pulsar/compare)!
+We have done our best to make these charts as seamless as possible. Occasionally, troubles do go outside of our control. We have collected tips and tricks for troubleshooting common issues. Please check them first before raising an [issue](https://github.com/apache/pulsar/issues/new/choose), and feel free to add to them by raising a [Pull Request](https://github.com/apache/pulsar/compare).
## Installation
The Apache Pulsar Helm chart contains all required dependencies.
-If you are just looking to deploy a Proof of Concept for testing,
-we strongly suggest you follow our [Quick Start Guide](getting-started-helm.md) for your first iteration.
+If you deploy a PoC for testing, we strongly suggest you follow our [Quick Start Guide](getting-started-helm.md) for your first iteration.
1. [Preparation](helm-prepare.md)
2. [Deployment](helm-deploy.md)
## Upgrading
-Once your Pulsar Chart is installed, configuration changes and chart
-updates should be done using `helm upgrade`.
+Once the Pulsar Helm chart is installed, use the `helm upgrade` to complete configuration changes and chart updates.
```bash
git clone https://github.com/apache/pulsar
@@ -92,19 +82,19 @@ helm upgrade <pulsar-release-name> pulsar -f pulsar.yaml
For more detailed information, see [Upgrading](helm-upgrade.md).
-## Uninstall
+## Uninstallation
-To uninstall the Pulsar Chart, run the following command:
+To uninstall the Pulsar Helm 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.
+For the purposes of continuity, these charts have some Kubernetes objects that cannot be removed when performing `helm delete`.
+It is recommended to *conciously* remove these items, as they affect re-deployment.
-* PVCs for stateful data, which you must *consciously* remove
+* PVCs for stateful data: *consciously* remove these items.
- 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/blob/master/deployment/kubernetes/helm/scripts/pulsar/prepare_helm_release.sh). They contain secret keys, tokens, etc. You can use [cleanup release script](https://github.com/apache/pulsar/blob/master/deployment/kubernetes/helm/scripts/pulsar/cleanup_helm_release.sh) to remove these secrets and tokens as needed.
\ No newline at end of file
+* Secrets: if the secrets are generated by the [prepare release script](https://github.com/apache/pulsar/blob/master/deployment/kubernetes/helm/scripts/pulsar/prepare_helm_release.sh), they contain secret keys and tokens. You can use the [cleanup release script](https://github.com/apache/pulsar/blob/master/deployment/kubernetes/helm/scripts/pulsar/cleanup_helm_release.sh) to remove these secrets and tokens as needed.
\ No newline at end of file
diff --git a/site2/docs/helm-prepare.md b/site2/docs/helm-prepare.md
index 426c830..a33c999 100644
--- a/site2/docs/helm-prepare.md
+++ b/site2/docs/helm-prepare.md
@@ -1,54 +1,61 @@
---
id: helm-prepare
-title: Preparing Kubernetes resources
+title: Prepare Kubernetes resources
sidebar_label: Prepare
---
-For a fully functional Pulsar cluster, you will need a few resources before deploying the Apache Pulsar Helm chart. The following provides instructions to prepare the Kubernetes cluster before deploying the Pulsar Helm chart.
+For a fully functional Pulsar cluster, you need a few resources before deploying the Apache Pulsar Helm chart. The following provides instructions to prepare the Kubernetes cluster before deploying the Pulsar Helm chart.
- [Google Kubernetes Engine](#google-kubernetes-engine)
+ - [Manual cluster creation](#manual-cluster-creation)
+ - [Scripted cluster creation](#scripted-cluster-creation)
+ - [Create cluster with local SSDs](#create-cluster-with-local-ssds)
+- [Next Steps](#next-steps)
## Google Kubernetes Engine
-To get started easier, a script is provided to automate the cluster creation. Alternatively, a cluster can be created manually as well.
+To get started easier, a script is provided to create the cluster automatically. Alternatively, a cluster can be created manually as well.
-- [Manual cluster creation](#manual-cluster-creation)
-- [Scripted cluster creation](#scripted-cluster-creation)
+- [Google Kubernetes Engine](#google-kubernetes-engine)
+ - [Manual cluster creation](#manual-cluster-creation)
+ - [Scripted cluster creation](#scripted-cluster-creation)
+ - [Create cluster with local SSDs](#create-cluster-with-local-ssds)
+- [Next Steps](#next-steps)
### Manual cluster creation
To provision a Kubernetes cluster manually, follow the [GKE instructions](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-cluster).
-Alternatively you can use the [instructions](#scripted-cluster-creation) below to provision a GKE cluster as needed.
+Alternatively, you can use the [instructions](#scripted-cluster-creation) below to provision a GKE cluster as needed.
### Scripted cluster creation
A [bootstrap script](https://github.com/streamnative/charts/tree/master/scripts/pulsar/gke_bootstrap_script.sh) has been created to automate much of the setup process for users on GCP/GKE.
-The script will:
+The script can:
1. Create a new GKE cluster.
-2. Allow the cluster to modify DNS records.
+2. Allow the cluster to modify DNS (Domain Name Server) records.
3. Setup `kubectl`, and connect it to the cluster.
-Google Cloud SDK is a dependency of this script, so make sure it's [set up correctly](helm-tools.md#connect-to-a-gke-cluster) in order for the script to work.
+Google Cloud SDK is a dependency of this script, so ensure it is [set up correctly](helm-tools.md#connect-to-a-gke-cluster) for the script to work.
The script reads various parameters from environment variables and an argument `up` or `down` for bootstrap and clean-up respectively.
-The table below describes all variables.
+The following table describes all variables.
| **Variable** | **Description** | **Default value** |
| ------------ | --------------- | ----------------- |
-| PROJECT | The ID of your GCP project | No defaults, required to be set. |
+| PROJECT | ID of your GCP project | No default value. It requires to be set. |
| CLUSTER_NAME | Name of the GKE cluster | `pulsar-dev` |
-| CONFDIR | Configuration directory to store kubernetes config | Defaults to ${HOME}/.config/streamnative |
-| INT_NETWORK | The IP space to use within this cluster | `default` |
-| LOCAL_SSD_COUNT | The number of local SSD counts | Defaults to 4 |
-| MACHINE_TYPE | The type of machine to use for nodes | `n1-standard-4` |
-| NUM_NODES | The number of nodes to be created in each of the cluster's zones | 4 |
+| CONFDIR | Configuration directory to store Kubernetes configuration | ${HOME}/.config/streamnative |
+| INT_NETWORK | IP space to use within this cluster | `default` |
+| LOCAL_SSD_COUNT | Number of local SSD counts | 4 |
+| MACHINE_TYPE | Type of machine to use for nodes | `n1-standard-4` |
+| NUM_NODES | Number of nodes to be created in each of the cluster's zones | 4 |
| PREEMPTIBLE | Create nodes using preemptible VM instances in the new cluster. | false |
| REGION | Compute region for the cluster | `us-east1` |
-| USE_LOCAL_SSD | Flag to create a cluster with local SSDs | Defaults to false |
+| USE_LOCAL_SSD | Flag to create a cluster with local SSDs | false |
| ZONE | Compute zone for the cluster | `us-east1-b` |
| ZONE_EXTENSION | The extension (`a`, `b`, `c`) of the zone name of the cluster | `b` |
| EXTRA_CREATE_ARGS | Extra arguments passed to create command | |
@@ -59,15 +66,15 @@ Run the script, by passing in your desired parameters. It can work with the defa
PROJECT=<gcloud project id> scripts/pulsar/gke_bootstrap_script.sh up
```
-The script can also be used to clean up the created GKE resources:
+The script can also be used to clean up the created GKE resources.
```bash
PROJECT=<gcloud project id> scripts/pulsar/gke_bootstrap_script.sh down
```
-#### Create a cluster with local SSDs
+#### Create cluster with local SSDs
-If you are planning to install a Pulsar Helm chart using local persistent volumes, you need to create a GKE cluster with local SSDs. You can do so using the provided script by specifying `USE_LOCAL_SSD` to be `true`. A sample command is listed as below:
+To install a Pulsar Helm chart using local persistent volumes, you need to create a GKE cluster with local SSDs. You can do so Specifying the `USE_LOCAL_SSD` to be `true` in the following command to create a Pulsar cluster with local SSDs.
```
PROJECT=<gcloud project id> USE_LOCAL_SSD=true LOCAL_SSD_COUNT=<local-ssd-count> scripts/pulsar/gke_bootstrap_script.sh up
diff --git a/site2/docs/helm-tools.md b/site2/docs/helm-tools.md
index 33a1870..60732c5 100644
--- a/site2/docs/helm-tools.md
+++ b/site2/docs/helm-tools.md
@@ -10,9 +10,9 @@ Before deploying Pulsar to your Kubernetes cluster, there are some tools you mus
kubectl is the tool that talks to the Kubernetes API. kubectl 1.14 or higher is required and it needs to be compatible with your cluster ([+/- 1 minor release from your cluster](https://kubernetes.io/docs/tasks/tools/install-kubectl/#before-you-begin)).
-[Install kubectl locally by following the Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl).
+To Install kubectl locally, follow the [Kubernetes documentation](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-kubectl).
-The server version of kubectl cannot be obtained until we connect to a cluster. Proceed with setting up Helm.
+The server version of kubectl cannot be obtained until we connect to a cluster.
## Helm
@@ -24,19 +24,19 @@ You can get Helm from the project's [releases page](https://github.com/helm/helm
### Next steps
-Once kubectl and Helm are configured, you can continue to configuring your [Kubernetes cluster](helm-prepare.md).
+Once kubectl and Helm are configured, you can configure your [Kubernetes cluster](helm-prepare.md).
## Additional information
### Templates
-Templating in Helm is done via golang's [text/template](https://golang.org/pkg/text/template/) and [sprig](https://godoc.org/github.com/Masterminds/sprig).
+Templating in Helm is done through Golang's [text/template](https://golang.org/pkg/text/template/) and [sprig](https://godoc.org/github.com/Masterminds/sprig).
-Some information on how all the inner workings behave:
+For more information about how all the inner workings behave, check these documents:
- [Functions and Pipelines](https://helm.sh/docs/chart_template_guide/functions_and_pipelines/)
- [Subcharts and Globals](https://helm.sh/docs/chart_template_guide/subcharts_and_globals/)
### Tips and tricks
-Helm repository has some additional information on developing with Helm in it's [tips and tricks section](https://helm.sh/docs/howto/charts_tips_and_tricks/).
\ No newline at end of file
+For additional information on developing with Helm, check [tips and tricks section](https://helm.sh/docs/howto/charts_tips_and_tricks/) in the Helm repository.
\ No newline at end of file
diff --git a/site2/docs/helm-upgrade.md b/site2/docs/helm-upgrade.md
index ec7ff3c..36ec9ee 100644
--- a/site2/docs/helm-upgrade.md
+++ b/site2/docs/helm-upgrade.md
@@ -1,31 +1,30 @@
---
id: helm-upgrade
-title: Upgrade a Pulsar Helm release
+title: Upgrade Pulsar Helm release
sidebar_label: Upgrade
---
-Before upgrading your Pulsar installation, you need to check the changelog corresponding to the specific release you want to upgrade
-to and look for any release notes that might pertain to the new Pulsar chart version.
+Before upgrading your Pulsar installation, you need to check the change log corresponding to the specific release you want to upgrade to and look for any release notes that might pertain to the new Pulsar helm chart version.
-We also recommend that you need to provide all values using `helm upgrade --set key=value` syntax or `-f values.yml` instead of using `--reuse-values` because some of the current values might be deprecated.
+We also recommend that you need to provide all values using the `helm upgrade --set key=value` syntax or the `-f values.yml` instead of using `--reuse-values`, because some of the current values might be deprecated.
-> **NOTE**:
+> #### Note
>
> You can retrieve your previous `--set` arguments cleanly, with `helm get values <release-name>`. If you direct this into a file (`helm get values <release-name> > pulsar.yml`), you can safely
-pass this file via `-f`. Thus `helm upgrade <release-name> pulsar -f pulsar.yaml`. This safely replaces the behavior of `--reuse-values`.
+pass this file through `-f`. Thus `helm upgrade <release-name> pulsar -f pulsar.yaml`. This safely replaces the behavior of `--reuse-values`.
## Steps
-The following are the steps to upgrade Apache Pulsar to a newer version:
+To upgrade Apache Pulsar to a newer version, follow these steps:
-1. Check the change log for the specific version you would like to upgrade to
-2. Go through [deployment documentation](helm-deploy.md) step by step
-3. Extract your previous `--set` arguments with
+1. Check the change log for the specific version you would like to upgrade to.
+2. Go through [deployment documentation](helm-deploy.md) step by step.
+3. Extract your previous `--set` arguments with the following command.
```bash
helm get values <release-name> > pulsar.yaml
```
-4. Decide on all the values you need to set
-5. Perform the upgrade, with all `--set` arguments extracted in step 4
+4. Decide all the values you need to set.
+5. Perform the upgrade, with all `--set` arguments extracted in step 4.
```bash
helm upgrade <release-name> pulsar \
--version <new version> \