Secrets beta test information.md

To use build secrets, make a subdirectory .resin in the root of your repository. Inside that directory, make another directory named secrets and a file named resin.yml, without any secrets, your tree should look like

[19:48] ➜  project tree -a
.
├── docker-compose.yml
├── .resin
│   ├── resin.yml
│   └── secrets
├── service1
│   └── Dockerfile.template
└── service2
    └── Dockerfile.template

4 directories, 4 files

to add a secret file, first add the file to the .resin/secrets directory:

[19:49] ➜  project tree -a
.
├── docker-compose.yml
├── .resin
│   ├── resin.yml
│   └── secrets
│       └── super-secret-recipe
├── service1
│   └── Dockerfile.template
└── service2
    └── Dockerfile.template

4 directories, 5 files

now, in the .resin/resin.yml file, add the following to mount that secret into every service:

build-secrets:
    global:
        - source: super-secret-recipe
          dest: my-recipe   

This will mount the super-secret-recipe file into /run/secrets/my-recipe file in every build container.

To add a secret file to a specific service's build:

[19:53] ➜  project tree -a
.
├── docker-compose.yml
├── .resin
│   ├── resin.yml
│   └── secrets
│       ├── super-secret-recipe
│       └── super-secret-recipe-2
├── service1
│   └── Dockerfile.template
└── service2
    └── Dockerfile.template

4 directories, 6 files

and resin.yml:

build-secrets:
    global:
        - source: super-secret-recipe
          dest: my-recipe
    services:
        service1:
            - source: super-secret-recipe-2
               dest: my-recipe2

and that will mount both the global and the service1 specific secret into /run/secrets as my-recipe2.

Subdirectories are supported in both the source (.resin/secrets) and the destination (/run/secrets)

Build variables

It is also possible to define build variables which will be added to your build from the resin.yml file:

build-variables:
    global:
        - MY_VAR_1=This is a variable
        - MY_VAR_2=Also a variable
    services:
        service1:
            - SERVICE1_VAR=This is a service specific variable

These will be added as build args to your builds, so for example, to read it in your build:

FROM resin/armv7hf-debian

ARG MY_VAR_1

RUN echo "The build variable is ${MY_VAR_1}"

Hm, you can override build variables on a per-service basis, but is there some way to vary them per-application? We have a number of apps that are bound to our test lab, and we'd like to feed that information automatically into the build process.

@memory sorry I didn't get a notification for whatever reason. Currently no you can't do that, I'd recommend having different yaml files that are fed into the directory based on the application you're building for - at least for the moment.

Something to note/clarify: build variables should not be used to hold secrets like access tokens or passwords if the docker image is accessible to untrusted parties, because the Dockerfile ARG instruction may be stored in the image as the Docker documentation advises:

https://docs.docker.com/engine/reference/builder/#arg
Warning: It is not recommended to use build-time variables for passing secrets like github keys, user credentials etc. Build-time variable values are visible to any user of the image with the docker history command.

However, secrets like tokens and passwords can be used in instructions like RUN through the mounted secret files, for example:

RUN /bin/cat /run/secrets/my-recipe/secret-recipe | command_that_reads_secrets_from_stdin

Files under the .resin or .balena folders are not saved in the final image, hence being more secure than ARG.

Note also that the .resin folder and the resin.yml file are now available with the new names .balena and balena.yml.