Integrate

Log in to Project Quay through the web UI.

Select the organization for which you configure the external application.

On the navigation pane, select Applications.

Select Create New Application and enter a name for the new application, for example, openshift.

On the OAuth Applications page, select your application, for example, openshift.

On the navigation pane, select Generate Token.

Select the following fields:

Review the assigned permissions.

Select Authorize Application and then confirm the authorization by selecting Authorize Application.

Save the generated access token.

Open the Administrator perspective of the web console and navigate to Operators → OperatorHub on the navigation pane.

Search for Quay Bridge Operator, click the Quay Bridge Operator title, and then click Install.

Select the version to install, for example, stable-{producty}, and then click Install.

Click View Operator when the installation finishes to go to the Quay Bridge Operator’s Details page. Alternatively, you can click Installed Operators → Red Hat Quay Bridge Operator to go to the Details page.

Create a quay-integration.yaml:

$ touch quay-integration.yaml

Use the following configuration for a minimal deployment of the QuayIntegration custom resource:

  apiVersion: quay.redhat.com/v1
  kind: QuayIntegration
  metadata:
    name: example-quayintegration
  spec:
    clusterID: openshift
    credentialsSecret:
      namespace: openshift-operators
      name: quay-integration
    quayHostname: https://<QUAY_URL>
    insecureRegistry: false

Create the QuayIntegration custom resource by entering the following command:

$ oc create -f quay-integration.yaml

Open the Administrator perspective of the web console and navigate to Operators → Installed Operators.

Click Red Hat Quay Bridge Operator.

On the Details page of the Quay Bridge Operator, click Create Instance on the Quay Integration API card.

On the Create QuayIntegration page, enter the following required information in either Form view or YAML view:

Enter the following command to create a new OpenShift Container Platform project called e2e-demo:

$ oc new-project e2e-demo

After you have created a new project, a new Organization is created in Project Quay. Navigate to the Project Quay registry and confirm that you have created a new Organization named openshift_e2e-demo.

On the Project Quay UI, click the name of the new Organization, for example, openshift_e2e-demo.

Click Robot Accounts in the navigation pane. As part of new project, the following Robot Accounts should have been created:

Enter the following command to confirm three secrets containing Docker configuration associated with the applicable Robot Accounts were created:

$ oc get secrets builder-quay-openshift deployer-quay-openshift default-quay-openshift

stevsmit@stevsmit ocp-quay $ oc get secrets builder-quay-openshift deployer-quay-openshift default-quay-openshift
NAME                      TYPE                             DATA   AGE
builder-quay-openshift    kubernetes.io/dockerconfigjson   1      77m
deployer-quay-openshift   kubernetes.io/dockerconfigjson   1      77m
default-quay-openshift    kubernetes.io/dockerconfigjson   1      77m

Enter the following command to display detailed information about builder ServiceAccount (SA), including its secrets, token expiration, and associated roles and role bindings. This ensures that the project is integrated via the Quay Bridge Operator.

$ oc describe sa builder default deployer

...
Name:                builder
Namespace:           e2e-demo
Labels:              <none>
Annotations:         <none>
Image pull secrets:  builder-dockercfg-12345
                     builder-quay-openshift
Mountable secrets:   builder-dockercfg-12345
                     builder-quay-openshift
Tokens:              builder-token-12345
Events:              <none>
...

Enter the following command to create and deploy a new application called httpd-template:

$ oc new-app --template=httpd-example

--> Deploying template "e2e-demo/httpd-example" to project e2e-demo
...
--> Creating resources ...
    service "httpd-example" created
    route.route.openshift.io "httpd-example" created
    imagestream.image.openshift.io "httpd-example" created
    buildconfig.build.openshift.io "httpd-example" created
    deploymentconfig.apps.openshift.io "httpd-example" created
--> Success
    Access your application via route 'httpd-example-e2e-demo.apps.quay-ocp.gcp.quaydev.org'
    Build scheduled, use 'oc logs -f buildconfig/httpd-example' to track its progress.
    Run 'oc status' to view your app.

The ImageChangeTrigger for the BuildConfig triggers a new Build when the Apache HTTPD image, located in the openshift namespace, is resolved. As the new Build is created, the MutatingWebhookConfiguration automatically rewrites the output to point at Project Quay. You can confirm that the build is complete by querying the output field of the build by running the following command:

$ oc get build httpd-example-1 --template='{{ .spec.output.to.name }}'

example-registry-quay-quay-enterprise.apps.quay-ocp.gcp.quaydev.org/openshift_e2e-demo/httpd-example:latest

On the Project Quay UI, navigate to the openshift_e2e-demo Organization and select the httpd-example repository.

Click Tags in the navigation pane and confirm that the latest tag has been successfully pushed.

Enter the following command to ensure that the latest tag has been resolved:

