Use Red Hat Quay

Procedure

1. Log in to your Red Hat Quay repository as the superuser.
2. In the navigation pane, select your account name, and then click Super User Admin Panel.
3. Click the Users icon in the column.
4. Click the Create User button.
5. Enter the new user’s Username and Email address, and then click the Create User button.

6. You are redirected to the Users page, where there is now another Red Hat Quay user.

   Note

   You might need to refresh the Users page to show the additional user.

7. On the Users page, click the Options cogwheel associated with the new user. A drop-down menu appears, as shown in the following figure:

   

8. Click Change Password.

9. Add the new password, and then click Change User Password.

   The new user can now use that username and password to log in using the web UI or through their preferred container client, like Podman.

Procedure

1. Enter the following command to create a new user using the POST /api/v1/superuser/users/ endpoint:

   $ curl -X POST -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json" -d '{
     "username": "newuser",
     "email": "newuser@example.com"
   }' "https://<quay-server.example.com>/api/v1/superuser/users/"

   Example output

   {"username": "newuser", "email": "newuser@example.com", "password": "IJWZ8TIY301KPFOW3WEUJEVZ3JR11CY1", "encrypted_password": "9Q36xF54YEOLjetayC0NBaIKgcFFmIHsS3xTZDLzZSrhTBkxUc9FDwUKfnxLWhco6oBJV1NDBjoBcDGmsZMYPt1dSA4yWpPe/JKY9pnDcsw="}

2. Navigate to your Red Hat Quay registry endpoint, for example, quay-server.example.com and login with the username and password generated from the API call. In this scenario, the username is newuser and the password is IJWZ8TIY301KPFOW3WEUJEVZ3JR11CY1. Alternatively, you can log in to the registry with the CLI. For example:

   $ podman login <quay-server.example.com>

   Example output

   username: newuser
   password: IJWZ8TIY301KPFOW3WEUJEVZ3JR11CY1

3. Optional. You can obtain a list of all users, including superusers, by using the GET /api/v1/superuser/users/ endpoint:

   $ curl -X GET -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/superuser/users/"

   Example output

   {"users": [{"kind": "user", "name": "quayadmin", "username": "quayadmin", "email": "quay@quay.com", "verified": true, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}, "super_user": true, "enabled": true}, {"kind": "user", "name": "newuser", "username": "newuser", "email": "newuser@example.com", "verified": true, "avatar": {"name": "newuser", "hash": "f338a2c83bfdde84abe2d3348994d70c34185a234cfbf32f9e323e3578e7e771", "color": "#9edae5", "kind": "user"}, "super_user": false, "enabled": true}]}

Procedure

1. Log in to your Red Hat Quay repository as the superuser.
2. In the navigation pane, select your account name, and then click Super User Admin Panel.
3. Click the Users icon in the navigation pane.
4. Click the Options cogwheel beside the user to be deleted.
5. Click Delete User, and then confirm deletion by clicking Delete User.

Procedure

1. Enter the following DELETE /api/v1/superuser/users/{username} command to delete a user from the command line:

   $ curl -X DELETE -H "Authorization: Bearer <insert token here>" https://<quay-server.example.com>/api/v1/superuser/users/<username>

2. The CLI does not return information when deleting a user from the CLI. To confirm deletion, you can check the Red Hat Quay UI by navigating to Superuser Admin Panel → Users, or by entering the following GET /api/v1/superuser/users/ command. You can then check to see if they are present.

   $ curl -X GET -H "Authorization: Bearer <bearer_token>" "https://<quay-server.example.com>/api/v1/superuser/users/"

Procedure

1. Log in to your Red Hat Quay registry.
2. Click Organization in the navigation pane.
3. Click Create Organization.
4. Enter an Organization Name, for example, testorg.
5. Enter an Organization Email.
6. Click Create.

Procedure

1. Enter the following command to create a new organization using the POST /api/v1/organization/ endpoint:

   $ curl -X POST   -H "Authorization: Bearer <bearer_token>" -H "Content-Type: application/json"   -d '{
       "name": "<new_organization_name>"
     }'   "https://<quay-server.example.com>/api/v1/organization/"

   Example output

   "Created"

Procedure

1. On the v2 UI, click Organizations.
2. Click the name of the organization that you will create the robot account for, for example, test-org.
3. Click the Settings tab.
4. Optional. Enter the email address associated with the organization.

5. Optional. Set the allotted time for the Time Machine feature to one of the following:

   • A few seconds
   • A day
   • 7 days
   • 14 days
   • A month
6. Click Save.

Procedure

1. On the Organizations page, select the name of the organization you want to delete, for example, testorg.
2. Click the More Actions drop down menu.

3. Click Delete.

   Note

   On the Delete page, there is a Search input box. With this box, users can search for specific organizations to ensure that they are properly scheduled for deletion. For example, if a user is deleting 10 organizations and they want to ensure that a specific organization was deleted, they can use the Search input box to confirm said organization is marked for deletion.

4. Confirm that you want to permanently delete the organization by typing confirm in the box.

5. Click Delete.

   After deletion, you are returned to the Organizations page.

   Note

   You can delete more than one organization at a time by selecting multiple organizations, and then clicking More Actions → Delete.

Procedure

1. Enter the following command to delete an organization using the DELETE /api/v1/organization/{orgname} endpoint:

   $ curl -X DELETE \
     -H "Authorization: Bearer <bearer_token>" \
     "https://<quay-server.example.com>/api/v1/organization/<organization_name>"

2. The CLI does not return information when deleting an organization from the CLI. To confirm deletion, you can check the Red Hat Quay UI, or you can enter the GET /api/v1/organization/{orgname} command to see if details are returned for the deleted organization:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     "<quay-server.example.com>/api/v1/organization/<organization_name>"

   Example output

   {"detail": "Not Found", "error_message": "Not Found", "error_type": "not_found", "title": "not_found", "type": "http://<quay-server.example.com>/api/v1/error/not_found", "status": 404}

Procedure

1. Click Repositories on the navigation pane.
2. Click Create Repository.

3. Select a namespace, for example, quayadmin, and then enter a Repository name, for example, testrepo.

   Important

   Do not use the following words in your repository name: * build * trigger * tag

   When these words are used for repository names, users are unable access the repository, and are unable to permanently delete the repository. Attempting to delete these repositories returns the following error: Failed to delete repository <repository_name>, HTTP404 - Not Found.

