<commit_before>= Getting Started with riff

Riff is designed to use https://kubernetes.io/[Kubernetes] features for running Functions in response to Events.
This guide covers installing riff using https://helm.sh/[Helm], which is a commonly used package manager for Kubernetes. 

== Prerequisites

* A running 1.7+ Kubernetes cluster

* Kubernetes CLI `kubectl` installed and on the local system PATH. We recommend using the same version or later as the Kubernetes cluster you are using.

* Docker, if you plan on building samples or your own functions then you will need Docker installed. We have used Docker version 17.x or later.

== [[helm]]Install Helm

Helm is comprised of two components: one is the client (helm) the other is the server component (tiller). The helm client runs on your local machine and can be installed using the instructions found https://github.com/kubernetes/helm/blob/master/README.md#install[here]

Once you have the helm client installed you can install the server component.

For a cluster that does not have RBAC enabled use:

[source, bash]
----
helm init
----

[NOTE]
====
It gets a bit more complicated if the cluster has RBAC enabled. The Helm project describes the https://docs.helm.sh/using_helm/#best-practices-for-securing-helm-and-tiller[Best Practices for Securing Helm and Tiller] in their documentation. This can be fairly involved and for less critical development clusters it is easier to configure the Helm tiller server to run with cluster-admin privileges using a service account in the `kube-system` namespace. You should have cluster admin rights and run the following:

[source, bash]
----
kubectl -n kube-system create serviceaccount tiller
kubectl create clusterrolebinding tiller --clusterrole cluster-admin --serviceaccount=kube-system:tiller
helm init --service-account=tiller
----

====

TIP: To verify that the tiller pod has started execute the following command: `kubectl get pod --namespace kube-system -l app=helm` and you should see the `tiller` pod running.

== [[riff-repo]]Add the riff repository to your helm configuration

Riff offers helm charts for deploying the FaaS and its required services to a Kubernetes Cluster.
The following instructions cover how to configure helm to be able to install the riff charts.

Run the following commands to add the repository:

[source, bash]
----
helm repo add projectriff https://riff-charts.storage.googleapis.com
helm repo update
----

Run the following command to see that the `riff` chart is available and also what versions you can install:

[source, bash]
----
helm search riff -l
----

== [[current]]Install the current riff release

We have separated the Kafka installation from the riff chart. This requires an extra step of installing Kafka in order to use riff. You can use the single-node Kafka chart provided by riff or the three-node kafka/zookeeper service provided by Kubeapps.

=== Install Kafka chart

We provide a lightweight single node Kafka installation in the `projectriff/kafka` chart. This works well for development purposes.

Create the `riff-system` namespace:

[source, bash]
----
kubectl create namespace riff-system
----

Install the kafka/zookeeper service provided by riff using:

[source, bash]
----
helm install --name transport --namespace riff-system projectriff/kafka
----

[TIP]
====
Alternatively, install the three-node kafka/zookeeper service provided by the Kubeapps `incubator/kafka` chart using:

[source, bash]
----
helm install --name transport --namespace riff-system incubator/kafka
----

Just be aware that this chart requires significantly more resources to run.
====

=== Install riff using a Kubernetes cluster supporting LoadBalancer

Install the riff helm chart as follows:

For an install with default configuration and no RBAC enabled use:

[source, bash]
----
helm install projectriff/riff --name control --namespace riff-system --set rbac.create=false
----

[NOTE]
====
For a cluster that has RBAC enabled, use the following (since `rbac.create` is `true` by default):

[source, bash]
----
helm install projectriff/riff --name control --namespace riff-system
----
====

=== Install riff using a Kubernetes cluster not supporting LoadBalancer (e.g. minikube)

For `NodePort` service types (e.g. running on Minikube) configure the httpGateway to use `NodePort`:

[source, bash]
----
helm install projectriff/riff --name control --namespace riff-system --set rbac.create=false --set httpGateway.service.type=NodePort
----

[NOTE]
====
For a cluster that has RBAC enabled, use the following (since `rbac.create` is `true` by default):

[source, bash]
----
helm install projectriff/riff --name control --namespace riff-system --set httpGateway.service.type=NodePort
----
====

=== Verify the installation

You should see a number of resources get created in your cluster. You can see them all using:

[source, bash]
----
kubectl get svc,deployments,pods,functions,topics
----

=== Components installed by the chart

The provided Helm chart installs the following components:

* Topic Controller - the controller that watches the Topic resources and creates new topics in Kafka

* Function Controller - the controller that watches the Function resources and deploys function images together with the sidecar image

