Skip to content

Reference

fs functions

fs copy(fs input, string src, string dst)

fs input

the filesystem to copy from.

string src

the path from the input filesystem.

string dst

the path in the current filesystem.

Copies a file from an input filesystem into the current filesystem.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
fs default() {
    copy scratch "src" "dst" with option {
        allowEmptyWildcard
        allowWildcard
        chmod 0
        chown "owner"
        contentsOnly
        createDestPath
        createdTime "created"
        followSymlinks
        unpack
    }
}

option::copy allowEmptyWildcard()

Allows wildcards to match no files in the path to copy.

option::copy allowWildcard()

Allows wildcards in the path to copy.

option::copy chmod(int filemode)

int filemode

the new permissions of the file.

Modifies the permissions of the copied files.

option::copy chown(string owner)

string owner

the user:group owner of the copy path.

Change the owner of the copy path.

option::copy contentsOnly()

If the `src` path is a directory, only the contents of the directory is copied to the destination.

option::copy createDestPath()

Create the parent directories of the destination if they don't already exist.

option::copy createdTime(string created)

string created

the created time in the RFC3339 format.

Sets the created time of the copy path.

Follow symlinks in the input filesystem and copy the symlink targets too.

option::copy unpack()

If the `src` path is an archive, attempt to unpack its contents into the destination.

fs dir(string path)

string path

the new working directory.

Sets the working directory for all subsequent calls in this filesystem block.

1
2
3
fs default() {
    dir "path"
}

fs dockerLoad(string ref)

string ref

the name of the Docker image.

Loads the filesystem as a Docker image to the docker client found in your environment.

1
2
3
fs default() {
    dockerLoad "ref"
}

fs dockerPush(string ref)

string ref

a distribution reference. if not fully qualified, it will be expanded the same as the docker CLI.

Pushes the filesystem to a registry following the distribution spec: https://github.com/opencontainers/distribution-spec/

1
2
3
fs default() {
    dockerPush "ref"
}

fs download(string localPath)

string localPath

the destination filepath for the filesystem contents.

Downloads the filesystem to a local path.

1
2
3
fs default() {
    download "localPath"
}

fs downloadDockerTarball(string localPath, string ref)

string localPath

the destination filepath for the tarball.

string ref

the name of the Docker image.

Downloads the filesystem as a Docker image tarball to a local path. The tarball is able to be loaded into a docker engine via `docker load`. See: https://docs.docker.com/engine/reference/commandline/save/ and https://docs.docker.com/engine/reference/commandline/load/

1
2
3
fs default() {
    downloadDockerTarball "localPath" "ref"
}

fs downloadOCITarball(string localPath)

string localPath

the destination filepath for the tarball.

Downloads the filesystem as a OCI filesystem bundle to a local path. See: https://github.com/opencontainers/runtime-spec/blob/master/bundle.md

1
2
3
fs default() {
    downloadOCITarball "localPath"
}

fs downloadTarball(string localPath)

string localPath

the destination filepath for the tarball.

Downloads the filesystem as a tarball to a local path.

1
2
3
fs default() {
    downloadTarball "localPath"
}

fs env(string key, string value)

string key

the environment key.

string value

the environment value.

Sets an environment key pair for all subsequent calls in this filesystem block.

1
2
3
fs default() {
    env "key" "value"
}

fs frontend(string source)

string source

Generates a filesystem using an external frontend.

1
2
3
4
5
6
fs default() {
    frontend "source" with option {
        input "key" scratch
        opt "key" "value"
    }
}

option::frontend input(string key, fs value)

string key

an unique key for the input.

fs value

a filesystem as an input.

Provide an input filesystem to the external frontend. Read the documentation for the frontend to see what it will accept.

option::frontend opt(string key, string value)

string key

an unique key for the option.

string value

a value for the option.

Provide a key value pair to the external frontend. Read the documentation for the frontend to see what it will accept.

fs git(string remote, string ref)

string remote

the fully qualified git remote.

string ref

the git reference to check out.

A filesystem with the files from a git repository checked out from a git reference. Note that by default, the `.git` directory is not included.

1
2
3
4
5
fs default() {
    git "remote" "ref" with option {
        keepGitDir
    }
}

option::git keepGitDir()

Keeps the `.git` directory of the git repository.

fs http(string url)