4. Click Create.

   Now, your example repository should populate under the Repositories page.

5. Optional. Click Settings → Repository visibility → Make private to set the repository to private.

Procedure

1. Pull a sample page from an example registry. For example:

   $ sudo podman pull busybox

   Example output

   Trying to pull docker.io/library/busybox...
   Getting image source signatures
   Copying blob 4c892f00285e done
   Copying config 22667f5368 done
   Writing manifest to image destination
   Storing signatures
   22667f53682a2920948d19c7133ab1c9c3f745805c14125859d20cede07f11f9

2. Tag the image on your local system with the new repository and image name. For example:

   $ sudo podman tag docker.io/library/busybox quay-server.example.com/quayadmin/busybox:test

3. Push the image to the registry. Following this step, you can use your browser to see the tagged image in your repository.

   $ sudo podman push --tls-verify=false quay-server.example.com/quayadmin/busybox:test

   Example output

   Getting image source signatures
   Copying blob 6b245f040973 done
   Copying config 22667f5368 done
   Writing manifest to image destination
   Storing signatures

Procedure

1. Enter the following command to create a repository using the POST /api/v1/repository endpoint:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     -d '{
       "repository": "<new_repository_name>",
       "visibility": "<private>",
       "description": "<This is a description of the new repository>."
     }' \
     "https://quay-server.example.com/api/v1/repository"

   Example output

   {"namespace": "quayadmin", "name": "<new_repository_name>", "kind": "image"}

Procedure

1. On the Repositories page of the v2 UI, check the box of the repository that you want to delete, for example, quayadmin/busybox.
2. Click the Actions drop-down menu.
3. Click Delete.

4. Type confirm in the box, and then click Delete.

   After deletion, you are returned to the Repositories page.

Procedure

1. Enter the following command to delete a repository using the DELETE /api/v1/repository/{repository} endpoint:

   $ curl -X DELETE   -H "Authorization: Bearer <bearer_token>" "<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>"

2. The CLI does not return information when deleting a repository from the CLI. To confirm deletion, you can check the Red Hat Quay UI, or you can enter the following GET /api/v1/repository/{repository} command to see if details are returned for the deleted repository:

   $ curl -X GET -H "Authorization: Bearer <bearer_token>" "<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>"

   Example output

   {"detail": "Not Found", "error_message": "Not Found", "error_type": "not_found", "title": "not_found", "type": "http://quay-server.example.com/api/v1/error/not_found", "status": 404}

Procedure

1. On the v2 UI, click Organizations.
2. Click the name of the organization that you will create the robot account for, for example, test-org.
3. Click the Robot accounts tab → Create robot account.
4. In the Provide a name for your robot account box, enter a name, for example, robot1. The name of your Robot Account becomes a combination of your username plus the name of the robot, for example, quayadmin+robot1

5. Optional. The following options are available if desired:

   1. Add the robot account to a team.
   2. Add the robot account to a repository.
   3. Adjust the robot account’s permissions.

6. On the Review and finish page, review the information you have provided, then click Review and finish. The following alert appears: Successfully created robot account with robot name: <organization_name> + <robot_name>.

   Alternatively, if you tried to create a robot account with the same name as another robot account, you might receive the following error message: Error creating robot account.

7. Optional. You can click Expand or Collapse to reveal descriptive information about the robot account.
8. Optional. You can change permissions of the robot account by clicking the kebab menu → Set repository permissions. The following message appears: Successfully updated repository permission.

9. Optional. You can click the name of your robot account to obtain the following information:

   • Robot Account: Select this obtain the robot account token. You can regenerate the token by clicking Regenerate token now.
   • Kubernetes Secret: Select this to download credentials in the form of a Kubernetes pull secret YAML file.
   • Podman: Select this to copy a full podman login command line that includes the credentials.
   • Docker Configuration: Select this to copy a full docker login command line that includes the credentials.

Procedure

1. On the Red Hat Quay v2 UI landing page, click Organizations in the navigation pane.
2. On the Organizations page, select the name of the organization that has multiple repositories. The number of repositories under a single organization can be found under the Repo Count column.
3. On your organization’s page, click Robot accounts.
4. For the robot account that will be added to multiple repositories, click the kebab icon → Set repository permissions.

5. On the Set repository permissions page, check the boxes of the repositories that the robot account will be added to. For example:

   

6. Set the permissions for the robot account, for example, None, Read, Write, Admin.
7. Click save. An alert that says Success alert: Successfully updated repository permission appears on the Set repository permissions page, confirming the changes.
8. Return to the Organizations → Robot accounts page. Now, the Repositories column of your robot account shows the number of repositories that the robot account has been added to.

Procedure

1. Update your config.yaml field to add the ROBOTS_DISALLOW variable, for example:

   ROBOTS_DISALLOW: true

2. Restart your Red Hat Quay deployment.

Verification: Creating a new robot account

1. Navigate to your Red Hat Quay repository.
2. Click the name of a repository.
3. In the navigation pane, click Robot Accounts.
4. Click Create Robot Account.
5. Enter a name for the robot account, for example, <organization-name/username>+<robot-name>.
6. Click Create robot account to confirm creation. The following message appears: Cannot create robot account. Robot accounts have been disabled. Please contact your administrator.

Verification: Logging into a robot account

1. On the command-line interface (CLI), attempt to log in as one of the robot accounts by entering the following command:

   $ podman login -u="<organization-name/username>+<robot-name>" -p="KETJ6VN0WT8YLLNXUJJ4454ZI6TZJ98NV41OE02PC2IQXVXRFQ1EJ36V12345678" <quay-server.example.com>

   The following error message is returned:

   Error: logging into "<quay-server.example.com>": invalid username/password

2. You can pass in the log-level=debug flag to confirm that robot accounts have been deactivated:

   $ podman login -u="<organization-name/username>+<robot-name>" -p="KETJ6VN0WT8YLLNXUJJ4454ZI6TZJ98NV41OE02PC2IQXVXRFQ1EJ36V12345678" --log-level=debug <quay-server.example.com>

   ...
   DEBU[0000] error logging into "quay-server.example.com": unable to retrieve auth token: invalid username/password: unauthorized: Robot accounts have been disabled. Please contact your administrator.

Procedure

1. Log into your Red Hat Quay registry:
2. Click the name of the Organization that has the robot account.
3. Click Robot accounts.
4. Check the box of the robot account to be deleted.
5. Click the kebab menu.
6. Click Delete.
7. Type confirm into the textbox, then click Delete.

