func/docs/getting_started_kubernetes.md

Getting Started with Kubernetes

Functions can be deployed to any kubernetes cluster which has been configured to support function workloads. This guide details how to set up and configure a kubernetes cluster accordingly.

This guide was developed using the dependency versions listed in their requisite sections. Instructions may deviate slightly as these projects are generally under active development. It is recommended to use the links to the official documentation provided in each section.

Provision a Cluster

Any Kubernetes-compatible API should be capable. Included herein are instructions for two popular variants: Kind and EKS.

Provision using Kind

Provision using Amazon EKS

Configuring the Cluster

Once access to a kubernetes-compatible cluster has been established, it will need to be configured to handle Function workloads. This includes Knative Serving and Eventing, the Kourier networking layer, and CertManager with the LetsEncrypt certificate provider.

Create a namespace for your Functions:

kubectl create namespace func

Set the default namespace for subsequent commands:

kubectl config set-context --current --namespace=func

Serving

Docs: https://knative.dev/docs/install/any-kubernetes-cluster/ )

Serving with Kourier networking

kubectl apply --filename https://github.com/knative/serving/releases/download/knative-v1.5.0/serving-crds.yaml
kubectl apply --filename https://github.com/knative/serving/releases/download/knative-v1.5.0/serving-core.yaml
kubectl apply --filename https://github.com/knative/net-kourier/releases/download/knative-v1.5.0/kourier.yaml

Update the networking layer to

• Use Kourier
• use TLS
• Redirect HTTP requests to HTTPS
• Add func subdomain annotations

kubectl apply -f knative/config-network.yaml

Note: for environments where Load Balancers are not supported (such as local Kind clusters), the Kourier service will be stuck in a pending state as it is awaiting the underlying infrastructure to provision a load-balancer. This can be solved by updating the Kourier configuration to type NodePort with its networking service attached to the host at ports HTTP 30080 and HTTPS 30443, you can use the following patch file:

kubectl patch -n kourier-system services/kourier -p "$(cat knative/config-kourier-nodeport.yaml)"

Domains

Configure cluster-wide domain TLD+1 by editing k8s/config-domain.yaml to include supported domains. First edit knative/config-domain.yaml to contain your domain of choice and then apply:

kubectl apply -f knative/config-domain.yaml

Note that this step is pending automation

DNS

For external routing to the cluster, register domain(s) to be used with a registrar and configure a DNS CNAME to the DNS or IP returned from: (May also register a wildcard subdomain match).

kubectl --namespace kourier-system get service kourier

For local installations such as Kind, the Kourier networking layer is configured as a local port, so DNS can be resolved by modifying one's local DNS resolver, or /etc/hosts, to point to the local host.

TLS

In order to provision HTTPS routes, we optionally set up a Certificate Manager for the cluster. In this example we configure it to use LetsEncrypt certificates vi a certificate provider and CloudFlare as the DNS provider.

Cert-Manager

Docs: https://cert-manager.io/docs/installation/kubernetes/

kubectl apply --validate=false -f https://github.com/cert-manager/cert-manager/releases/download/v1.9.0-beta.1/cert-manager.yaml

Create a Cluster Issuer by updating tls/letsencrypt-issuer.yaml with an email addresses for the LetsEncrypt registration and for the associated CloudFlare account:

kubectl apply -f tls/letsencrypt-issuer.yaml

Generate a token with CloudFlare with the following settings:

• Permission: Zone - Zone - Read
• Permission: Zone - DNS - Edit
• Zone Resources: Include - All ZOnes

Base64 encode the token:

echo -n "$CLOUDFLARE_TOKEN" | base64

Update the tls/cloudflare-secret.yaml with the base64-encoded token value and create the secret:

kubectl apply -f tls/cloudflare-secret.yaml

KNative Serving Cert-Manager Integration

Install the latest networking certmanager packaged with KNative Serving: Docs: https://knative.dev/docs/serving/using-auto-tls/

kubectl apply --filename https://github.com/knative-sandbox/net-certmanager/releases/download/knative-v1.5.0/release.yaml

Edit config-certmanager to reference the letsencrypt issuer. There should be an issuerRef pointing to a ClusterIssuer of name letsencrypt-issuer:

kubectl edit configmap config-certmanager --namespace knative-serving

Eventing

Eventing with In-memory channels, a Channel broker, and enable the default broker in the func namespace.

kubectl apply --filename https://github.com/knative/eventing/releases/download/knative-v1.5.1/eventing-crds.yaml
kubectl apply --filename https://github.com/knative/eventing/releases/download/knative-v1.5.1/eventing-core.yaml
kubectl apply --filename https://github.com/knative/eventing/releases/download/knative-v1.5.1/in-memory-channel.yaml
kubectl apply --filename https://github.com/knative/eventing/releases/download/knative-v1.5.1/mt-channel-broker.yaml

GitHub events source:

kubectl apply --filename https://github.com/knative/eventing-contrib/releases/download/v0.16.0/github.yaml

Learn more about the GitHub source at https://knative.dev/docs/eventing/samples/github-source/index.html

Enable Broker for func namespace:

kubectl label namespace func knative-eventing-injection=enabled

Monitoring

Optionally the addition of the metrics-server API allows one to run kubectl top nodes and kubectl top pods. It can be installed with:

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/download/v0.3.7/components.yaml

Note that on local clusters such as Kind, it is necessary to add the following arguments to the metrics-server deployment in kube-system:

    args:
        - --kubelet-insecure-tls
        - --kubelet-preferred-address-types=InternalIP

Troubleshooting

Get the installed KNative serving and Eventing versions

kubectl get namespace knative-serving -o 'go-template={{index .metadata.labels "serving.knative.dev/release"}}'
kubectl get namespace knative-eventing -o 'go-template={{index .metadata.labels "eventing.knative.dev/release"}}'