# Docker Image<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4


[cols="1^,1^,1^",options=header]
|===
| source | condition | target
| &#10004; | &#10004; | &#10007;
|===

== Description

The `dockerimage` resource queries a container registry about an image.

**source**::
Returns the image tag matching `versionfilter`.

**condition**::
Tests that a tag exists for the image, optionally for a set of architectures.

**target**::
Not supported - a target fails with `target not supported for the plugin Docker Image`. To write a tag into a file, use the link:/docs/plugins/resource/yaml/["Yaml"] or link:/docs/plugins/resource/dockerfile/["Dockerfile"] resources.

NOTE: An `scm` attached to a condition is ignored, with a warning (the lookup always goes to the registry).

To pin an image by digest rather than by tag, see the link:/docs/plugins/resource/docker_digest/["Docker Digest" resource].

== Parameters

{{< resourceparameters "sources" "dockerimage" >}}

**Remark**:

It's considered a very bad practice to store credentials in an unencrypted file.
Consider using an environment variable to store the token.

== Architectures

`architecture` names one platform; `architectures` takes a list, and the condition passes only when the tag exists for all of them.

[IMPORTANT]
====
Leaving both unset is not the same as asking for the default platform. With no architecture, Updatecli retrieves the digest of the **image index** - the multi-architecture manifest list, valid whichever platform pulls it. Naming an architecture retrieves the digest of that **specific image** instead.

The two digests are different values for the same tag, so switching between them changes what a source returns. See link:https://github.com/updatecli/updatecli/issues/1603[updatecli#1603].
====

Remarks:

* The default operating system is `linux`, so `amd64` means `linux/amd64`.
* When querying the `v7` variant of `arm`, the operating system must be spelled out: `linux/arm/v7`.
* Checking architectures is not supported on v1 registries.

Accepted forms:

* `amd64` - checks `linux/amd64`
* `linux/amd64`
* `windows/amd64`
* `linux/arm/v7`

== Authentication

Depending on the Docker Registry, authentication may be required. The way to retrieve the token depends on the registry.

=== GHCR

Github uses personal access token. How to retrieve one, is explained https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token[here]

=== DockerHub

To retrieve the token, it's easier to run `docker login` and then retrieve the token stored in '~/.docker/config.json'

.~/.docker/config.json
```
        "auths": {
                "https://index.docker.io/v1/": {
                        "auth": "token"
                }
        },
```

== Example

Please note that in this example we are using a go template `updatecli.tpl` with values from `values.yaml`
The main motivation is to use {{ requiredEnv ENV_VARIABLE }} to read the github token from a environment variable.

[source,yaml]
----
# updatecli.yaml
{{<include "assets/code_example/docs/plugins/resources/docker/image/updatecli.d/default.yaml">}}
----

[source,yaml]
----
# values.yaml
{{<include "assets/code_example/docs/plugins/resources/docker/image/values.yaml">}}
----

What it says:

**Source**
Retrieve the latest version from the Github release of the project jenkis-infra/plugins-site-api
=> v1.11.1

**Condition**
Test that the tag `v1.11.1` exist for the image `jenkinsciinfra/plugin-site-api` on DockerHub and architecture `linux/amd64` is present
=> No, then abort

**target**
If the condition was passing then it would have update the key `backend.image.tag` in the yaml file `charts/plugin-site/values.yaml` located on the Github repository `olblak/charts` on the branch `master` using the Github Pull request workflow