From 30967de2c06bda65fac832b41be20a56a7cf0003 Mon Sep 17 00:00:00 2001 From: Dan Webb Date: Wed, 11 Dec 2024 15:58:39 +0000 Subject: [PATCH] Docs: update docs for tmpfs (#1291) Signed-off-by: Dan Webb --- CHANGELOG.md | 5 ++++ documentation/docker_container.md | 29 +++++++++++++++---- resources/container.rb | 12 +++++++- .../docker_test/recipes/container.rb | 16 ++++++++++ .../inspec/assert_functioning_spec.rb | 2 +- 5 files changed, 57 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 76aa4f024..455880c98 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased +- Enhance tmpfs support for containers + - Added support for array format in tmpfs property + - Improved documentation with examples + - Added test coverage for tmpfs functionality + ## 11.8.1 - *2024-12-11* - Fix issue with container network mode causing unnecessary redeployment when using `container:` format diff --git a/documentation/docker_container.md b/documentation/docker_container.md index 17cf438f3..08b18efd4 100644 --- a/documentation/docker_container.md +++ b/documentation/docker_container.md @@ -74,8 +74,10 @@ Most `docker_container` properties are the `snake_case` version of the `CamelCas - `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 ``, 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`. +- `sysctls` - A hash of sysctl settings to configure for the container. +- `timeout` - Timeout setting for container operations. +- `tmpfs` - A hash or array of tmpfs mounts to add to the container. Useful for providing a temporary filesystem without requiring privileged mode. +- `tty` - Boolean value, allocates 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 `[:]` @@ -84,13 +86,11 @@ Most `docker_container` properties are the `snake_case` version of the `CamelCas - `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 -- `tmpfs` - A hash of paths to tmpfs options. Defaults to `{}`. - `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` @@ -108,6 +108,26 @@ docker_container 'hello-world' do end ``` +### Create a container with tmpfs mounts + +```ruby +# Using hash format with mount options +docker_container 'tmpfs_test' do + repo 'nginx' + tmpfs({ + '/tmpfs1' => '', # No options + '/tmpfs2' => 'size=100M,uid=1000', # With size and uid options + '/tmpfs3' => 'rw,noexec,nosuid,size=200M' # With multiple options + }) +end + +# Using array format (all mounts will have default options) +docker_container 'tmpfs_test' do + repo 'nginx' + tmpfs ['/tmpfs1', '/tmpfs2'] +end +``` + ### Run a command on every Chef Infra Client run This will exit succesfully. It will happen on every chef-client run @@ -544,4 +564,3 @@ docker_container 'custom_gpu_container' do gpu_driver 'custom_driver' action :run_if_missing end -``` diff --git a/resources/container.rb b/resources/container.rb index d05e70562..803adc84c 100644 --- a/resources/container.rb +++ b/resources/container.rb @@ -67,7 +67,8 @@ property :stdin_once, [true, false], default: false, desired_state: false property :sysctls, Hash, default: {} property :timeout, Integer, desired_state: false -property :tmpfs, Hash, default: {} +property :tmpfs, [Hash, Array], default: {}, coerce: proc { |v| coerce_tmpfs(v) }, + description: 'A hash or array of tmpfs mounts to add to the container. Hash format: { "/path" => "size=100M,uid=1000" }. Array format: ["/path", "/path2"]. See https://docs.docker.com/storage/tmpfs/' property :tty, [true, false], default: false property :ulimits, [Array, nil], coerce: proc { |v| coerce_ulimits(v) } property :user, String @@ -212,6 +213,15 @@ def coerce_volumes(v) end end +def coerce_tmpfs(v) + case v + when Hash, nil + v + when Array + v.each_with_object({}) { |path, h| h[path] = '' } + end +end + def state # Always return the latest state, see #510 Docker::Container.get(container_name, {}, connection).info['State'] diff --git a/test/cookbooks/docker_test/recipes/container.rb b/test/cookbooks/docker_test/recipes/container.rb index a1dc1a91c..90a953578 100644 --- a/test/cookbooks/docker_test/recipes/container.rb +++ b/test/cookbooks/docker_test/recipes/container.rb @@ -302,6 +302,22 @@ action :run_if_missing end +################ +# tmpfs test +################ + +docker_container 'tmpfs_test' do + repo 'alpine' + tag '3.1' + command 'df -h' + tmpfs({ + '/tmpfs1' => '', + '/tmpfs2' => 'size=20M,uid=1000', + '/tmpfs3' => 'rw,noexec,nosuid,size=50M', + }) + action :run_if_missing +end + ############## # volumes_from ############## diff --git a/test/integration/resources/inspec/assert_functioning_spec.rb b/test/integration/resources/inspec/assert_functioning_spec.rb index 7ae9f2341..6095e43d8 100644 --- a/test/integration/resources/inspec/assert_functioning_spec.rb +++ b/test/integration/resources/inspec/assert_functioning_spec.rb @@ -117,7 +117,7 @@ its('tag') { should eq 'latest' } end -# docker_tag[private repo tag for name.w.dots:latest / v0.1.0 / / v0.1.1 /] +# docker_image[private repo tag for name.w.dots:latest / v0.1.0 / / v0.1.1 /] describe docker_image('localhost:5043/someara/name.w.dots:latest') do it { should exist }