Procedure

1. Enter the following command to delete a robot account for an organization using the DELETE /api/v1/organization/{orgname}/robots/{robot_shortname} endpoint:

   curl -X DELETE \
     -H "Authorization: Bearer <bearer_token>" \
     "<quay-server.example.com>/api/v1/organization/<organization_name>/robots/<robot_shortname>"

2. The CLI does not return information when deleting a robot account with the API. To confirm deletion, you can check the Red Hat Quay UI, or you can enter the following GET /api/v1/organization/{orgname}/robots command to see if details are returned for the robot account:

   $ curl -X GET   -H "Authorization: Bearer <bearer_token>"   "https://<quay-server.example.com>/api/v1/organization/<organization_name>/robots"

   Example output

   {"robots": []}

3. Enter the following command to delete a robot account for the current user with the DELETE /api/v1/user/robots/{robot_shortname} endpoint:

   $ curl -X DELETE \
     -H "Authorization: Bearer <bearer_token>" \
     "<quay-server.example.com>/api/v1/user/robots/<robot_shortname>"

4. The CLI does not return information when deleting a robot account for the current user with the API. To confirm deletion, you can check the Red Hat Quay UI, or you can enter the following GET /api/v1/user/robots/{robot_shortname} command to see if details are returned for the robot account:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     "<quay-server.example.com>/api/v1/user/robots/<robot_shortname>"

   Example output

   {"message":"Could not find robot with specified username"}

Procedure

1. Click the name of an organization.
2. Click Default permissions.
3. Click Create default permissions. A toggle drawer appears.

4. Select either Anyone or Specific user to create a default permission when a repository is created.

   1. If selecting Anyone, the following information must be provided:

      • Applied to. Search, invite, or add a user/robot/team.
      • Permission. Set the permission to one of Read, Write, or Admin.

   2. If selecting Specific user, the following information must be provided:

      • Repository creator. Provide either a user or robot account.
      • Applied to. Provide a username, robot account, or team name.
      • Permission. Set the permission to one of Read, Write, or Admin.
5. Click Create default permission. A confirmation box appears, returning the following alert: Successfully created default permission for creator.

Procedure

1. Enter the following command to create a default permission with the POST /api/v1/organization/{orgname}/prototypes endpoint:

   $ curl -X POST   -H "Authorization: Bearer <bearer_token>"   -H "Content-Type: application/json"   --data '{
       "role": "<admin_read_or_write>",
       "delegate": {
         "name": "<username>",
         "kind": "user"
       },
       "activating_user": {
         "name": "<robot_name>"
       }
     }'   https://<quay-server.example.com>/api/v1/organization/<organization_name>/prototypes

   Example output

   {"activating_user": {"name": "test-org+test", "is_robot": true, "kind": "user", "is_org_member": true, "avatar": {"name": "test-org+test", "hash": "aa85264436fe9839e7160bf349100a9b71403a5e9ec684d5b5e9571f6c821370", "color": "#8c564b", "kind": "robot"}}, "delegate": {"name": "testuser", "is_robot": false, "kind": "user", "is_org_member": false, "avatar": {"name": "testuser", "hash": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "color": "#6b6ecf", "kind": "user"}}, "role": "admin", "id": "977dc2bc-bc75-411d-82b3-604e5b79a493"}

2. Enter the following command to update a default permission using the PUT /api/v1/organization/{orgname}/prototypes/{prototypeid} endpoint, for example, if you want to change the permission type. You must include the ID that was returned when you created the policy.

   $ curl -X PUT \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     --data '{
       "role": "write"
     }' \
     https://<quay-server.example.com>/api/v1/organization/<organization_name>/prototypes/<prototypeid>

   Example output

   {"activating_user": {"name": "test-org+test", "is_robot": true, "kind": "user", "is_org_member": true, "avatar": {"name": "test-org+test", "hash": "aa85264436fe9839e7160bf349100a9b71403a5e9ec684d5b5e9571f6c821370", "color": "#8c564b", "kind": "robot"}}, "delegate": {"name": "testuser", "is_robot": false, "kind": "user", "is_org_member": false, "avatar": {"name": "testuser", "hash": "f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a", "color": "#6b6ecf", "kind": "user"}}, "role": "write", "id": "977dc2bc-bc75-411d-82b3-604e5b79a493"}

3. You can delete the permission by entering the DELETE /api/v1/organization/{orgname}/prototypes/{prototypeid} command:

   curl -X DELETE \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/organization/<organization_name>/prototypes/<prototype_id>

   This command does not return an output. Instead, you can obtain a list of all permissions by entering the GET /api/v1/organization/{orgname}/prototypes command:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/organization/<organization_name>/prototypes

   Example output

   {"prototypes": []}

Procedure

1. Log into Red Hat Quay.
2. On the v2 UI, click Repositories.
3. Click the name of a repository, for example, quayadmin/busybox.
4. Click the Settings tab.

5. Optional. Click User and robot permissions. You can adjust the settings for a user or robot account by clicking the dropdown menu option under Permissions. You can change the settings to Read, Write, or Admin.

   • Read. The User or Robot Account can view and pull from the repository.
   • Write. The User or Robot Account can read (pull) from and write (push) to the repository.
   • Admin. The User or Robot account has access to pull from, and push to, the repository, plus the ability to do administrative tasks associated with the repository.

Procedure

1. Enter the following PUT /api/v1/repository/{repository}/permissions/user/{username} command to change the permissions of a user:

   $ curl -X PUT \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     -d '{"role": "admin"}' \
     https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository>/permissions/user/<username>

   Example output

   {"role": "admin", "name": "quayadmin+test", "is_robot": true, "avatar": {"name": "quayadmin+test", "hash": "ca9afae0a9d3ca322fc8a7a866e8476dd6c98de543decd186ae090e420a88feb", "color": "#8c564b", "kind": "robot"}}

2. To delete the current permission, you can enter the DELETE /api/v1/repository/{repository}/permissions/user/{username} command:

   $ curl -X DELETE \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository>/permissions/user/<username>

   This command does not return any output in the CLI. Instead, you can check that the permissions were deleted by entering the GET /api/v1/repository/{repository}/permissions/user/ command:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository>/permissions/user/<username>/

   Example output

   {"message":"User does not have permission for repo."}

