Execution Environment
Containerization
Dagger Functions execute within containers spawned by the Dagger Engine. This serves a few important purposes:
- Reproducibility: Executing in a well-defined and well-controlled container ensures that a function to run the same way every time it is invoked. It also guards against creating "hidden dependencies" on ambient properties of the execution environment that could change at any moment.
- Caching: A reproducible containerized environment makes it possible to cache the result of function execution, which in turn allows Dagger to automatically speed up function execution.
- Security: Even when running third-party Dagger Functions sourced from a Git repository, those Dagger Functions will not have default access to your host environment (host files, directories, environment variables, etc.). Access to these host resources can only be granted by explicitly passing them as argument values to the Dagger Function.
Code execution
When implementing Dagger Functions, you are free to write arbitrary code that will execute inside the Dagger Module's container. You have access to the Dagger API to make calls to the core Dagger API or other Dagger Modules you depend on, but you are also free to just use the language's standard library and/or imported third-party libraries.
The process your code executes in will currently be with the root
user, but without a full set of Linux capabilities and other standard container sandboxing provided by runc
.
The current working directory of your code will be an initially empty directory. You can write and read files and directories in this directory if needed. This includes using the Export
APIs on File
/Directory
/Container
to write those to this local directory if needed.
CurrentModule
API
The Dagger API client available to all Dagger Functions includes a CurrentModule
API that provides abilities to introspect the function's module and interface between the current execution environment and the Dagger API.
For example:
-
The
Source
API onCurrentModule
returns aDirectory
where your module's source code is stored, which grants access to any files or directories within there. -
The
Workdir
andWorkdirFile
APIs onCurrentModule
allow you to load directories and files, respectively, from your function's current working directory (as described in the above section).
Host resources
As mentioned above, Dagger Functions execute in containers and thus do not have access to resources on the host you invoke the function from (i.e. the host you execute a CLI command like dagger call
from). Instead, these resources need to be explicitly passed when executing dagger call
.
This includes:
-
Files and directories: Dagger Functions can accept arguments of type
File
orDirectory
. Pass files and directories on your host by specifying their path as the value of the argument when usingdagger call
. -
Environment variables: Pass environment variable values as argument values when invoking a function by just using the standard shell convention of using
$ENV_VAR_NAME
when usingdagger call
. -
Local network services: Dagger Functions that accept an argument of type
Service
can be passed local network services in the formtcp://<host>:<port>
.