Zudoku
Tutorials

Environment Variables

Environment variables are a common way to configure applications at runtime. Unikraft Cloud supports passing environment variables to instances during deployment through many methods. This tutorial discusses each below and orders them by superseeding precedence (from most powerful to weakest).

Below are all the ways you can set environment variables for your Unikraft Cloud instances. The order they're presented is from the least precedence to the highest precedence.

Dockerfile ENV

You can set environment variables in your Dockerfile using the ENV instruction in your target FROM stage. The CLI automatically reads them when building the image and sets them in the resulting packaged image.

Dockerfile
# ...
FROM ubuntu:latest
ENV MY_ENV_VAR=my_value
# ...

Kraftfile env

You can set environment variables in your Kraftfile using the env field. unikraft build reads them and sets them in the resulting packaged image.

YAMLKraftfile
# ...
env:
  MY_ENV_VAR: my_value

This method takes precedence over the Dockerfile. It will override environment variables with the same name set in the Dockerfile.

CLI flags

When deploying an instance, you can pass environment variables using the --env (or -e) flag. You can specify many environment variables by using the flag many times. The flag works similarly to the docker run -e flag.

TerminalCode
unikraft run --metro fra \
  -e MY_ENV_VAR=my_value \
  --image <my-org>/my-app:latest

This method takes precedence over the Dockerfile and Kraftfile. It will override environment variables with the same name set in the previous two methods.

Wrapper script

Create a wrapper script that sets the environment variables before executing the main app. Check what the original entrypoint of your app is and call it after setting the variables. For example, if the original entrypoint is /entrypoint.sh, you can create a new script wrapper.sh like this:

Terminalwrapper.sh
#!/bin/sh

export MY_ENV_VAR="my_value"

exec /entrypoint.sh "$@"

Then you change either your Dockerfile or Kraftfile to start this wrapper script. Unikraft Cloud starts the image's CMD (or the Kraftfile cmd) and ignores the Dockerfile ENTRYPOINT, so set the wrapper as the command. To pass arguments on to the app, list them after the wrapper, for example CMD ["/wrapper.sh", "--port", "8080"]:

Dockerfile
# ...
COPY wrapper.sh /wrapper.sh
RUN chmod +x /wrapper.sh
CMD ["/wrapper.sh"]

This method has the highest precedence and will override environment variables set in the CLI, Dockerfile, or Kraftfile as it hardcodes them in the script. Thus it's recommended to do this only for variables that you set and don't change.

Learn more

Last modified on
KraftKit To UnikraftRootfs Formats