From 3c5e57a98196e2141b1de6f2427c1c8de666b35e Mon Sep 17 00:00:00 2001 From: ltagliaferri Date: Thu, 26 Dec 2024 18:05:31 -0500 Subject: [PATCH] Update Tag History API doc (#1983) Not sure what happened with #1732 , but I am resolving the comments and updating the doc. --------- Signed-off-by: ltagliaferri --- .../features/using-the-tag-history-api.md | 56 +++++++++++++------ 1 file changed, 39 insertions(+), 17 deletions(-) diff --git a/content/chainguard/chainguard-images/features/using-the-tag-history-api.md b/content/chainguard/chainguard-images/features/using-the-tag-history-api.md index daf1a576a7..0090b6d0b7 100644 --- a/content/chainguard/chainguard-images/features/using-the-tag-history-api.md +++ b/content/chainguard/chainguard-images/features/using-the-tag-history-api.md @@ -8,7 +8,7 @@ aliases: type: "article" description: "Learn how to use the Chainguard Images Tag History API to fetch the tag history of image variants." date: 2023-05-26T08:49:31+00:00 -lastmod: 2024-08-02T15:22:20+01:00 +lastmod: 2024-12-26T15:22:20+01:00 draft: false tags: ["Chainguard Images", "Product"] images: [] @@ -32,6 +32,8 @@ If you have a container environment that was working fine but suddenly breaks wi Before making API calls, you'll need to generate a token within the [Chainguard Registry](/chainguard/chainguard-registry/overview/). +### Public Images + The Registry API endpoint for obtaining the token is: ``` @@ -42,46 +44,66 @@ Where `IMAGE_NAME` is the name of the image that you want to pull the tag histor For public images (tagged as `latest` or `latest-dev`), you can request a registry token anonymously, without providing any pre-existing auth. -The following command will obtain a token for the **Python** image and register a variable called `tok` with the resulting value, which you can use in a subsequent command to obtain the tag history: +The following command will obtain a token for the **Python** image and register a variable called `auth_header` with the resulting value, which you can use in a subsequent command to obtain the tag history: ```shell -tok=$(curl "https://cgr.dev/token?scope=repository:chainguard/python:pull" \ - | jq -r .token) +auth_header="Authorization: Bearer $(curl 'https://cgr.dev/token?scope=repository:chainguard/python:pull' \ + | jq -r .token)" ``` -For images that are not public, you'll need to exchange your Chainguard token for a registry token. This assumes you've set up authentication with [chainctl auth configure-docker](https://edu.chainguard.dev/chainguard/chainguard-registry/authenticating/)): +### Private Images + +You'll need to use your Chainguard Docker credentials. This assumes you've set up authentication with [chainctl auth configure-docker](https://edu.chainguard.dev/chainguard/chainguard-registry/authenticating/): ```shell -tok=$(curl -H "Authorization: Bearer \ - $(echo 'cgr.dev' | docker-credential-cgr get)" \ - -v "https://cgr.dev/token?scope=repository:chainguard/python:pull" \ - | jq -r .token) +auth_header="Authorization: Bearer $(echo 'cgr.dev' | docker-credential-cgr get | jq -r .Secret)" ``` -To make sure your token is set, you can run the following command: +You may use the [`crane` tool](https://github.com/google/go-containerregistry/tree/main/cmd/crane) to get your token instead: ```shell -echo $tok +auth_header="$(crane auth token -H cgr.dev/ORGANIZATION_NAME/IMAGE_NAME)" ``` -And you should get a long string token as output. +Replace `ORGANIZATION_NAME` and `IMAGE_NAME` as required. For example, if your organization is `foo.com` and you're interested in the `chainguard-base` image, you will use the following command: + +```shell +auth_header="$(crane auth token -H cgr.dev/foo.com/chainguard-base) +``` You should now be ready to call the API, either manually or programmatically. ## Calling the API -Once you have your token available, you can run a `curl` query passing on your token within an `Authorization: bearer` header to the following endpoint: +Make sure your authorization header is set, by running the following command: +```shell +echo $auth_header ``` -https://cgr.dev/v2/chainguard/IMAGE_NAME/_chainguard/history/IMAGE_TAG + +You should receive `Authorization: Bearer` followed by a long string (a [JWT](https://jwt.io/introduction)) as output. You can now run a `curl` query to this endpoint, following the below format. + +```shell +https://cgr.dev/v2/ORGANIZATION_NAME/IMAGE_NAME/_chainguard/history/IMAGE_TAG ``` -Where `IMAGE_NAME` is the name of the image, for instance: `python`, and `IMAGE_TAG` is the tag that you want to pull history from. +Where: +- For private images `ORGANIZATION_NAME` is the name of your organization, for example: `foo.com`. +- For public images `ORGANIZATION_NAME` is always `chainguard`. +- `IMAGE_NAME` is the name of the image, for example: `chainguard-base` or `python`. +- `IMAGE_TAG` is the tag that you want to pull history from. + +For example, this is how you can fetch the tag history of **foo.com's** **chainguard-base:latest** Chainguard image using `curl` on the command line: + +```shell +curl -H "$auth_header" \ + https://cgr.dev/v2/foo.com/chainguard-base/_chainguard/history/latest | jq +``` -For example, this is how you can fetch the tag history of the **python:latest** Chainguard image using `curl` on the command line: +Or for a public image such as **python:latest**: ```shell -curl -H "Authorization: Bearer $tok" \ +curl -H "$auth_header" \ https://cgr.dev/v2/chainguard/python/_chainguard/history/latest | jq ```