Cross-Platform Compatibility - docker/docker-credential-helpers

The docker-credential-helpers project (https://github.com/docker/docker-credential-helpers) is a collection of command-line tools that enable cross-platform compatibility for securely storing Docker credentials. The project supports various operating systems, including Windows, macOS, and Linux. This response will discuss the possible options and provide examples for each option, quoting the source of information to build confidence.

Design Philosophy

The docker-credential-helpers project follows a simple protocol inspired by Git, allowing programs or scripts to securely store and retrieve Docker credentials (https://docs.docker.com/engine/reference/commandline/login). The helpers use the first argument in the command to identify the action.

Programming languages

The project utilizes multiple programming languages:

Go: The main language used for the project, including the github.com/docker/docker-credential-helpers and github.com/docker/docker-credential-helpers/client modules.
C: The github.com/danieljoos/wincred module is implemented in C for Windows support.
Shell: The docker-credential-secretservice module is written in shell for Linux secret service support.
HCL: The docker-credential-pass module is written in HCL for pass password manager support.

Key Technologies and Dependencies

golang.org/x/sys: A Go package that provides a portable way to perform system-specific operations.
github.com/docker/docker-credential-helpers: The main Go module for the project.
github.com/docker/docker-credential-osxkeychain: A Go module for macOS Keychain support.
github.com/docker/docker-credential-secretservice: A Go module for Linux secret service support.
github.com/docker/docker-credential-pass: A Go module for pass password manager support.
golangci/golangci-lint: A Go linter used for code analysis.
crazymax/osxcross: A tool for cross-compiling Go applications for macOS on other platforms.

Cross-Platform Compatibility Examples

Windows

To use the credential manager on Windows, install the wincred binary into a directory in your $PATH. Edit ~/.policy/config.json to set wincred as the credential store:

{
"auths": {},
"credStore": "wincred"
}

macOS

Install osxkeychain for amd64 or arm64 into a directory in your $PATH. Edit ~/.policy/config.json to set osxkeychain as the credential store:

{
"auths": {},
"credStore": "osxkeychain"
}

Linux

By default, Docker looks for the native binary on each platform, i.e., “osxkeychain” on macOS, “wincred” on windows, and “pass” on Linux. If none of these binaries are present, it stores the credentials (i.e., password) in base64 encoding in the config files.

For example, to use the pass password manager on Linux, install the pass binary into a directory in your $PATH. Edit ~/.docker/config.json to set pass as the configured credentials store:

{
"credsStore": "pass"
}

For more information, see the Docker documentation on credential stores.

Docker Compose

Docker Compose version 2.12.0 and higher support the use of Docker credential helpers. To configure a credentials store in the Docker configuration file, add a credStore to ~/.docker/config.json:

{
"credsStore": "osxkeychain"
}

For more information, see the Docker Compose documentation.

Prometheus

Prometheus supports Docker credential helpers for authentication when scraping metrics from Docker containers. To configure Prometheus to use a credentials store, add a credsStore to the docker block in the Prometheus configuration file:

docker:
server: 'unix:///var/run/docker.sock'
credsStore: 'osxkeychain'

For more information, see the Prometheus documentation on Docker SD configuration.

Conclusion

The docker-credential-helpers project provides cross-platform compatibility for securely storing Docker credentials. By following the simple protocol and using the provided modules, developers can easily integrate Docker credential helpers into their projects, ensuring secure authentication across various operating systems.