Project: Apache Mesos (Orchestration & Management / Scheduling & Orchestration)
File: secrets.md

title: Apache Mesos - Secrets Handling layout: documentation Starting 1.4.0 release, Mesos allows tasks to populate environment variables and file volumes with secret contents that are retrieved using a secret-resolver interface. It also allows specifying image-pull secrets for private container registry. This allows users to avoid exposing critical secrets in task definitions. Secrets are fetched/resolved using a secret-resolver module (see below). NOTE: Secrets are only supported for Mesos containerizer and not for the Docker containerizer. Secrets can be specified using the following protobuf message: ``` message Secret { enum Type { UNKNOWN = 0; REFERENCE = 1; VALUE = 2; } message Reference { required string name = 1; optional string key = 2; } message Value { required bytes data = 1; } optional Type type = 1; optional Reference reference = 2; optional Value value = 3; } ``` Secrets can be of type `reference` or `value` (only one of `reference` and `value` must be set). A secret reference can be used by modules to refer to a secret stored in a secure back-end. The `key` field can be used to reference a single value within a secret containing arbitrary key-value pairs. For example, given a back-end secret store with a secret named "/my/secret" containing the following key-value pairs: ``` { "username": "my-user", "password": "my-password } ``` The username could be referred to in a `Secret` by specifying "my/secret" for the `name` and "username" for the `key`. Secret also supports pass-by-value where the value of a secret can be directly passed in the message. Environment variables can either be traditional value-based or secret-based. For the latter, one can specify a secret as part of environment definition as shown in the following example: ``` { "variables" : [ { "name": "MYSECRETENV", "type": "SECRET", "secret": { "type": "REFERENCE", "reference": { "name": "/my/secret", "key": "username" } } }, { "name": "MYNORMALENV", "value": "foo" } ] } ``` A new `volume/secret` isolator is available to create secret-based files inside the task container. To use a secret, one can specify a new volume as follows: ``` { "mode": "RW", "container_path": "path/to/secret/file", "source": { "type": "SECRET", "secret": { "type": "REFERENCE", "reference": { "name": "/my/secret", "key": "username" } } } } ``` This will create a tmpfs-based file mount in the container at "path/to/secret/file" which will contain the secret text fetched from the back-end secret store. The `volume/secret` isolator is not enabled by default. To enable it, it must be specified in `--isolator=volume/secret` agent flag. Currently, image-pull secrets only support Docker images for Mesos containerizer. Appc images are not supported. One can store Docker config containing credentials to authenticate with Docker registry in the secret store. The secret is expected to be a Docker config file in JSON format with UTF-8 character encoding. The secret can then be referenced in the `Image` protobuf as follows: ``` { "type": "DOCKER", "docker": message Docker { "name": "<REGISTRY_HOST>/path/to/image", "secret": { "type": "REFERENCE", "reference": { "name": "/my/secret/docker/config" } } } } ``` The SecretResolver module is called from Mesos agent to fetch/resolve any image-pull, environment-based, or file-based secrets. (See for more information on using Mesos modules). ``` class SecretResolver { virtual process::Future<Secret::Value> resolve(const Secret& secret) const; }; ``` The default implementation simply resolves value-based Secrets. A custom secret-resolver module can be specified using the `--secret_resolver=<module-name>` agent flag.