Code-Entry Types

This document describes the Nuclio function code-entry types and related configuration fields.

Overview

As part of the function specification (spec), you must configure one of the following code-entry types and related information that points either to a pre-built function image or to code from which to build such an image:

• Function image (image) — set the spec.image configuration field to the name of a function container image. See Function-image code-entry type (image).

• Function source code — provide the function source code either by setting the spec.build.functionSourceCode configuration field to an encoded source-code string (sourceCode), or by setting the spec.build.path field to a URL for downloading a function source-code file. See Function source-code entry types.

• External function code — set the spec.build.codeEntryType configuration field to a code-entry type for downloading the function's source code and optional additional configuration ("function code") from an external source — GitHub repository (github), archive file (archive), or AWS S3 bucket (s3) — and configure the required download information. See External function-code entry types.

Determining the code-entry type

The code-entry type is determined by using the following processing logic:

1. If spec.image is set, the implied code-entry type is function image (image) and the configured function image is used. The spec.build.codeEntryType, spec.build.functionSourceCode, and spec.build.path fields are ignored.

   Note

   When you build and deploy a Nuclio function, the spec.image field is automatically updated to the name of the function's container image, so to use a different code-entry type for a redeployed function you must first reset the spec.image configuration field. This is handled implicitly when deploying a function from the Nuclio dashboard.

