diff --git a/compose/compose-file/index.md b/compose/compose-file/index.md index 35694eb04c..00691a9dd2 100644 --- a/compose/compose-file/index.md +++ b/compose/compose-file/index.md @@ -529,7 +529,7 @@ an error. ### credential_spec -> **Note**: this option was added in v3.3. +> **Note**: This option was added in v3.3. Using group Managed Service Account (gMSA) configurations with compose files is supported in Compose version 3.8. Configure the credential spec for managed service account. This option is only used for services using Windows containers. The `credential_spec` must be in the @@ -558,6 +558,22 @@ credential_spec: registry: my-credential-spec ``` +#### Example gMSA configuration +When configuring a gMSA credential spec for a service, you only need +to specify a credential spec with `config`, as shown in the following example: +``` +version: "3.8" +services: + myservice: + image: myimage:latest + credential_spec: + config: my_credential_spec + +configs: + my_credentials_spec: + file: ./my-credential-spec.json| +``` + ### depends_on Express dependency between services, Service dependencies cause the following diff --git a/engine/swarm/configs.md b/engine/swarm/configs.md index a739122e39..3732e3dd2f 100644 --- a/engine/swarm/configs.md +++ b/engine/swarm/configs.md @@ -43,6 +43,10 @@ examples below. Keep the following notable differences in mind: UID, GID, and mode are not supported for configs. Configs are currently only accessible by administrators and users with `system` access within the container. + +- On Windows, create or update a service using `--credential-spec` with the `config://` format. +This passes the gMSA credentials file directly to nodes before a container starts. No gMSA credentials are written +to disk on worker nodes. For more information, refer to [Deploy services to a swarm](/engine/swarmservices/). ## How Docker manages configs diff --git a/engine/swarm/secrets.md b/engine/swarm/secrets.md index e52c644220..0c17032c6e 100644 --- a/engine/swarm/secrets.md +++ b/engine/swarm/secrets.md @@ -73,7 +73,6 @@ examples below. Keep the following notable differences in mind: accessible by administrators and users with `system` access within the container. - ## How Docker manages secrets When you add a secret to the swarm, Docker sends the secret to the swarm manager diff --git a/engine/swarm/services.md b/engine/swarm/services.md index 8e5e0f3f48..3f8cacd1ca 100644 --- a/engine/swarm/services.md +++ b/engine/swarm/services.md @@ -94,6 +94,44 @@ This passes the login token from your local client to the swarm nodes where the service is deployed, using the encrypted WAL logs. With this information, the nodes are able to log into the registry and pull the image. +### Provide credential specs for managed service accounts + + In Enterprise Edition 3.0, security is improved through the centralized distribution and management of Group Managed Service Account(gMSA) credentials using Docker Config functionality. Swarm now allows using a Docker Config as a gMSA credential spec, which reduces the burden of distributing credential specs to the nodes on which they are used. + + **Note**: This option is only applicable to services using Windows containers. + + Credential spec files are applied at runtime, eliminating the need for host-based credential spec files or registry entries - no gMSA credentials are written to disk on worker nodes. You can make credential specs available to Docker Engine running swarm kit worker nodes before a container starts. When deploying a service using a gMSA-based config, the credential spec is passed directly to the runtime of containers in that service. + + The `--credential-spec` must be one of the following formats: + + - `file://`: The referenced file must be present in the `CredentialSpecs` subdirectory in the docker data directory, which defaults to `C:\ProgramData\Docker\` on Windows. For example, specifying `file://spec.json` loads `C:\ProgramData\Docker\CredentialSpecs\spec.json`. +- `registry://`: The credential spec is read from the Windows registry on the daemon’s host. +- `config://`: The config name is automatically converted to the config ID in the CLI. +The credential spec contained in the specified `config` is used. + + The following simple example retrieves the gMSA name and JSON contents from your Active Directory (AD) instance: + + ``` +name="mygmsa" +contents="{...}" +echo $contents > contents.json +``` +Make sure that the nodes to which you are deploying are correctly configured for the gMSA. + + To use a Config as a credential spec, create a Docker Config in a credential spec file named `credpspec.json`. + You can specify any name for the name of the `config`. + +``` +docker config create credspec credspec.json +``` + +Now you can create a service using this credential spec. Specify the `--credential-spec` flag with the config name: +``` +docker service create --credential-spec="config://credspec" +``` + + Your service uses the gMSA credential spec when it starts, but unlike a typical Docker Config (used by passing the --config flag), the credential spec is not mounted into the container. + ## Update a service You can change almost everything about an existing service using the