* HTTP Gateway - the external facing gateway that listens for data posted to the various topics and forwards the data as a message for the corresponding Kafka topic

=== To upgrade to a new version

Assuming that you named your release `control` you can run the following command to upgrade to the latest released version:

TIP: Older instructions used `demo` for the release name and `riffrepo` as the name for riff's Helm repository. You should substitute `control` with `demo` and `projectriff/riff` with `riffrepo/riff` if you have an older riff install. Another option is to remove the old install using `helm delete --purge demo` and then follow the instructions link:Getting-Started.adoc#riff-repo[above] for installing the new version.

[source, bash]
----
helm repo update
helm upgrade control projectriff/riff
----

=== To tear it all down

[source, bash]
----
helm delete --purge control
----

== [[CLI]]Install the current riff CLI tool

We provide a CLI tool written in Go that makes it easy to create and deploy functions.
Install the CLI by following the instructions on the https://github.com/projectriff/riff/releases[riff release page].

=== [[cli-config]]riff CLI configuration

The riff CLI can be configured either using environment variables or using a config file. 
The config file to be used can be set using `--config` option and it defaults to `$HOME/.riff.yaml`.

Environment variables are prefixed with `RIFF_` and the variables from the following example are supported:

```
RIFF_VERSION=0.0.6-snapshot
RIFF_USERACCOUNT=myaccount
RIFF_NAMESPACE=test
```

For the config file, you can create a `~/.riff.yaml` file with something like the following content:

```
riffVersion: 0.0.6-snapshot
useraccount: myaccount
namespace: test
publishNamespace: riff-system
```

=== [[cli-completion]]riff CLI bash completion

The riff CLI command supports generating a bash completion file in the same way as the `kubectl` command does.

==== [[cli-completion-macos]]riff CLI bash completion on macOS
<commit_msg>Updating the Getting-Started guide to the 0.0.6 instructions<commit_after>= Getting Started with riff

Riff is designed to use https://kubernetes.io/[Kubernetes] features for running Functions in response to Events.
This guide covers installing riff using https://helm.sh/[Helm], which is a commonly used package manager for Kubernetes. 

== Prerequisites

* A running 1.7+ Kubernetes cluster

* Kubernetes CLI `kubectl` installed and on the local system PATH. We recommend using the same version or later as the Kubernetes cluster you are using.

* Docker, if you plan on building samples or your own functions then you will need Docker installed. We have used Docker version 17.x or later.

== [[helm]]Install Helm

Helm is comprised of two components: one is the client (helm) the other is the server component (tiller). The helm client runs on your local machine and can be installed using the instructions found https://github.com/kubernetes/helm/blob/master/README.md#install[here]

Once you have the helm client installed you can install the server component.

For a cluster that does not have RBAC enabled use:

[source, bash]
----
helm init
----

[NOTE]
====
It gets a bit more complicated if the cluster has RBAC enabled. The Helm project describes the https://docs.helm.sh/using_helm/#best-practices-for-securing-helm-and-tiller[Best Practices for Securing Helm and Tiller] in their documentation. This can be fairly involved and for less critical development clusters it is easier to configure the Helm tiller server to run with cluster-admin privileges using a service account in the `kube-system` namespace. You should have cluster admin rights and run the following:

[source, bash]
----
kubectl -n kube-system create serviceaccount tiller
kubectl create clusterrolebinding tiller --clusterrole cluster-admin --serviceaccount=kube-system:tiller
helm init --service-account=tiller
----

====

TIP: To verify that the tiller pod has started execute the following command: `kubectl get pod --namespace kube-system -l app=helm` and you should see the `tiller` pod running.

== [[riff-repo]]Add the riff repository to your helm configuration

Riff offers helm charts for deploying the FaaS and its required services to a Kubernetes Cluster.
The following instructions cover how to configure helm to be able to install the riff charts.

Run the following commands to add the repository:

[source, bash]
----
helm repo add projectriff https://riff-charts.storage.googleapis.com
helm repo update
----

Run the following command to see that the `riff` chart is available and also what versions you can install:

[source, bash]
----
helm search riff -l
----

== [[current]]Install the current riff release

We provide a lightweight single node Kafka installation with the `projectriff/kafka` chart. 
This works well for development purposes and it can be installed together with the riff chart by providing `--set kafka.create=true` when installing the riff chart.

=== Create riff-system namespace

All riff components willbe deployed into a `riff-system` namespace. 
Any functions that are developed can be deployed into any other namespace including the `default` namespace.