2. If spec.build.functionSourceCode is set (and spec.image isn't set), the implied code-entry type is encoded source-code string (sourceCode) and the function is built from the configured source code. The spec.build.codeEntryType and spec.build.path fields are ignored.

3. If spec.build.codeEntryType is set (and spec.image and spec.build.functionSourceCode aren't set), the value of the code-entry field determines the external function-code code-entry type (archive, github, or s3).

4. If spec.build.path is set (and spec.image, spec.build.functionSourceCode, and spec.build.codeEntryType aren't set), the implied code-entry type is source-code-file and the function is built from the configured source code.

Configuring the code-entry type from the dashboard

When deploying a function from the Nuclio dashboard, you select the code-entry type from the Code entry type drop-down list in the Code function tab. Additional configuration parameters are displayed according to the selected entry type. When you select to deploy the function, the respective function-configuration parameters are automatically updated based on your dashboard configuration. The dashboard notes in this reference refer to fields in the Code function dashboard tab.

Function-image code-entry type (image)

Set the spec.image function-configuration field to the name of a function container image ([<host name>.]<namespace>.<repository>[:<tag>]) to deploy the function from this image.

Example

spec:
  description: my Go function
  image: mydockeruser/my-func:latest

Function source-code entry types

Use either of the following methods to provide the function source code:

• Set the spec.build.functionSourceCode configuration field to the function's source code, encoded as a Base64 string. This implies the sourceCode code-entry type. See Encoded source-code string code-entry type (sourceCode).
• Set the spec.build.path configuration field to a URL for downloading a function source-code file. See Source-code file code-entry type.

Encoded source-code string code-entry type (sourceCode)

Set the spec.build.functionSourceCode function-configuration field to the function's source code, encoded as a Base64-encoded string, to build the function image from this code.

Example

spec:
  description: my Go function
  handler: main:Handler
  runtime: golang
  build:
    functionSourceCode: "cGFja2FnZSBtYWluDQoNCmltcG9ydCAoDQogICAgImdpdGh1Yi5jb20vbnVjbGlvL251Y2xpby1zZGstZ28iDQopDQoNCmZ1bmMgSGFuZGxlcihjb250ZXh0ICpudWNsaW8uQ29udGV4dCwgZXZlbnQgbnVjbGlvLkV2ZW50KSAoaW50ZXJmYWNle30sIGVycm9yKSB7DQogICAgcmV0dXJuIG5pbCwgbmlsDQp9"

Source-code file code-entry type

Set the spec.build.path function-configuration field to a URL for downloading a function source-code file.

Example

spec:
  description: my Go function
  handler: main:Handler
  runtime: golang
  build:
    path: "https://www.my-host.com/my-function.go"

External function-code entry types

Set the spec.build.codeEntryType function-configuration field to one of the following code-entry types to download the function code from the respective external source:

• github — download the code from a GitHub repository. See GitHub code-entry type (github).
• archive — download the code as an archive file from an Iguazio Data Science Platform data container (authenticated) or from any URL that doesn't require download authentication. See Archive-file code-entry type (archive).
• s3 — download the code as an archive file from an AWS S3 bucket. See AWS S3 code-entry type (s3).

Additional information for performing the download — such as the download URL or authentication information — is provided in dedicated configuration fields for each code-entry type, as detailed in the documentation of each code-entry type.

The downloaded function code can optionally contain a function.yaml file with function configuration for enriching the original configuration (in the configuration file that sets the code-entry type) according to the following merge strategy:

• Field values that are set only in the downloaded configuration are added to the original configuration.
• List and map field values — such as meta.labels and spec.env —are merged by adding any values that are set only in the downloaded configuration to the values that are set in the original configuration.
• In case of a conflict — i.e., if the original and downloaded configurations set different values for the same element — the original configuration takes precedence and the value in the downloaded configuration is ignored.

GitHub code-entry type (github)

Set the spec.build.codeEntryType function-configuration field to github (dashboard: Code entry type = GitHub) to download the function code from a GitHub repository. The following configuration fields provide additional information for performing the download:

• spec.build —
  • path (dashboard: URL) (Required) — the URL of the GitHub repository that contains the function code.
  • codeEntryAttributes —
    • branch (dashboard: Branch) (Required) — the GitHub repository branch from which to download the function code.
    • headers.Authorization (dashboard: Token) (Optional) — a GitHub access token for download authentication.
    • workDir (dashboard: Work directory) (Optional) — the relative path to the function-code directory within the configured repository branch. The default work directory is the root directory of the GitHub repository ("/").

Example

spec:
  description: my Go function
  handler: main:Handler
  runtime: golang
  build:
    codeEntryType: "github"
    path: "https://github.com/my-organization/my-repository"
    codeEntryAttributes:
      branch: "my-branch"
      headers:
        Authorization: "my-Github-access-token"
      workDir: "/go/myfunc"

Archive-file code-entry type (archive)

Set the spec.build.codeEntryType function-configuration field to archive (dashboard: Code entry type = Archive) to download an archive file of the function code from one of the following sources:

• An Iguazio Data Science Platform ("platform") data container. Downloads from this source require user authentication.
• Any URL that doesn't require user authentication to perform the download.

The following configuration fields provide additional information for performing the download:

• spec.build —
  • path (dashboard: URL) (Required) — a URL for downloading the archive file.
    To download an archive file from an Iguazio Data Science Platform data container, the URL should be set to <API URL of the platform's web-APIs service>/<container name>/<path to archive file>, and a respective data-access key must be provided in the spec.build.codeEntryAttributes.headers.X-V3io-Session-Key field.
  • codeEntryAttributes —
    • headers.X-V3io-Session-Key (dashboard: Access key) (Required for a platform archive file) — an Iguazio Data Science Platform access key, which is required when the download URL (spec.build.path) refers to an archive file in a platform data container.
    • workDir (dashboard: Work directory) (Optional) — the relative path to the function-code directory within the extracted archive-file directory. The default work directory is the root of the extracted archive-file directory ("/").

Example

spec:
  description: my Go function
  handler: main:Handler
  runtime: golang
  build:
    codeEntryType: "archive"
    path: "https://webapi.default-tenant.app.mycluster.iguazio.com/users/myuser/my-functions.zip"
    codeEntryAttributes:
      headers:
        X-V3io-Session-Key: "my-platform-access-key"
      workDir: "/go/myfunc"

AWS S3 code-entry type (s3)

Set the spec.build.codeEntryType function-configuration field to s3 (dashboard: Code entry type = S3) to download an archive file of the function code from an Amazon Simple Storage Service (AWS S3) bucket. The following configuration fields provide additional information for performing the download:

• spec.build.codeEntryAttributes —
  • s3Bucket (dashboard: Bucket) (Required) — the name of the S3 bucket that contains the archive file.
  • s3ItemKey (dashboard: Item key) (Required) — the relative path to the archive file within the bucket.
  • s3AccessKeyId (dashboard: Access key ID) (Optional) — an S3 access key ID for download authentication.
  • s3SecretAccessKey (dashboard: Secret access key) (Optional) — an S3 secret access key for download authentication.
  • s3SessionToken (dashboard: Session token) (Optional) — an S3 session token for download authentication.
  • s3Region (dashboard: Region) (Optional) — the AWS Region of the configured bucket. When this parameter isn't provided, it's implicitly deduced.
  • workDir (dashboard: Work directory) (Optional) — the relative path to the function-code directory within the extracted archive-file directory. The default work directory is the root of the extracted archive-file directory ("/").

Example

spec:
  description: my Go function
  handler: main:Handler
  runtime: golang
  build:
    codeEntryType: "s3"
    codeEntryAttributes:
      s3Bucket: "my-s3-bucket"
      s3ItemKey: "my-folder/my-functions.zip"
      s3AccessKeyId: "my-@cc355-k3y"
      s3SecretAccessKey: "my-53cr3t-@cce55-k3y"
      s3SessionToken: "my-s3ss10n-t0k3n"
      s3Region: "us-east-1"
      workDir: "/go/myfunc"

See also

• Function-Configuration Reference