Getting Started on Docker for Windows
The following will help you get started running a riff function with Knative on Docker Community Edition for Windows.
To get started with streaming or with the core runtime, follow these steps first, and then continue with the Streaming or Core runtime docs. Runtimes can be used separately or together.
Install Docker
v0.5 of riff requires Kubernetes v1.15 or later. Docker Desktop requires Hyper-V on Windows 10 Pro.
Download the latest stable release from Docker. Kubernetes and the kubectl CLI are included.
resize the VM
Once Docker is installed and running, open Settings by right-clicking the Docker tray icon and configure your VM with 5GB of memory and 4 CPUs in the Advanced settings tab. Click on Apply.
allow sharing of the C: drive
In the File Sharing settings under Resources, enable sharing for the C drive, and enter your Windows password if prompted. This will be used for persistent volume claims to provide cache storage during function builds.
enable Kubernetes
Enable Kubernetes in the Kubernetes tab, click on Apply, and wait for the installation to complete and the cluster to start. If there is no Kubernetes tab, you may need to switch to Linux containers first.
Confirm that your kubectl context is pointing to "docker-desktop".
kubectl config current-context
If you previously had a different cluster configured, switch your kubectl context to "docker-desktop" using a PowerShell or command window.
kubectl config use-context docker-desktop
monitor your cluster
At this point it is useful to monitor your Kubernetes cluster. If you have git bash installed, create a bash script called watch, with the following content.
#!/bin/bash
ARGS="${@}"
clear;
while(true); do
OUTPUT=`$ARGS`
clear
echo -e "${OUTPUT[@]}"
sleep 1
done
Start by watching all namespaces to confirm that Kubernetes is running.
watch kubectl get pod --all-namespaces
NAMESPACE NAME READY STATUS RESTARTS AGE
docker compose-6c67d745f6-gcjcl 1/1 Running 0 19s
docker compose-api-57ff65b8c7-sz7g4 1/1 Running 0 19s
kube-system coredns-fb8b8dccf-5t7bx 1/1 Running 1 90s
kube-system coredns-fb8b8dccf-ltlwf 1/1 Running 1 90s
kube-system etcd-docker-desktop 1/1 Running 0 23s
kube-system kube-apiserver-docker-desktop 1/1 Running 0 39s
kube-system kube-controller-manager-docker-desktop 1/1 Running 0 20s
kube-system kube-proxy-6q844 1/1 Running 0 89s
kube-system kube-scheduler-docker-desktop 1/1 Running 0 32s
Install kapp
kapp is a simple deployment tool for Kubernetes. The riff runtime and its dependencies are provided as standard Kubernetes yaml files, that can be installed with kapp.
Download a recent binary for your platform from github. Move it into a directory on your path, and make it executable. Complete kapp installation instructions can be found here
Validate the installation.
kapp version
Client Version: 0.18.0
Succeeded
Install ytt
ytt is a tool for templating yaml. It can be used to apply changes to the distributed Kubernetes yamls files used to install riff.
Download a recent binary for your platform from github. Move it into a directory on your path, and make it executable. Complete ytt installation instructions can be found here
Validate the installation.
ytt version
Version: 0.23.0
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.5.0.
riff --version
riff version 0.5.0 (f96cf2f5ca6fddfaf4716c0045f5f142da2d3828)
Install riff Using kapp
riff can be installed with optional runtimes. The riff build system is always installed, and is required by each runtime.
NOTE: If you have riff v0.4.0 installed then you must first uninstall that version. See instructions in the v0.4.0 documentation.
Create a namespace for kapp to store configuration:
kubectl create ns apps
install riff Build
Each kapp command below will display a list of changes and then prompt for confirmation. Press y to proceed. To auto-confirm, append a -y flag to the command.
kapp deploy -n apps -a cert-manager -f https://storage.googleapis.com/projectriff/release/0.5.0/cert-manager.yaml
kapp deploy -n apps -a kpack -f https://storage.googleapis.com/projectriff/release/0.5.0/kpack.yaml
kapp deploy -n apps -a riff-builders -f https://storage.googleapis.com/projectriff/release/0.5.0/riff-builders.yaml
kapp deploy -n apps -a riff-build -f https://storage.googleapis.com/projectriff/release/0.5.0/riff-build.yaml
install Contour ingress controller
The Contour ingress controller can be used by both Knative and Core runtimes.
# ytt is used to convert the ingress service to NodePort because Docker for Widows does not support `LoadBalancer` services.
ytt -f https://storage.googleapis.com/projectriff/release/0.5.0/contour.yaml -f https://storage.googleapis.com/projectriff/charts/overlays/service-nodeport.yaml --file-mark contour.yaml:type=yaml-plain | kapp deploy -n apps -a contour -f - -y
install riff Knative Runtime
To install riff Knative Runtime and it's dependencies:
kapp deploy -n apps -a knative -f https://storage.googleapis.com/projectriff/release/0.5.0/knative.yaml
kapp deploy -n apps -a riff-knative-runtime -f https://storage.googleapis.com/projectriff/release/0.5.0/riff-knative-runtime.yaml
verify riff installation
Resources may be missing if the corresponding runtime was not installed.
riff doctor
NAMESPACE STATUS
default ok
riff-system ok
RESOURCE NAMESPACE NAME READ WRITE
configmaps riff-system builders allowed n/a
configmaps default * allowed allowed
secrets default * allowed allowed
pods default * allowed n/a
pods/log default * allowed n/a
applications.build.projectriff.io default * allowed allowed
containers.build.projectriff.io default * allowed allowed
functions.build.projectriff.io default * allowed allowed
deployers.core.projectriff.io default * missing missing
processors.streaming.projectriff.io default * missing missing
streams.streaming.projectriff.io default * missing missing
inmemoryproviders.streaming.projectriff.io default * missing missing
kafkaproviders.streaming.projectriff.io default * missing missing
pulsarproviders.streaming.projectriff.io default * missing missing
adapters.knative.projectriff.io default * allowed allowed
deployers.knative.projectriff.io default * 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.
riff credential apply my-creds --set-default-image-prefix --docker-hub ???
You will be prompted to provide the password.
On Windows, a known issue prevents the password prompt from working in git bash. Use the Windows PowerShell or Command terminal instead.
Create a function from a GitHub repo
This riff command (formatted for PowerShell) 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 dockerhub 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 get the built image by listing functions.
riff function list
NAME LATEST IMAGE ARTIFACT HANDLER INVOKER STATUS AGE
square index.docker.io/$DOCKER_ID/square@sha256:ac089ca183368aa831597f94a2dbb462a157ccf7bbe0f3868294e15a24308f68 square.js <empty> <empty> Ready 1m13s
Due to differences between Windows and Linux file permissions, local builds are not supported on Windows. We suggest building from a git repository as a workaround.
Create a Knative deployer
The Knative Runtime is only available on clusters with 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 --ingress-policy External --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 28s
invoke the function
Knative configures HTTP routes on the ingress controller. Requests are routed by hostname.
Look up the nodePort for the ingress gateway; you should see a port value like 30086.
$INGRESS_PORT = kubectl get svc envoy-external --namespace projectcontour `
--output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}'
$INGRESS_PORT
Invoke the function by POSTing to the ingress gateway on the nodePort, passing hostname and content-type as headers.
curl http://localhost:$INGRESS_PORT/ `
-H 'Host: knative-square.default.example.com' `
-H 'Content-Type: application/json' `
-d 7
49
The command above uses OSS curl which can be installed from an Admin PowerShell using choco install curl (assumes Chocolatey).
Remove the built-in PowerShell curl alias with Remove-item alias:curl.
Delete the function and deployer
riff knative deployer delete knative-square
riff function delete square
Uninstalling riff
You can reset the Kubernetes cluster (this will remove all state including riff).
Alternatively, you can use the following commands to uninstall riff:
remove any riff resources
kubectl delete riff --all-namespaces --all
remove riff Streaming Runtime
kapp delete -n apps -a riff-streaming-runtime
kapp delete -n apps -a keda
remove riff Core Runtime (if installed)
kapp delete -n apps -a riff-core-runtime
remove riff Knative Runtime (if installed)
kubectl delete knative --all-namespaces --all
kapp delete -n apps -a riff-knative-runtime
kapp delete -n apps -a knative
remove Contour
kapp delete -n apps -a contour
remove riff Build
kapp delete -n apps -a riff-build
kapp delete -n apps -a riff-builders
kapp delete -n apps -a kpack
kapp delete -n apps -a cert-manager