> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

## Prerequisites

To use StreamNative Private Cloud, the following are required:

* Prepare a Kubernetes cluster (Kubernetes version >= 1.16).
* Install [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) (v1.16 or above), compatible with your cluster (+/- 1 minor release from your cluster).
* Install [`Helm`](https://helm.sh/docs/intro/install/) (v3.0.2 or above).

## Create the operators namespace

1. Create a Kubernetes namespace where the operator will be installed later.

   ```bash theme={null}
   kubectl create namespace operators
   ```

## Install StreamNative Private Cloud

### Import license

Before installing StreamNative Private Cloud, you need to import a valid license. Otherwise, StreamNative Private Cloud will stop reconciling with a "no valid license" error message:

```
ERROR	controller.pulsarcoordinator	Reconciler error	{"reconciler group": "k8s.streamnative.io", "reconciler kind": "PulsarCoordinator", "name": "private-cloud", "namespace": "pulsar", "error": "No valid license has been found under namespace operators, please contact https://streamnative.io/deployment/start-free-trial"}
sigs.k8s.io/controller-runtime/pkg/internal/controller.(*Controller).processNextWorkItem
```

If you do not have any license, you can contact StreamNative to apply for a [free trial](https://streamnative.io/deployment/start-free-trial).

When you have a license in hand, you can import it through:

<Note title="Note">
  `metadata.labels` with the `cloud.streamnative.io/type: "license"` is required because the `sn-operator` will detect secrets in its namespace with label and to import automatically.
</Note>

```
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
# This label is a required field for the sn-operator to detect the license.
  labels:
    cloud.streamnative.io/type: "license"
  name: sn-license
  namespace: operators
type: Opaque
stringData:
  license: "Your license token"
EOF
```

## Install the StreamNative Operator

1. Add the StreamNative chart repository.

   ```bash theme={null}
   helm repo add streamnative https://charts.streamnative.io
   helm repo update
   ```

2. Deploy the StreamNative Operator using the `sn-operator` Helm chart in the created Kubernetes namespace.

   **Cluster-scoped installation (default)**

   By default, the operator is installed with cluster-wide scope and watches for Pulsar resources across all namespaces:

   ```bash theme={null}
   helm install sn-operator streamnative/sn-operator -n operators
   ```

   In this mode, the operator creates ClusterRole and ClusterRoleBinding resources to manage Pulsar clusters in any namespace.

   **Namespace-scoped installation**

   Alternatively, you can restrict the operator to watch only specific namespaces. This creates Role and RoleBinding resources instead of cluster-level permissions:

   ```bash theme={null}
   helm install sn-operator streamnative/sn-operator -n operators \
     --set watchNamespaces="pulsar\,pulsar-staging"
   ```

   <Note>
     In namespace-scoped mode, the operator will only reconcile Pulsar resources in the specified namespaces. Multiple namespaces should be comma-separated with escaped commas (`\,`) in the Helm command.
   </Note>

3. Verify that Operator Pods are running.

   ```bash theme={null}
   kubectl get all -n operators
   ```

### Create the Pulsar namespaces

Create the namespaces `pulsar`. The `pulsar` namespace is used for deploying your Pulsar cluster.

```
kubectl create ns pulsar
```

### Provision a Pulsar cluster

To provision a Pulsar cluster through the StreamNative Operator, you need to define a YAML file for your Pulsar cluster.

Run the command below to deploy your Pulsar cluster in `pulsar` namespace

```
kubectl apply -f https://raw.githubusercontent.com/streamnative/private-cloud/main/quick-start/pulsar-cluster.yaml
```

### Tools usage

StreamNative Private Cloud provisions a toolset Pod which packages regual Pulsar tools:

```
kubectl exec -it private-cloud-toolset-0 -n pulsar -- bash
```

Use `pulsar-client` to quickly produce some messages

```
bin/pulsar-client produce private-cloud -m "sn-private-cloud" -n 10

2023-10-21T20:39:56,476+0000 [pulsar-client-io-1-1] INFO  org.apache.pulsar.client.impl.ProducerImpl - [private-cloud] [brokers-1-0] Closed Producer
2023-10-21T20:39:56,478+0000 [main] INFO  org.apache.pulsar.client.impl.PulsarClientImpl - Client closing. URL: http://brokers-broker.pulsar.svc.cluster.local:8080
2023-10-21T20:39:56,494+0000 [pulsar-client-io-1-1] INFO  org.apache.pulsar.client.impl.ClientCnx - [id: 0x570456f6, L:/10.244.0.22:48324 ! R:brokers-broker-1.brokers-broker-headless.pulsar.svc.cluster.local/10.244.0.31:6650] Disconnected
2023-10-21T20:39:58,509+0000 [main] INFO  org.apache.pulsar.client.cli.PulsarClientTool - 10 messages successfully produced
```

Use `pulsarctl` to check the resource status

```
bin/pulsarctl topics list public/default

+-------------------------------------------+---------------+
|                TOPIC NAME                 | PARTITIONED ? |
+-------------------------------------------+---------------+
| persistent://public/default/private-cloud | N             |
+-------------------------------------------+---------------+
```

### Access to Console

```
kubectl port-forward console-streamnative-console-0 9527:9527 -n pulsar
```

## Clean up

Run the command below to delete your Pulsar cluster.

```
kubectl delete -f https://raw.githubusercontent.com/streamnative/private-cloud/main/quick-start/pulsar-cluster.yaml
```

Run the command below to remove the `sn-operator`.

```
helm uninstall sn-operator -n operators
```