string url

a fully-qualified URL to send a HTTP GET request.

A filesystem with a file retrieved from a HTTP URL.

1
2
3
4
5
6
7
fs default() {
    http "url" with option {
        checksum "digest"
        chmod 0
        filename "name"
    }
}

option::http checksum(string digest)

string digest

a checksum in the form of an OCI digest. https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests

Verifies the checksum of the retrieved file against a digest.

option::http chmod(int filemode)

int filemode

the new permissions of the file.

Modifies the permissions of the retrieved file.

option::http filename(string name)

string name

the name of the file.

Writes the retrieved file with a specified name.

fs image(string ref)

string ref

a docker registry reference. if not fully qualified, it will be expanded the same as the docker CLI.

An OCI image's filesystem.

1
2
3
4
5
fs default() {
    image "ref" with option {
        resolve
    }
}

option::image resolve()

Resolves the OCI Image Config and inherit its environment, working directory, and entrypoint.

fs local(string path)

string path

the local path to the directory to sync up.

A filesystem with the files synced up from a directory on the local system.

1
2
3
4
5
6
7
fs default() {
    local "path" with option {
        excludePatterns "pattern"
        followPaths "path"
        includePatterns "pattern"
    }
}

option::local excludePatterns(string pattern)

string pattern

a list of patterns for files that should not be synced.

Sync only files that do not match any of the excluded patterns.

option::local followPaths(string path)

string path

a list of paths to files that may be symlinks.

Sync the targets of symlinks if path is to a symlink.

option::local includePatterns(string pattern)

string pattern

a list of patterns for files that should be synced.

Sync only files that match any of the included patterns.

fs mkdir(string path, int filemode)

string path

the path of the directory.

int filemode

the permissions of the directory.

Creates a directory in the current filesystem.

1
2
3
4
5
6
7
fs default() {
    mkdir "path" 0 with option {
        chown "owner"
        createParents
        createdTime "created"
    }
}

option::mkdir chown(string owner)

string owner

the user:group owner of the directory.

Change the owner of the directory.

option::mkdir createParents()

Create the parent directories if they don't exist already.

option::mkdir createdTime(string created)

string created

the created time in the RFC3339 format.

Sets the created time of the directory.

fs mkfile(string path, int filemode, string content)

string path

the path of the file.

int filemode

the permissions of the file.

string content

the contents of the file.

Creates a file in the current filesystem.

1
2
3
4
5
6
fs default() {
    mkfile "path" 0 "content" with option {
        chown "owner"
        createdTime "created"
    }
}

option::mkfile chown(string owner)

string owner

the user:group owner of the file.

Change the owner of the file.

option::mkfile createdTime(string created)

string created

the created time in the RFC3339 format.

Sets the created time of the file.

fs rm(string path)

string path

the path of the file to remove.

Removes a file from the current filesystem.

1
2
3
4
5
6
fs default() {
    rm "path" with option {
        allowNotFound
        allowWildcard
    }
}

option::rm allowNotFound()

Allows the file to not be found.

option::rm allowWildcard()

Allows wildcards in the path to remove.

fs run(string arg)

string arg

are optional arguments to execute.

Executes an command in the current filesystem. If no arguments are given, it will execute the current args set on the filesystem. If exactly one arg is given it will be wrapped with /bin/sh -c 'arg'. If more than one arg is given, it will be executed directly, without a shell.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
fs default() {
    run "arg" with option {
        dir "path"
        env "key" "value"
        forward "src" "dest"
        host "hostname" "address"
        ignoreCache
        mount scratch "mountPoint"
        network "networkmode"
        readonlyRootfs
        secret "localPath" "mountPoint"
        security "securitymode"
        shlex
        ssh
        user "name"
    }
}

option::run dir(string path)

string path

the new working directory.

Sets the working directory for the duration of the run command.

option::run env(string key, string value)

string key

the environment key.

string value

the environment value.

Sets an environment key pair for the duration of the run command.

option::run forward(string src, string dest)

string src

a fully qualified URI to forward traffic to/from.

string dest

a mountpoint for a unix domain socket that is forwarded to/from.

Forwards traffic to/from a local source to a unix domain socket mounted for the duration of the run command. The source must be a fully qualified URI where the scheme must be either `unix://` or `tcp://`.

