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.
Install Docker
Kubernetes and the kubectl CLI are now included with Docker Desktop for Windows. Docker Desktop for Windows requires Hyper-V on Windows 10 Pro.
resize the VM
Once Docker is installed and running, open Settings by right-clicking the Docker tray icon and configure your VM with 4GB of memory and 4 CPUs in the Advanced settings tab. Click on Apply.
allow sharing of the C: drive
In the Shared Drives settings, enable sharing for the C drive, and enter your Windows password when 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 the helm CLI
Helm is a popular package manager for Kubernetes. The riff runtime and its dependencies are provided as Helm charts.
Download the latest Helm 2.x client CLI for your platform. (Helm 3 is currently in alpha and has not been tested for compatibility with riff)
After copying helm.exe to a directory in your path, initialize the Helm Tiller.
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
A zip with the riff CLI for Windows is available to download from our GitHub releases page. Extract riff.exe and add it to a directory in your path. Once installed, check that the riff CLI version is 0.4.0 or later.
riff --version
riff version 0.4.0 (d1b042f4247d8eb01ee0b9e984926028a2844fe8)
Most riff CLI commands below are formatted for PowerShell which has a different way of interpreting colors. Disable riff CLI colors with the following command.
Add-Content -Path $env:USERPROFILE\.riff.yaml -Value 'no-color: true'
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.
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 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 28s
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 30086.
$INGRESS_PORT = kubectl get svc istio-ingressgateway --namespace istio-system `
--output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}'
$INGRESS_PORT
Invoke the function by POSTing to the ingressgateway 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.
create a Core deployer
The Core Runtime runs riff workloads by creating Kubernetes built-in deployment and service resources.
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 deployer list
NAME TYPE REF SERVICE STATUS AGE
k8s-square function square k8s-square-deployer Ready 21s
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/ `
-H 'Content-Type: application/json' `
-d 8
64
Note that unlike Knative, the Core runtime will not scale deployments down to zero.
Delete the function and deployers
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 reset the Kubernetes cluster (this will remove all state including riff).
