This document provides a reference of the Nuclio function configuration.
- Basic configuration structure
- Function Metadata (
metadata) - Function Specification (
spec) - Function Status (
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.7 \ python:3.8 \ python:3.9 \ python:3.10 \ python:3.11 \ shell \ java \ nodejs |
| image | string | The name of the function's container image — used for the image code-entry type; 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).maxWorkers | int | 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).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 |
| build.path | string | The URL of a GitHub repository or an archive-file that contains the function code — for the git, github or archive code-entry type — or the URL of a function source-code file; see Code-Entry Types |
| build.functionSourceCode | string | Base-64 encoded function source code for the sourceCode code-entry type; 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.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.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 code-entry type |
| 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 |
| eventTimeout | string | Global event timeout, 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 |
| 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. |
| sidecars.(name).name | string | the name of the sidecar container (optional, will be enriched from the map if not present) video0:rwm) |
| sidecars.(name).image | string | the image to run in the sidecar container (required) |
| sidecars.(name).imagePullPolicy | string | one of "Always", "Never", "IfNotPresent" |
| sidecars.(name).resources | v1.ResourceRequirements | Kubernetes resource requirements |
| sidecars.(name).ports | []v1.ContainerPort | A list of ports to expose the container |
| sidecars.(name).command | []string | A list of commands to run in the container (Entrypoint array) |
| sidecars.(name).args | []string | a list of arguments to the entrypoint |
| sidecars.(name).livenessProbe | v1.Probe | See kubernetes docs for more info |
| sidecars.(name).readinessProbe | v1.Probe | See kubernetes docs for more info |
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 |
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