Skip to content

Commit 01ec477

Browse files
stevsmitSteven Smith
stevsmit
and
Steven Smith
authored
Adds annotations label to docs (quay#1279)
Co-authored-by: Steven Smith <[email protected]>
1 parent b132c2a commit 01ec477

File tree

1 file changed

+112
-4
lines changed

1 file changed

+112
-4
lines changed

‎modules/setting-tag-expirations-v2-ui.adoc‎

Lines changed: 112 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,11 @@ ifeval::["{context}" == "use-quay"]
2121
The {productname} superuser has no special privilege related to deleting expired images from user repositories. There is no central mechanism for the superuser to gather information and act on user repositories. It is up to the owners of each repository to manage expiration and the deletion of their images.
2222
endif::[]
2323

24-
Tag expiration can be set up in one of two ways:
24+
Tag expiration can be set up in one of three ways:
2525

26-
* By setting the `quay.expires-after=` label in the Dockerfile when the image is created. This sets a time to expire from when the image is built.
26+
* By setting the `quay.expires-after=` label in the Dockerfile when the image is created. This sets a time to expire from when the image is built. This label only works for image manifests.
27+
28+
* By setting the `quay.expires-after=` annotation label in the Dockerfile when the image is created. `--annotation` can be passed in for both image manifests and image indexes.
2729
2830
* By selecting an expiration date on the
2931
ifeval::["{context}" == "quay-io"]
@@ -74,9 +76,115 @@ Expiration begins from the time that the image is pushed to the registry.
7476

7577
.Procedure
7678

77-
* Enter the following `docker label` command to add a label to the desired image tag. The label should be in the format `quay.expires-after=20h` to indicate that the tag should expire after 20 hours. Replace 20h with the desired expiration time. For example:
79+
* Enter the following `docker label` command to add a label to the desired image tag. The label should be in the format `quay.expires-after=20h` to indicate that the tag should expire after 20 hours. Replace `20h` with the desired expiration time. For example:
7880
+
7981
[source,terminal]
8082
----
8183
$ docker label quay.expires-after=20h quay-server.example.com/quayadmin/<image>:<tag>
82-
----
84+
----
85+
86+
[id="setting-tag-expiration-annotation"]
87+
== Setting tag expiration using annotations
88+
89+
You can add an annotation, for example, `quay.expires-after=20h`, to an image tag using the `--annotation` flag when pushing an image to the registry. This annotation causes the tag to automatically expire after the specified time. The annotation can be applies to both image manifests and image indexes. The following values for hours, days, or weeks are accepted:
90+
91+
* `1h`
92+
* `2d`
93+
* `3w`
94+
95+
Expiration begins from the time that the image is pushed to the registry.
96+
97+
[NOTE]
98+
====
99+
Using the `--annotation` flag is simplest using the `oras` CLI tool.
100+
====
101+
102+
.Prerequisites
103+
104+
* You have downloaded the `oras` CLI. For more information, see link:https://oras.land/docs/installation[Installation].
105+
106+
.Procedure
107+
108+
. Enter the following `oras push --annotation` command to add an annotation to the desired image tag. The annotation should be in the format `quay.expires-after=<value>` to indicate that the tag should expire the set time. For example:
109+
+
110+
[source,terminal]
111+
----
112+
$ oras push --annotation quay.expires-after=<value> \
113+
<quay-server.example.com>/<organization>/<repository>:<tag> \
114+
<file_path>:<media_type>
115+
----
116+
+
117+
.Example output
118+
+
119+
[source,terminal]
120+
----
121+
✓ Uploaded hello.txt 12/12 B 100.00% 321ms
122+
└─ sha256:74b9e308133afb3bceae961097cb2aa481483869d695ce1414cd2bc7f046027c
123+
✓ Uploaded application/vnd.oci.empty.v1+json 2/2 B 100.00% 328ms
124+
└─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
125+
✓ Uploaded application/vnd.oci.image.manifest.v1+json 620/620 B 100.00% 0s
126+
└─ sha256:c370e931b5eca44fd753bd92e6991ed3be70008e8df15078083359409111f8c3
127+
Pushed [registry] quay-server.example.com/fortestuser/busybox:test2
128+
ArtifactType: application/vnd.unknown.artifact.v1
129+
----
130+
131+
. Confirm that the expiration date has been applied by checking the {productname} UI, or by entering the following command:
132+
+
133+
[source,terminal]
134+
----
135+
$ curl -X GET \
136+
-H "Authorization: Bearer <bearer_token>" \
137+
-H "Accept: application/json" \
138+
https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/?specificTag=<tag>" \
139+
----
140+
+
141+
.Example output
142+
+
143+
[source,terminal]
144+
----
145+
{"tags": [{"name": "test2", "reversion": false, "start_ts": 1743706344, "end_ts": 1743778344, "manifest_digest": "sha256:c370e931b5eca44fd753bd92e6991ed3be70008e8df15078083359409111f8c3", "is_manifest_list": false, "size": 12, "last_modified": "Thu, 03 Apr 2025 18:52:24 -0000", "expiration": "Fri, 04 Apr 2025 14:52:24 -0000"}, {"name": "test2", "reversion": false, "start_ts": 1742493776, "end_ts": 1743706344, "manifest_digest": "sha256:d80aa3d7f5f5388cfae543b990d3cd3d47ff51c48ef29ff66102427bf7bc0a88", "is_manifest_list": false, "size": 2266046, "last_modified": "Thu, 20 Mar 2025 18:02:56 -0000", "expiration": "Thu, 03 Apr 2025 18:52:24 -0000"}], "page": 1, "has_additional": false}
146+
----
147+
148+
[id="removing-tag-expiration-annotation"]
149+
== Removing tag expiration using annotations
150+
151+
With the `oras` CLI tool, you can unset previously established expiration times.
152+
153+
.Prerequisites
154+
155+
* You have downloaded the `oras` CLI. For more information, see link:https://oras.land/docs/installation[Installation].
156+
* You have pushed an image with the `quay.expires-after=<value>` annotation.
157+
158+
.Procedure
159+
160+
. Enter the following `oras push --annotation` command to remove an annotation to the desired image tag. The annotation should be in the format `quay.expires-after=never`. For example:
161+
+
162+
[source,terminal]
163+
----
164+
$ oras push --annotation quay.expires-after=never \
165+
<quay-server.example.com>/<organization>/<repository>:<tag> \
166+
<file_path>:<media_type>
167+
----
168+
+
169+
.Example output
170+
+
171+
[source,terminal]
172+
----
173+
✓ Uploaded hello.txt 12/12 B 100.00% 321ms
174+
└─ sha256:74b9e308133afb3bceae961097cb2aa481483869d695ce1414cd2bc7f046027c
175+
✓ Uploaded application/vnd.oci.empty.v1+json 2/2 B 100.00% 328ms
176+
└─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
177+
✓ Uploaded application/vnd.oci.image.manifest.v1+json 620/620 B 100.00% 0s
178+
└─ sha256:c370e931b5eca44fd753bd92e6991ed3be70008e8df15078083359409111f8c3
179+
Pushed [registry] quay-server.example.com/fortestuser/busybox:test2
180+
ArtifactType: application/vnd.unknown.artifact.v1
181+
----
182+
183+
. The latest manifest will no longer have an expiration time. Confirm that the expiration date has been removed by checking the {productname} UI, or by entering the following command:
184+
+
185+
[source,terminal]
186+
----
187+
{"tags": [{"name": "test2", "reversion": false, "start_ts": 1743708135, "manifest_digest": "sha256:19e3a3501b4125cce9cb6bb26ac9207c325259bef94dc66490b999f93c4c83a9", "is_manifest_list": false, "size": 12, "last_modified": "Thu, 03 Apr 2025 19:22:15 -0000"}, {"name": "test2", "reversion": false, "start_ts": 1743706344, "end_ts": 1743708135}]}
188+
----
189+
+
190+
Note that no expiration time is listed.

0 commit comments

Comments
 (0)