How to include files and use template substitution in the container build context

How to include files and use template substitution in the container build context.

This guide will show you how to provide files to your CodeDirect container build context. These files may include secret references to secrets securely stored with Webscale and substituted at build time.

Prerequisites

Before you begin, ensure you have:

A builder created and saved
The file you want included in your build context uploaded to Webscale Files

Add file to build context

Click the Edit icon for the Builder you would like to modify.
Expand the Build context panel and select the File archive and Path for the specific file you would like to include in the build context.
Enter a relative mount path. This is where the file will be mounted in the container. This must not start with a /.
If the file is a template file and you would like the value template references to be substituted at build time, check the Template substitution box.

How to use template substitution

If there are secure values that are not safe to store in the Webscale File directly, but need to be injected into the build context, you can utilize value templates in your file and specify that template substitution should occur during the build. This allows you to securely inject secrets into your build context.

A value template can be specified using the syntax: $(). Inside the parens, include the relevant function call. For example, to inject a secret your file might look like this:

{
  "db": {
    "username": "admin",
    "password": "$(secrets("secrets/efgh1234abcd"))"
  }
}

Where secrets/efgh1234abcd is a reference to a secret stored with Webscale. When the build context is prepared, the contents of that secret will replace the template reference, leaving the file as follows:

{
  "db": {
    "username": "admin",
    "password": "mysecurepassword"
  }
}

Uploading secrets to Webscale

To upload a secret to your Webscale account, send a POST request with a valid authorization token to /v2/secrets. Refer to the “Create a secret” API documentation here.
Record the secret href that is returned from the API. This reference is what should be used in the template file, as shown in the above example (secrets/efgh1234abcd).

How to use JSON secrets

Secrets may be of type “application/json” in which case, the secret reference in your template file can include the relevant key path to a specific part of your secret content.

For example:

POST /v2/secrets

{
  "mime_type": "application/json",
   "content": {
      "db": {
        "username": "admin",
        "password": "mysecurepassword"
      }
    }
}

The username and password in this secret could be referenced in your template file as follows:

{
  "db": {
    "username": "$(secret("secrets/efgh1234abcd", "db.username"))",
    "password": "$(secret("secrets/efgh1234abcd", "db.password"))"
  }
}

Note that the JSON key is a dot separated optional second argument provided to the secrets expression. If the second argument is omitted, the entire secrets content will be injected.

Table of Contents