v1

Secure /

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

Build arguments

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 .

Runtime variables

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.

Runtime environmentEnvironment variable accessorRequired import
Nodeprocess.env.ENV_VALUEnone
DenoDeno.env.get("ENV_VALUE")none
Pythonos.environ.get("ENV_VALUE")import os
PHP.$_ENV["ENV_VALUE"]none
Ruby on RailsENV["ENV_VALUE"]none
Rustenv::var("ENV_VALUE")use std::env
JavaSystem.getenv("ENV_VALUE")none

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 .

Access Northflank injected secrets

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 argument keyValuesExample
NF_GIT_SHAThe git commit hash that is being builtc7d1f7f0e95116dce9cdfe126edcf782f6de8712
NF_GIT_BRANCHThe git branch of the current buildmain
NF_PREVIOUS_BUILD_GIT_SHAThe git commit hash of the previous build attempted by the build servicef12a3fd2738de900f36c8043cf48c29242bff8fe
Environment variable keyValuesExample
NF_HOSTSA comma-separated string of Northflank generated DNS entries from your public ports for the deployment, combined with any custom DNS entries assigned to your public portsport1--my-service--my-project--user-1bfg.code.run,port2--my-service--my-project--user-1bfg.code.run,testing.example.com
NF_HOSTS_CUSTOMA comma-separated string of your custom DNS entries assigned to public ports on the deploymenttesting.example.com
NF_OBJECT_IDThe Northflank ID for the deployment, generated from your original deployment namemy-service
NF_PROJECT_IDThe Northflank ID for the project, generated from your original project namemy-project
NF_DEPLOYMENT_SHAThe git commit hash of the deployed buildc7d1f7f0e95116dce9cdfe126edcf782f6de8712
NF_DEPLOYMENT_REPOThe git repo of the deployed buildhttps://gitservice.com/my-username/my-code-repo
NF_DEPLOYMENT_BRANCHThe git branch of the deployed buildmain

Dynamic templating

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.

Functions

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:

FunctionArguments
fn.randomSecret(length, encoding)Length: a number between 1 and 256 (required), encoding: hex or base64 (optional, base64 by default)

© 2023 Northflank Ltd. All rights reserved.