Skip to content

Latest commit

 

History

History
324 lines (248 loc) · 19.3 KB

code-entry-types.md

File metadata and controls

324 lines (248 loc) · 19.3 KB
Raw

Code-Entry Types

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

In This Document

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:

Go Note
To import packages in Go source code, use the following syntax:
import "github.com/nuclio/handler/<package_name>"

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.

Note: When spec.image is set, the implied code-entry type is image and spec.build.codeEntryType and spec.build.path are ignored. See Determining the code-entry type.

Dashboard Note: To configure a function image from the dashboard, select Image from the Code entry type list, and then enter the image name in the URL field.

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:

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.

Note: When spec.build.functionSourceCode is set and spec.image isn't set, the implied code-entry type is sourceCode and spec.build.codeEntryType and spec.build.path are ignored. When spec.image is set, spec.build.functionSourceCode is ignored. See Determining the code-entry type.

Dashboard Note: To configure the function source code from the dashboard, select Edit online from the Code entry type list (default), and then edit the code in the unnamed function-code text box, as needed. When you select to deploy the function, the source code will automatically be encoded as a Base64 encoded string.

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.

Note: This code-entry type is applicable only when spec.image, spec.build.functionSourceCode, and spec.build.codeEntryType aren't set. See Determining the code-entry type.

Dashboard Note: The source-code file code-entry type isn't supported from the dashboard.

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:

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.

Note:

  • When spec.image or spec.build.functionSourceCode are set, spec.build.codeEntryType is ignored. See Determining the code-entry type.
  • The archive and s3 code-entry types support the following archive-file formats: *.jar, *.rar, *.tar, *.tar.bz2, *.tar.lz4, *.tar.gz, *.tar.sz, *.tar.xz, *.zip
  • The downloaded code files are saved and can be used by the function handler.

Dashboard Note: To configure an external function-code source from the dashboard, select the relevant code-entry type — Archive, Git, GitHub, or S3 — from the Code entry type list.

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.

Git code-entry type (git)

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

  • spec.build —

    • path (dashboard: URL) (Required) — the URL of the Git repository that contains the function code.

    • codeEntryAttributes —

      // must use one of the following as git reference

      • branch (dashboard: Branch) — the Git repository branch from which to download the function code.

      • tag (dashboard: Tag) — the Git repository tag from which to download the function code.

      • reference (dashboard: Reference) — the Git repository reference from which to download the function code.

      • username (dashboard: Username) (Optional) Git username

      • password (dashboard: Password) (Optional) Git password

      • workDir (dashboard: Work directory) (Optional) — the relative path to the function-code directory within the configured repository. The default work directory is the root directory of the git repository ("/").

Examples

Using Branch:

spec:
  description: my Go function
  handler: main:Handler
  runtime: golang
  build:
    codeEntryType: "git"
    path: "https://bitbucket.org/<my-user>/<my-repo>"
    codeEntryAttributes:
      workDir: "/go-function"
      branch: "go-func"

      # Uncomment in case of a private repository
      #
      #  username: "myusername"
      #  password: "mypassword"

Using Tag:

spec:
  description: my Go function
  handler: main:Handler
  runtime: golang
  build:
    codeEntryType: "git"
    path: "https://bitbucket.org/<my-user>/<my-repo>"
    codeEntryAttributes:
      workDir: "/go-function"
      tag: "0.0.1"

Using Full Reference:

spec:
  description: my Go function
  handler: main:Handler
  runtime: golang
  build:
    codeEntryType: "git"
    path: "https://bitbucket.org/<my-user>/<my-repo>"
    codeEntryAttributes:
      workDir: "/go-function"
      reference: "refs/heads/go-func"

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