$ oc describe is httpd-example

Name:			httpd-example
Namespace:		e2e-demo
Created:		55 minutes ago
Labels:			app=httpd-example
			template=httpd-example
Description:		Keeps track of changes in the application image
Annotations:		openshift.io/generated-by=OpenShiftNewApp
			openshift.io/image.dockerRepositoryCheck=2023-10-02T17:56:45Z
Image Repository:	image-registry.openshift-image-registry.svc:5000/e2e-demo/httpd-example
Image Lookup:		local=false
Unique Images:		0
Tags:			1

latest
  tagged from example-registry-quay-quay-enterprise.apps.quay-ocp.gcp.quaydev.org/openshift_e2e-demo/httpd-example:latest

After the ImageStream is resolved, a new deployment should have been triggered. Enter the following command to generate a URL output:

$ oc get route httpd-example --template='{{ .spec.host }}'

httpd-example-e2e-demo.apps.quay-ocp.gcp.quaydev.org

Navigate to the URL. If a sample web page appears, the deployment was successful.

Enter the following command to delete the resources and clean up your Project Quay repository:

$ oc delete project e2e-demo

After the command completes, navigate to your Project Quay repository and confirm that the openshift_e2e-demo Organization is no longer available.

Use the POST /api/v1/organization/{orgname}/mirror endpoint to create a new organization-level mirroring configuration:

$ curl -X POST "https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "external_registry_type": "quay",
    "external_registry_url": "https://quay.io",
    "external_namespace": "<external_namespace>",
    "robot_username": "<orgname>+<robot_account>",
    "visibility": "private",
    "sync_interval": 3600,
    "sync_start_date": "2025-01-01T00:00:00Z",
    "is_enabled": true
  }'

Use the GET /api/v1/organization/{orgname}/mirror endpoint to retrieve the organization-level mirroring configuration:

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

{"is_enabled": true, "external_registry_type": "quay", "external_registry_url": "http://quay.io", "external_namespace": "test", "external_registry_username": null, "external_registry_config": {}, "repository_filters": [], "robot_username": "example+test", "visibility": "private", "sync_interval": 3600, "sync_start_date": "2025-01-01T00:00:00Z", "sync_expiration_date": null, "sync_status": "NEVER_RUN", "sync_retries_remaining": 3, "skopeo_timeout": 300, "creation_date": "2026-03-09T18:39:21.993431Z"}

Use the GET /api/v1/organization/{orgname}/mirror/repositories endpoint to obtain a list of repositories that are being mirrored in the organization:

$ curl -X GET \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  "https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror/repositories?page=1&limit=100"

{"repositories": [], "page": 1, "limit": 100, "total": 0, "has_next": false}

Use the POST /api/v1/organization/{orgname}/mirror/sync-now endpoint to trigger an immediate sync of all repositories in the organization:

$ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror/sync-now

Use the POST /api/v1/organization/{orgname}/mirror/sync-cancel endpoint to cancel a pending sync of all repositories in the organization:

$ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror/sync-cancel

Use the PUT /api/v1/organization/{orgname}/mirror endpoint to update the organization-level mirroring configuration:

$ curl -X PUT \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"is_enabled": true, "sync_interval": 7200}' \
  https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror

" "

Use the POST /api/v1/organization/{orgname}/mirror/verify endpoint to verify the connection to the external registry for the organization-level mirroring configuration:

$ curl -X POST \
  -H "Authorization: Bearer <bearer_token>" \
  -H "Accept: application/json" \
  https://<quay-server.example.com>/api/v1/organization/<orgname>/mirror/verify

{"success": false, "message": "Unexpected response: 301"}

Use the DELETE /api/v1/organization/{orgname}/mirror endpoint to delete the organization-level mirroring configuration:

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

Navigate to the Mirroring tab of your repository or organization.

Click Sync Now.

Click the Logs tab to view available logs.

When mirroring is complete, the images appear in the Tags tab.

On the Project Quay v2 UI, click the name of an organization, for example, cache-org.

In the navigation pane, click Settings.

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

Optional. In the Remote Registry username box, enter the username for authenticating into the remote registry specified in the previous step. If you leave this empty, Quay will attempt to pull content anonymously from the upstream registry.

Optional. In the Remote registry password box, enter the password for authenticating into the remote registry. If you leave this empty, Quay will attempt to pull content anonymously from the upstream registry.

Optional. Set a time in the Expiration field.

Optional. Check the http box if you want an unsecure protocol used. If not checked, https is used to request the remote registry.

Click Save.

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

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

Pull an image to your repository from your proxy organization, for example:

$ podman pull quay-server.example.com/proxytest/projectquay/quay:3.7.9

Depending on the space left in your repository, you might need to pull additional images from your proxy organization, for example:

$ podman pull quay-server.example.com/proxytest/projectquay/quay:3.6.2

