[RFC] UX/Consistency: the state of credential spec

While working on https://github.com/moby/moby/pull/34002, I noticed there's a lot of confusing bits in this feature that we may want to improve on;

on docker run / docker create

• set through --security-opt credentialspec=file://foo (https://github.com/moby/moby/pull/23389)

• flag --credentialspec was not implemented, and removed in https://github.com/moby/moby/pull/31976

• compose-file (version: 2 - undocumented https://docs.docker.com/compose/compose-file/compose-file-v2/#security_opt):

    version: '2'
    services:
      sqlserver:
        ...
        security_opt:
          - "credentialspec=file://sqlserverapp.json"
  

on docker service create / docker service update

• set through dedicated flag: --credential-spec=file://foo (https://github.com/moby/moby/pull/32339)
• compose-file (version 3): https://docs.docker.com/compose/compose-file/#credential_spec
• top-level option for service

Docker compose docs / implementation (version 3):

Documentation needs some updating;

    credential_spec:
      file: c:/WINDOWS/my-credential-spec.txt

    credential_spec:
      registry: HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs

Using:

registry: "HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs"

Produces an error:

yaml: line 6: found unknown escape character

And has to be changed to;

registry: "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Virtualization\\Containers\\CredentialSpecs"

In addition:

• The example file in the documentation is an absolute path, but paths should be specified relative to C:\ProgramData\docker\CredentialSpecs\, or more factually <docker root>/CredentialSpecs (docker root is configurable)
• The example file in the documentation is specified using a Linux path, but should use Windows (backslash, instead of forward slash)
• We should explain if "file" refers to a file on the local host, the daemon host, or inside the container
• The registry option only expects a registry key name, not the full path (i.e. it searches for a key named "the-key-I-specified" inside HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs)
• There's no example of the expected format of the credential specs file
  • the example shows .txt, but the credential specs file is actually a JSON file, in which case, our example should use my-credential-spec.json
  • can we provide an example file, and how to create/generate one (or refer to Windows documentation on creating one)

Error message consistency

Using this compose file;

version: '3.3'
services:
  web:
    image: "nginx:alpine"
    credential_spec:
        file: c:/WINDOWS/my-credential-spec.txt
        registry: "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Virtualization\\Containers\\CredentialSpecs"

produces an error, because both file: and registry: is specified;

service web: Invalid credential spec - must provide one of `File` or `Registry`

The error is correct, but given that this error is generated client-side;

• should File and Registry be changed to file: and registry: ?
• do we perform the same validation server-side? (we should)

Start with the Docker CLI credential-spec entry points for docker run/create and service create/update, then compare the Compose v2 and v3 documentation and client-side validation described here. Resolve the proposed option names, path and registry semantics, examples, and server-side validation scope. Done means the behavior and documentation are consistent and the conflicting file/registry case is validated consistently.