Quay Bridge Operator

Red Hat Quay 3.17

Red Hat Quay

Red Hat OpenShift Documentation Team

Preface

To replace the integrated container registry in OpenShift Container Platform with a Red Hat Quay registry, you can use the Quay Bridge Operator. The Quay Bridge Operator duplicates registry features and synchronizes namespaces, image streams, and robot accounts between your clusters.

The features enabled with the Quay Bridge Operator include:

Synchronizing OpenShift Container Platform namespaces as Red Hat Quay organizations.
Creating robot accounts for each default namespace service account.
Creating secrets for each created robot account, and associating each robot secret to a service account as Mountable and Image Pull Secret.
Synchronizing OpenShift Container Platform image streams as Red Hat Quay repositories.
Automatically rewriting new builds making use of image streams to output to Red Hat Quay.
Automatically importing an image stream tag after a build completes.

By using the following procedures, you can enable bi-directional communication between your Red Hat Quay and OpenShift Container Platform clusters.

Chapter 1. Setting up Red Hat Quay for the Quay Bridge Operator

To enable the Quay Bridge Operator to communicate with your Red Hat Quay registry, you can create a dedicated organization and generate an OAuth token with the required permissions.

Prerequisites

You are logged in to Red Hat Quay as a user with administrative privileges.

Procedure

Log in to Red Hat Quay through the web UI.
Select the organization for which the external application will be configured.
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:
- Administer Organization
- Administer Repositories
- Create Repositories
- View all visible repositories
- Read/Write to any accessible repositories
- Super User Access
- Administer User
- Read User Information
Review the assigned permissions.
Select Authorize Application and then confirm confirm the authorization by selecting Authorize Application.
Save the generated access token.
Important
Red Hat Quay does not offer token management. You cannot list tokens, delete tokens, or modify tokens. The generated access token is only shown once and cannot be re-obtained after closing the page.

Chapter 2. Installing the Quay Bridge Operator on OpenShift Container Platform

To enable the Quay Bridge Operator to synchronize your OpenShift Container Platform registry with Red Hat Quay, you can install the operator from OperatorHub in the OpenShift Container Platform web console.

Prerequisites

You have set up Red Hat Quay and obtained an OAuth access token.
You are logged in to OpenShift Container Platform as a user with administrative privileges.

Procedure

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-3.17, 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.

Chapter 3. Creating an OpenShift Container Platform secret for the OAuth token

To enable the Quay Bridge Operator to communicate with your Red Hat Quay deployment, you can create a secret in OpenShift Container Platform that stores the OAuth access token.

Prerequisites

You have set up Red Hat Quay and obtained an access token.
You have deployed the Quay Bridge Operator on OpenShift Container Platform.
You have installed the OpenShift CLI (oc).

Procedure

Create a secret that contains the access token in the openshift-operators namespace:
```
$ oc create secret -n openshift-operators generic <secret_name> --from-literal=token=<access_token>
```
<secret_name> specifies the name of the secret to create, for example, quay-bridge-operator-token. <access_token> specifies the access token generated during "Setting up Red Hat Quay for the Quay Bridge Operator".

Chapter 4. Creating the QuayIntegration custom resource

The QuayIntegration custom resource connects your OpenShift Container Platform cluster to a Red Hat Quay registry and defines the configuration that the Quay Bridge Operator uses to synchronize projects, organizations, and robot accounts.

The QuayIntegration custom resource can be created by using the OpenShift Container Platform web console, or from the command-line interface.

4.1. Creating the QuayIntegration custom resource using the CLI

To create the QuayIntegration custom resource from the command line, you can define the configuration in a YAML file and apply it using the oc create command.

Prerequisites

You have installed the Quay Bridge Operator on OpenShift Container Platform.
You have created a secret containing the OAuth access token in OpenShift Container Platform.
You have installed the OpenShift CLI (oc).

