Function-Configuration Reference#

This document provides a reference of the Nuclio function configuration.

In This Document#

Basic configuration structure
Function Metadata (metadata)
- Example
Function Specification (spec)
- Example
Function Status
- Function State (state)
- Status Example
See also

Basic configuration structure#

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:latest

Function Metadata#

The 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

Example#

metadata:
  name: example
  namespace: nuclio
  labels:
    l1: lv1
    l2: lv2
    l3: 100
  annotations:
    a1: av1  

Function Specification (`spec`)#

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.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 is`image`; 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
`triggers.(name).async.establishConnectionTimeout`	string	Total budget for the Go processor to establish connections to the Python wrapper and receive its readiness signal during function startup (e.g., `5m`, `10m`). Useful when `init_context` is slow. Defaults to `3 × readinessTimeoutSeconds`. Accepts any value valid for `time.ParseDuration`
`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 - GoogleContainerTools/kaniko, 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
`runtimeClassName`	string	Kubernetes RuntimeClass name for function pods. When unset, the cluster default runtime is used.
`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`.

Specification example#

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: 3000
  runtimeClassName: nvidia

Function Status#

The 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

Function state (`state`)#

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 example#

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

Function-Configuration Reference

Contents

Function-Configuration Reference#

In This Document#

Basic configuration structure#

Function Metadata#

Example#

Function Specification (`spec`)#

Specification example#

Function Status#

Function state (`state`)#

Status example#

See also#

Function-Configuration Reference

Contents

Function-Configuration Reference#

In This Document#

Basic configuration structure#

Function Metadata#

Example#

Function Specification (spec)#

Specification example#

Function Status#

Function state (state)#

Status example#

See also#

Function Specification (`spec`)#

Function state (`state`)#