docker_secret - Manage docker secrets.
New in version 2.4.
Synopsis
- Create and remove Docker secrets in a Swarm environment. Similar to
docker secret create
anddocker secret rm
. - Adds to the metadata of new secrets ‘ansible_key’, an encrypted hash representation of the data, which is then used
- in future runs to test if a secret has changed.
- If ‘ansible_key is not present, then a secret will not be updated unless the
force
option is set. - Updates to secrets are performed by removing the secret and creating it again.
Requirements
The below requirements are needed on the host that executes this module.
- docker-py >= 2.1.0
- Docker API >= 1.25
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
api_version | Default:
default provided by docker-py
|
The version of the Docker API running on the Docker Host. Defaults to the latest version of the API supported by docker-py.
aliases: docker_api_version |
cacert_path | Default:
None
|
Use a CA certificate when performing server verification by providing the path to a CA certificate file.
aliases: tls_ca_cert |
cert_path | Default:
None
|
Path to the client's TLS certificate file.
aliases: tls_client_cert |
data |
String. The value of the secret. Required when state is
present .
|
|
docker_host | Default:
unix://var/run/docker.sock
|
The URL or Unix socket path used to connect to the Docker API. To connect to a remote host, provide the TCP connection string. For example, 'tcp://192.0.2.23:2376'. If TLS is used to encrypt the connection, the module will automatically replace 'tcp' in the connection URL with 'https'.
aliases: docker_url |
force | Default:
no
|
Boolean. Use with state
present to always remove and recreate an existing secret.
If
true, an existing secret will be replaced, even if it has not changed.
|
key_path | Default:
None
|
Path to the client's TLS key file.
aliases: tls_client_key |
labels |
A map of key:value meta data, where both the
key and
value are expected to be a string.
If new meta data is provided, or existing meta data is modified, the secret will be updated by removing it and creating it again.
|
|
name
required
|
The name of the secret.
|
|
ssl_version | Default:
1.0
|
Provide a valid SSL version number. Default value determined by docker-py, currently 1.0.
|
state |
|
Set to
present , if the secret should exist, and
absent , if it should not.
|
timeout | Default:
60
|
The maximum amount of time in seconds to wait on a response from the API.
|
tls | Default:
no
|
Secure the connection to the API by using TLS without verifying the authenticity of the Docker host server.
|
tls_hostname | Default:
localhost
|
When verifying the authenticity of the Docker Host server, provide the expected name of the server.
|
tls_verify | Default:
no
|
Secure the connection to the API by using TLS and verifying the authenticity of the Docker host server.
|
Notes
Note
- Connect to the Docker daemon by providing parameters with each task or by defining environment variables. You can define DOCKER_HOST, DOCKER_TLS_HOSTNAME, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_SSL_VERSION, DOCKER_TLS, DOCKER_TLS_VERIFY and DOCKER_TIMEOUT. If you are using docker machine, run the script shipped with the product that sets up the environment. It will set these variables for you. See https://docker-py.readthedocs.org/en/stable/machine/ for more details.
Examples
- name: Create secret foo docker_secret: name: foo data: Hello World! state: present - name: Change the secret data docker_secret: name: foo data: Goodnight everyone! labels: bar: baz one: '1' state: present - name: Add a new label docker_secret: name: foo data: Goodnight everyone! labels: bar: baz one: '1' # Adding a new label will cause a remove/create of the secret two: '2' state: present - name: No change docker_secret: name: foo data: Goodnight everyone! labels: bar: baz one: '1' # Even though 'two' is missing, there is no change to the existing secret state: present - name: Update an existing label docker_secret: name: foo data: Goodnight everyone! labels: bar: monkey # Changing a label will cause a remove/create of the secret one: '1' state: present - name: Force the removal/creation of the secret docker_secret: name: foo data: Goodnight everyone! force: yes state: present - name: Remove secret foo docker_secret: name: foo state: absent
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
secret_id
string
|
success |
The ID assigned by Docker to the secret object.
Sample:
hzehrmyjigmcp2gb6nlhmjqcv
|
Status
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
Author
- Chris Houseknecht (@chouseknecht)
Hint
If you notice any issues in this documentation you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.5/modules/docker_secret_module.html