Skip to content

Commit 5fd3100

Browse files
adamwgtr0njavolta
adamwg
and
tr0njavolta
authored
Document the Knative function runtime (#1009)
* Document the Knative function runtime Add a guide for enabling function scale-to-zero with the knative function runtime. This includes a basic knative installation (along with its cert-manager dependency). Fixes CONTENT-24 Fixes CTP-30 * Vale fixes in scale-to-zero docs * Update with clarity and consistency --------- Co-authored-by: Rae Sharp <resharp20@gmail.com>
1 parent 1ac4e35 commit 5fd3100

File tree

2 files changed

+310
-0
lines changed

2 files changed

+310
-0
lines changed

‎docs/manuals/uxp/howtos/function-scale-to-zero.md‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
---
2+
title: Function Scale-to-Zero
3+
description: "Enable the Knative function runtime to autoscale functions to zero"
4+
plan: "standard"
5+
---
6+
7+
<Standard />
8+
9+
This guide walks through how to enable the Knative function runtime in Upbound
10+
Crossplane (UXP). The Knative function runtime runs functions using [Knative]
11+
services instead of standard Kubernetes deployments, allowing functions to
12+
scale to zero when not called. This helps reduce resource
13+
consumption from functions in a Kubernetes cluster running UXP.
14+
15+
## Prerequisites
16+
17+
Before you enable the Knative function runtime, make sure you have:
18+
19+
* A running UXP control plane
20+
* A valid Standard or Development license applied to your control plane
21+
22+
This guide also requires:
23+
24+
* [cert-manager]
25+
* [Knative]
26+
27+
## Install required dependencies
28+
29+
:::tip
30+
If you already have Knative and cert-manager installed, skip to [creating and
31+
configuring the cert-manager `Issuer`][issuer], which is required for this
32+
feature.
33+
:::
34+
35+
### Install cert-manager
36+
37+
Use Helm to install cert-manager:
38+
39+
```bash
40+
helm install \
41+
cert-manager oci://quay.io/jetstack/charts/cert-manager \
42+
--version v1.18.2 \
43+
--namespace cert-manager \
44+
--create-namespace \
45+
--set crds.enabled=true
46+
```
47+
48+
### Install Knative Serving
49+
50+
:::tip
51+
52+
Knative supports many installation options. This guide provides sensible
53+
defaults, but if you wish to customize your Knative installation you can follow
54+
the [Knative installation documentation]. In particular, if you already use
55+
Istio in your cluster, you may wish to use it for Knative ingress instead of the
56+
Kourier ingress gateway documented here.
57+
58+
:::
59+
60+
Install the Knative Serving components using their manifests:
61+
62+
```bash
63+
kubectl apply -f https://github.com/knative/serving/releases/download/knative-v1.19.7/serving-crds.yaml
64+
kubectl apply -f https://github.com/knative/serving/releases/download/knative-v1.19.7/serving-core.yaml
65+
```
66+
67+
Install the [Kourier] ingress controller:
68+
69+
```bash
70+
kubectl apply -f https://github.com/knative-extensions/net-kourier/releases/download/knative-v1.19.6/kourier.yaml
71+
```
72+
73+
Update the Knative configuration so it uses Kourier for ingress and uses TLS to
74+
secure endpoints within the cluster:
75+
76+
```bash
77+
kubectl patch configmap/config-network \
78+
--namespace knative-serving \
79+
--type merge \
80+
--patch '{"data":{"ingress-class":"kourier.ingress.networking.knative.dev","cluster-local-domain-tls":"Enabled"}}'
81+
82+
```
83+
## Create a cert-manager `Issuer` {#cert-issuer}
84+
85+
Create a cert-manager `Issuer` using the Crossplane CA certificate. Knative uses
86+
this to generate certificates for function services that Crossplane calls:
87+
88+
```bash
89+
kubectl apply -f - --server-side <<EOF
90+
apiVersion: cert-manager.io/v1
91+
kind: Issuer
92+
metadata:
93+
name: crossplane-issuer
94+
namespace: crossplane-system
95+
spec:
96+
ca:
97+
secretName: crossplane-root-ca
98+
EOF
99+
```
100+
101+
102+
Configure Knative to use the cert-manager `Issuer` you created in the previous
103+
section:
104+
105+
```bash
106+
kubectl apply -f - --server-side <<EOF
107+
apiVersion: v1
108+
kind: ConfigMap
109+
metadata:
110+
labels:
111+
app.kubernetes.io/component: controller
112+
app.kubernetes.io/name: knative-serving
113+
app.kubernetes.io/version: 1.17.0
114+
networking.knative.dev/certificate-provider: cert-manager
115+
name: config-certmanager
116+
namespace: knative-serving
117+
data:
118+
clusterLocalIssuerRef: |
119+
kind: Issuer
120+
name: crossplane-issuer
121+
namespace: crossplane-system
122+
issuerRef: |
123+
kind: Issuer
124+
name: crossplane-issuer
125+
namespace: crossplane-system
126+
systemInternalIssuerRef: |
127+
kind: Issuer
128+
name: crossplane-issuer
129+
namespace: crossplane-system
130+
EOF
131+
```
132+
133+
Restart the Knative controllers to apply the configuration:
134+
```bash
135+
kubectl -n knative-serving rollout restart deploy/activator
136+
kubectl -n knative-serving rollout restart deploy/controller
137+
```
138+
139+
## Enable the Knative function runtime
140+
141+
<Tabs>
142+
<TabItem value="Helm" label="Helm">
143+
144+
1. Add the `upbound-stable` chart repository:
145+
```bash
146+
helm repo add upbound-stable https://charts.upbound.io/stable && helm repo update
147+
```
148+
2. Install Upbound Crossplane:
149+
```bash
150+
helm install crossplane \
151+
--namespace crossplane-system \
152+
--create-namespace \
153+
upbound-stable/crossplane \
154+
--devel \
155+
--set "upbound.manager.args[0]=--enable-knative-runtime"
156+
```
157+
158+
:::note
159+
Helm requires the use of `--devel` flag for versions with suffixes, like
160+
`v2.0.0-up.1`. The Helm repository Upbound uses is the stable repository, so use
161+
of that flag is only a workaround. You will always get the latest stable version
162+
of Upbound Crossplane.
163+
:::
164+
165+
</TabItem>
166+
167+
<TabItem value="up CLI" label="up CLI">
168+
169+
Make sure you have the up CLI installed and that your current kubeconfig context
170+
points to the desired Kubernetes cluster, then run the following command:
171+
172+
```bash
173+
up uxp upgrade --set "upbound.manager.args[0]=--enable-knative-runtime"
174+
```
175+
176+
</TabItem>
177+
</Tabs>
178+
179+
## Configure the Knative function runtime
180+
181+
Runtime configurations control how UXP deploys and operates Functions in your
182+
cluster. The `UpboundRuntimeConfig` resource controls UXP-specific features such
183+
as the Knative function runtime.
184+
185+
To configure UXP to run all functions with the Knative runtime, update the
186+
default `UpboundRuntimeConfig` to enable the Knative runtime:
187+
188+
```bash
189+
kubectl patch upboundruntimeconfig default --type=merge -p='{"spec":{"capabilities":["FunctionKnativeRuntime"]}}'
190+
```
191+
192+
## Test scale-to-zero
193+
194+
The Knative function runtime automatically scales down functions that aren't
195+
being actively used. This could happen because no compositions are using a given
196+
function, or because nothing has changed to cause reconciliation of a composite
197+
resource.
198+
199+
To see scale-to-zero in action, install an example Configuration that depends on
200+
some Functions:
201+
202+
```bash
203+
up controlplane configuration install xpkg.upbound.io/upbound/configuration-app:v0.12.1
204+
```
205+
206+
You should see the packages become ready:
207+
208+
```bash
209+
$ kubectl get pkg
210+
NAME INSTALLED HEALTHY PACKAGE AGE
211+
configuration.pkg.crossplane.io/upbound-configuration-app True True xpkg.upbound.io/upbound/configuration-app:v0.12.1 64s
212+
213+
NAME INSTALLED HEALTHY PACKAGE AGE
214+
function.pkg.crossplane.io/crossplane-contrib-function-auto-ready True True xpkg.upbound.io/crossplane-contrib/function-auto-ready:v0.5.1 60s
215+
function.pkg.crossplane.io/upbound-configuration-appxapp True True xpkg.upbound.io/upbound/configuration-app_xapp@sha256:3975a44efa4db7644284a10a0f832f7a76e7f044313fd74e094f4f6339d8247e 58s
216+
217+
NAME INSTALLED HEALTHY PACKAGE AGE
218+
provider.pkg.crossplane.io/upbound-provider-helm True True xpkg.upbound.io/upbound/provider-helm:v0.21.1 63s
219+
```
220+
221+
Because the Knative function runtime is active, each Function has an associated
222+
Knative Service instead of a standard Kubernetes Deployment:
223+
224+
```bash
225+
$ kubectl -n crossplane-system get kservice
226+
NAME URL LATESTCREATED LATESTREADY READY REASON
227+
crossplane-contrib-function-auto-ready https://crossplane-contrib-function-auto-ready.crossplane-system.svc.cluster.local crossplane-contrib-function-auto-ready-23e6fdeb2c05 crossplane-contrib-function-auto-ready-23e6fdeb2c05 True
228+
upbound-configuration-appxapp https://upbound-configuration-appxapp.crossplane-system.svc.cluster.local upbound-configuration-appxapp-3975a44efa4d upbound-configuration-appxapp-3975a44efa4d True
229+
```
230+
231+
When you first install the configuration, Knative scales up the Functions, so
232+
each Function has a Pod:
233+
234+
```bash
235+
$ kubectl -n crossplane-system get pod -l serving.knative.dev/service
236+
NAME READY STATUS RESTARTS AGE
237+
crossplane-contrib-function-auto-ready-23e6fdeb2c05-deployjcgth 2/2 Running 0 57s
238+
upbound-configuration-appxapp-3975a44efa4d-deployment-66c5cdgzf 2/2 Running 0 56s
239+
```
240+
241+
Since there are no XRs in the cluster, nothing calls the functions and
242+
Knative scales them down to zero:
243+
244+
```bash
245+
$ kubectl -n crossplane-system get pod -l serving.knative.dev/service
246+
No resources found in crossplane-system namespace.
247+
```
248+
249+
Create an XR to trigger the composition pipeline to call the function:
250+
251+
```bash
252+
kubectl apply -f - <<EOF
253+
apiVersion: platform.upbound.io/v1alpha1
254+
kind: XApp
255+
metadata:
256+
name: test-app
257+
namespace: default
258+
spec:
259+
parameters:
260+
helm:
261+
wait: false
262+
providerConfigName: uptest
263+
passwordSecretRef:
264+
namespace: default
265+
name: configuration-app-mariadb
266+
writeConnectionSecretToRef:
267+
name: configuration-app
268+
namespace: default
269+
EOF
270+
```
271+
272+
Within seconds, Pods start for the Functions:
273+
274+
```bash
275+
$ kubectl -n crossplane-system get pod -l serving.knative.dev/service
276+
NAME READY STATUS RESTARTS AGE
277+
crossplane-contrib-function-auto-ready-23e6fdeb2c05-deploylzwkc 2/2 Running 0 5s
278+
upbound-configuration-appxapp-3975a44efa4d-deployment-66c5tpfk2 2/2 Running 0 7s
279+
```
280+
281+
## Disable the Knative function runtime
282+
283+
To disable the Knative function runtime, remove the `FunctionKnativeRuntime`
284+
capability from the default `UpboundRuntimeConfig`:
285+
286+
```bash
287+
kubectl patch upboundruntimeconfig default --type=merge -p='{"spec":{"capabilities":[]}}'
288+
```
289+
290+
The runtime controller deletes the Knative services for the functions and creates
291+
Deployments instead:
292+
293+
```bash
294+
$ kubectl -n crossplane-system get kservice
295+
No resources found in crossplane-system namespace.
296+
297+
$ kubectl -n crossplane-system get deployment
298+
NAME READY UP-TO-DATE AVAILABLE AGE
299+
...
300+
crossplane-contrib-function-auto-ready-23e6fdeb2c05 1/1 1 1 5m11s
301+
upbound-configuration-appxapp-3975a44efa4d 1/1 1 1 5m11s
302+
...
303+
```
304+
305+
[Knative]: https://knative.dev
306+
[issuer]: #cert-issuer
307+
[cert-manager]: https://cert-manager.io
308+
[Kourier]: https://github.com/knative-extensions/net-kourier
309+
[Knative installation documentation]: https://knative.dev/docs/install/

‎utils/vale/styles/Upbound/spelling-exceptions.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ Grafana
5959
Istio
6060
istio
6161
image_uri
62+
Knative
6263
kubeconfig
6364
kubectl
6465
Kustomize

0 commit comments

Comments
 (0)