This document provides a reference of the Nuclio function configuration.
- Basic configuration structure
- Function Metadata (
metadata) - Function Specification (
spec) - Function Status
- See also
The basic structure of the Nuclio function configuration resembles Kubernetes resource definitions, and includes
the apiVersion, kind, metadata, spec, and status sections. Following is an example of a minimal definition:
apiVersion: "nuclio.io/v1"
kind: NuclioFunction
metadata:
name: example
spec:
image: example:latestThe metadata section includes the following attributes:
| Path | Type | Description |
|---|---|---|
| name | string | The name of the function |
| namespace | string | A level of isolation provided by the platform (e.g., Kubernetes) |
| labels | map | A list of key-value tags that are used for looking up the function (immutable, can't update after first deployment) |
| annotations | map | A list of annotations based on the key-value tags |
metadata:
name: example
namespace: nuclio
labels:
l1: lv1
l2: lv2
l3: 100
annotations:
a1: av1 The spec section contains the requirements and attributes and has the following elements:
| Path | Type | Description |
|---|---|---|
description |
string | A textual description of the function |
handler |
string | The entry point to the function, in the form of package:entrypoint; varies slightly between runtimes, see the appropriate runtime documentation for specifics |
runtime |
string | The name of the language runtime - golang \ python:3.9 \ python:3.10 \ python:3.11 \ python:3.12 \ shell \ java \ nodejs |
image |
string | The name of the function's container image — used for the image if spec.build.codeEntryType isimage; see Code-Entry Types |
env |
map | A name-value environment-variables tuple; it's also possible to reference secrets from the map elements, as demonstrated in the specification example |
envFrom |
[]v1.EnvFromSource | List of sources from which the function takes environment variables (ConfigMaps/Secrets). It is being merged with the correspondent platform runtime.common.envFrom. The function's values have a higher priority. |
volumes |
map | A map in an architecture similar to Kubernetes volumes, for Docker deployment |
replicas |
int | The number of desired instances; 0 for auto-scaling. |
minReplicas |
int | The minimum number of replicas |
platform.attributes.restartPolicy.name |
string | The name of the restart policy for the function-image container; applicable only to Docker platforms |
platform.attributes.restartPolicy.maximumRetryCount |
int | The maximum retries for restarting the function-image container; applicable only to Docker platforms |
platform.attributes.mountMode |
string | Function mount mode, which determines how Docker mounts the function configurations - bind \ volume (default: bind); applicable only to Docker platforms |
platform.attributes.healthCheckInterval |
string,int | The interval between health checks, in seconds or as a duration string (e.g., 5s, 1m, 1h). |
maxReplicas |
int | The maximum number of replicas |
targetCPU |
int | Target CPU when auto scaling, as a percentage (default: 75%) |
dataBindings |
See reference | A map of data sources used by the function ("data bindings") |
triggers.(name).numWorkers |
int | The number of concurrent requests this trigger can process |
triggers.(name).maxWorkers |
int | Deprecated: The max number of concurrent requests this trigger can process |
triggers.(name).kind |
string | The trigger type (kind) - cron \ eventhub \ http \ kafka-cluster \ kinesis \ nats \ rabbit-mq |
triggers.(name).url |
string | The trigger specific URL (not used by all triggers) |
triggers.(name).workerTerminationTimeout |
string | Waiting time for workers to drop or ACK on events before rebalance in seconds or as a duration string (e.g., 5s, 1m, 1h); 10s by default. It is used only for Kafka trigger now. |
triggers.(name).annotations |
list of strings | Annotations to be assigned to the trigger, if applicable |
triggers.(name).workerAvailabilityTimeoutMilliseconds |
int | The number of milliseconds to wait for a worker if one is not available. 0 = never wait (default: 10000, which is 10 seconds) |
triggers.(name).attributes |
See reference | The per-trigger attributes |
triggers.(name).batch.mode |
string | Batching mode, can be enable/disable (see batching) |
triggers.(name).batch.batchSize |
int | Size of batch |
triggers.(name).batch.timeout |
string | Timeout after which the batch is sent to runtime even if the batch is not full yet (e.g., 5s, 1ms, 1m) |
triggers.(name).mode |
string | Event processing mode. Can be sync/async (sync is default). async is supported for python runtime with http trigger only. More information about async mode here |
triggers.(name).async.minConnectionsNumber |
int | The minimum number of connections to maintain for asynchronous triggers (default is 1000). |
triggers.(name).async.maxConnectionsNumber |
int | The maximum number of connections to maintain for asynchronous triggers (default is 1000). |
triggers.(name).async.connectionCreationMode |
string | The mode of connection creation for asynchronous triggers. Can be static or dynamic (static is default). |
triggers.(name).async.connectionAvailabilityTimeout |
string | Timeout during which connection must be allocated for an event, in the format supported for the Duration parameter of the time.ParseDuration Go function |
build.path |
string | The URL of a GitHub repository or an archive-file that contains the function code — for the git, github or archive in spec.build.codeEntryType — or the URL of a function source-code file; see Code-Entry Types |
build.functionSourceCode |
string | Base-64 encoded function source code for the spec.build.sourceCode; see Code-Entry Types |
build.registry |
string | The container image repository to which the built image will be pushed |
build.noBaseImagePull |
string | Do not pull any base images when building, use local images only |
build.noCache |
string | Do not use any caching when building container images |
build.baseImage |
string | The name of a base container image from which to build the function's processor image |
build.commands |
list of string | Commands run opaquely as part of container image build |
build.directives |
map | Build directives in the form of key to list of kind and value. Supported keys are preCopy and postCopy, which determine when to run the directives. Example: { "postCopy": [{ "kind": "RUN", "value": "pip install -r /opt/nuclio/requirements.txt" }]} |
build.onbuildImage |
string | The name of an "onbuild" container image from which to build the function's processor image; the name can include {{ .Label }} and {{ .Arch }} for formatting |
build.image |
string | The name of the built container image (default: the function name) |
build.args |
map | Build args to pass to the docker file when building the function. The map is a key-value for each argument |
build.flags |
[]string | Build flags to pass to the container builder-pusher. List of flags is here: Kaniko - https://github.com/GoogleContainerTools/kaniko/blob/main/README.md#additional-flags, Docker - https://docs.docker.com/engine/reference/commandline/image_build/ |
build.codeEntryType |
string | The function's code-entry type - archive \ git \ github \ image \ s3 \ sourceCode; see Code-Entry Types |
build.codeEntryAttributes |
See reference | Code-entry attributes, which provide information for downloading the function when using the github, s3, or archive as spec.build.codeEntryType |
build.builderServiceAccount |
string | The name of the service account for the builder pods (relevant for a kubernetes setup with kaniko container builder |
runRegistry |
string | The container image repository from which the platform will pull the image |
runtimeAttributes |
See reference | Runtime-specific attributes |
resources |
See reference | Limit resources allocated to deployed function |
readinessTimeoutSeconds |
int | Number of seconds that the controller will wait for the function to become ready before declaring failure (default: 60) |
waitReadinessTimeoutBeforeFailure |
bool | Wait for the expiration of the readiness timeout period even if the deployment fails or isn't expected to complete before the readinessTimeout expires |
avatar |
string | Base64 representation of an icon to be shown in UI for the function (Deprecated) |
eventTimeout |
string | Global event timeout, in the format supported for the Duration parameter of the time.ParseDuration Go function |
streamChunkTimeout |
string | Timeout per chunk when streaming response from a runtime. Applied for all chunks except the 1st one, eventTimeout is applied for the 1st one. In the format supported for the Duration parameter of the time.ParseDuration Go function. |
securityContext.runAsUser |
int | The user ID (UID) for running the entry point of the container process |
securityContext.runAsGroup |
int | The group ID (GID) for running the entry point of the container process |
securityContext.fsGroup |
int | A supplemental group to add and use for running the entry point of the container process |
serviceType |
string | Describes ingress methods for a service |
affinity |
v1.Affinity | Set of rules used to determine the node that schedule the pod |
nodeSelector |
map | Constrain function pod to a node by key-value pairs selectors. Node selectors with empty values are automatically removed from the map. |
nodeName |
string | Constrain function pod to a node by node name |
priorityClassName |
string | Indicates the importance of a function pod relatively to other function pods |
preemptionPolicy |
string | Function pod preemption policy (one of Never or PreemptLowerPriority) |
tolerations |
[]v1.Toleration | Function pod tolerations |
disableSensitiveFieldsMasking |
bool | Don't scrub sensitive information form the function configuration |
customScalingMetricSpecs |
autosv2.MetricSpec | Custom function horizontal pod autoscaling metric spec, allowing to override the default |
devices |
[]string | List of devices to be made available to the function. Relevant for local platform only. (e.g. /dev/video0:/dev/video0:rwm) |
disableDefaultHttpTrigger |
*bool | Disable default http trigger creation. If flag isn’t set, value is taken from the platform config. |
initContainers |
[]*v1.Container | See kubernetes docs for more info |
sidecars |
[]*v1.Container | See kubernetes docs for more info |
readinessProbe |
*v1.Probe | See kubernetes docs for more info . The configurable fields: - initialDelaySeconds - periodSeconds- timeoutSeconds - failureThreshold Note: InitialDelaySeconds can technically be 0, but only allow setting it to greater than 0 so that there will always be a delay before the first probe check. |
livenessProbe |
*v1.Probe | See kubernetes docs for more info . The configurable fields: - initialDelaySeconds - periodSeconds- timeoutSeconds - failureThreshold Note: InitialDelaySeconds can technically be 0, but only allow setting it to greater than 0 so that there will always be a delay before the first probe check. |
loggerSinks |
[]LoggerSink | A list of logging sinks that define where function logs should be sent and at what log level. Each sink entry defines a destination and the minimum level of log messages to send. |
loggerSinks[].level |
string | Minimum severity level for messages to be sent to this sink (e.g. debug, info, warn, and error). |
loggerSinks[].sink |
string | The log sink destination. For example: stdout. |
spec:
description: my Go function
handler: main:Handler
runtime: golang
image: myfunctionimage:latest
platform:
attributes:
# Docker will retry starting the function's image container 3 times.
# For more information, see https://docs.docker.com/config/containers/start-containers-automatically.
restartPolicy:
name: on-failure
maximumRetryCount: 3
# Set the healthcheck interval to specific value
# For more information, see https://docs.docker.com/engine/reference/builder/#healthcheck
# By default, set to 1s by Nuclio.
# Note: This is relevant for local platform only (Docker).
healthCheckInterval: 10s
# Use `volume` to mount the processor into the function.
# For more information, see https://docs.docker.com/storage/volumes.
mountMode: volume
env:
- name: SOME_ENV
value: abc
- name: SECRET_PASSWORD_ENV_VAR
valueFrom:
secretKeyRef:
name: my-secret
key: password
volumes:
- volume:
hostPath:
path: "/var/run/docker.sock"
volumeMount:
mountPath: "/var/run/docker.sock"
minReplicas: 2
maxReplicas: 8
targetCPU: 60
build:
registry: localhost:5000
noBaseImagePull: true
noCache: true
commands:
- apk --update --no-cache add curl
- pip install simplejson
resources:
# Kubernetes Limits & Requests for the function's CPU and memory usage.
# For more information, see https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
# Leave empty to use the default values.
# Note: This is mostly relevant for Kubernetes platform only.
# For local platform (Docker), only the `limits` section is relevant.
# When nvidia gpu limit is set, the function will be deployed with "--gpus all"
# When cpu limit set, the function will be deployed with "--cpus <cpu limit>"
# When memory limit set, the function will be deployed with "--memory <memory limit>"
requests:
cpu: 1
memory: 128M
limits:
cpu: 2
memory: 256M
nvidia.com/gpu: 1
securityContext:
runAsUser: 1000
runAsGroup: 2000
fsGroup: 3000The status section contains the requirements and attributes and has the following elements:
| Path | Type | Description |
|---|---|---|
| state | string | A textual representation of the function status |
| message | string | Function state message, mostly in use to represent why a function has failed |
| logs | map | The function deployment logs to be returned |
| scaleToZero | object | The details of the last scale event of the function (contains event message and time) |
| apiGateways | []string | A list of the function's api-gateways |
| httpPort | int | The http port used to invoke the function |
| containerImage | string | The name of the built function container image, including the registry. |
| internalInvocationUrls | []string | A list of internal URLs to invoke the function |
| externalInvocationUrls | []string | A list of external URLs to invoke the function, including ingresses and external-ip:function-port |
The state field describes the current function status, and can be one of the following:
| State | Description |
|---|---|
| ready | Function is deployed successfully and ready to process events. |
| imported | Function is imported but not yet deployed. |
| scaledToZero | Function is scaled to zero, so the number of function replicas is zero. |
| building | Function image is being built. |
| waitingForResourceConfiguration | Function waits for resources to be ready. For instance, in case of k8s function waits for deployment/pods and etc. |
| waitingForScaleResourceFromZero | Function is scaling up from zero replicas. |
| waitingForScaleResourceToZero | Function is scaling down to zero replicas. |
| error | An error occurred during function deployment that cannot be rectified without redeployment. |
| unhealthy | An error occurred during function deployment, which might be resolved over time, and might require redeployment. For example, issues with insufficient resources or a missing image. |
status:
state: ready
scaleToZero:
lastScaleEvent: resourceUpdated
lastScaleEventTime: "2022-12-11T16:23:52.130851057Z"
apiGateways:
- some-api-gateway
containerImage: localhost:5000/nuclio-my-function-image-processor:latest
externalInvocationUrls:
- ing-nuclio.my-nuclio-domain.com/function-name
internalInvocationUrls:
- nuclio-function-name.nuclio.svc.cluster.local:8080