Skip to content

Commit 0cfe7b1

Browse files
abrennan89abrennan89
authored
Merge pull request #34442 from rh-max/srvls-func-yaml
SRVOCF-290: Add docs on function project configuration in func.yaml
2 parents 467fda4 + f2ea56e commit 0cfe7b1

File tree

4 files changed

+193
-0
lines changed

4 files changed

+193
-0
lines changed

‎_topic_map.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3130,6 +3130,8 @@ Topics:
31303130
File: serverless-developing-quarkus-functions
31313131
- Name: Using functions with Knative Eventing
31323132
File: serverless-functions-eventing
3133+
- Name: Function project configuration in func.yaml
3134+
File: serverless-functions-yaml
31333135
- Name: Accessing secrets and config maps from Serverless functions
31343136
File: serverless-functions-accessing-secrets-configmaps
31353137
- Name: Adding annotations to functions

‎modules/serverless-functions-func-yaml-environment-variables.adoc‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
[id="serverless-functions-func-yaml-environment-variables_{context}"]
2+
= Referencing local environment variables from func.yaml fields
3+
4+
In the `envs` field in the `func.yaml`, you can put a reference to an environment variable available in the local environment. This can be useful for avoiding storing sensitive information, such as an API key in the function configuration.
5+
6+
.Procedure
7+
8+
* To refer to a local environment variable, use the following syntax:
9+
+
10+
[source]
11+
----
12+
{{ env:ENV_VAR }}
13+
----
14+
+
15+
Substitute `ENV_VAR` with the name of the variable in the local environment that you want to use.
16+
+
17+
For example, you might have the `API_KEY` variable available in the local environment. You can assign its value to the `MY_API_KEY` variable, which you can then directly use within your function:
18+
+
19+
[source,yaml]
20+
----
21+
name: test
22+
namespace: ""
23+
runtime: go
24+
...
25+
envs:
26+
- name: MY_API_KEY
27+
value: '{{ env:API_KEY }}'
28+
----

