This cookbook is concerned with the [Docker](http://docker.io) container engine as distributed by Docker, Inc. It does not address Docker ecosystem tooling or prerequisite technology such as cgroups or aufs.
This cookbook automatically sets up the upstream Docker package repositories. If you would like to use your own repositories this functionality can be disabled and you can instead setup the repos yourself with yum_repository/apt_repository resources or the [chef-apt-docker](https://supermarket.chef.io/cookbooks/chef-apt-docker) / [chef-yum-docker](https://supermarket.chef.io/cookbooks/chef-yum-docker) cookbooks.
If you are not using the official docker repositories you may run into issues with the docker group being different. RHEL is a known issue that defaults to using `dockerroot` for the service group. Add the `group` property to the `docker_service`.
The `docker_installation_tarball` resource copies the precompiled Go binary tarball onto the disk. It should not be used in production, especially with devicemapper.
The `docker_installation_script` resource runs the script hosted by Docker, Inc at <http://get.docker.com>. It configures package repositories and installs a dynamically compiled binary.
The `docker_installation_package` resource uses the system package manager to install Docker. It relies on the pre-configuration of the system's package repositories. The `chef-yum-docker` and `chef-apt-docker` Supermarket cookbooks can be used to use Docker's own repositories.
-`package_name` - Name of package to install. Defaults to 'docker-ce'
-`package_options` - Manually specify additional options, like apt-get directives for example
-`setup_docker_repo` - Setup the download.docker.com repo. If you would like to manage the repo yourself so you can use an internal repo then set this to false. default: true on all platforms except Amazon Linux.
-`repo_channel` - The channel of docker to setup from download.docker.com. Only used if `setup_docker_repo` is true. default: 'stable'
The `docker_service_manager` resource auto-selects a strategy from the `docker_service_manager_*` group of resources based on platform and version. The `docker_service` family share a common set of properties.
WARNING - When creating multiple `docker_service` resources on the same machine, you will need to specify unique data_root properties to avoid unexpected behavior and possible data corruption.
The `docker_service` resource property list mostly corresponds to the options found in the [Docker Command Line Reference](https://docs.docker.com/engine/reference/commandline/docker/)
-`source` - URL to the pre-compiled Docker binary used for installation. Defaults to a calculated URL based on kernel version, Docker version, and platform arch. By default, this will try to get to "<http://get.docker.io/builds/>".
-`systemd_opts` - An array of strings that will be included as individual lines in the systemd service unit for Docker. _Note_: This option is only relevant for systems where systemd is the default service manager or where systemd is specified explicitly as the service manager.
-`systemd_socket_opts` - An array of strings that will be included as individual lines in the systemd socket unit for Docker. _Note_: This option is only relevant for systems where systemd is the default service manager or where systemd is specified explicitly as the service manager.
The `docker_image` is responsible for managing Docker image pulls, builds, and deletions. It speaks directly to the [Docker Engine API](https://docs.docker.com/engine/api/v1.35/#tag/Image).
### Actions
-`:pull` - Pulls an image from the registry. Default action.
-`:pull_if_missing` - Pulls an image from the registry, only if it missing
-`:build` - Builds an image from a Dockerfile, directory, or tarball
-`:build_if_missing` - Same build, but only if it is missing
-`:save` - Exports an image to a tarball at `destination`
-`:import` - Imports an image from a tarball at `destination`
-`:remove` - Removes (untags) an image
-`:push` - Pushes an image to the registry
### Properties
The `docker_image` resource properties mostly corresponds to the [Docker Engine API](https://docs.docker.com/engine/api/v1.35/#tag/Image) as driven by the [docker-api Ruby gem](https://github.com/swipely/docker-api)
A `docker_image`'s full identifier is a string in the form "\
-`repo` - aka `image_name` - The first half of a Docker image's identity. This is a string in the form: `registry:port/owner/image_name`. If the `registry:port` portion is left off, Docker will implicitly use the Docker public registry. "Official Images" omit the owner part. This means a repo id can be as short as `busybox`, `alpine`, or `centos`. These names refer to official images on the public registry. Names can be as long as `my.computers.biz:5043/what/ever` to refer to custom images on an private registry. Often you'll see something like `chef/chef` to refer to private images on the public registry. - Defaults to resource name.
-`tag` - The second half of a Docker image's identity. - Defaults to `latest`
-`source` - Path to input for the `:import`, `:build` and `:build_if_missing` actions. For building, this can be a Dockerfile, a tarball containing a Dockerfile in its root, or a directory containing a Dockerfile. For `:import`, this should be a tarball containing Docker formatted image, as generated with `:save`.
-`destination` - Path for output from the `:save` action.
-`force` - A force boolean used in various actions - Defaults to false
-`nocache` - Used in `:build` operations. - Defaults to false
-`noprune` - Used in `:remove` operations - Defaults to false
-`rm` - Remove intermediate containers after a successful build (default behavior) - Defaults to `true`
-`read_timeout` - May need to increase for long image builds/pulls
-`write_timeout` - May need to increase for long image builds/pulls
-`host` - A string containing the host the API should communicate with. Defaults to `ENV['DOCKER_HOST']` if set.
-`tls` - Use TLS; implied by --tlsverify. Defaults to ENV['DOCKER_TLS'] if set.
-`tls_verify` - Use TLS and verify the remote. Defaults to `ENV['DOCKER_TLS_VERIFY']` if set
-`tls_ca_cert` - Trust certs signed only by this CA. Defaults to `ENV['DOCKER_CERT_PATH']` if set.
-`tls_client_cert` - Path to TLS certificate file for docker cli. Defaults to `ENV['DOCKER_CERT_PATH']` if set
-`tls_client_key` - Path to TLS key file for docker cli. Defaults to `ENV['DOCKER_CERT_PATH']` if set.
- build from a tarball NOTE: this is not an "export" tarball generated from an an image save. The contents should be a Dockerfile, and anything it references to COPY or ADD
The `docker_image_prune` is responsible for pruning Docker images from the system. It speaks directly to the [Docker Engine API](https://docs.docker.com/engine/api/v1.35/#operation/ImagePrune).
Note - this is best implemented by subscribing to `docker_image` changes. There is no need to to clean up old images upon each converge. It is best done at the end of a chef run (delayed) only if a new image was pulled.
-`dangling` - When set to true (or 1), prune only unused and untagged images. When set to false (or 0), all unused images are pruned
-`prune_until` - Prune images created before this timestamp. The <timestamp> can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the daemon machine’s time.
-`with_label/without_label` - (label=<key>, label=<key>=<value>, label!=<key>, or label!=<key>=<value>) Prune images with (or without, in case label!=... is used) the specified labels.
-`host` - A string containing the host the API should communicate with. Defaults to `ENV['DOCKER_HOST']` if set.
Docker tags work very much like hard links in a Unix filesystem. They are just references to an existing image. Therefore, the docker_tag resource has taken inspiration from the Chef `link` resource.
The `docker_container` is responsible for managing Docker container actions. It speaks directly to the [Docker remote API](https://docs.docker.com/reference/api/docker_remote_api_v1.20/).
Containers are process oriented, and move through an event cycle. Thanks to [Glider Labs](http://gliderlabs.com/) for this excellent diagram. 
### Actions
-`:create` - Creates the container but does not start it. Useful for Volume containers.
-`:start` - Starts the container. Useful for containers that run jobs.. command that exit.
-`:run` - The default action. Both `:create` and `:start` the container in one action. Redeploys the container on resource change.
-`:run_if_missing` - Runs a container only once.
-`:stop` - Stops the container.
-`:restart` - Stops and then starts the container.
-`:kill` - Send a signal to the container process. Defaults to `SIGKILL`.
-`:pause` - Pauses the container.
-`:unpause` - Unpauses the container.
-`:delete` - Deletes the container.
-`:redeploy` - Deletes and runs the container.
-`:reload` - Sends SIGHUP to pid 1 in the container
Most `docker_container` properties are the `snake_case` version of the `CamelCase` keys found in the [Docker Remote Api](https://docs.docker.com/reference/api/docker_remote_api_v1.20/)
-`container_name` - The name of the container. Defaults to the name of the `docker_container` resource.
-`repo` - aka `image_name`. The first half of a the complete identifier for a Docker Image.
-`tag` - The second half of a Docker image's identity. - Defaults to `latest`.
-`command` - The command to run when starting the container.
-`autoremove` - Boolean - Automatically delete a container when it's command exits. Defaults to `false`.
-`volumes` - An array of volume bindings for this container. Each volume binding is a string in one of these forms: `container_path` to create a new volume for the container. `host_path:container_path` to bind-mount a host path into the container. `host_path:container_path:ro` to make the bind-mount read-only inside the container.
-`cap_add` - An array Linux Capabilities (`man 7 capabilities`) to add to grant the container beyond what it normally gets.
-`cap_drop` - An array Linux Capabilities (`man 7 capabilities`) to revoke that the container normally has.
-`cpu_shares` - An integer value containing the CPU Shares for the container.
-`devices` - A Hash of devices to add to the container.
-`dns` - An array of DNS servers the container will use for name resolution.
-`dns_search` - An array of domains the container will search for name resolution.
-`domain_name` - Set's the container's dnsdomainname as returned by the `dnsdomainname` command.
-`entrypoint` - Set the entry point for the container as a string or an array of strings.
-`env` - Set environment variables in the container in the form `['FOO=bar', 'BIZ=baz']`
-`env_file` - Read environment variables from a file and set in the container. Accepts an Array or String to the file location. lazy evaluator must be set if the file passed is created by Chef.
-`extra_hosts` - An array of hosts to add to the container's `/etc/hosts` in the form `['host_a:10.9.8.7', 'host_b:10.9.8.6']`
-`force` - A boolean to use in container operations that support a `force` option. Defaults to `false`
-`health_check` - A hash containing the health check options - https://docs.docker.com/engine/reference/run/#healthcheck
-`host` - A string containing the host the API should communicate with. Defaults to ENV['DOCKER_HOST'] if set
-`host_name` - The hostname for the container.
-`labels` A string, array, or hash to set metadata on the container in the form ['foo:bar', 'hello:world']`
-`links` - An array of source container/alias pairs to link the container to in the form `[container_a:www', container_b:db']`
-`log_driver` - Sets a custom logging driver for the container (json-file/syslog/journald/gelf/fluentd/none).
-`log_opts` - Configures the above logging driver options (driver-specific).
-`init` - Run an init inside the container that forwards signals and reaps processes.
-`mac_address` - The mac address for the container to use.
-`memory` - Memory limit in bytes.
-`memory_swap` - Total memory limit (memory + swap); set `-1` to disable swap limit (unlimited). You must use this with memory and make the swap value larger than memory.
-`network_disabled` - Boolean to disable networking. Defaults to `false`.
-`network_mode` - Sets the networking mode for the container. One of `bridge`, `host`, `container`.
-`network_aliases` - Adds network-scoped alias for the container in form `['alias-1', 'alias-2']`.
-`oom_kill_disable` - Whether to disable OOM Killer for the container or not.
-`oom_score_adj` - Tune container's OOM preferences (-1000 to 1000).
-`open_stdin` - Boolean value, opens stdin. Defaults to `false`.
-`outfile` - The path to write the file when using `:export` action.
-`port` - The port configuration to use in the container. Matches the syntax used by the `docker` CLI tool.
-`privileged` - Boolean to start the container in privileged more. Defaults to `false`
-`publish_all_ports` - Allocates a random host port for all of a container's exposed ports.
-`remove_volumes` - A boolean to clean up "dangling" volumes when removing the last container with a reference to it. Default to `false` to match the Docker CLI behavior.
-`restart_policy` - One of `no`, `on-failure`, `unless-stopped`, or `always`. Use `always` if you want a service container to survive a Dockerhost reboot. Defaults to `no`.
-`restart_maximum_retry_count` - Maximum number of restarts to try when `restart_policy` is `on-failure`. Defaults to an ever increasing delay (double the previous delay, starting at 100mS), to prevent flooding the server.
-`running_wait_time` - Amount of seconds `docker_container` wait to determine if a process is running.
-`runtime` - Runtime to use when running container. Defaults to `runc`.
-`security_opt` - A list of string values to customize labels for MLS systems, such as SELinux.
-`shm_size` - The size of `/dev/shm`. The format is `<number><unit>`, where number must be greater than 0. Unit is optional and can be b (bytes), k (kilobytes), m(megabytes), or g (gigabytes). The default is `64m`.
-`signal` - The signal to send when using the `:kill` action. Defaults to `SIGTERM`.
-`sysctls` - A hash of sysctls to set on the container. Defaults to `{}`.
-`tty` - Boolean value to allocate a pseudo-TTY. Defaults to `false`.
-`user` - A string value specifying the user inside the container.
-`volumes` - An Array of paths inside the container to expose. Does the same thing as the `VOLUME` directive in a Dockerfile, but works on container creation.
-`volumes_from` - A list of volumes to inherit from another container. Specified in the form `<container name>[:<ro|rw>]`
-`volume_driver` - Driver that this container users to mount volumes.
-`working_dir` - A string specifying the working directory for commands to run in.
-`read_timeout` - May need to increase for commits or exports that are slow
-`write_timeout` - May need to increase for commits or exports that are slow
-`kill_after` - Number of seconds to wait before killing the container. Defaults to wait indefinitely; eventually will hit read_timeout limit.
-`timeout` - Seconds to wait for an attached container to return
-`tls` - Use TLS; implied by --tlsverify. Defaults to ENV['DOCKER_TLS'] if set
-`tls_verify` - Use TLS and verify the remote. Defaults to ENV['DOCKER_TLS_VERIFY'] if set
-`tls_ca_cert` - Trust certs signed only by this CA. Defaults to ENV['DOCKER_CERT_PATH'] if set
-`tls_client_cert` - Path to TLS certificate file for docker cli. Defaults to ENV['DOCKER_CERT_PATH'] if set
-`tls_client_key` - Path to TLS key file for docker cli. Defaults to ENV['DOCKER_CERT_PATH'] if set
-`userns_mode` - Modify the user namespace mode - Defaults to `nil`, example option: `host`
-`pid_mode` - Set the PID (Process) Namespace mode for the container. `host`: use the host's PID namespace inside the container.
-`ipc_mode` - Set the IPC mode for the container - Defaults to `nil`, example option: `host`
-`uts_mode` - Set the UTS namespace mode for the container. The UTS namespace is for setting the hostname and the domain that is visible to running processes in that namespace. By default, all containers, including those with `--network=host`, have their own UTS namespace. The host setting will result in the container using the same UTS namespace as the host. Note that --hostname is invalid in host UTS mode.
-`ro_rootfs` - Mount the container's root filesystem as read only using the `--read-only` flag. Defaults to `false`
The `docker_network` resource is responsible for managing Docker named networks. Usage of `overlay` driver requires the `docker_service` to be configured to use a distributed key/value store like `etcd`, `consul`, or `zookeeper`.
The `docker_plugin` resource allows you to install, configure, enable, disable and remove [Docker Engine managed plugins](https://docs.docker.com/engine/extend/).
-`local_alias` - Local name for the plugin (defaults to the resource name).
-`remote` - Ref of the plugin (e.g. `vieux/sshfs`). Defaults to `local_alias` or the resource name. Only used for `:install`.
-`remote_tag` - Remote tag of the plugin to pull (e.g. `1.0.1`, defaults to `latest`) Only used for `:install`.
-`options` - Hash of options to set on the plugin. Only used for `:update` and `:install`.
-`grant_privileges` - Array of privileges or true. If it is true, all privileges requested by the plugin will be automatically granted (potentially dangerous). Otherwise, this must be an array in the same format as returned by the [`/plugins/privileges` docker API](https://docs.docker.com/engine/api/v1.37/#operation/GetPluginPrivileges) endpoint. If the array of privileges is not sufficient for the plugin, docker will reject it and the installation will fail. Defaults to `[]` (empty array => no privileges). Only used for `:install`. Does not modify the privileges of already-installed plugins.
