When using combined tag@digest references (e.g., nginx:1.21@sha256:abc...),
Docker does NOT store the tag in RepoTags. It only stores the digest in
RepoDigests. The previous implementation required BOTH to match, which
always failed because RepoTags was empty.
This caused docker_container to pull the image on every run even when
the image with the correct digest already existed locally, breaking
idempotency.
The fix: When a digest is specified, match by digest only since it's the
authoritative identifier. The tag is informational for human readability.
Real-world example from docker image inspect:
"RepoTags": [], # Empty when pulled by digest\!
"RepoDigests": ["portainer/portainer-ee@sha256:7ecf2008..."]
Updated tests to reflect the correct behavior:
- test_empty_repo_tags_matches_by_digest (the critical fix case)
- test_combined_tag_digest_matches_even_if_tag_differs
- test_multiple_tags_irrelevant_for_combined
When using combined image:tag@digest references, parse_repository_tag
returns (repo, "tag@digest"). The Docker SDK and API don't accept
tag@digest in the tag parameter, causing "invalid tag format" errors.
This fix:
1. Adds build_pull_arguments() helper function to _util.py
2. Uses the helper in both pull_image implementations
3. When tag contains @ (but isn't a pure digest), passes the full
reference as the repository/fromImage parameter instead of splitting
Tested formats:
- portainer/portainer-ee:2.35.0-alpine@sha256:abc...
- ghcr.io/gethomepage/homepage:v1.7@sha256:abc...
- localhost:5000/myapp:v2.0@sha256:abc...
The existing filter_images_by_tag already handles tag@digest for
lookups, so find_image continues to work correctly.
Includes comprehensive unit tests for build_pull_arguments().
The parse_repository_tag fix alone is not sufficient because Docker stores
RepoTags and RepoDigests separately. When looking up an image with combined
tag@digest (e.g., nginx:1.21@sha256:abc...), the _image_lookup function must
split the combined format and match BOTH RepoTags (for the tag) AND
RepoDigests (for the digest).
Docker stores:
- RepoTags: ["nginx:1.21"]
- RepoDigests: ["nginx@sha256:abc..."]
But NEVER stores the combined format. The previous code would construct:
- lookup = "nginx:1.21@sha256:abc..." (never matches RepoTags)
- lookup_digest = "nginx@1.21@sha256:abc..." (never matches RepoDigests)
This fix:
1. Adds filter_images_by_tag() helper function to _util.py to avoid code
duplication between _common.py and _common_api.py
2. Detects combined tag@digest format in the tag parameter
3. Splits into tag_part and digest_part
4. Constructs proper lookups for both RepoTags and RepoDigests
5. Requires BOTH to match for successful image lookup
Without this fix, image_label_mismatch: ignore fails because the image
cannot be found, resulting in no image labels being included in expected
labels comparison.
Includes comprehensive unit tests in test__util.py covering all scenarios
including edge cases for multiple @ symbols and empty tag parts.
The parse_repository_tag() function was incorrectly parsing Docker image
references that contained both a tag and a digest (e.g., nginx:1.0@sha256:abc).
Previously, when splitting by '@' first, the tag would be included in the
repository name, resulting in incorrect parsing:
- Input: "nginx:1.0@sha256:abc123"
- Old output: ("nginx:1.0", "sha256:abc123")
- Expected: ("nginx", "1.0@sha256:abc123")
The fix now:
1. Checks for digest (@) separator first
2. Examines the part before the digest for a tag (:) separator
3. Combines tag and digest as "tag@digest" when both are present
Added test cases:
- test_index_image_tag_and_sha
- test_index_user_image_tag_and_sha
- test_private_reg_image_tag_and_sha
* Add debug flag to failing task.
* Add more debug output.
* Fix pull idempotency.
* Revert "Add more debug output."
This reverts commit 64020149bf.
* Fix casing.
* Remove unreliable test.
* Add 'debug: true' to all tasks.
* Reformat.
* Fix idempotency problem for IPv6 addresses.
* Fix expose ranges handling.
* Update changelog fragment to also mention other affected modules.
* Re-enable typing and improve config.
* Make mypy pass.
* Improve settings.
* First batch of types.
* Add more type hints.
* Fixes.
* Format.
* Fix split_port() without returning to previous type chaos.
* Continue with type hints (and ignores).
* Remove __metaclass__ = type.
for i in $(grep -REl '__metaclass__ = type' plugins/ tests/); do
sed -e '/^__metaclass__ = type/d' -i $i;
done
* Remove super arguments, and stop inheriting from object.
* Adjust all __future__ imports:
for i in $(grep -REl "__future__.*absolute_import" plugins/ tests/); do
sed -e 's/from __future__ import .*/from __future__ import annotations/g' -i $i;
done
* Remove all UTF-8 encoding specifications for Python source files:
for i in $(grep -REl '[-][*]- coding: utf-8 -[*]-' plugins/ tests/); do
sed -e '/^# -\*- coding: utf-8 -\*-/d' -i $i;
done
* Reformat.
* Make all doc fragments, module utils, and plugin utils private.
* Remove some unused and no longer needed imports.
This hopefully also fixes the CI issues, which do not happen locally for me...
* Fix formatting.
* Try to make CI happy, again.
* Fix imports.
* Lint.
* Remove unicode text prefixes.
* Replace str.format() uses with f-strings.
* Replace % with f-strings, and do some cleanup.
* Fix wrong variable.
* Avoid unnecessary string conversion.
* Vendor parts of the Docker SDK for Python
This is a combination of the latest git version
(db7f8b8bb6)
with some fixes to make it compatible with Python 2.7
and adjusting some imports.
* Polishing.
* Fix bug that prevents contexts to be found when no Docker config file is present.
Ref: https://github.com/docker/docker-py/issues/3190
* Linting.
* Fix typos.
* Adjust more to behavior of Docker CLI.
* Add first iteration of docker_context_info module.
* Improvements.
* Add basic CI.
* Add caveat on contexts[].config result.
* Determine the compose version via a CLI call and not the docker API.
* Update plugins/module_utils/compose_v2.py
Co-authored-by: Felix Fontein <felix@fontein.de>
---------
Co-authored-by: Felix Fontein <felix@fontein.de>
