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:
Function image (
image
) — set thespec.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 thespec.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.
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:
If
spec.image
is set, the implied code-entry type is function image (image
) and the configured function image is used. Thespec.build.codeEntryType
,spec.build.functionSourceCode
, andspec.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 thespec.image
configuration field. This is handled implicitly when deploying a function from the Nuclio dashboard.If
spec.build.functionSourceCode
is set (andspec.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. Thespec.build.codeEntryType
andspec.build.path
fields are ignored.If
spec.build.codeEntryType
is set (andspec.image
andspec.build.functionSourceCode
aren’t set), the value of the code-entry field determines the external function-code code-entry type (archive
,github
, ors3
).If
spec.build.path
is set (andspec.image
,spec.build.functionSourceCode
, andspec.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 isimage
andspec.build.codeEntryType
andspec.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:
Set the
spec.build.functionSourceCode
configuration field to the function’s source code, encoded as a Base64 string. This implies thesourceCode
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.
Note: When
spec.build.functionSourceCode
is set andspec.image
isn’t set, the implied code-entry type issourceCode
andspec.build.codeEntryType
andspec.build.path
are ignored. Whenspec.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
, andspec.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:
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.
Note:
When
spec.image
orspec.build.functionSourceCode
are set,spec.build.codeEntryType
is ignored. See Determining the code-entry type.The
archive
ands3
code-entry types support the following archive-file formats: *.jar, *.rar, *.tar, *.tar.bz2, *.tar.lz4, *.tar.gz, *.tar.sz, *.tar.xz, *.zipThe 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
, orS3
— 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
andspec.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 usernamepassword
(dashboard: Password) (Optional) Git passwordworkDir
(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 thespec.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"