Getting started on Minikube
The following will help you get started running a riff function on Minikube.
Install Minikube
Minikube is a Kubernetes environment which runs in a single virtual machine. See the latest release for installation, and the readme for more detailed information.
For macOS we recommend using Hyperkit as the vm driver. To install Hyperkit, first install Docker Desktop (Mac), then run:
curl -LO https://storage.googleapis.com/minikube/releases/latest/docker-machine-driver-hyperkit \
&& sudo install -o root -g wheel -m 4755 docker-machine-driver-hyperkit /usr/local/bin/
For Linux we suggest using the kvm2 driver.
For additional details see the minikube driver installation docs.
Install Docker
Installing Docker Community Edition is the easiest way get started with Docker. Since Minikube includes its own Docker daemon, you actually only need the docker CLI to run docker login for --local-path function builds. This means that if you want to, you can shut down the Docker Desktop app and depend on the Minikube Docker daemon by running eval $(minikube docker-env).
Install kubectl
kubectl is the Kubernetes CLI. It is used to manage minikube as well as hosted Kubernetes clusters.
Create a Minikube cluster
minikube start --memory=4096 --cpus=4
To use the kvm2 driver for Linux specify --vm-driver=kvm2. Omitting the --vm-driver option will use the default driver.
Confirm that your kubectl context is pointing to the new cluster
kubectl config current-context
Install Helm
Helm is a popular package manager for Kubernetes. The riff runtime and its dependencies are provided as Helm charts.
Download and install the latest Helm 2.x release for your platform. (Helm 3 is currently in alpha and has not been tested for compatibility with riff)
After installing the Helm CLI, we need to initialize the Helm Tiller in our cluster.
kubectl create serviceaccount tiller -n kube-system
kubectl create clusterrolebinding tiller --clusterrole cluster-admin --serviceaccount kube-system:tiller
helm init --wait --service-account tiller
Please see the Helm documentation for additional Helm security configuration.
Install the riff CLI
The riff CLI is available to download from our GitHub releases page. Once installed, check that the riff CLI version is 0.4.0 or later.
riff --version
riff version 0.4.0 (d1b042f4247d8eb01ee0b9e984926028a2844fe8)
At this point it is useful to monitor your cluster using a utility like watch. To install on a Mac
brew install watch
Watch pods in a separate terminal.
watch -n 1 kubectl get pod --all-namespaces
Install riff using Helm
Load the projectriff charts
helm repo add projectriff https://projectriff.storage.googleapis.com/charts/releases
helm repo update
riff can be installed with or without Knative. The riff Core runtime is available in both environments, however, the riff Knative Runtime is only available if Knative is installed.
To install riff with Knative and Istio:
helm install projectriff/istio --name istio --version 0.4.x --namespace istio-system --set gateways.istio-ingressgateway.type=NodePort --wait
helm install projectriff/riff --name riff --version 0.4.x --set knative.enabled=true
Alternatively, install riff without Knative or Istio:
helm install projectriff/riff --name riff --version 0.4.x
Verify the riff install.
riff doctor
NAMESPACE STATUS
riff-system ok
RESOURCE READ WRITE
configmaps allowed allowed
secrets allowed allowed
pods allowed n/a
pods/log allowed n/a
applications.build.projectriff.io allowed allowed
containers.build.projectriff.io allowed allowed
functions.build.projectriff.io allowed allowed
deployers.core.projectriff.io allowed allowed
processors.streaming.projectriff.io allowed allowed
streams.streaming.projectriff.io allowed allowed
adapters.knative.projectriff.io allowed allowed
deployers.knative.projectriff.io allowed allowed
apply build credentials
Use the riff CLI to apply credentials to a container registry (if you plan on using a namespace other than default add the --namespace flag). Replace the ??? with your docker username.
DOCKER_ID=???
riff credential apply my-creds --docker-hub $DOCKER_ID --set-default-image-prefix
You will be prompted to provide the password.
Create a function
This step will pull the source code for a function from a GitHub repo, build a container image based on the node function invoker, and push the resulting image to your Docker Hub repo.
riff function create square \
--git-repo https://github.com/projectriff-samples/node-square \
--artifact square.js \
--tail
After the function is created, you can see the built image by listing functions.
riff function list
NAME LATEST IMAGE ARTIFACT HANDLER INVOKER STATUS AGE
square index.docker.io/jldec/square@sha256:527053273ec98697dbdd88951f77edf82a9a46767125cd1e4348422fe5b8e09f square.js <empty> <empty> Ready 4m3s
Create a Knative deployer
The Knative Runtime is only available on clusters with Istio and Knative installed. Knative deployers run riff workloads using Knative resources which provide auto-scaling (including scale-to-zero) based on HTTP request traffic, and routing.
riff knative deployer create knative-square --function-ref square --tail
After the deployer is created, you can see the hostname by listing deployers.
riff knative deployer list
NAME TYPE REF HOST STATUS AGE
knative-square function square knative-square.default.example.com Ready 19s
invoke the function
Knative configures HTTP routes on the istio-ingressgateway. Requests are routed by hostname.
Look up the nodePort for the ingressgateway; you should see a port value like 30195.
MINIKUBE_IP=$(minikube ip)
INGRESS_PORT=$(kubectl get svc istio-ingressgateway --namespace istio-system --output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}')
echo $MINIKUBE_IP:$INGRESS_PORT
Invoke the function by POSTing to the ingressgateway, passing the hostname and content-type as headers.
curl http://$MINIKUBE_IP:$INGRESS_PORT/ -w '\n' \
-H 'Host: knative-square.default.example.com' \
-H 'Content-Type: application/json' \
-d 7
49
Create a Core deployer
The Core runtime is available on all riff clusters. It deploys riff workloads as "vanilla" Kubernetes deployments and services.
riff core deployer create k8s-square --function-ref square --tail
After the deployer is created, you can see the service name by listing deployers.
riff core deployers list
NAME TYPE REF SERVICE STATUS AGE
k8s-square function square k8s-square-deployer Ready 7s
invoke the function
In a separate terminal, start port-forwarding to the ClusterIP service created by the deployer.
kubectl port-forward service/k8s-square-deployer 8080:80
Forwarding from 127.0.0.1:8080 -> 8080
Forwarding from [::1]:8080 -> 8080
Make a POST request to invoke the function using the port assigned above.
curl http://localhost:8080/ -w '\n' \
-H 'Content-Type: application/json' \
-d 8
64
NOTE: unlike Knative, the Core runtime will not scale deployments down to zero.
Cleanup
riff knative deployer delete knative-square
riff core deployer delete k8s-square
riff function delete square
Upgrading
If you need to upgrade riff, we recommend uninstalling and then reinstalling.
Uninstalling
You can use helm to uninstall riff.
# remove any riff resources
kubectl delete riff --all-namespaces --all
# remove any Knative resources (if Knative runtime is enabled)
kubectl delete knative --all-namespaces --all
# remove riff
helm delete --purge riff
kubectl delete customresourcedefinitions.apiextensions.k8s.io -l app.kubernetes.io/managed-by=Tiller,app.kubernetes.io/instance=riff
# remove istio (if installed)
helm delete --purge istio
kubectl delete namespace istio-system
kubectl get customresourcedefinitions.apiextensions.k8s.io -oname | grep istio.io | xargs -L1 kubectl delete
Alternatively, you can delete your Minikube cluster and then recreate it.
minikube delete
minikube start --memory=4096 --cpus=4