Procedure

1. On the v2 UI, click Repositories.
2. Click the name of a repository.

3. Click the name of a tag. You are taken to the Details page of that tag. The page reveals the following information:

   • Name
   • Repository
   • Digest
   • Vulnerabilities
   • Creation
   • Modified
   • Size
   • Labels
   • How to fetch the image tag
4. Click Security Report to view the tag’s vulnerabilities. You can expand an advisory column to open up CVE data.
5. Click Packages to view the tag’s packages.
6. Click the name of the repository to return to the Tags page.

Procedure

1. To obtain tag information, you must use the GET /api/v1/repository/{repository} API endpoint and pass in the includeTags parameter. For example:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>?includeTags=true

   Example output

   {"namespace": "quayadmin", "name": "busybox", "kind": "image", "description": null, "is_public": false, "is_organization": false, "is_starred": false, "status_token": "d8f5e074-690a-46d7-83c8-8d4e3d3d0715", "trust_enabled": false, "tag_expiration_s": 1209600, "is_free_account": true, "state": "NORMAL", "tags": {"example": {"name": "example", "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000", "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d"}, "test": {"name": "test", "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d"}}, "can_write": true, "can_admin": true}

2. Alternatively, you can use the GET /api/v1/repository/{repository}/tag/ endpoint. For example:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/

   Example output

   {"tags": [{"name": "test-two", "reversion": true, "start_ts": 1718737153, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 18 Jun 2024 18:59:13 -0000"}, {"name": "test-two", "reversion": false, "start_ts": 1718737029, "end_ts": 1718737153, "manifest_digest": "sha256:0cd3dd6236e246b349e63f76ce5f150e7cd5dbf2f2f1f88dbd734430418dbaea", "is_manifest_list": false, "size": 2275317, "last_modified": "Tue, 18 Jun 2024 18:57:09 -0000", "expiration": "Tue, 18 Jun 2024 18:59:13 -0000"}, {"name": "test-two", "reversion": false, "start_ts": 1718737018, "end_ts": 1718737029, "manifest_digest": "sha256:0cd3dd6236e246b349e63f76ce5f150e7cd5dbf2f2f1f88dbd734430418dbaea", "is_manifest_list": false, "size": 2275317, "last_modified": "Tue, 18 Jun 2024 18:56:58 -0000", "expiration": "Tue, 18 Jun 2024 18:57:09 -0000"}, {"name": "sample_tag", "reversion": false, "start_ts": 1718736147, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 18 Jun 2024 18:42:27 -0000"}, {"name": "test-two", "reversion": false, "start_ts": 1717680780, "end_ts": 1718737018, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:33:00 -0000", "expiration": "Tue, 18 Jun 2024 18:56:58 -0000"}, {"name": "tag-test", "reversion": false, "start_ts": 1717680378, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:26:18 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}], "page": 1, "has_additional": false}

Procedure

1. On the Red Hat Quay v2 UI dashboard, click Repositories in the navigation pane.
2. Click the name of a repository that has image tags.
3. Click the menu kebab, then click Add new tag.

4. Enter a name for the tag, then, click Create tag.

   The new tag is now listed on the Repository Tags page.

Procedure

1. You can change which image a tag points to or create a new tag by using the PUT /api/v1/repository/{repository}/tag/{tag} command:

   $ curl -X PUT \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     --data '{
       "manifest_digest": "<manifest_digest>"
     }' \
     https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/<tag>

   Example output

   "Updated"

2. You can restore a repository tag to its previous image by using the POST /api/v1/repository/{repository}/tag/{tag}/restore command. For example:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     --data '{
       "manifest_digest": <manifest_digest>
     }' \
     quay-server.example.com/api/v1/repository/quayadmin/busybox/tag/test/restore

   Example output

   {}

3. To see a list of tags after creating a new tag you can use the GET /api/v1/repository/{repository}/tag/ command. For example:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
      https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag

   Example output

   {"tags": [{"name": "test", "reversion": false, "start_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715697708, "end_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:41:48 -0000", "expiration": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715695488, "end_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "expiration": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715631517, "end_ts": 1715695488, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Mon, 13 May 2024 20:18:37 -0000", "expiration": "Tue, 14 May 2024 14:04:48 -0000"}], "page": 1, "has_additional": false}

Procedure

1. On the v2 UI dashboard, click Repositories in the navigation pane.
2. Click the name of a repository that has image tags.
3. Click the menu kebab for an image and select Edit labels.
4. In the Edit labels window, click Add new label.

5. Enter a label for the image tag using the key=value format, for example, com.example.release-date=2023-11-14.

   Note

   The following error is returned when failing to use the key=value format: Invalid label format, must be key value separated by =.

6. Click the whitespace of the box to add the label.
7. Optional. Add a second label.
8. Click Save labels to save the label to the image tag. The following notification is returned: Created labels successfully.
9. Optional. Click the same image tag’s menu kebab → Edit labels → X on the label to remove it; alternatively, you can edit the text. Click Save labels. The label is now removed or edited.

Procedure

1. Use the GET /api/v1/repository/{repository}/manifest/{manifestref} command to retrieve the details of a specific manifest in a repository:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>

2. Use the GET /api/v1/repository/{repository}/manifest/{manifestref}/labels command to retrieve a list of labels for a specific manifest:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels

   Example output

   {"labels": [{"id": "e9f717d2-c1dd-4626-802d-733a029d17ad", "key": "org.opencontainers.image.url", "value": "https://github.com/docker-library/busybox", "source_type": "manifest", "media_type": "text/plain"}, {"id": "2d34ec64-4051-43ad-ae06-d5f81003576a", "key": "org.opencontainers.image.version", "value": "1.36.1-glibc", "source_type": "manifest", "media_type": "text/plain"}]}

3. Use the GET /api/v1/repository/{repository}/manifest/{manifestref}/labels/{labelid} command to obtain information about a specific manifest:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
     https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels/<label_id>

   Example output

   {"id": "e9f717d2-c1dd-4626-802d-733a029d17ad", "key": "org.opencontainers.image.url", "value": "https://github.com/docker-library/busybox", "source_type": "manifest", "media_type": "text/plain"}

4. You can add an additional label to a manifest in a given repository with the POST /api/v1/repository/{repository}/manifest/{manifestref}/labels command. For example:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     --data '{
       "key": "<key>",
       "value": "<value>",
       "media_type": "<media_type>"
     }' \
     https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels

   Example output

   {"label": {"id": "346593fd-18c8-49db-854f-4cb1fb76ff9c", "key": "example-key", "value": "example-value", "source_type": "api", "media_type": "text/plain"}}

5. You can delete a label using the DELETE /api/v1/repository/{repository}/manifest/{manifestref}/labels/{labelid} command:

   $ curl -X DELETE \
     -H "Authorization: Bearer <bearer_token>" \
     https://<quay-server.example.com>/api/v1/repository/<repository>/manifest/<manifestref>/labels/<labelid>

   This command does not return output in the CLI. You can use one of the commands above to ensure that it was successfully removed.

Procedure

1. Navigate to the Tags page of a repository.
2. Under Manifest, click the Fetch Tag icon.

3. When the popup box appears, users are presented with the following options:

   • Podman Pull (by tag)
   • Docker Pull (by tag)
   • Podman Pull (by digest)

   • Docker Pull (by digest)

     Selecting any one of the four options returns a command for the respective client that allows users to pull the image.

4. Click Copy Command to copy the command, which can be used on the command-line interface (CLI). For example:

   $ podman pull quay-server.example.com/quayadmin/busybox:test2

Procedure

1. On the Red Hat Quay v2 UI dashboard, click Repositories in the navigation pane.
2. Click the name of a repository that has image tags.

3. Click Tag History. On this page, you can perform the following actions:

   • Search by tag name
   • Select a date range
   • View tag changes
   • View tag modification dates and the time at which they were changed

Procedure

1. Enter the following command to view tag history by using the GET /api/v1/repository/{repository}/tag/ command and passing in one of the following queries:

   • onlyActiveTags=<true/false>: Filters to only include active tags.
   • page=<number>: Specifies the page number of results to retrieve.
   • limit=<number>: Limits the number of results per page.

   • specificTag=<tag_name>: Filters the tags to include only the tag with the specified name.

     $ curl -X GET \
       -H "Authorization: Bearer <bearer_token>" \
       -H "Accept: application/json" \
       "https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository>/tag/?onlyActiveTags=true&page=1&limit=10"

     Example output

     {"tags": [{"name": "test-two", "reversion": false, "start_ts": 1717680780, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:33:00 -0000"}, {"name": "tag-test", "reversion": false, "start_ts": 1717680378, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Thu, 06 Jun 2024 13:26:18 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}], "page": 1, "has_additional": false}

2. By using the specificTag=<tag_name> query, you can filter results for a specific tag. For example:

   $ curl -X GET   -H "Authorization: Bearer <bearer_token>"   -H "Accept: application/json"   "<quay-server.example.com>/api/v1/repository/quayadmin/busybox/tag/?onlyActiveTags=true&page=1&limit=20&specificTag=test-two"

   Example output

   {"tags": [{"name": "test-two", "reversion": true, "start_ts": 1718737153, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 18 Jun 2024 18:59:13 -0000"}], "page": 1, "has_additional": false}

Procedure

1. On the Repositories page of the v2 UI, click the name of the image you want to delete, for example, quay/admin/busybox.
2. Click the More Actions drop-down menu.

3. Click Delete.

   Note

   If desired, you could click Make Public or Make Private.

4. Type confirm in the box, and then click Delete.

5. After deletion, you are returned to the Repositories page.

   Note

   Deleting an image tag can be reverted based on the amount of time allotted assigned to the time machine feature. For more information, see "Reverting tag changes".

Procedure

1. You can delete an image tag by using the DELETE /api/v1/repository/{repository}/tag/{tag} command:

   $ curl -X DELETE \
     -H "Authorization: Bearer <bearer_token>" \
     https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag/<tag>

   This command does not return output in the CLI. Continue on to the next step to return a list of tags.

2. To see a list of tags after deleting a tag, you can use the GET /api/v1/repository/{repository}/tag/ command. For example:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
      https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag

   Example output

   {"tags": [{"name": "test", "reversion": false, "start_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715697708, "end_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:41:48 -0000", "expiration": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715695488, "end_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "expiration": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715631517, "end_ts": 1715695488, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Mon, 13 May 2024 20:18:37 -0000", "expiration": "Tue, 14 May 2024 14:04:48 -0000"}], "page": 1, "has_additional": false}

Procedure

1. On the Repositories page of the v2 UI, click the name of the image you want to revert.
2. Click the Tag History tab.
3. Find the point in the timeline at which image tags were changed or removed. Next, click the option under Revert to restore a tag to its image.

Procedure

1. You can restore a repository tag to its previous image by using the POST /api/v1/repository/{repository}/tag/{tag}/restore command. For example:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     --data '{
       "manifest_digest": <manifest_digest>
     }' \
     quay-server.example.com/api/v1/repository/quayadmin/busybox/tag/test/restore

   Example output

   {}

2. To see a list of tags after restoring an old tag you can use the GET /api/v1/repository/{repository}/tag/ command. For example:

   $ curl -X GET \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Accept: application/json" \
      https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/tag

   Example output

   {"tags": [{"name": "test", "reversion": false, "start_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "example", "reversion": false, "start_ts": 1715697708, "end_ts": 1715698131, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:41:48 -0000", "expiration": "Tue, 14 May 2024 14:48:51 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715695488, "end_ts": 1716324069, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Tue, 14 May 2024 14:04:48 -0000", "expiration": "Tue, 21 May 2024 20:41:09 -0000"}, {"name": "test", "reversion": false, "start_ts": 1715631517, "end_ts": 1715695488, "manifest_digest": "sha256:57583a1b9c0a7509d3417387b4f43acf80d08cdcf5266ac87987be3f8f919d5d", "is_manifest_list": false, "size": 2275314, "last_modified": "Mon, 13 May 2024 20:18:37 -0000", "expiration": "Tue, 14 May 2024 14:04:48 -0000"}], "page": 1, "has_additional": false}

Procedure

1. Log in to your Red Hat Quay registry.
2. Navigate to an Organization, repository, or namespace for which you are an administrator of.

3. Click Logs.

   

4. Optional. Set the date range for viewing log entries by adding dates to the From and To boxes.
5. Optional. Export the logs by clicking Export. You must enter an email address or a valid callback URL that starts with http:// or https://. This process can take an hour depending on how many logs there are.

Procedure

1. Select a repository for which you have administrator privileges.
2. Click the Logs tab.
3. Optional. If you want to specify specific dates, enter the range in the From and to boxes.

4. Click the Export Logs button. An Export Usage Logs pop-up appears, as shown

   

5. Enter an email address or callback URL to receive the exported log. For the callback URL, you can use a URL to a specified domain, for example, <webhook.site>.
6. Select Confirm to start the process for gather the selected log entries. Depending on the amount of logging data being gathered, this can take anywhere from a few minutes to several hours to complete.

7. When the log export is completed, the one of following two events happens:

   • An email is received, alerting you to the available of your requested exported log entries.
   • A successful status of your log export request from the webhook URL is returned. Additionally, a link to the exported data is made available for you to delete to download the logs.

Procedure

1. Use the POST /api/v1/user/exportlogs endpoint to export logs for the current user:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
           "starttime": "<MM/DD/YYYY>",
           "endtime": "<MM/DD/YYYY>",
           "callback_email": "your.email@example.com"
         }' \
     "http://<quay-server.example.com>/api/v1/user/exportlogs"

   Example output

   {"export_id": "6a0b9ea9-444c-4a19-9db8-113201c38cd4"}

2. Use the POST /api/v1/organization/{orgname}/exportlogs endpoint to export logs for an Organization:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
           "starttime": "<MM/DD/YYYY>",
           "endtime": "<MM/DD/YYYY>",
           "callback_email": "org.logs@example.com"
         }' \
     "http://<quay-server.example.com>/api/v1/organization/{orgname}/exportlogs"

3. Use the POST /api/v1/repository/{repository}/exportlogs endpoint to export logs for a repository:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
           "starttime": "2024-01-01",
           "endtime": "2024-06-18",
           "callback_url": "http://your-callback-url.example.com"
         }' \
     "http://<quay-server.example.com>/api/v1/repository/{repository}/exportlogs"

Procedure

1. Navigate to a repository and click Tags in the navigation pane. This page shows the results of the security scan.
2. To reveal more information about multi-architecture images, click See Child Manifests to see the list of manifests in extended view.
3. Click a relevant link under See Child Manifests, for example, 1 Unknown to be redirected to the Security Scanner page.
4. The Security Scanner page provides information for the tag, such as which CVEs the image is susceptible to, and what remediation options you might have available.

Procedure

1. Navigate to a repository on Red Hat Quay.
2. In the navigation pane, click Settings.
3. In the Events and Notifications category, click Create Notification to add a new notification for a repository event. The Create notification popup box appears.

4. On the Create repository popup box, click the When this event occurs box to select an event. You can select a notification for the following types of events:

   • Push to Repository
   • Image build failed
   • Image build queued
   • Image build started
   • Image build success
   • Image build cancelled
   • Image expiry trigger

5. After you have selected the event type, select the notification method. The following methods are supported:

   • Quay Notification
   • E-mail Notification
   • Webhook POST
   • Flowdock Team Notification
   • HipChat Room Notification

   • Slack Notification

     Depending on the method that you choose, you must include additional information. For example, if you select E-mail, you are required to include an e-mail address and an optional notification title.

6. After selecting an event and notification method, click Create Notification.

Procedure

1. Enter the following POST /api/v1/repository/{repository}/notification command to create a notification on your repository:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     -H "Content-Type: application/json" \
     --data '{
       "event": "<event>",
       "method": "<method>",
       "config": {
         "<config_key>": "<config_value>"
       },
       "eventConfig": {
         "<eventConfig_key>": "<eventConfig_value>"
       }
     }' \
     https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/

   This command does not return output in the CLI. Instead, you can enter the following GET /api/v1/repository/{repository}/notification/{uuid} command to obtain information about the repository notification:

   {"uuid": "240662ea-597b-499d-98bb-2b57e73408d6", "title": null, "event": "repo_push", "method": "quay_notification", "config": {"target": {"name": "quayadmin", "kind": "user", "is_robot": false, "avatar": {"name": "quayadmin", "hash": "b28d563a6dc76b4431fc7b0524bbff6b810387dac86d9303874871839859c7cc", "color": "#17becf", "kind": "user"}}}, "event_config": {}, "number_of_failures": 0}

2. You can test your repository notification by entering the following POST /api/v1/repository/{repository}/notification/{uuid}/test command:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>/test

   Example output

   {}

3. You can reset repository notification failures to 0 by entering the following POST /api/v1/repository/{repository}/notification/{uuid} command:

   $ curl -X POST \
     -H "Authorization: Bearer <bearer_token>" \
     https://<quay-server.example.com>/api/v1/repository/<repository>/notification/<uuid>

4. Enter the following DELETE /api/v1/repository/{repository}/notification/{uuid} command to delete a repository notification:

   $ curl -X DELETE \
     -H "Authorization: Bearer <bearer_token>" \
     https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification/<uuid>

   This command does not return output in the CLI. Instead, you can enter the following GET /api/v1/repository/{repository}/notification/ command to retrieve a list of all notifications:

   $ curl -X GET  -H "Authorization: Bearer <bearer_token>"   -H "Accept: application/json"  https://<quay-server.example.com>/api/v1/repository/<namespace>/<repository_name>/notification

   Example output

   {"notifications": []}

Procedure

1. In your Quay organization on the UI, for example, cache-quayio, click Organization Settings on the left hand pane.

2. Optional: Click Add Storage Quota to configure quota management for your organization. For more information about quota management, see Quota Management.

   Note

   In some cases, pulling images with Podman might return the following error when quota limit is reached during a pull: unable to pull image: Error parsing image configuration: Error fetching blob: invalid status code from registry 403 (Forbidden). Error 403 is inaccurate, and occurs because Podman hides the correct API error: Quota has been exceeded on namespace. This known issue will be fixed in a future Podman update.

3. In Remote Registry enter the name of the remote registry to be cached, for example, quay.io, and click Save.

   Note

   By adding a namespace to the Remote Registry, for example, quay.io/<namespace>, users in your organization will only be able to proxy from that namespace.

4. Optional: Add a Remote Registry Username and Remote Registry Password.

   Note

   If you do not set a Remote Registry Username and Remote Registry Password, you cannot add one without removing the proxy cache and creating a new registry.

5. Optional: Set a time in the Expiration field.

   Note
   • The default tag Expiration field for cached images in a proxy organization is set to 86400 seconds. In the proxy organization, the tag expiration is refreshed to the value set in the UI’s Expiration field every time the tag is pulled. This feature is different than Quay’s default individual tag expiration feature. In a proxy organization, it is possible to override the individual tag feature. When this happens, the individual tag’s expiration is reset according to the Expiration field of the proxy organization.
   • Expired images will disappear after the allotted time, but are still stored in Quay. The time in which an image is completely deleted, or collected, depends on the Time Machine setting of your organization. The default time for garbage collection is 14 days unless otherwise specified.
6. Click Save.

7. On the CLI, pull a public image from the registry, for example, quay.io, acting as a proxy cache:

   $ podman pull <registry_url>/<organization_name>/<quayio_namespace>/<image_name>

   Important

   If your organization is set up to pull from a single namespace in the remote registry, the remote registry namespace must be omitted from the URL. For example, podman pull <registry_url>/<organization_name>/<image_name>.

Procedure

1. On the main page, select an Organization.
2. In the navigation pane, select Applications.
3. Click Create New Application and provide a new application name, then press Enter.
4. On the OAuth Applications page, select the name of your application.

5. Optional. Enter the following information:

   1. Application Name
   2. Homepage URL
   3. Description
   4. Avatar E-mail
   5. Redirect/Callback URL prefix
6. In the navigation pane, select Generate Token.

7. Check the boxes for the following options:

   1. Administer Organization
   2. Administer Repositories
   3. Create Repositories
   4. View all visible repositories
   5. Read/Write to any accessible repositories
   6. Super User Access
   7. Administer User
   8. Read User Information
8. Click Generate Access Token. You are redirected to a new page.
9. Review the permissions that you are allowing, then click Authorize Application. Confirm your decision by clicking Authorize Application.

10. You are redirected to the Access Token page. Copy and save the access token.

    Important

    This is the only opportunity to copy and save the access token. It cannot be reobtained after leaving this page.

Procedure

1. Update your config.yaml file to include the FEATURE_REFERRERS_API: true field. For example:

   # ...
   FEATURE_REFERRERS_API: true
   # ...

2. Enter the following command to Base64 encode your credentials:

   $ echo -n '<username>:<password>' | base64

   Example output

   abcdeWFkbWluOjE5ODlraWROZXQxIQ==

3. Enter the following command to use the base64 encoded string and modify the URL endpoint to your Red Hat Quay server:

   $ curl --location '<quay-server.example.com>/v2/auth?service=<quay-server.example.com>&scope=repository:quay/listocireferrs:pull,push' --header 'Authorization: Basic <base64_username:password_encode_token>' -k | jq

   Example output

   {
     "token": "<example_secret>
   }

Procedure

1. Optional. If not already, update your Red Hat Quay config.yaml file to include the FEATURE_ASSIGN_OAUTH_TOKEN: true field:

   # ...
   FEATURE_ASSIGN_OAUTH_TOKEN: true
   # ...

2. Optional. Restart your Red Hat Quay registry.
3. Log in to your Red Hat Quay registry as an organization administrator.
4. Click the name of the organization in which you created the OAuth token for.
5. In the navigation pane, click Applications.
6. Click the proper application name.
7. In the navigation pane, click Generate Token.
8. Click Assign another user and enter the name of the user that will take over the OAuth token.

9. Check the boxes for the desired permissions that you want the new user to have. For example, if you only want the new user to be able to create repositories, click Create Repositories.

   Important

   Permission control is defined by the team role within an organization and must be configured regardless of the options selected here. For example, the user that you are assigning the OAuth token to must have the Admin team role to use administrative API endpoints.

   Solely checking the Super User Access box does not actually grant the user this permission. Superusers must be configured via the config.yaml file and the box must be checked here.

10. Click Assign token. A popup box appears that confirms authorization with the following message and shows you the approved permissions:

    This will prompt user <username> to generate a token with the following permissions:
    repo:create

11. Click Assign token in the popup box. You are redirected to a new page that displays the following message:

    Token assigned successfully

Verification

1. After reassigning an OAuth token, the assigned user must accept the token to receive the bearer token, which is required to use API endpoints. Request that the assigned user logs into the Red Hat Quay registry.
2. After they have logged in, they must click their username under Users and Organizations.
3. In the navigation pane, they must click External Logins And Applications.
4. Under Authorized Applications, they must confirm the application by clicking Authorize Application. They are directed to a new page where they must reconfirm by clicking Authorize Application.
5. They are redirected to a new page that reveals their bearer token. They must save this bearer token, as it cannot be viewed again.

Procedure

1. Add a chart repository by entering the following command:

   $ helm repo add redhat-cop https://redhat-cop.github.io/helm-charts

2. Enter the following command to update the information of available charts locally from the chart repository:

   $ helm repo update

3. Enter the following command to pull a chart from a repository:

   $ helm pull redhat-cop/etherpad --version=0.0.4 --untar

4. Enter the following command to package the chart into a chart archive:

   $ helm package ./etherpad

   Example output

   Successfully packaged chart and saved it to: /home/user/linux-amd64/etherpad-0.0.4.tgz

5. Log in to Red Hat Quay using helm registry login:

   $ helm registry login quay370.apps.quayperf370.perfscale.devcluster.openshift.com

6. Push the chart to your repository using the helm push command:

   $ helm push etherpad-0.0.4.tgz oci://quay370.apps.quayperf370.perfscale.devcluster.openshift.com

   Example output:

   Pushed: quay370.apps.quayperf370.perfscale.devcluster.openshift.com/etherpad:0.0.4
   Digest: sha256:a6667ff2a0e2bd7aa4813db9ac854b5124ff1c458d170b70c2d2375325f2451b

7. Ensure that the push worked by deleting the local copy, and then pulling the chart from the repository:

   $ rm -rf etherpad-0.0.4.tgz

   $ helm pull oci://quay370.apps.quayperf370.perfscale.devcluster.openshift.com/etherpad --version 0.0.4

   Example output:

   Pulled: quay370.apps.quayperf370.perfscale.devcluster.openshift.com/etherpad:0.0.4
   Digest: sha256:4f627399685880daf30cf77b6026dc129034d68c7676c7e07020b70cf7130902

Verification

1. Pull the image with oras. For example:

   $ oras pull quay.io/<organization_name>/<repository>/<image_name>:<tag>

2. Inspect the changes using oras. For example:

   $ oras manifest fetch quay.io/<organization_name>/<repository>/<image_name>:<tag>

   Example output

   {"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","artifactType":"application/vnd.unknown.artifact.v1","config":{"mediaType":"application/vnd.oci.empty.v1+json","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2,"data":"e30="},"layers":[{"mediaType":"application/vnd.oci.empty.v1+json","digest":"sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a","size":2,"data":"e30="}],"annotations":{"org.opencontainers.image.created":"2024-07-11T15:22:42Z","version ":" 8.11"}}

Procedure

1. Tag an OCI media artifact by entering the following command:

   $ podman tag <myartifact_image> <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag>

2. Push the artifact to your Red Hat Quay registry. For example:

   $ podman push <myartifact_image> <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag>

3. Enter the following command to attach a manifest using the OCI 1.1 referrers API schema with oras:

   $ oras attach --artifact-type <MIME_type> --distribution-spec v1.1-referrers-api <myartifact_image> \
   <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag> \
   <example_file>.txt

   Example output

   -spec v1.1-referrers-api quay.io/testorg3/myartifact-image:v1.0 hi.txt
   ✓ Exists    hi.txt                                                               3/3  B 100.00%     0s
     └─ sha256:98ea6e4f216f2fb4b69fff9b3a44842c38686ca685f3f55dc48c5d3fb1107be4
   ✓ Exists    application/vnd.oci.empty.v1+json                                    2/2  B 100.00%     0s
     └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
   ✓ Uploaded  application/vnd.oci.image.manifest.v1+json                       723/723  B 100.00%  677ms
     └─ sha256:31c38e6adcc59a3cfbd2ef971792aaf124cbde8118e25133e9f9c9c4cd1d00c6
   Attached to [registry] quay.io/testorg3/myartifact-image@sha256:db440c57edfad40c682f9186ab1c1075707ce7a6fdda24a89cb8c10eaad424da
   Digest: sha256:31c38e6adcc59a3cfbd2ef971792aaf124cbde8118e25133e9f9c9c4cd1d00c6

4. Enter the following command to attach a manifest using the OCI 1.1 referrers tag schema:

   $ oras attach --artifact-type <MIME_type> --distribution-spec v1.1-referrers-tag \
   <myartifact_image> <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag> \
   <example_file>.txt

   Example output

   ✓ Exists    hi.txt                                                             3/3  B 100.00%     0s
     └─ sha256:98ea6e4f216f2fb4b69fff9b3a44842c38686ca685f3f55dc48c5d3fb1107be4
   ✓ Exists    application/vnd.oci.empty.v1+json                                  2/2  B 100.00%     0s
     └─ sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a
   ✓ Uploaded  application/vnd.oci.image.manifest.v1+json                     723/723  B 100.00%  465ms
     └─ sha256:2d4b54201c8b134711ab051389f5ba24c75c2e6b0f0ff157fce8ffdfe104f383
   Attached to [registry] quay.io/testorg3/myartifact-image@sha256:db440c57edfad40c682f9186ab1c1075707ce7a6fdda24a89cb8c10eaad424da
   Digest: sha256:2d4b54201c8b134711ab051389f5ba24c75c2e6b0f0ff157fce8ffdfe104f383

5. Enter the following command to discoverer referrers of the artifact using the tag schema:

   $ oras discover --insecure --distribution-spec v1.1-referrers-tag \
   <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag>

   Example output

   quay.io/testorg3/myartifact-image@sha256:db440c57edfad40c682f9186ab1c1075707ce7a6fdda24a89cb8c10eaad424da
   └── doc/example
       └── sha256:2d4b54201c8b134711ab051389f5ba24c75c2e6b0f0ff157fce8ffdfe104f383

6. Enter the following command to discoverer referrers of the artifact using the API schema:

   $ oras discover --distribution-spec v1.1-referrers-api \
   <quay-server.example.com>/<organization_name>/<repository>/<image_name>:<tag>

   Example output

   Discovered 3 artifacts referencing v1.0
   Digest: sha256:db440c57edfad40c682f9186ab1c1075707ce7a6fdda24a89cb8c10eaad424da
   
   Artifact Type   Digest
                   sha256:2d4b54201c8b134711ab051389f5ba24c75c2e6b0f0ff157fce8ffdfe104f383
                   sha256:22b7e167793808f83db66f7d35fbe0088b34560f34f8ead36019a4cc48fd346b
                   sha256:bb2b7e7c3a58fd9ba60349473b3a746f9fe78995a88cb329fc2fd1fd892ea4e4

7. Optional. You can also discover referrers by using the /v2/<organization_name>/<repository_name>/referrers/<sha256_digest> endpoint. For this to work, you must generate a v2 API token and set FEATURE_REFERRERS_API: true in your config.yaml file.

   1. Update your config.yaml file to include the FEATURE_REFERRERS_API field. For example:

      # ...
      FEATURE_REFERRERS_API: true
      # ...

   2. Enter the following command to Base64 encode your credentials:

      $ echo -n '<username>:<password>' | base64

      Example output

      abcdeWFkbWluOjE5ODlraWROZXQxIQ==

   3. Enter the following command to use the base64 encoded token and modify the URL endpoint to your Red Hat Quay server:

      $ curl --location '<quay-server.example.com>/v2/auth?service=<quay-server.example.com>&scope=repository:quay/listocireferrs:pull,push' --header 'Authorization: Basic <base64_username:password_encode_token>' -k | jq

      Example output

      {
        "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Ijl5RWNtWmdiZ0l6czBBZW16emhTMHM1R0g2RDJnV2JGUTdUNGZYand4MlUiLCJ0eXAiOiJKV1QifQ..."
      }

8. Enter the following command, using the v2 API token, to list OCI referrers of a manifest under a repository:

   $ GET https://<quay-server.example.com>/v2/<organization_name>/<repository_name>/referrers/sha256:0de63ba2d98ab328218a1b6373def69ec0d0e7535866f50589111285f2bf3fb8
   --header 'Authorization: Bearer <v2_bearer_token> -k | jq

   Example output

   {
     "schemaVersion": 2,
     "mediaType": "application/vnd.oci.image.index.v1+json",
     "manifests": [
       {
         "mediaType": "application/vnd.oci.image.manifest.v1+json",
         "digest": "sha256:2d4b54201c8b134711ab051389f5ba24c75c2e6b0f0ff157fce8ffdfe104f383",
         "size": 793
       },
     ]
   }