‎modules/serverless-functions-func-yaml-fields.adoc‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
[id="serverless-functions-func-yaml_{context}"]
2+
= Configurable fields in func.yaml
3+
4+
Many of the fields in `func.yaml` are generated automatically when you create, build, and deploy your function. However, there are also fields that you modify manually to change things, such as the function name or the image name.
5+
6+
== builder
7+
8+
The `builder` field specifies the Buildpack builder image to use when building the function. In most cases, this value should not be changed. When you do change it, use a value that is listed in the `builderMap` field.
9+
10+
== builderMap
11+
12+
Some function runtimes can be built in multiple ways. For example, a Quarkus function can be built for the JVM or as a native binary. The `builderMap` field contains all of the builders available for a given runtime.
13+
14+
== envs
15+
16+
The `envs` field enables you to set environment variables to be available to your function at runtime. You can set an environment variable in several different ways:
17+
18+
. Directly from a value.
19+
. From a value assigned to a local environment variable. See the section "Referencing local environment variables from func.yaml fields" for more information.
20+
. From a key-value pair stored in a secret or config map.
21+
. You can also import all key-value pairs stored in a secret or config map, with keys used as names of the created environment variables.
22+
23+
This examples demonstrates the different ways to set an environment variable:
24+
25+
[source,yaml]
26+
----
27+
name: test
28+
namespace: ""
29+
runtime: go
30+
...
31+
envs:
32+
- name: EXAMPLE1 <1>
33+
value: value
34+
- name: EXAMPLE2 <2>
35+
value: '{{ env:LOCAL_ENV_VALUE }}'
36+
- name: EXAMPLE3 <3>
37+
value: '{{ secret:mysecret:key }}'
38+
- name: EXAMPLE4 <4>
39+
value: '{{ configMap:myconfigmap:key }}'
40+
- value: '{{ secret:mysecret2 }}' <5>
41+
- value: '{{ configMap:myconfigmap2 }}' <6>
42+
----
43+
<1> An environment variable set directly from a value.
44+
<2> An environment variable set from a value assigned to a local environment variable.
45+
<3> An environment variable assigned from a key-value pair stored in a secret.
46+
<4> An environment variable assigned from a key-value pair stored in a config map.
47+
<5> A set of environment variables imported from key-value pairs of a secret.
48+
<6> A set of environment variables imported from key-value pairs of a config map.
49+
50+
== volumes
51+
52+
The `volumes` field enables you to mount secrets and config maps as a volume accessible to the function at the specified path, as shown in the following example:
53+
54+
[source,yaml]
55+
----
56+
name: test
57+
namespace: ""
58+
runtime: go
59+
...
60+
volumes:
61+
- secret: mysecret <1>
62+
path: /workspace/secret
63+
- configMap: myconfigmap <2>
64+
path: /workspace/configmap
65+
----
66+
<1> The `mysecret` secret is mounted as a volume residing at `/workspace/secret`.
67+
<2> The `myconfigmap` config map is mounted as a volume residing at `/workspace/configmap`.
68+
69+
== options
70+
71+
The `options` field enables you to modify Knative Service properties for the deployed function, such as autoscaling. If these options are not set, the default ones are used.
72+
73+
These options are available:
74+
75+
* `scale`
76+
** `min`: The minimum number of replicas. Must be a non-negative integer. The default is 0.
77+
** `max`: The maximum number of replicas. Must be a non-negative integer. The default is 0, which means no limit.
78+
** `metric`: Defines which metric type is watched by the Autoscaler. It can be set to `concurrency`, which is the default, or `rps`.
79+
** `target`: Recommendation for when to scale up based on the number of concurrently incoming requests. The `target` option can be a float value greater than 0.01. The default is 100, unless the `options.resources.limits.concurrency` is set, in which case `target` defaults to its value.
80+
** `utilization`: Percentage of concurrent requests utilization allowed before scaling up. It can be a float value between 1 and 100. The default is 70.
81+
* `resources`
82+
** `requests`
83+
*** `cpu`: A CPU resource request for the container with deployed function.
84+
*** `memory`: A memory resource request for the container with deployed function.
85+
** `limits`
86+
*** `cpu`: A CPU resource limit for the container with deployed function.
87+
*** `memory`: A memory resource limit for the container with deployed function.
88+
*** `concurrency`: Hard Limit of concurrent requests to be processed by a single replica. It can be integer value greater than or equal to 0, default is 0 - meaning no limit.
89+
90+
This is an example configuration of the `scale` options:
91+
92+
[source,yaml]
93+
----
94+
name: test
95+
namespace: ""
96+
runtime: go
97+
...
98+
options:
99+
scale:
100+
min: 0
101+
max: 10
102+
metric: concurrency
103+
target: 75
104+
utilization: 75
105+
resources:
106+
requests:
107+
cpu: 100m
108+
memory: 128Mi
109+
limits:
110+
cpu: 1000m
111+
memory: 256Mi
112+
concurrency: 100
113+
----
114+
115+
== image
116+
117+
The `image` field sets the image name for your function after it has been built. You can modify this field. If you do, the next time you run `kn func build` or `kn func deploy`, the function image will be created with the new name.
118+
119+
== imageDigest
120+
121+
The `imageDigest` field contains the SHA256 hash of the image manifest when the function is deployed. Do not modify this value.
122+
123+
== name
124+
125+
The `name` field defines the name of your function. This value is used as the name of your Knative service when it is deployed. You can change this field to rename the function on subsequent deployments.
126+
127+
== namespace
128+
129+
The `namespace` field specifies the namespace in which your function is deployed.
130+
131+
== runtime
132+
133+
The `runtime` field specifies the language runtime for your function, for example, `python`.
134+
135+
== template
136+
137+
The `template` field specifies the type of the invocation event that triggers your function. You can set it to `http` for triggering with plain HTTP requests or to `events` for triggering with CloudEvents.

‎serverless/functions/serverless-functions-yaml.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
include::modules/serverless-document-attributes.adoc[]
2+
[id="serverless-functions-project-configuration"]
3+
= Function project configuration in func.yaml
4+
include::modules/common-attributes.adoc[]
5+
:context: serverless-functions-yaml
6+
7+
toc::[]
8+
9+
The `func.yaml` file contains the configuration for your function project.
10+
11+
Generally, these values are used when you execute a `kn func` command. For example, when you run the `kn func build` command, the value in the `builder` field is used.
12+
13+
[NOTE]
14+
====
15+
In many cases, you can override these values with command line flags or environment variables.
16+
====
17+
18+
include::modules/serverless-functions-func-yaml-fields.adoc[leveloffset=+1]
19+
include::modules/serverless-functions-func-yaml-environment-variables.adoc[leveloffset=+1]
20+
21+
.Additional resources
22+
23+
* For information on overriding values in the `func.yaml` file, see xref:serverless-functions-getting-started.adoc#serverless-functions-getting-started[Getting started with functions].
24+
* For more information on accessing data in secrets and config maps, see xref:serverless-functions-accessing-secrets-configmaps.adoc#serverless-functions-accessing-secrets-configmaps[Accessing secrets and config maps from Serverless functions].
25+
* For more information on the `scale` set of options, see the link:https://knative.dev/docs/serving/autoscaling/[Knative documentation on Autoscaling].
26+
* For more information on the `resources` set of options, see the https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/[Kubernetes documentation on managing resources for containers] and the https://knative.dev/docs/serving/autoscaling/concurrency/[Knative documentation on configuring concurrency].

0 commit comments

Comments
 (0)