Procedure

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
```
where:
spec.clusterID
Specifies the unique identifier for the OpenShift Container Platform cluster. This value is required and defaults to openshift.
spec.credentialsSecret
Specifies the namespace and name of the secret containing the token that was previously created.
spec.quayHostname
Specifies the hostname of your Red Hat Quay instance.
spec.insecureRegistry
Specifies whether Red Hat Quay is using self signed certificates. If it is, set the property to insecureRegistry: true.
For a list of all configuration fields, see "`QuayIntegration` configuration fields".
Create the QuayIntegration custom resource by entering the following command:
```
$ oc create -f quay-integration.yaml
```

4.2. Creating the QuayIntegration custom resource using the web console

To create the QuayIntegration custom resource using the web console, you can use the Create Instance option from the Quay Bridge Operator operator details page and enter the required configuration fields.

After the QuayIntegration custom resource is created, your OpenShift Container Platform cluster is linked to your Red Hat Quay instance. Organizations within your Red Hat Quay registry should be created for the related namespace for the OpenShift Container Platform environment.

Prerequisites

You have installed the Quay Bridge Operator on OpenShift Container Platform.
You have created a secret containing the OAuth access token in OpenShift Container Platform.
You are logged in to OpenShift Container Platform as a cluster administrator.

Procedure

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:
- Name: The name that will refer to the QuayIntegration custom resource object.
- Cluster ID: The ID associated with this cluster. This value should be unique across the entire ecosystem. Defaults to openshift if left unspecified.
- Credentials secret: Refers to the namespace and name of the secret containing the token that was previously created.
- Quay hostname: The hostname of the Quay registry.

Chapter 5. Using the Quay Bridge Operator

To verify that the Quay Bridge Operator synchronizes your OpenShift Container Platform projects with Red Hat Quay, you can create a test project and confirm that organizations, robot accounts, and image repositories are created automatically.

Prerequisites

You have installed the Red Hat Quay Operator.
You have logged into OpenShift Container Platform as a cluster administrator.
You have logged into your Red Hat Quay registry.
You have installed the Quay Bridge Operator.
You have configured the QuayIntegration custom resource.

Procedure

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 Red Hat Quay. Navigate to the Red Hat Quay registry and confirm that you have created a new Organization named openshift_e2e-demo.
Note
The openshift value of the Organization might different if the clusterID in your QuayIntegration resource used a different value.
On the Red Hat 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:
- openshift_e2e-demo+deployer
- openshift_e2e-demo+default
- openshift_e2e-demo+builder

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

Example output

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

Example output

...
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

Example output

--> 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.

After running this command, BuildConfig, ImageStream, Service, Route, and DeploymentConfig resources are created. When the ImageStream resource is created, an associated repository is created in Red Hat Quay.

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 rewriters the output to point at Red Hat 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 output
```
example-registry-quay-quay-enterprise.apps.quay-ocp.gcp.quaydev.org/openshift_e2e-demo/httpd-example:latest
```
On the Red Hat 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

Example output

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 }}'
```
Example output
```
httpd-example-e2e-demo.apps.quay-ocp.gcp.quaydev.org
```
Navigate to the URL. If a sample webpage appears, the deployment was successful.
Enter the following command to delete the resources and clean up your Red Hat Quay repository:
```
$ oc delete project e2e-demo
```
Note
The command waits until the project resources have been removed. This can be bypassed by adding the --wait=false to the above command
After the command completes, navigate to your Red Hat Quay repository and confirm that the openshift_e2e-demo Organization is no longer available.

Additional resources

This page is not included, but the link has been rewritten to point to the nearest parent document.OpenShift Container Platform documentation

Chapter 6. Upgrading the Quay Bridge Operator

To receive the latest Red Hat Quay upgrades and features, you can upgrade the Quay Bridge Operator by changing the update channel in the operator subscription.

Prerequisites

You have installed Red Hat Quay.
You are logged in to OpenShift Container Platform as a cluster administrator.

Procedure

On the OpenShift Container Platform web console, click Operators → Installed Operators → Quay Bridge Operator.
Click the Subscription tab.
Under Update channel, click stable-3.15 → Save.

Legal Notice

Except as otherwise noted below, the text of and illustrations in this documentation are licensed by Red Hat under the Creative Commons Attribution–Share Alike 3.0 Unported license . If you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, the Red Hat logo, JBoss, Hibernate, and RHCE are trademarks or registered trademarks of Red Hat, LLC. or its subsidiaries in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

XFS is a trademark or registered trademark of Hewlett Packard Enterprise Development LP or its subsidiaries in the United States and other countries.

The OpenStack® Word Mark and OpenStack logo are trademarks or registered trademarks of the Linux Foundation, used under license.

All other trademarks are the property of their respective owners.