diff --git a/CHANGELOG.md b/CHANGELOG.md index c52522f12..158384338 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Update documentation for `docker_container` resource - Update documentation for `docker_service` resource - Update documentation for `docker_exec` resource +- Update resources overview +- Update documentation for `docker_installation_package` resource +- Update documentation for `docker_installation_script` resource +- Update documentation for `docker_installation_tarball` resource +- Update documentation for `docker_service_manager_execute` resource +- Update documentation for `docker_service_manager_systemd` resource +- Update documentation for `docker_volume_prune` resource ## 11.8.2 - *2024-12-11* diff --git a/README.md b/README.md index 1f0478a7b..989819d21 100644 --- a/README.md +++ b/README.md @@ -73,19 +73,21 @@ Those recipes are found at `test/cookbooks/docker_test`. ## Resources Overview - [docker_service](documentation/docker_service.md): composite resource that uses docker_installation and docker_service_manager -- [docker_installation](#docker_installation): automatically select an installation method -- [docker_service_manager](#docker_service_manager): automatically selects a service manager -- [docker_installation_script](#docker_installation_script): curl | bash -- [docker_installation_package](#docker_installation_package): package 'docker-ce' -- [docker_service_manager_execute](#docker_service_manager_execute): manage docker daemon with Chef -- [docker_service_manager_systemd](#docker_service_manager_systemd): manage docker daemon with systemd unit files -- [docker_image](documentation/docker_image.md): image/repository operations - [docker_container](documentation/docker_container.md): container operations -- [docker_tag](documentation/docker_tag.md): image tagging operations -- [docker_registry](documentation/docker_registry.md): registry operations +- [docker_exec](documentation/docker_exec.md): execute commands inside running containers +- [docker_image](documentation/docker_image.md): image/repository operations +- [docker_image_prune](documentation/docker_image_prune.md): remove unused docker images +- [docker_installation_package](documentation/docker_installation_package.md): install Docker via package 'docker-ce' +- [docker_installation_script](documentation/docker_installation_script.md): install Docker via curl | bash +- [docker_installation_tarball](documentation/docker_installation_tarball.md): install Docker from a tarball - [docker_network](documentation/docker_network.md): network operations -- [docker_volume](documentation/docker_volume.md): volume operations - [docker_plugin](documentation/docker_plugin.md): plugin operations +- [docker_registry](documentation/docker_registry.md): registry operations +- [docker_service_manager_execute](documentation/docker_service_manager_execute.md): manage docker daemon with Chef +- [docker_service_manager_systemd](documentation/docker_service_manager_systemd.md): manage docker daemon with systemd unit files +- [docker_tag](documentation/docker_tag.md): image tagging operations +- [docker_volume](documentation/docker_volume.md): volume operations +- [docker_volume_prune](documentation/docker_volume_prune.md): remove unused docker volumes ## Getting Started diff --git a/documentation/docker_installation_package.md b/documentation/docker_installation_package.md new file mode 100644 index 000000000..fefd457fe --- /dev/null +++ b/documentation/docker_installation_package.md @@ -0,0 +1,94 @@ +# docker_installation_package + +The `docker_installation_package` resource is responsible for installing Docker via package manager. It supports both Debian/Ubuntu and RHEL/Fedora platforms. + +## Actions + +- `:create` - Installs Docker package and sets up the Docker repository if enabled +- `:delete` - Removes the Docker package + +## Properties + +| Property | Type | Default | Description | +|------------------|---------|------------------------|------------------------------------------------------------| +| `setup_docker_repo` | Boolean | `true` | Whether to set up the Docker repository | +| `repo_channel` | String | `'stable'` | Repository channel to use (`stable`, `test`, `nightly`) | +| `package_name` | String | `'docker-ce'` | Name of the Docker package to install | +| `package_version` | String | `nil` | Specific package version to install | +| `version` | String | `nil` | Docker version to install (e.g., '20.10.23') | +| `package_options` | String | `nil` | Additional options to pass to the package manager | +| `site_url` | String | `'download.docker.com'`| Docker repository URL | + +## Examples + +### Install Latest Version of Docker + +```ruby +docker_installation_package 'default' do + action :create +end +``` + +### Install Specific Version of Docker + +```ruby +docker_installation_package 'default' do + version '20.10.23' + action :create +end +``` + +### Install from Test Channel + +```ruby +docker_installation_package 'default' do + repo_channel 'test' + action :create +end +``` + +### Install Without Setting Up Docker Repository + +```ruby +docker_installation_package 'default' do + setup_docker_repo false + action :create +end +``` + +### Remove Docker Installation + +```ruby +docker_installation_package 'default' do + action :delete +end +``` + +## Platform Support + +This resource supports the following platforms: + +### Debian/Ubuntu + +- Debian 9 (Stretch) +- Debian 10 (Buster) +- Debian 11 (Bullseye) +- Debian 12 (Bookworm) +- Ubuntu 18.04 (Bionic) +- Ubuntu 20.04 (Focal) +- Ubuntu 22.04 (Jammy) +- Ubuntu 24.04 (Noble) + +### RHEL/Fedora + +- RHEL/CentOS 7 and later +- Fedora (latest versions) + +## Notes + +- The resource automatically handles architecture-specific package names and repositories +- For Debian/Ubuntu systems, it installs `apt-transport-https` package as a prerequisite +- Version strings are handled differently based on the Docker version and platform: + - For versions < 18.06: Uses format like `VERSION~ce-0~debian` or `VERSION~ce-0~ubuntu` + - For versions >= 18.09: Uses format like `5:VERSION~3-0~debian-CODENAME` or `5:VERSION~3-0~ubuntu-CODENAME` + - For versions >= 23.0 on Ubuntu: Uses format like `5:VERSION-1~ubuntu.VERSION~CODENAME` diff --git a/documentation/docker_installation_script.md b/documentation/docker_installation_script.md new file mode 100644 index 000000000..e0d581c04 --- /dev/null +++ b/documentation/docker_installation_script.md @@ -0,0 +1,75 @@ +# docker_installation_script + +The `docker_installation_script` resource installs Docker on Linux systems using the official Docker installation scripts. This is also known as the "curl pipe bash" installation method. + +## Actions + +- `:create` - Downloads and executes the Docker installation script +- `:delete` - Removes Docker packages installed by the script + +## Properties + +| Property | Type | Default | Description | +|-------------|--------|----------------|-----------------------------------------------------------------------| +| `repo` | String | `'main'` | Repository to use for installation. One of: `main`, `test`, or `experimental` | +| `script_url`| String | Based on repo | URL of the installation script. Defaults to official Docker URLs based on the repo property | + +## Examples + +### Install Docker from Main Repository + +```ruby +docker_installation_script 'default' do + action :create +end +``` + +### Install Docker from Test Repository + +```ruby +docker_installation_script 'default' do + repo 'test' + action :create +end +``` + +### Install Docker from Experimental Repository + +```ruby +docker_installation_script 'default' do + repo 'experimental' + action :create +end +``` + +### Install Docker Using Custom Script URL + +```ruby +docker_installation_script 'default' do + script_url 'https://my-custom-docker-install.example.com/install.sh' + action :create +end +``` + +### Remove Docker Installation + +```ruby +docker_installation_script 'default' do + action :delete +end +``` + +## Notes + +- This resource is only available on Linux systems +- The installation script requires `curl` to be installed (the resource will install it if missing) +- The script is executed with `sh` shell +- The installation is considered complete when `/usr/bin/docker` exists +- When removing Docker, both `docker-ce` and `docker-engine` packages are removed +- Default script URLs: + - Main: + - Test: + +## Platform Support + +This resource is supported on all Linux platforms that can run the Docker installation scripts. diff --git a/documentation/docker_installation_tarball.md b/documentation/docker_installation_tarball.md new file mode 100644 index 000000000..1827f1c8f --- /dev/null +++ b/documentation/docker_installation_tarball.md @@ -0,0 +1,84 @@ +# docker_installation_tarball + +The `docker_installation_tarball` resource installs Docker on a system using pre-compiled binary tarballs from the official Docker downloads. + +## Actions + +- `:create` - Downloads and installs Docker from a tarball +- `:delete` - Removes Docker installed from a tarball + +## Properties + +| Property | Type | Default | Description | +|------------|--------|-------------------|--------------------------------------------| +| `checksum` | String | Based on version | SHA256 checksum of the Docker tarball | +| `source` | String | Based on version | URL of the Docker tarball | +| `channel` | String | `'stable'` | Docker release channel to use | +| `version` | String | `'20.10.11'` | Docker version to install | + +## Examples + +### Install Default Version + +```ruby +docker_installation_tarball 'default' do + action :create +end +``` + +### Install Specific Version + +```ruby +docker_installation_tarball 'default' do + version '19.03.15' + action :create +end +``` + +### Install from Custom Source + +```ruby +docker_installation_tarball 'default' do + source 'https://example.com/docker-20.10.11.tgz' + checksum 'dd6ff72df1edfd61ae55feaa4aadb88634161f0aa06dbaaf291d1be594099ff3' + action :create +end +``` + +### Remove Docker Installation + +```ruby +docker_installation_tarball 'default' do + action :delete +end +``` + +## Platform Support + +This resource supports the following platforms: + +### Linux + +- Version 18.03.1: checksum `0e245c42de8a21799ab11179a4fce43b494ce173a8a2d6567ea6825d6c5265aa` +- Version 18.06.3: checksum `346f9394393ee8db5f8bd1e229ee9d90e5b36931bdd754308b2ae68884dd6822` +- Version 18.09.9: checksum `82a362af7689038c51573e0fd0554da8703f0d06f4dfe95dd5bda5acf0ae45fb` +- Version 19.03.15: checksum `5504d190eef37355231325c176686d51ade6e0cabe2da526d561a38d8611506f` +- Version 20.10.11: checksum `dd6ff72df1edfd61ae55feaa4aadb88634161f0aa06dbaaf291d1be594099ff3` + +### Darwin (macOS) + +- Version 18.03.1: checksum `bbfb9c599a4fdb45523496c2ead191056ff43d6be90cf0e348421dd56bc3dcf0` +- Version 18.06.3: checksum `f7347ef27db9a438b05b8f82cd4c017af5693fe26202d9b3babf750df3e05e0c` +- Version 18.09.9: checksum `ed83a3d51fef2bbcdb19d091ff0690a233aed4bbb47d2f7860d377196e0143a0` +- Version 19.03.15: checksum `61672045675798b2075d4790665b74336c03b6d6084036ef22720af60614e50d` +- Version 20.10.11: checksum `8f338ba618438fa186d1fa4eae32376cca58f86df2b40b5027c193202fad2acf` + +## Notes + +- The resource automatically detects the system architecture and kernel type to download the appropriate tarball +- Requires `tar` package to be installed (the resource will install it if missing) +- Creates a `docker` system group +- Filename format varies based on Docker version: + - For versions >= 19.x.x: `docker-VERSION.tgz` + - For version 18.09.x: `docker-VERSION.tgz` + - For versions <= 18.06.x: `docker-VERSION-ce.tgz` diff --git a/documentation/docker_service.md b/documentation/docker_service.md index 5f005f42d..2a33814fb 100644 --- a/documentation/docker_service.md +++ b/documentation/docker_service.md @@ -20,16 +20,19 @@ The service management strategy is automatically chosen based on the platform bu - `service_manager` - Service manager to use: `execute`, `systemd`, `none`, or `auto` (default) #### Script Installation + - `repo` - Repository URL for script installation - `script_url` - Custom script URL for installation #### Package Installation + - `package_version` - Specific package version to install - `package_name` - Package name (default: docker-ce) - `setup_docker_repo` - Whether to configure Docker repository - `package_options` - Additional package installation options #### Tarball Installation + - `checksum` - SHA256 checksum of Docker binary - `docker_bin` - Path to Docker binary - `source` - URL to Docker binary tarball @@ -118,6 +121,7 @@ The service management strategy is automatically chosen based on the platform bu ### Service Management #### Systemd Options + - `systemd_opts` - Additional systemd service unit options - `systemd_socket_opts` - Additional systemd socket unit options - `mount_flags` - Systemd mount propagation flags diff --git a/documentation/docker_service_manager_execute.md b/documentation/docker_service_manager_execute.md new file mode 100644 index 000000000..bba7b4731 --- /dev/null +++ b/documentation/docker_service_manager_execute.md @@ -0,0 +1,74 @@ +# docker_service_manager_execute + +The `docker_service_manager_execute` resource manages the Docker daemon using Chef's execute resources. This is a basic service manager that uses shell commands to start, stop, and restart the Docker daemon. + +## Actions + +- `:start` - Starts the Docker daemon +- `:stop` - Stops the Docker daemon +- `:restart` - Restarts the Docker daemon (stop followed by start) + +## Properties + +This resource inherits properties from the `docker_service_base` resource. Common properties include: + +| Property | Type | Default | Description | +|-------------------|--------|------------|------------------------------------------------| +| `docker_daemon_cmd`| String | Generated | Command to start the Docker daemon | +| `logfile` | String | Based on name | Path to the log file | +| `pidfile` | String | Based on name | Path to the PID file | +| `http_proxy` | String | `nil` | HTTP proxy settings | +| `https_proxy` | String | `nil` | HTTPS proxy settings | +| `no_proxy` | String | `nil` | No proxy settings | +| `tmpdir` | String | `nil` | Temporary directory path | + +## Examples + +### Basic Usage + +```ruby +docker_service_manager_execute 'default' do + action :start +end +``` + +### Start Docker with Custom Settings + +```ruby +docker_service_manager_execute 'default' do + http_proxy 'http://proxy.example.com:3128' + https_proxy 'http://proxy.example.com:3128' + no_proxy 'localhost,127.0.0.1' + action :start +end +``` + +### Stop Docker Service + +```ruby +docker_service_manager_execute 'default' do + action :stop +end +``` + +### Restart Docker Service + +```ruby +docker_service_manager_execute 'default' do + action :restart +end +``` + +## Notes + +- This resource enables IPv4 and IPv6 forwarding using sysctl +- The Docker daemon is started as a background process using bash +- A wait script is created to ensure the daemon is ready before proceeding +- The stop action uses a timeout of 10 seconds when stopping the daemon +- The resource uses process checking to prevent duplicate daemon instances +- Log output is redirected to the specified logfile +- Environment variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, TMPDIR) are passed to the daemon process + +## Platform Support + +This resource should work on any platform that can run the Docker daemon, but it's primarily tested on Linux systems. diff --git a/documentation/docker_service_manager_systemd.md b/documentation/docker_service_manager_systemd.md new file mode 100644 index 000000000..d041620ab --- /dev/null +++ b/documentation/docker_service_manager_systemd.md @@ -0,0 +1,98 @@ +# docker_service_manager_systemd + +The `docker_service_manager_systemd` resource manages the Docker daemon using systemd. This is the preferred way to manage Docker on systems that use systemd as their init system. + +## Actions + +- `:start` - Starts and enables the Docker daemon +- `:stop` - Stops and disables the Docker daemon +- `:restart` - Restarts the Docker daemon (stop followed by start) + +## Properties + +This resource inherits properties from the `docker_service_base` resource. Common properties include: + +| Property | Type | Default | Description | +|-------------------|---------|------------|--------------------------------------------------| +| `docker_daemon_cmd`| String | Generated | Command to start the Docker daemon | +| `docker_name` | String | `'docker'` | Name of the Docker service | +| `connect_socket` | String | `nil` | Docker socket path | +| `docker_containerd`| Boolean | - | Whether to use containerd | +| `env_vars` | Hash | `{}` | Environment variables for the Docker daemon | +| `systemd_socket_args`| Hash | `{}` | Additional systemd socket arguments | +| `systemd_args` | Hash | `{}` | Additional systemd service arguments | + +## Examples + +### Basic Usage + +```ruby +docker_service_manager_systemd 'default' do + action :start +end +``` + +### Custom Service Configuration + +```ruby +docker_service_manager_systemd 'default' do + systemd_args({ + 'TimeoutStartSec' => '0', + 'ExecStartPost' => '/usr/bin/sleep 1' + }) + env_vars({ + 'HTTP_PROXY' => 'http://proxy.example.com:3128', + 'NO_PROXY' => 'localhost,127.0.0.1' + }) + action :start +end +``` + +### Using Custom Socket + +```ruby +docker_service_manager_systemd 'default' do + connect_socket 'unix:///var/run/custom-docker.sock' + action :start +end +``` + +### Stop Docker Service + +```ruby +docker_service_manager_systemd 'default' do + action :stop +end +``` + +## Files Created/Modified + +The resource manages the following files: + +- `/lib/systemd/system/[docker_name].socket` - Main systemd socket file +- `/etc/systemd/system/[docker_name].socket` - Socket override file +- `/lib/systemd/system/[docker_name].service` - Main systemd service file +- `/etc/systemd/system/[docker_name].service` - Service override file +- `/etc/containerd/config.toml` - Containerd configuration +- `/etc/systemd/system/containerd.service` - Containerd service file (if enabled) + +## Notes + +- This resource is only available on Linux systems using systemd +- Automatically creates and manages containerd configuration when needed +- Supports both socket activation and direct service management +- Handles systemd daemon-reload automatically when configurations change +- Includes retry logic for service start operations +- Creates a wait-ready script to ensure Docker is fully operational +- Supports custom environment variables and systemd unit options +- Can be used with custom Docker socket paths +- Manages both the Docker service and its associated socket unit + +## Platform Support + +This resource is supported on Linux distributions that use systemd as their init system, including: + +- Recent versions of Ubuntu (16.04+) +- Recent versions of Debian (8+) +- Recent versions of CentOS/RHEL (7+) +- Recent versions of Fedora diff --git a/documentation/docker_volume_prune.md b/documentation/docker_volume_prune.md new file mode 100644 index 000000000..2db73210e --- /dev/null +++ b/documentation/docker_volume_prune.md @@ -0,0 +1,76 @@ +# docker_volume_prune + +The `docker_volume_prune` resource removes all unused Docker volumes. Volumes that are still referenced by at least one container are not removed. + +## Actions + +- `:prune` - Remove unused Docker volumes + +## Properties + +| Property | Type | Default | Description | +|-----------------|---------|----------------------|---------------------------------------------------| +| `without_label` | String | `nil` | Only remove volumes without the specified label | +| `with_label` | String | `nil` | Only remove volumes with the specified label | +| `read_timeout` | Integer | `120` | HTTP read timeout for Docker API calls | +| `host` | String | `ENV['DOCKER_HOST']` | Docker daemon socket to connect to | +| `all` | Boolean | `false` | Remove all unused volumes, not just dangling ones | + +## Examples + +### Basic Usage - Remove Unused Volumes + +```ruby +docker_volume_prune 'prune' do + action :prune +end +``` + +### Remove All Unused Volumes + +```ruby +docker_volume_prune 'prune_all' do + all true + action :prune +end +``` + +### Remove Volumes with Specific Label + +```ruby +docker_volume_prune 'prune_labeled' do + with_label 'environment=test' + action :prune +end +``` + +### Remove Volumes Without Specific Label + +```ruby +docker_volume_prune 'prune_without_label' do + without_label 'environment=production' + action :prune +end +``` + +### Custom Docker Host + +```ruby +docker_volume_prune 'prune' do + host 'tcp://127.0.0.1:2375' + action :prune +end +``` + +## Notes + +- Uses Docker Engine API v1.42 +- The prune operation removes all unused volumes that are not referenced by any containers +- The operation is irreversible - once a volume is pruned, its data cannot be recovered +- The resource logs the result of the prune operation +- The `read_timeout` property can be adjusted if the operation takes longer than expected +- Label filters can be used to selectively prune volumes based on their metadata + +## Platform Support + +This resource is supported on any platform that can run the Docker daemon. diff --git a/resources/installation_script.rb b/resources/installation_script.rb index b794a48c8..22c9ef9ec 100644 --- a/resources/installation_script.rb +++ b/resources/installation_script.rb @@ -21,9 +21,6 @@ def default_script_url 'https://get.docker.com/' when 'test' 'https://test.docker.com/' - when 'experimental' - 'https://experimental.docker.com/' - end end #########