Chapter 12. Configuring functions
12.1. Accessing secrets and config maps from functions using CLI
After your functions have been deployed to the cluster, they can access data stored in secrets and config maps. This data can be mounted as volumes, or assigned to environment variables. You can configure this access interactively by using the Knative CLI, or by manually by editing the function configuration YAML file.
To access secrets and config maps, the function must be deployed on the cluster. This functionality is not available to a function running locally.
If a secret or config map value cannot be accessed, the deployment fails with an error message specifying the inaccessible values.
12.1.1. Modifying function access to secrets and config maps interactively
You can manage the secrets and config maps accessed by your function by using the kn func config
interactive utility. The available operations include listing, adding, and removing values stored in config maps and secrets as environment variables, as well as listing, adding, and removing volumes. This functionality enables you to manage what data stored on the cluster is accessible by your function.
Prerequisites
- The OpenShift Serverless Operator and Knative Serving are installed on the cluster.
-
You have installed the Knative (
kn
) CLI. - You have created a function.
Procedure
Run the following command in the function project directory:
$ kn func config
Alternatively, you can specify the function project directory using the
--path
or-p
option.Use the interactive interface to perform the necessary operation. For example, using the utility to list configured volumes produces an output similar to this:
$ kn func config ? What do you want to configure? Volumes ? What operation do you want to perform? List Configured Volumes mounts: - Secret "mysecret" mounted at path: "/workspace/secret" - Secret "mysecret2" mounted at path: "/workspace/secret2"
This scheme shows all operations available in the interactive utility and how to navigate to them:
kn func config ├─> Environment variables │ ├─> Add │ │ ├─> ConfigMap: Add all key-value pairs from a config map │ │ ├─> ConfigMap: Add value from a key in a config map │ │ ├─> Secret: Add all key-value pairs from a secret │ │ └─> Secret: Add value from a key in a secret │ ├─> List: List all configured environment variables │ └─> Remove: Remove a configured environment variable └─> Volumes ├─> Add │ ├─> ConfigMap: Mount a config map as a volume │ └─> Secret: Mount a secret as a volume ├─> List: List all configured volumes └─> Remove: Remove a configured volume
Optional. Deploy the function to make the changes take effect:
$ kn func deploy -p test
12.1.2. Modifying function access to secrets and config maps interactively by using specialized commands
Every time you run the kn func config
utility, you need to navigate the entire dialogue to select the operation you need, as shown in the previous section. To save steps, you can directly execute a specific operation by running a more specific form of the kn func config
command:
To list configured environment variables:
$ kn func config envs [-p <function-project-path>]
To add environment variables to the function configuration:
$ kn func config envs add [-p <function-project-path>]
To remove environment variables from the function configuration:
$ kn func config envs remove [-p <function-project-path>]
To list configured volumes:
$ kn func config volumes [-p <function-project-path>]
To add a volume to the function configuration:
$ kn func config volumes add [-p <function-project-path>]
To remove a volume from the function configuration:
$ kn func config volumes remove [-p <function-project-path>]
12.2. Configuring your function project using the func.yaml file
The func.yaml
file contains the configuration for your function project. Values specified in func.yaml
are used when you execute a kn func
command. For example, when you run the kn func build
command, the value in the build
field is used. In some cases, you can override these values with command line flags or environment variables.
12.2.1. Referencing local environment variables from func.yaml fields
If you want to avoid storing sensitive information such as an API key in the function configuration, you can add a reference to an environment variable available in the local environment. You can do this by modifying the envs
field in the func.yaml
file.
Prerequisites
- You need to have the function project created.
- The local environment needs to contain the variable that you want to reference.
Procedure
To refer to a local environment variable, use the following syntax:
{{ env:ENV_VAR }}
Substitute
ENV_VAR
with the name of the variable in the local environment that you want to use.For example, you might have the
API_KEY
variable available in the local environment. You can assign its value to theMY_API_KEY
variable, which you can then directly use within your function:Example function
name: test namespace: "" runtime: go ... envs: - name: MY_API_KEY value: '{{ env:API_KEY }}' ...
12.2.2. Adding annotations to functions
You can add Kubernetes annotations to a deployed Serverless function. Annotations enable you to attach arbitrary metadata to a function, for example, a note about the function’s purpose. Annotations are added to the annotations
section of the func.yaml
configuration file.
There are two limitations of the function annotation feature:
-
After a function annotation propagates to the corresponding Knative service on the cluster, it cannot be removed from the service by deleting it from the
func.yaml
file. You must remove the annotation from the Knative service by modifying the YAML file of the service directly, or by using the OpenShift Container Platform web console. -
You cannot set annotations that are set by Knative, for example, the
autoscaling
annotations.
12.2.3. Adding annotations to a function
You can add annotations to a function. Similar to a label, an annotation is defined as a key-value map. Annotations are useful, for example, for providing metadata about a function, such as the function’s author.
Prerequisites
- The OpenShift Serverless Operator and Knative Serving are installed on the cluster.
-
You have installed the Knative (
kn
) CLI. - You have created a function.
Procedure
-
Open the
func.yaml
file for your function. For every annotation that you want to add, add the following YAML to the
annotations
section:name: test namespace: "" runtime: go ... annotations: <annotation_name>: "<annotation_value>" 1
- 1
- Substitute
<annotation_name>: "<annotation_value>"
with your annotation.
For example, to indicate that a function was authored by Alice, you might include the following annotation:
name: test namespace: "" runtime: go ... annotations: author: "alice@example.com"
- Save the configuration.
The next time you deploy your function to the cluster, the annotations are added to the corresponding Knative service.
12.2.4. Additional resources
12.2.5. Adding function access to secrets and config maps manually
You can manually add configuration for accessing secrets and config maps to your function. This might be preferable to using the kn func config
interactive utility and commands, for example when you have an existing configuration snippet.
12.2.5.1. Mounting a secret as a volume
You can mount a secret as a volume. Once a secret is mounted, you can access it from the function as a regular file. This enables you to store on the cluster data needed by the function, for example, a list of URIs that need to be accessed by the function.
Prerequisites
- The OpenShift Serverless Operator and Knative Serving are installed on the cluster.
-
You have installed the Knative (
kn
) CLI. - You have created a function.
Procedure
-
Open the
func.yaml
file for your function. For each secret you want to mount as a volume, add the following YAML to the
volumes
section:name: test namespace: "" runtime: go ... volumes: - secret: mysecret path: /workspace/secret
-
Substitute
mysecret
with the name of the target secret. Substitute
/workspace/secret
with the path where you want to mount the secret.For example, to mount the
addresses
secret, use the following YAML:name: test namespace: "" runtime: go ... volumes: - configMap: addresses path: /workspace/secret-addresses
-
Substitute
- Save the configuration.
12.2.5.2. Mounting a config map as a volume
You can mount a config map as a volume. Once a config map is mounted, you can access it from the function as a regular file. This enables you to store on the cluster data needed by the function, for example, a list of URIs that need to be accessed by the function.
Prerequisites
- The OpenShift Serverless Operator and Knative Serving are installed on the cluster.
-
You have installed the Knative (
kn
) CLI. - You have created a function.
Procedure
-
Open the
func.yaml
file for your function. For each config map you want to mount as a volume, add the following YAML to the
volumes
section:name: test namespace: "" runtime: go ... volumes: - configMap: myconfigmap path: /workspace/configmap
-
Substitute
myconfigmap
with the name of the target config map. Substitute
/workspace/configmap
with the path where you want to mount the config map.For example, to mount the
addresses
config map, use the following YAML:name: test namespace: "" runtime: go ... volumes: - configMap: addresses path: /workspace/configmap-addresses
-
Substitute
- Save the configuration.
12.2.5.3. Setting environment variable from a key value defined in a secret
You can set an environment variable from a key value defined as a secret. A value previously stored in a secret can then be accessed as an environment variable by the function at runtime. This can be useful for getting access to a value stored in a secret, such as the ID of a user.
Prerequisites
- The OpenShift Serverless Operator and Knative Serving are installed on the cluster.
-
You have installed the Knative (
kn
) CLI. - You have created a function.
Procedure
-
Open the
func.yaml
file for your function. For each value from a secret key-value pair that you want to assign to an environment variable, add the following YAML to the
envs
section:name: test namespace: "" runtime: go ... envs: - name: EXAMPLE value: '{{ secret:mysecret:key }}'
-
Substitute
EXAMPLE
with the name of the environment variable. -
Substitute
mysecret
with the name of the target secret. Substitute
key
with the key mapped to the target value.For example, to access the user ID that is stored in
userdetailssecret
, use the following YAML:name: test namespace: "" runtime: go ... envs: - value: '{{ configMap:userdetailssecret:userid }}'
-
Substitute
- Save the configuration.
12.2.5.4. Setting environment variable from a key value defined in a config map
You can set an environment variable from a key value defined as a config map. A value previously stored in a config map can then be accessed as an environment variable by the function at runtime. This can be useful for getting access to a value stored in a config map, such as the ID of a user.
Prerequisites
- The OpenShift Serverless Operator and Knative Serving are installed on the cluster.
-
You have installed the Knative (
kn
) CLI. - You have created a function.
Procedure
-
Open the
func.yaml
file for your function. For each value from a config map key-value pair that you want to assign to an environment variable, add the following YAML to the
envs
section:name: test namespace: "" runtime: go ... envs: - name: EXAMPLE value: '{{ configMap:myconfigmap:key }}'
-
Substitute
EXAMPLE
with the name of the environment variable. -
Substitute
myconfigmap
with the name of the target config map. Substitute
key
with the key mapped to the target value.For example, to access the user ID that is stored in
userdetailsmap
, use the following YAML:name: test namespace: "" runtime: go ... envs: - value: '{{ configMap:userdetailsmap:userid }}'
-
Substitute
- Save the configuration.
12.2.5.5. Setting environment variables from all values defined in a secret
You can set an environment variable from all values defined in a secret. Values previously stored in a secret can then be accessed as environment variables by the function at runtime. This can be useful for simultaneously getting access to a collection of values stored in a secret, for example, a set of data pertaining to a user.
Prerequisites
- The OpenShift Serverless Operator and Knative Serving are installed on the cluster.
-
You have installed the Knative (
kn
) CLI. - You have created a function.
Procedure
-
Open the
func.yaml
file for your function. For every secret for which you want to import all key-value pairs as environment variables, add the following YAML to the
envs
section:name: test namespace: "" runtime: go ... envs: - value: '{{ secret:mysecret }}' 1
- 1
- Substitute
mysecret
with the name of the target secret.
For example, to access all user data that is stored in
userdetailssecret
, use the following YAML:name: test namespace: "" runtime: go ... envs: - value: '{{ configMap:userdetailssecret }}'
- Save the configuration.
12.2.5.6. Setting environment variables from all values defined in a config map
You can set an environment variable from all values defined in a config map. Values previously stored in a config map can then be accessed as environment variables by the function at runtime. This can be useful for simultaneously getting access to a collection of values stored in a config map, for example, a set of data pertaining to a user.
Prerequisites
- The OpenShift Serverless Operator and Knative Serving are installed on the cluster.
-
You have installed the Knative (
kn
) CLI. - You have created a function.
Procedure
-
Open the
func.yaml
file for your function. For every config map for which you want to import all key-value pairs as environment variables, add the following YAML to the
envs
section:name: test namespace: "" runtime: go ... envs: - value: '{{ configMap:myconfigmap }}' 1
- 1
- Substitute
myconfigmap
with the name of the target config map.
For example, to access all user data that is stored in
userdetailsmap
, use the following YAML:name: test namespace: "" runtime: go ... envs: - value: '{{ configMap:userdetailsmap }}'
- Save the file.
12.3. Configurable fields in func.yaml
You can configure some of the func.yaml
fields.
12.3.1. Configurable fields in func.yaml
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.
12.3.1.1. buildEnvs
The buildEnvs
field enables you to set environment variables to be available to the environment that builds your function. Unlike variables set using envs
, a variable set using buildEnv
is not available during function runtime.
You can set a buildEnv
variable directly from a value. In the following example, the buildEnv
variable named EXAMPLE1
is directly assigned the one
value:
buildEnvs: - name: EXAMPLE1 value: one
You can also set a buildEnv
variable from a local environment variable. In the following example, the buildEnv
variable named EXAMPLE2
is assigned the value of the LOCAL_ENV_VAR
local environment variable:
buildEnvs: - name: EXAMPLE1 value: '{{ env:LOCAL_ENV_VAR }}'
12.3.1.2. envs
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:
- Directly from a value.
- From a value assigned to a local environment variable. See the section "Referencing local environment variables from func.yaml fields" for more information.
- From a key-value pair stored in a secret or config map.
- 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.
This examples demonstrates the different ways to set an environment variable:
name: test namespace: "" runtime: go ... envs: - name: EXAMPLE1 1 value: value - name: EXAMPLE2 2 value: '{{ env:LOCAL_ENV_VALUE }}' - name: EXAMPLE3 3 value: '{{ secret:mysecret:key }}' - name: EXAMPLE4 4 value: '{{ configMap:myconfigmap:key }}' - value: '{{ secret:mysecret2 }}' 5 - value: '{{ configMap:myconfigmap2 }}' 6
- 1
- An environment variable set directly from a value.
- 2
- An environment variable set from a value assigned to a local environment variable.
- 3
- An environment variable assigned from a key-value pair stored in a secret.
- 4
- An environment variable assigned from a key-value pair stored in a config map.
- 5
- A set of environment variables imported from key-value pairs of a secret.
- 6
- A set of environment variables imported from key-value pairs of a config map.
12.3.1.3. builder
The builder
field specifies the strategy used by the function to build the image. It accepts values of pack
or s2i
.
12.3.1.4. build
The build
field indicates how the function should be built. The value local
indicates that the function is built locally on your machine. The value git
indicates that the function is built on a cluster by using the values specified in the git
field.
12.3.1.5. volumes
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:
name: test namespace: "" runtime: go ... volumes: - secret: mysecret 1 path: /workspace/secret - configMap: myconfigmap 2 path: /workspace/configmap
12.3.1.6. options
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.
These options are available:
scale
-
min
: The minimum number of replicas. Must be a non-negative integer. The default is 0. -
max
: The maximum number of replicas. Must be a non-negative integer. The default is 0, which means no limit. -
metric
: Defines which metric type is watched by the Autoscaler. It can be set toconcurrency
, which is the default, orrps
. -
target
: Recommendation for when to scale up based on the number of concurrently incoming requests. Thetarget
option can be a float value greater than 0.01. The default is 100, unless theoptions.resources.limits.concurrency
is set, in which casetarget
defaults to its value. -
utilization
: Percentage of concurrent requests utilization allowed before scaling up. It can be a float value between 1 and 100. The default is 70.
-
resources
requests
-
cpu
: A CPU resource request for the container with deployed function. -
memory
: A memory resource request for the container with deployed function.
-
limits
-
cpu
: A CPU resource limit for the container with deployed function. -
memory
: A memory resource limit for the container with deployed function. -
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.
-
This is an example configuration of the scale
options:
name: test namespace: "" runtime: go ... options: scale: min: 0 max: 10 metric: concurrency target: 75 utilization: 75 resources: requests: cpu: 100m memory: 128Mi limits: cpu: 1000m memory: 256Mi concurrency: 100
12.3.1.7. image
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.
12.3.1.8. imageDigest
The imageDigest
field contains the SHA256 hash of the image manifest when the function is deployed. Do not modify this value.
12.3.1.9. labels
The labels
field enables you to set labels on a deployed function.
You can set a label directly from a value. In the following example, the label with the role
key is directly assigned the value of backend
:
labels: - key: role value: backend
You can also set a label from a local environment variable. In the following example, the label with the author
key is assigned the value of the USER
local environment variable:
labels: - key: author value: '{{ env:USER }}'
12.3.1.10. name
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.
12.3.1.11. namespace
The namespace
field specifies the namespace in which your function is deployed.
12.3.1.12. runtime
The runtime
field specifies the language runtime for your function, for example, python
.