change ssh type to string and update ssh section with contributors feebacks

glours · ndeloof · commit 08508335e115 · 2022-03-09T08:42:56.000+01:00
Signed-off-by: Guillaume Lours &lt;guillaume.lours@docker.com&gt;
diff --git a/build.md b/build.md
@@ -161,8 +161,8 @@ args:
 
 `ssh` property syntax can be either:
 * `default` - let the builder connect to the ssh-agent.
-* `ID=socket` - a key/value definition of an ID and the associated socket
-* `ssh` without any value which is a shortcut of the `default` configuration
+* `ID=path` - a key/value definition of an ID and the associated path. Can be either a [PEM](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) file, or path to ssh-agent socket
+* `{}` (no value) which is a shortcut of the `default` configuration
 
 `ssh` without any parameter
 ```yaml
@@ -177,12 +177,16 @@ build:
   context: .
   ssh: default   # mount the default ssh agent
 ```
-Using a custom id `myproject` which will be use in the Dockerfile (i.e., `RUN --mount=type=ssh,id=myproject git clone ...`)
+Using a custom id `myproject` with path to a local SSH key:
 ```yaml
 build:
   context: .
   ssh: myproject=~/.ssh/myproject.pem
 ```
+Image builder can then rely on this to mount SSH key during build.
+For illustration, [Buildkit extended syntax](https://github.com/compose-spec/compose-spec/pull/234/%5Bmoby/buildkit@master/frontend/dockerfile/docs/syntax.md#run---mounttypessh%5D(https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md#run---mounttypessh)) can be used to mount ssh key set by ID and access a secured resource:
+
+`RUN --mount=type=ssh,id=myproject git clone ...`
 
 ### cache_from
 
diff --git a/schema/compose-spec.json b/schema/compose-spec.json
@@ -91,7 +91,7 @@
                 "context": {"type": "string"},
                 "dockerfile": {"type": "string"},
                 "args": {"$ref": "#/definitions/list_or_dict"},
-                "ssh": {"$ref": "#/definitions/string_or_list"},
+                "ssh": {"type": "string"},
                 "labels": {"$ref": "#/definitions/list_or_dict"},
                 "cache_from": {"type": "array", "items": {"type": "string"}},
                 "cache_to": {"type": "array", "items": {"type": "string"}},