option::run host(string hostname, string address)

string hostname

the host name of the entry, may include spaces to delimit multiple host names.

string address

the IP of the entry.

Adds a host entry to /etc/hosts for the duration of the run command.

option::run ignoreCache()

Ignore any previously cached results for the run command. @ return an option to ignore existing cache for the run command.

option::run mount(fs input, string mountPoint)

fs input

the additional filesystem to mount. the input's root filesystem becomes available from the mountPoint directory.

string mountPoint

the directory where the mount is attached.

Attaches an additional filesystem for the duration of the run command.

option::run network(string networkmode)

string networkmode

the network mode of the container, must be one of the following: - unset: use the default network provider. - host: use the host's network namespace. - none: disable networking.

Sets the networking mode for the duration of the run command. By default, the value is `unset` (using BuildKit's CNI provider, otherwise its host namespace).

option::run readonlyRootfs()

Sets the rootfs as read-only for the duration of the run command.

option::run secret(string localPath, string mountPoint)

string localPath

the filepath for a secure file or directory.

string mountPoint

the directory where the secret is attached.

Mounts a secure file for the duration of the run command. Secrets are attached via a tmpfs mount, so all the data stays in volatile memory.

option::run security(string securitymode)

string securitymode

the security mode of the container, must be one of the following: - sandbox: use the default containerd seccomp profile. - insecure: enables all capabilities.

Sets the security mode for the duration of the run command. By default, the value is `sandbox`.

option::run shlex()

Attempt to lex the single-argument shell command provided to `run` to determine if a `/bin/sh -c '...'` wrapper needs to be added.

option::run ssh()

Mounts a SSH socket for the duration of the run command. By default, it will try to use the SSH socket found from $SSH_AUTH_SOCK. Otherwise, an option `localPath` can be provided to specify a filepath to a SSH auth socket or *.pem file.

option::run user(string name)

string name

the name of the user.

Sets the current user for the duration of the run command.

fs scratch()

An empty filesystem.

1
2
3
fs default() {
    scratch
}

fs shell(string arg)

string arg

the list of args used to prefix `run` statements.

Sets the current shell command to use when executing subsequent `run` methods. By default, this is ["sh", "-c"].

1
2
3
fs default() {
    shell "arg"
}

fs user(string name)

string name

the name of the user.

Sets the current user for all subsequent calls in this filesystem block.

1
2
3
fs default() {
    user "name"
}

string functions

string format(string formatString, string values)

string formatString

the format specifier.

string values

the list of values to be interpolated into the format specifier.

A format specifier that is interpolated with values.

1
2
3
string myString() {
    format "formatString" "values"
}

string localArch()

The architecture for the clients local environment.

1
2
3
string myString() {
    localArch
}

string localCwd()

The current working directory from the clients local environment.

1
2
3
string myString() {
    localCwd
}

string localEnv(string key)

string key

the environment variable's key.

An environment variable from the client's local environment.

1
2
3
string myString() {
    localEnv "key"
}

string localOs()

The OS from the clients local environment.

1
2
3
string myString() {
    localOs
}

string localRun(string command, string args)

string command

a command to execute.

string args

optional arguments to the command.

Executes an command in the local environment. If exactly one arg is given it will be wrapped with /bin/sh -c 'arg'. If more than one arg is given, it will be executed directly, without a shell.

1
2
3
4
5
6
7
8
string myString() {
    localRun "command" "args" with option {
        ignoreError
        includeStderr
        onlyStderr
        shlex
    }
}

option::localRun ignoreError()

If the command returns a non-zero status code ignore the failure and continue processing the hlb file.

option::localRun includeStderr()

Capture stderr intermixed with stdout on the command.

option::localRun onlyStderr()

Only capture the stderr from the command, ignore stdout.

option::localRun shlex()

Attempt to lex the single-argument shell command provided to `localRun` to determine if a `/bin/sh -c '...'` wrapper needs to be added.

string template(string text)

string text

the text of the template

Process text as a Go text template. For template syntax documentation see: https://golang.org/pkg/text/template/

1
2
3
4
5
string myString() {
    template "text" with option {
        stringField "name" "value"
    }
}

option::template stringField(string name, string value)

string name

the name of the field inside the template

string value

the value of the field inside the template

Add a string field with provided name to be available inside the template.