To create the `riff-system` namespace run:

[source, bash]
----
kubectl create namespace riff-system
----

[TIP]
====
If you want to install Kafka using the three-node kafka/zookeeper service provided by the Kubeapps `incubator/kafka` chart, then you should use:

[source, bash]
----
helm install --name transport --namespace riff-system incubator/kafka
----

Just be aware that this chart requires significantly more resources to run.

When you install the riff chart during the next step, you need to add some config settings so that the riff components can find the Kafka service.
Add the following config settings instead of `--set kafka.create=true` to the `helm install` command that you use:

[source, bash]
----
--set kafka.broker.nodes=transport-kafka.riff-system:9092 --set kafka.zookeeper.nodes=transport-zookeeper.riff-system:2181
----

====

=== Install riff using a Kubernetes cluster supporting LoadBalancer

Install the riff helm chart as follows:

For an install with default configuration and no RBAC enabled use:

[source, bash]
----
helm install projectriff/riff --name projectriff --namespace riff-system --set kafka.create=true --set rbac.create=false
----

[NOTE]
====
For a cluster that has RBAC enabled, use the following (since `rbac.create` is `true` by default):

[source, bash]
----
helm install projectriff/riff --name projectriff --namespace riff-system --set kafka.create=true
----
====

=== Install riff using a Kubernetes cluster not supporting LoadBalancer (e.g. minikube)

For `NodePort` service types (e.g. running on Minikube) configure the httpGateway to use `NodePort`:

[source, bash]
----
helm install projectriff/riff --name projectriff --namespace riff-system --set kafka.create=true --set rbac.create=false --set httpGateway.service.type=NodePort
----

[NOTE]
====
For a cluster that has RBAC enabled, use the following (since `rbac.create` is `true` by default):

[source, bash]
----
helm install projectriff/riff --name projectriff --namespace riff-system --set kafka.create=true --set httpGateway.service.type=NodePort
----
====

=== Verify the installation

You should see a number of resources get created in your cluster. You can see them all using:

[source, bash]
----
kubectl get -n riff-system crd,svc,deploy,pod
----

=== Components installed by the chart

The provided Helm chart installs the following components:

* CustomResourceDefinitions for invokers, functions and topics

* Optional Kafka single-node development cluster with Zookeeper (can be substituted for external Kafka service)

* Topic Controller - the controller that watches the Topic resources and creates new topics in Kafka

* Function Controller - the controller that watches the Function resources and deploys function images together with the sidecar image

* HTTP Gateway - the external facing gateway that listens for data posted to the various topics and forwards the data as a message for the corresponding Kafka topic

=== To upgrade to a new version

Assuming that you named your release `projectriff` you can run the following command to upgrade to the latest released version:

TIP: Older instructions used `demo` for the release name and `riffrepo` as the name for riff's Helm repository. You should substitute `projectriff` with `demo` and `projectriff/riff` with `riffrepo/riff` if you have an older riff install. Another option is to remove the old install using `helm delete --purge demo` and then follow the instructions link:Getting-Started.adoc#riff-repo[above] for installing the new version.

[source, bash]
----
helm repo update
helm upgrade projectriff projectriff/riff
----

=== To tear it all down

[source, bash]
----
helm delete --purge projectriff
----

== [[CLI]]Install the current riff CLI tool

We provide a CLI tool written in Go that makes it easy to create and deploy functions.
Install the CLI by following the instructions on the https://github.com/projectriff/riff/releases[riff release page].

=== [[cli-config]]riff CLI configuration

The riff CLI can be configured either using environment variables or using a config file. 
The config file to be used can be set using `--config` option and it defaults to `$HOME/.riff.yaml`.

Environment variables are prefixed with `RIFF_` and the variables from the following example are supported:

```
RIFF_VERSION=0.0.6-snapshot
RIFF_USERACCOUNT=myaccount
RIFF_NAMESPACE=test
```

For the config file, you can create a `~/.riff.yaml` file with something like the following content:

```
riffVersion: 0.0.6-snapshot
useraccount: myaccount
namespace: test
```

=== [[cli-completion]]riff CLI bash completion

The riff CLI command supports generating a bash completion file in the same way as the `kubectl` command does.

==== [[cli-completion-macos]]riff CLI bash completion on macOS

{'fraction_non_alphanumeric': 0.08357329842931938, 'fraction_numerical': 0.0020287958115183247, 'mean_word_length': 4.265678842177809, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '310744', 'n_tokens_mistral': 4246, 'n_tokens_neox': 4062, 'n_words': 1997}