Inject secrets

You can define build arguments and runtime variables to be injected at build or runtime respectively for services and jobs. You can set build arguments and environment variables in individual resources, or create a secret group so that multiple resources in a project can inherit the same secrets.

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 as base
ARG PACKAGES
RUN echo "Using: ${PACKAGES}"
# PACKAGES available

FROM base as stage1
RUN echo "Using: ${PACKAGES}"
# PACKAGES not available

FROM base as stage2
ARG PACKAGES
RUN echo "Using: ${PACKAGES}"
# PACKAGES available

To set build arguments for a single resource, navigate to the build arguments page in your resource 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 as production
ARG PACKAGES
ENV PACKAGES=${PACKAGES}
# PACKAGES available in build and runtime

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.

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

Learn more about runtime variables and the Docker ENV command .

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.

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 use the randomSecret function in your secrets as an argument, for example ${fn.randomSecret(32)}.

If you use this function in a build argument, runtime variable, or when creating a secret group, the function will be evaluated when you save it. This means the result will be securely stored as a secret rather than the function call itself, and the generated value will remain the same unless it is manually changed.