add secrets property to build section

Signed-off-by: Guillaume Lours <guillaume.lours@docker.com>
krutkurt · Apr 11, 2022 · cb27949 · cb27949
1 parent 24e1994
commit cb27949
Show file tree

Hide file tree

Showing 2 changed files with 91 additions and 1 deletion.
diff --git a/build.md b/build.md
@@ -301,6 +301,76 @@ build:
   target: prod
 ```
 
+### secrets
+`secrets` grants access to sensitive data defined by [secrets](secrets) on a per-service build basis. Two
+different syntax variants are supported: the short syntax and the long syntax.
+
+Compose implementations MUST report an error if the secret doesn't exist on the platform or isn't defined in the
+[`secrets`](#secrets-top-level-element) section of this Compose file.
+
+#### Short syntax
+
+The short syntax variant only specifies the secret name. This grants the
+container access to the secret and mounts it as read-only to `/run/secrets/<secret_name>`
+within the container. The source name and destination mountpoint are both set
+to the secret name.
+
+The following example uses the short syntax to grant the build of the `frontend` service
+access to the `server-certificate` secret. The value of `server-certificate` is set
+to the contents of the file `./server.cert`.
+
+```yml
+services:
+  frontend:
+    build: 
+      context: .
+      secrets:
+        - server-certificate
+secrets:
+  server-certificate:
+    file: ./server.cert
+```
+
+#### Long syntax
+
+The long syntax provides more granularity in how the secret is created within
+the service's containers.
+
+- `source`: The name of the secret as it exists on the platform.
+- `target`: The name of the file to be mounted in `/run/secrets/` in the
+  service's task containers. Defaults to `source` if not specified.
+- `uid` and `gid`: The numeric UID or GID that owns the file within
+  `/run/secrets/` in the service's task containers. Default value is USER running container.
+- `mode`: The [permissions](http://permissions-calculator.org/) for the file to be mounted in `/run/secrets/`
+  in the service's task containers, in octal notation.
+  Default value is world-readable permissions (mode `0444`).
+  The writable bit MUST be ignored if set. The executable bit MAY be set.
+
+The following example sets the name of the `server-certificate` secret file to `server.crt`
+within the container, sets the mode to `0440` (group-readable) and sets the user and group
+to `103`. The value of `server-certificate` secret is provided by the platform through a lookup and
+the secret lifecycle not directly managed by the Compose implementation.
+
+```yml
+services:
+  frontend:
+    build:
+      context: .
+      secrets:
+        - source: server-certificate
+          target: server.cert
+          uid: "103"
+          gid: "103"
+          mode: 0440
+secrets:
+  server-certificate:
+    external: true
+```
+
+Service builds MAY be granted access to multiple secrets. Long and short syntax for secrets MAY be used in the
+same Compose file. Defining a secret in the top-level `secrets` MUST NOT imply granting any service build access to it.
+Such grant must be explicit within service specification as [secrets](spec.md#secrets) service element.
+
 ## Implementations
 
 * [docker-compose](https://docs.docker.com/compose)

diff --git a/schema/compose-spec.json b/schema/compose-spec.json
@@ -99,7 +99,27 @@
                 "target": {"type": "string"},
                 "shm_size": {"type": ["integer", "string"]},
                 "extra_hosts": {"$ref": "#/definitions/list_or_dict"},
-                "isolation": {"type": "string"}
+                "isolation": {"type": "string"},
+                "secrets": {
+                  "type": "array",
+                  "items": {
+                    "oneOf": [
+                      {"type": "string"},
+                      {
+                        "type": "object",
+                        "properties": {
+                          "source": {"type": "string"},
+                          "target": {"type": "string"},
+                          "uid": {"type": "string"},
+                          "gid": {"type": "string"},
+                          "mode": {"type": "number"}
+                        },
+                        "additionalProperties": false,
+                        "patternProperties": {"^x-": {}}
+                      }
+                    ]
+                  }
+                }
               },
               "additionalProperties": false,
               "patternProperties": {"^x-": {}}