In the Project Quay registry UI, click the name of your repository.

Pull the last image that will result in your repository exceeding the allotted quota, for example:

$ podman pull quay-server.example.com/proxytest/projectquay/quay:3.5.1

Refresh the Tags page of your Project Quay registry. The first image that you pushed, for example, quay:3.7.9 should have been auto-pruned. The Tags page should now show quay:3.6.2 and quay:3.5.1.

Log in to the Amazon Web Services (AWS) console and navigate to the Identity and Access Management (IAM) console.

In the navigation pane, under Access management click Users.

Click Create User and enter the following information:

On the review and create page, click Create user. You are redirected to the Users page.

Click the username, for example, quay-user.

Copy the ARN of the user, for example, arn:aws:iam::123456:user/quay-user.

On the same page, click the Security credentials tab.

Navigate to Access keys.

Click Create access key.

On the Access key best practices & alternatives page, click Command Line Interface (CLI), then, check the confirmation box. Then click Next.

Optional. On the Set description tag - optional page, enter a description.

Click Create access key.

Copy and store the access key and the secret access key.

Click Done.

Navigate to the IAM dashboard.

In the navigation pane, click Roles under Access management.

Click Create role → Custom Trust Policy.

Under the Principal configuration field, add your AWS ARN information. For example:

{
    "Version": "2012-10-17",
    "Statement": [
   	 {
   		 "Sid": "Statement1",
   		 "Effect": "Allow",
   		 "Principal": {
   		 	"AWS": "arn:aws:iam::123456:user/quay-user"
   		 },
   		 "Action": "sts:AssumeRole"
   	 }
    ]
}

Click Next.

On the Add permissions page, type AmazonS3FullAccess in the search box. Check the box to add that policy to the S3 role, then click Next.

On the Name, review, and create page, enter the following information:

Click the Create role button. You are navigated to the Roles page. Under Role name, the newly created S3 should be available.

On the Home page of your OpenShift Container Platform deployment, click Operators → Installed Operators.

Click Red Hat Quay.

Click Quay Registry and then the name of your Project Quay registry.

Under Config Bundle Secret, click the name of your registry configuration bundle, for example, quay-registry-config-bundle-qet56.

On the configuration bundle page, click Actions to reveal a drop-down menu. Then click Edit Secret.

Update your the DISTRIBUTED_STORAGE_CONFIG fields of your config.yaml file with the following information:

# ...
DISTRIBUTED_STORAGE_CONFIG:
   default:
    - STSS3Storage
    - sts_role_arn: <role_arn>
      s3_bucket: <s3_bucket_name>
      storage_path: <storage_path>
      s3_region: <region>
      sts_user_access_key: <s3_user_access_key>
      sts_user_secret_key: <s3_user_secret_key>
# ...

Click Save.

Tag a sample image, for example, busybox, that will be pushed to the repository. For example:

$ podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/busybox:test

Push the sample image by running the following command:

$ podman push <quay-server.example.com>/<organization_name>/busybox:test

Verify that the push was successful by navigating to the Organization that you pushed the image to in your Project Quay registry → Tags.

Navigate to the Amazon Web Services (AWS) console and locate your s3 bucket.

Click the name of your s3 bucket.

On the Objects page, click datastorage/.

On the datastorage/ page, the following resources should seen:

Get the serviceAccountIssuer resource by entering the following command:

$ oc get authentication.config.openshift.io cluster -o json | jq -r .spec.serviceAccountIssuer | sed -e "s/^https:\/\///"

oidc.op1.openshiftapps.com/123456

On the Identity and Access Management (IAM) console of the Amazon Web Services (AWS) console:

On the Roles page, click the new role and store the Role ARN resource. For example:

arn:aws:iam::123456:role/test_s3_access

On the Project Quay web console:

Click Save. Your QuayRegistry custom resource (CR) automatically restarts.

Annotate the Service Account (SA) that executes pods with the EKS configuration values. For example:

$ oc annotate sa registry-quay-app "eks.amazonaws.com/role-arn"="arn:aws:iam::123456:role/test_s3_access" "eks.amazonaws.com/audience"="sts.amazonaws.com" "eks.amazonaws.com/sts-regional-endpoints"="true"

Tag a sample image, for example, busybox, that will be pushed to the repository. For example:

$ podman tag docker.io/library/busybox <quay-server.example.com>/<organization_name>/busybox:test

Push the sample image by running the following command:

$ podman push <quay-server.example.com>/<organization_name>/busybox:test

Verify that the push was successful by navigating to the Organization that you pushed the image to in your Project Quay registry → Tags.

Navigate to the Amazon Web Services (AWS) console and locate your s3 bucket.

Click the name of your s3 bucket.

On the Objects page, click datastorage/.

On the datastorage/ page, the following resources should seen: