Inject secrets

You can define build arguments and runtime variables in your services to be injected at build or runtime respectively.

The editor for both allows you to view arguments and variables, edit them in a table as key-value pairs, or in JSON or ENV format.

If you are working in a team, or edit the variables in another tab, you will be notified that the values have changed and can either view a difference editor or discard your changes. The difference editor will update the remote values in real-time so you can be sure of any variables you may overwrite.

To enter or edit environment variables using JSON use the following format:

{
    "KEY_1": "value1",
    "KEY_2": "value2"
}

To upload or edit a .env file use the following format:

KEY_1=value1
KEY_2=value2

You can set build arguments (ARG) to be passed to the Docker container at build-time in jobs, build services, and combined services.

Your build arguments will be passed to the Dockerfile on build via the --build-arg flag. They do not persist in the built image and are set as key-value pairs.

For example, a variable set as PACKAGES=npm-cache can be accessed in the Dockerfile by declaring the ARG. Variables must be declared in the Dockerfile with ARG before being accessed. Arguments will only be in scope for the build section where they are declared.

FROM alpine
ARG PACKAGES
RUN echo "Using: ${PACKAGES}"
# packages available

FROM alpine
RUN echo "Using: ${PACKAGES}"
# packages not available

To set build arguments for a single service, navigate to the build arguments page in your service and select an editor mode. You may be prompted to enter your password.

Persist build arguments in the runtime environment

If you want to access a build argument value in the runtime environment, declare it as an runtime variable (ENV) in the Dockerfile with the value of the build argument. You should not pass secrets to your runtime environment in this way, as it will be visible to anyone with the image.

FROM alpine
ARG PACKAGES
ENV PACKAGES=${PACKAGES}

# or add with default value:
# ENV PACKAGES=${PACKAGES:-npm-cache}

Learn more about build arguments and the Docker ARG command .

You can set runtime variables (ENV) in to be passed to the Docker container at runtime. Secrets can be saved and used within a project in secret groups.

Your runtime variables can be accessed via the process environment, for example in a Node environment a variable set as ENV_VALUE=Northflank can be accessed within the container by referring to process.env.ENV_VALUE.

To set runtime variables for a single service, navigate to the environment page in your service and select an editor mode. You may be prompted to enter your password.

Learn more about runtime variables and the Docker ENV command .

Northflank injects build arguments and runtime variables into build and runtime workloads by default. You can access these values (as strings) using their key via the environment in your build and runtime workloads, or in your Dockerfile by specifying the key as an ARG.

Build arguments and runtime variables can be constructed using dynamic templating. This allows you to create new variables from multiple sources, including previously defined variables and inherited secrets from addons.

You can create build arguments or runtime variables using template literals (${VARIABLE_NAME}) in all editors (table, JSON, and env). Autocomplete is available in every editor, simply begin typing the template literal syntax (${) and a list of available variables will be displayed in a tooltip. You can hover over a variable reference to check its value.

You cannot refer to build arguments in runtime variables, or runtime variables in build arguments. However, if a variable is inherited from a secret group set to build & runtime, you can refer to it in both.

For example if VARIABLE_NAME with a value of hello is previously defined, or inherited by a service from a group, a new variable defined as ${VARIABLE_NAME} world will have the value hello world.

You can include functions in your secrets and templates as arguments, for example ${fn.randomSecret(32)}.

If you use a function when setting build arguments, runtime variables, or creating a secret group, the function will be evaluated when you save it. This means the result will be stored rather than the function call.

If you use a function in a template it will be saved as a function call. The function will be evaluated every time you run the template, which means the value can change if a template is used to update resources.

Northflank currently supports the following functions: