Added secrets docs.
Review: https://reviews.apache.org/r/61725
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/27379a79
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/27379a79
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/27379a79
Branch: refs/heads/1.4.x
Commit: 27379a790145fd9ccfbefca7294e0e4de06e2976
Parents: 7bdab76
Author: Kapil Arya <ka...@mesosphere.io>
Authored: Thu Aug 17 21:28:19 2017 -0400
Committer: Kapil Arya <ka...@mesosphere.io>
Committed: Fri Aug 18 13:36:35 2017 -0400
----------------------------------------------------------------------
docs/home.md | 1 +
docs/secrets.md | 148 +++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 149 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/27379a79/docs/home.md
----------------------------------------------------------------------
diff --git a/docs/home.md b/docs/home.md
index ab32838..ad91f2f 100644
--- a/docs/home.md
+++ b/docs/home.md
@@ -35,6 +35,7 @@ layout: documentation
* [Monitoring](monitoring.md)
* [Operational Guide](operational-guide.md)
* [Roles](roles.md)
+* [Secrets](secrets.md) for managing secrets within Mesos.
* [SSL](ssl.md) for enabling and enforcing SSL communication.
* [Nested Container and Task Group (Pod)](nested-container-and-task-group.md)
* [Tools](tools.md) for setting up and running a Mesos cluster.
http://git-wip-us.apache.org/repos/asf/mesos/blob/27379a79/docs/secrets.md
----------------------------------------------------------------------
diff --git a/docs/secrets.md b/docs/secrets.md
new file mode 100644
index 0000000..ce5341a
--- /dev/null
+++ b/docs/secrets.md
@@ -0,0 +1,148 @@
+---
+title: Apache Mesos - Secrets Handling
+layout: documentation
+---
+
+# Secrets
+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 Message
+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-based Secrets
+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": "MY_SECRET_ENV",
+ "type": "SECRET",
+ "secret": {
+ "type": "REFERENCE",
+ "reference": {
+ "name": "/my/secret",
+ "key": "username"
+ }
+ }
+ },
+ {
+ "name": "MY_NORMAL_ENV",
+ "value": "foo"
+ }
+ ]
+}
+```
+
+## File-based Secrets
+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.
+
+## Image-pull Secrets
+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"
+ }
+ }
+ }
+}
+```
+
+## SecretResolver Module
+The SecretResolver module is called from Mesos agent to fetch/resolve any image-pull, environment-based, or file-based secrets. (See [Mesos Modules](modules.md) 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.