Installing and deploying Apicurio Registry on OpenShift

Procedure

1. Browse to Red Hat Software Downloads, select the product version, and download the examples in the Apicurio Registry CRDs .zip file.
2. Extract the downloaded CRDs .zip file and change to the apicurio-registry-install-examples directory.

3. Create an OpenShift project for the Apicurio Registry Operator installation, for example:

   Copy to Clipboard Toggle word wrap

   export NAMESPACE="apicurio-registry"
   oc new-project "$NAMESPACE"

4. Enter the following command to apply the example CRD in the install/install.yaml file:

   Copy to Clipboard Toggle word wrap

   cat install/install.yaml | sed "s/apicurio-registry-operator-namespace/$NAMESPACE/g" | oc apply -f -

5. Enter oc get deployment to check the readiness of the Apicurio Registry Operator. For example, the output should be as follows:

   Copy to Clipboard Toggle word wrap

   NAME                     	READY   UP-TO-DATE  AVAILABLE   AGE
   apicurio-registry-operator  1/1 	1        	1       	XmYs

Procedure

1. Open the examples/apicurioregistry_sql_cr.yaml file in an editor and view the ApicurioRegistry custom resource (CR):

   Example CR for SQL storage

   Copy to Clipboard Toggle word wrap

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry-sql
   spec:
     configuration:
       persistence: "sql"
       sql:
         dataSource:
           url: "jdbc:postgresql://<service name>.<namespace>.svc:5432/<database name>"
           userName: "postgres"
           password: "<password>" # Optional

2. In the dataSource section, replace the example settings with your database connection details. For example:

   Copy to Clipboard Toggle word wrap

   dataSource:
       url: "jdbc:postgresql://postgresql.apicurio-registry.svc:5432/registry"
       userName: "pgadmin"
       password: "pgpass"

3. Enter the following commands to apply the updated ApicurioRegistry CR in the namespace with the Apicurio Registry Operator, and wait for the Apicurio Registry instance to deploy:

   Copy to Clipboard Toggle word wrap

   oc project "$NAMESPACE"
   oc apply -f ./examples/apicurioregistry_sql_cr.yaml

4. Enter oc get deployment to check the readiness of the Apicurio Registry instance. For example, the output should be as follows:

   Copy to Clipboard Toggle word wrap

   NAME                     	        READY UP-TO-DATE AVAILABLE AGE
   example-apicurioregistry-sql-deployment 1/1   1          1         XmYs

5. Enter oc get routes to get the HOST/PORT URL to launch the Apicurio Registry web console in your browser. For example:

   Copy to Clipboard Toggle word wrap

   example-apicurioregistry-sql.apicurio-registry.router-default.apps.mycluster.myorg.mycompany.com

Procedure

1. In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.

2. Create a new OpenShift project:

   1. In the left navigation menu, click Home, Project, and then Create Project.
   2. Enter a project name, for example, my-project, and click Create.
3. In the left navigation menu, click Operators and then OperatorHub.
4. In the Filter by keyword text box, enter registry to find the Red Hat Integration - Service Registry Operator.
5. Read the information about the Operator, and click Install to display the Operator subscription page.

6. Select your subscription settings, for example:

   • Update Channel: Select one of the following:

     • 2.x: Includes all minor and patch updates, such as 2.3.0 and 2.0.3. For example, an installation on 2.0.x will upgrade to 2.3.x.
     • 2.0.x: Includes patch updates only, such as 2.0.1 and 2.0.2. For example, an installation on 2.0.x will ignore 2.3.x.

   • Installation Mode: Select one of the following:

     • All namespaces on the cluster (default)
     • A specific namespace on the cluster and then my-project
   • Approval Strategy: Select Automatic or Manual
7. Click Install, and wait a few moments until the Operator is ready for use.

Procedure

1. In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.
2. Change to the OpenShift project in which you want to install AMQ Streams. For example, from the Project drop-down, select my-project.
3. In the left navigation menu, click Operators and then OperatorHub.
4. In the Filter by keyword text box, enter AMQ Streams to find the Red Hat Integration - AMQ Streams Operator.
5. Read the information about the Operator, and click Install to display the Operator subscription page.

6. Select your subscription settings, for example:

   • Update Channel and then amq-streams-2.6.x

   • Installation Mode: Select one of the following:

     • All namespaces on the cluster (default)
     • A specific namespace on the cluster > my-project
   • Approval Strategy: Select Automatic or Manual
7. Click Install, and wait a few moments until the Operator is ready for use.

Procedure

1. In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.

2. If you do not already have a Kafka cluster configured, create a new Kafka cluster using AMQ Streams. For example, in the OpenShift OperatorHub:

   1. Click Installed Operators and then Red Hat Integration - AMQ Streams.
   2. Under Provided APIs and then Kafka, click Create Instance to create a new Kafka cluster.

   3. Edit the custom resource definition as appropriate, and click Create.

      Warning

      The default example creates a cluster with 3 Zookeeper nodes and 3 Kafka nodes with ephemeral storage. This temporary storage is suitable for development and testing only, and not for production. For more details, see Deploying and Managing AMQ Streams on OpenShift.

3. After the cluster is ready, click Provided APIs > Kafka > my-cluster > YAML.

4. In the status block, make a copy of the bootstrapServers value, which you will use later to deploy Apicurio Registry. For example:

   Copy to Clipboard Toggle word wrap

   status:
     ...
     conditions:
     ...
     listeners:
       - addresses:
           - host: my-cluster-kafka-bootstrap.my-project.svc
             port: 9092
         bootstrapServers: 'my-cluster-kafka-bootstrap.my-project.svc:9092'
         type: plain
     ...

5. Click Installed Operators > Red Hat Integration - Service Registry > ApicurioRegistry > Create ApicurioRegistry.

6. Paste in the following custom resource definition, but use your bootstrapServers value that you copied earlier:

   Copy to Clipboard Toggle word wrap

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry-kafkasql
   spec:
     configuration:
       persistence: 'kafkasql'
       kafkasql:
         bootstrapServers: 'my-cluster-kafka-bootstrap.my-project.svc:9092'

7. Click Create and wait for the Apicurio Registry route to be created on OpenShift.

8. Click Networking > Route to access the new route for the Apicurio Registry web console. For example:

   Copy to Clipboard Toggle word wrap

   http://example-apicurioregistry-kafkasql.my-project.my-domain-name.com/

9. To configure the Kafka topic that Apicurio Registry uses to store data, click Installed Operators > Red Hat Integration - AMQ Streams > Provided APIs > Kafka Topic > kafkasql-journal > YAML. For example:

   Copy to Clipboard Toggle word wrap

   apiVersion: kafka.strimzi.io/v1beta2
   kind: KafkaTopic
   metadata:
     name: kafkasql-journal
     labels:
       strimzi.io/cluster: my-cluster
     namespace: ...
   spec:
     partitions: 3
     replicas: 3
     config:
       cleanup.policy: compact

   Warning

   You must configure the Kafka topic used by Apicurio Registry (named kafkasql-journal by default) with a compaction cleanup policy, otherwise a data loss might occur.

Procedure

1. In the OpenShift web console, click Installed Operators, select the AMQ Streams Operator details, and then the Kafka tab.
2. Click Create Kafka to provision a new Kafka cluster for Apicurio Registry storage.

3. Configure the authorization and tls fields to use TLS authentication for the Kafka cluster, for example:

   Copy to Clipboard Toggle word wrap

   apiVersion: kafka.strimzi.io/v1beta2
   kind: Kafka
   metadata:
     name: my-cluster
     namespace: registry-example-kafkasql-tls
     # Change or remove the explicit namespace
   spec:
     kafka:
       config:
         offsets.topic.replication.factor: 3
         transaction.state.log.replication.factor: 3
         transaction.state.log.min.isr: 2
         log.message.format.version: '2.7'
         inter.broker.protocol.version: '2.7'
       version: 2.7.0
       storage:
         type: ephemeral
       replicas: 3
       listeners:
         - name: tls
           port: 9093
           type: internal
           tls: true
           authentication:
             type: tls
       authorization:
         type: simple
     entityOperator:
       topicOperator: {}
       userOperator: {}
     zookeeper:
       storage:
         type: ephemeral
       replicas: 3

   The default Kafka topic name automatically created by Apicurio Registry to store data is kafkasql-journal. You can override this behavior or the default topic name by setting environment variables. The default values are as follows:

   • REGISTRY_KAFKASQL_TOPIC_AUTO_CREATE=true
   • REGISTRY_KAFKASQL_TOPIC=kafkasql-journal

   If you decide not to create the Kafka topic manually, skip the next step.

4. Click the Kafka Topic tab, and then Create Kafka Topic to create the kafkasql-journal topic:

   Copy to Clipboard Toggle word wrap

   apiVersion: kafka.strimzi.io/v1beta1
   kind: KafkaTopic
   metadata:
     name: kafkasql-journal
     labels:
       strimzi.io/cluster: my-cluster
     namespace: registry-example-kafkasql-tls
   spec:
     partitions: 2
     replicas: 1
     config:
       cleanup.policy: compact

5. Create a Kafka User resource to configure authentication and authorization for the Apicurio Registry user. You can specify a user name in the metadata section or use the default my-user.

   Copy to Clipboard Toggle word wrap

   apiVersion: kafka.strimzi.io/v1beta1
   kind: KafkaUser
   metadata:
     name: my-user
     labels:
       strimzi.io/cluster: my-cluster
     namespace: registry-example-kafkasql-tls
   spec:
     authentication:
       type: tls
     authorization:
       acls:
         - operation: All
           resource:
             name: '*'
             patternType: literal
             type: topic
         - operation: All
           resource:
             name: '*'
             patternType: literal
             type: cluster
         - operation: All
           resource:
             name: '*'
             patternType: literal
             type: transactionalId
         - operation: All
           resource:
             name: '*'
             patternType: literal
             type: group
       type: simple

   Note

   This simple example assumes admin permissions and creates the Kafka topic automatically. You must configure the authorization section specifically for the topics and resources that the Apicurio Registry requires.

   The following example shows the minimum configuration required when the Kafka topic is created manually:

   Copy to Clipboard Toggle word wrap

    ...
     authorization:
       acls:
       - operations:
           - Read
           - Write
         resource:
           name: kafkasql-journal
           patternType: literal
           type: topic
       - operations:
           - Read
           - Write
         resource:
           name: apicurio-registry-
           patternType: prefix
           type: group
       type: simple

6. Click Workloads and then Secrets to find two secrets that AMQ Streams creates for Apicurio Registry to connect to the Kafka cluster:

   • my-cluster-cluster-ca-cert - contains the PKCS12 truststore for the Kafka cluster

   • my-user - contains the user’s keystore

     Note

     The name of the secret can vary based on your cluster or user name.

7. If you create the secrets manually, they must contain the following key-value pairs:

   • my-cluster-ca-cert

     • ca.p12 - truststore in PKCS12 format
     • ca.password - truststore password

   • my-user

     • user.p12 - keystore in PKCS12 format
     • user.password - keystore password

8. Configure the following example configuration to deploy the Apicurio Registry.

   Copy to Clipboard Toggle word wrap

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry-kafkasql-tls
   spec:
     configuration:
       persistence: "kafkasql"
       kafkasql:
         bootstrapServers: "my-cluster-kafka-bootstrap.registry-example-kafkasql-tls.svc:9093"
         security:
           tls:
             keystoreSecretName: my-user
             truststoreSecretName: my-cluster-cluster-ca-cert

Procedure

1. In the OpenShift web console, click Installed Operators, select the AMQ Streams Operator details, and then the Kafka tab.
2. Click Create Kafka to provision a new Kafka cluster for Apicurio Registry storage.

3. Configure the authorization and tls fields to use SCRAM-SHA-512 authentication for the Kafka cluster, for example:

   Copy to Clipboard Toggle word wrap

   apiVersion: kafka.strimzi.io/v1beta2
   kind: Kafka
   metadata:
     name: my-cluster
     namespace: registry-example-kafkasql-scram
     # Change or remove the explicit namespace
   spec:
     kafka:
       config:
         offsets.topic.replication.factor: 3
         transaction.state.log.replication.factor: 3
         transaction.state.log.min.isr: 2
         log.message.format.version: '2.7'
         inter.broker.protocol.version: '2.7'
       version: 2.7.0
       storage:
         type: ephemeral
       replicas: 3
       listeners:
         - name: tls
           port: 9093
           type: internal
           tls: true
           authentication:
             type: scram-sha-512
       authorization:
         type: simple
     entityOperator:
       topicOperator: {}
       userOperator: {}
     zookeeper:
       storage:
         type: ephemeral
       replicas: 3

   The default Kafka topic name automatically created by Apicurio Registry to store data is kafkasql-journal. You can override this behavior or the default topic name by setting environment variables. The default values are as follows:

   • REGISTRY_KAFKASQL_TOPIC_AUTO_CREATE=true
   • REGISTRY_KAFKASQL_TOPIC=kafkasql-journal

   If you decide not to create the Kafka topic manually, skip the next step.

4. Click the Kafka Topic tab, and then Create Kafka Topic to create the kafkasql-journal topic:

   Copy to Clipboard Toggle word wrap

   apiVersion: kafka.strimzi.io/v1beta1
   kind: KafkaTopic
   metadata:
     name: kafkasql-journal
     labels:
       strimzi.io/cluster: my-cluster
     namespace: registry-example-kafkasql-scram
   spec:
     partitions: 2
     replicas: 1
     config:
       cleanup.policy: compact

5. Create a Kafka User resource to configure SCRAM authentication and authorization for the Apicurio Registry user. You can specify a user name in the metadata section or use the default my-user.

   Copy to Clipboard Toggle word wrap

   apiVersion: kafka.strimzi.io/v1beta1
   kind: KafkaUser
   metadata:
     name: my-user
     labels:
       strimzi.io/cluster: my-cluster
     namespace: registry-example-kafkasql-scram
   spec:
     authentication:
       type: scram-sha-512
     authorization:
       acls:
         - operation: All
           resource:
             name: '*'
             patternType: literal
             type: topic
         - operation: All
           resource:
             name: '*'
             patternType: literal
             type: cluster
         - operation: All
           resource:
             name: '*'
             patternType: literal
             type: transactionalId
         - operation: All
           resource:
             name: '*'
             patternType: literal
             type: group
       type: simple

   Note

   This simple example assumes admin permissions and creates the Kafka topic automatically. You must configure the authorization section specifically for the topics and resources that the Apicurio Registry requires.

   The following example shows the minimum configuration required when the Kafka topic is created manually:

   Copy to Clipboard Toggle word wrap

    ...
     authorization:
       acls:
       - operations:
           - Read
           - Write
         resource:
           name: kafkasql-journal
           patternType: literal
           type: topic
       - operations:
           - Read
           - Write
         resource:
           name: apicurio-registry-
           patternType: prefix
           type: group
       type: simple

6. Click Workloads and then Secrets to find two secrets that AMQ Streams creates for Apicurio Registry to connect to the Kafka cluster:

   • my-cluster-cluster-ca-cert - contains the PKCS12 truststore for the Kafka cluster

   • my-user - contains the user’s keystore

     Note

     The name of the secret can vary based on your cluster or user name.

7. If you create the secrets manually, they must contain the following key-value pairs:

   • my-cluster-ca-cert

     • ca.p12 - the truststore in PKCS12 format
     • ca.password - truststore password

   • my-user

     • password - user password

8. Configure the following example settings to deploy the Apicurio Registry:

   Copy to Clipboard Toggle word wrap

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry-kafkasql-scram
   spec:
     configuration:
       persistence: "kafkasql"
       kafkasql:
         bootstrapServers: "my-cluster-kafka-bootstrap.registry-example-kafkasql-scram.svc:9093"
         security:
           scram:
             truststoreSecretName: my-cluster-cluster-ca-cert
             user: my-user
             passwordSecretName: my-user

Procedure

1. In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.
2. Change to the OpenShift project in which you want to install the PostgreSQL Operator. For example, from the Project drop-down, select my-project.
3. In the left navigation menu, click Operators and then OperatorHub.
4. In the Filter by keyword text box, enter PostgreSQL to find an Operator suitable for your environment, for example, Crunchy PostgreSQL for OpenShift.
5. Read the information about the Operator, and click Install to display the Operator subscription page.

6. Select your subscription settings, for example:

   • Update Channel: stable
   • Installation Mode: A specific namespace on the cluster and then my-project
   • Approval Strategy: Select Automatic or Manual

7. Click Install, and wait a few moments until the Operator is ready for use.

   Important

   You must read the documentation from your chosen PostgreSQL Operator for details on how to create and manage your database.

Procedure

1. In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.
2. Change to the OpenShift project in which Apicurio Registry and your PostgreSQL Operator are installed. For example, from the Project drop-down, select my-project.
3. Create a PostgreSQL database for your Apicurio Registry storage. For example, click Installed Operators, PostgreSQL Operator by Dev4Ddevs.com, and then Create database.

4. Click YAML and edit the database settings as follows:

   • name: Change the value to registry
   • image: Change the value to centos/postgresql-12-centos7

5. Edit any other database settings as needed depending on your environment, for example:

   Copy to Clipboard Toggle word wrap

   apiVersion: postgresql.dev4devs.com/v1alpha1
   kind: Database
   metadata:
     name: registry
     namespace: my-project
   spec:
     databaseCpu: 30m
     databaseCpuLimit: 60m
     databaseMemoryLimit: 512Mi
     databaseMemoryRequest: 128Mi
     databaseName: example
     databaseNameKeyEnvVar: POSTGRESQL_DATABASE
     databasePassword: postgres
     databasePasswordKeyEnvVar: POSTGRESQL_PASSWORD
     databaseStorageRequest: 1Gi
     databaseUser: postgres
     databaseUserKeyEnvVar: POSTGRESQL_USER
     image: centos/postgresql-12-centos7
     size: 1

6. Click Create, and wait until the database is created.
7. Click Installed Operators > Red Hat Integration - Service Registry > ApicurioRegistry > Create ApicurioRegistry.

8. Paste in the following custom resource definition, and edit the values for the database url and credentials to match your environment:

   Copy to Clipboard Toggle word wrap

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry-sql
   spec:
     configuration:
       persistence: 'sql'
       sql:
         dataSource:
           url: 'jdbc:postgresql://<service name>.<namespace>.svc:5432/<database name>'
           # e.g. url: 'jdbc:postgresql://acid-minimal-cluster.my-project.svc:5432/registry'
           userName: 'postgres'
           password: '<password>' # Optional

9. Click Create and wait for the Apicurio Registry route to be created on OpenShift.

10. Click Networking > Route to access the new route for the Apicurio Registry web console. For example:

    Copy to Clipboard Toggle word wrap

    http://example-apicurioregistry-sql.my-project.my-domain-name.com/

Procedure

1. Enter the following command to create the database:

   Copy to Clipboard Toggle word wrap

    $ createdb -T template0 dbname

2. Enter the following command to restore the SQL dump

   Copy to Clipboard Toggle word wrap

    $ psql dbname < dumpfile

3. Run ANALYZE on each database so the query optimizer has useful statistics.

Procedure

1. In the OpenShift web console, click Installed Operators and Red Hat Single Sign-On Operator, and then the Keycloak tab.

2. Click Create Keycloak to provision a new Red Hat Single Sign-On instance for securing a Apicurio Registry deployment. You can use the default value, for example:

   Copy to Clipboard Toggle word wrap

   apiVersion: keycloak.org/v1alpha1
   kind: Keycloak
   metadata:
     name: example-keycloak
     labels:
       app: sso
   spec:
     instances: 1
     externalAccess:
       enabled: True
     podDisruptionBudget:
       enabled: True

3. Wait until the instance has been created, and click Networking and then Routes to access the new route for the keycloak instance.
4. Click the Location URL and copy the displayed URL value for later use when deploying Apicurio Registry.

5. Click Installed Operators and Red Hat Single Sign-On Operator, and click the Keycloak Realm tab, and then Create Keycloak Realm to create a registry example realm:

   Copy to Clipboard Toggle word wrap

   apiVersion: keycloak.org/v1alpha1
   kind: KeycloakRealm
   metadata:
     name: registry-keycloakrealm
     labels:
       app: sso
   spec:
     instanceSelector:
       matchLabels:
         app: sso
     realm:
       displayName: Registry
       enabled: true
       id: registry
       realm: registry
       sslRequired: none
       roles:
         realm:
           - name: sr-admin
           - name: sr-developer
           - name: sr-readonly
       clients:
         - clientId: registry-client-ui
           implicitFlowEnabled: true
           redirectUris:
             - '*'
           standardFlowEnabled: true
           webOrigins:
             - '*'
           publicClient: true
         - clientId: registry-client-api
           implicitFlowEnabled: true
           redirectUris:
             - '*'
           standardFlowEnabled: true
           webOrigins:
             - '*'
           publicClient: true
       users:
         - credentials:
             - temporary: false
               type: password
               value: changeme
           enabled: true
           realmRoles:
             - sr-admin
           username: registry-admin
         - credentials:
             - temporary: false
               type: password
               value: changeme
           enabled: true
           realmRoles:
             - sr-developer
           username: registry-developer
         - credentials:
             - temporary: false
               type: password
               value: changeme
           enabled: true
           realmRoles:
             - sr-readonly
           username: registry-user

   Important

   You must customize this KeycloakRealm resource with values suitable for your environment if you are deploying to production. You can also create and manage realms using the Red Hat Single Sign-On web console.

6. If your cluster does not have a valid HTTPS certificate configured, you can create the following HTTP Service and Ingress resources as a temporary workaround:

   1. Click Networking and then Services, and click Create Service using the following example:

      Copy to Clipboard Toggle word wrap

      apiVersion: v1
      kind: Service
      metadata:
        name: keycloak-http
        labels:
          app: keycloak
      spec:
        ports:
          - name: keycloak-http
            protocol: TCP
            port: 8080
            targetPort: 8080
        selector:
          app: keycloak
          component: keycloak
        type: ClusterIP
        sessionAffinity: None
      status:
        loadBalancer: {}

   2. Click Networking and then Ingresses, and click Create Ingress using the following example::

      Copy to Clipboard Toggle word wrap

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: keycloak-http
        labels:
          app: keycloak
      spec:
        rules:
          - host: KEYCLOAK_HTTP_HOST
            http:
              paths:
                - path: /
                  pathType: ImplementationSpecific
                  backend:
                    service:
                      name: keycloak-http
                      port:
                        number: 8080

      Modify the host value to create a route accessible for the Apicurio Registry user, and use it instead of the HTTPS route created by Red Hat Single Sign-On Operator.

7. Click the Apicurio Registry Operator, and on the ApicurioRegistry tab, click Create ApicurioRegistry, using the following example, but replace your values in the keycloak section.

   Copy to Clipboard Toggle word wrap

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry-kafkasql-keycloak
   spec:
     configuration:
       security:
         keycloak:
           url: "http://keycloak-http-<namespace>.apps.<cluster host>"
           # ^ Required
           # Use an HTTP URL in development.
           realm: "registry"
           # apiClientId: "registry-client-api"
           # ^ Optional (default value)
           # uiClientId: "registry-client-ui"
           # ^ Optional (default value)
       persistence: 'kafkasql'
       kafkasql:
         bootstrapServers: '<my-cluster>-kafka-bootstrap.<my-namespace>.svc:9092'

Procedure

1. In the Red Hat Single Sign-On Admin Console, create a Red Hat Single Sign-On realm for Apicurio Registry. By default, Apicurio Registry expects a realm name of registry. For details on creating realms, see the the Red Hat Single Sign-On user documentation.

2. Create a Red Hat Single Sign-On client for the Apicurio Registry API. By default, Apicurio Registry expects the following settings:

   • Client ID: registry-api
   • Client Protocol: openid-connect

   • Access Type: bearer-only

     You can use the defaults for the other client settings.

     Note

     If you are using Red Hat Single Sign-On service accounts, the client Access Type must be confidential instead of bearer-only.

3. Create a Red Hat Single Sign-On client for the Apicurio Registry web console. By default, Apicurio Registry expects the following settings:

   • Client ID: apicurio-registry
   • Client Protocol: openid-connect
   • Access Type: public
   • Valid Redirect URLs: http://my-registry-url:8080/*

   • Web Origins: +

     You can use the defaults for the other client settings.

4. In your Apicurio Registry deployment on OpenShift, set the following Apicurio Registry environment variables to configure authentication using Red Hat Single Sign-On:

   Table 5.2. Configuration for Apicurio Registry authentication with Red Hat Single Sign-On

   Environment variable	Description	Type	Default
   AUTH_ENABLED	Enables authentication for Apicurio Registry. When set to true, the environment variables that follow are required for authentication using Red Hat Single Sign-On.	String	false
   KEYCLOAK_URL	The URL of the Red Hat Single Sign-On authentication server. For example, http://localhost:8080.	String	-
   KEYCLOAK_REALM	The Red Hat Single Sign-On realm for authentication. For example, registry.	String	-
   KEYCLOAK_API_CLIENT_ID	The client ID for the Apicurio Registry REST API.	String	registry-api
   KEYCLOAK_UI_CLIENT_ID	The client ID for the Apicurio Registry web console.	String	apicurio-registry

   Tip

   For an example of setting environment variables on OpenShift, see Section 6.1, “Configuring Apicurio Registry health checks on OpenShift”.

5. Set the following option to true to enable Apicurio Registry user roles in Red Hat Single Sign-On:

   Table 5.3. Configuration for Apicurio Registry role-based authorization

   Environment variable	Java system property	Type	Default value
   ROLE_BASED_AUTHZ_ENABLED	registry.auth.role-based-authorization	Boolean	false

6. When Apicurio Registry user roles are enabled, you must assign Apicurio Registry users to at least one of the following default user roles in your Red Hat Single Sign-On realm:

   Table 5.4. Default user roles for registry authentication and authorization

   Role	Read artifacts	Write artifacts	Global rules	Summary
   sr-admin	Yes	Yes	Yes	Full access to all create, read, update, and delete operations.
   sr-developer	Yes	Yes	No	Access to create, read, update, and delete operations, except configuring global rules. This role can configure artifact-specific rules.
   sr-readonly	Yes	No	No	Access to read and search operations only. This role cannot configure any rules.

7. Set the following to true to enable owner-only authorization for updates to schema and API artifacts in Apicurio Registry:

   Table 5.5. Configuration for owner-only authorization

   Environment variable	Java system property	Type	Default value
   REGISTRY_AUTH_OBAC_ENABLED	registry.auth.owner-only-authorization	Boolean	false

Procedure

1. Log in to the Azure AD portal using your email address or GitHub account.

2. In the navigation menu, select Manage > App registrations > New registration, and complete the following settings:

   • Name: Enter your application name. For example: apicurio-registry-example
   • Supported account types: Click Accounts in any organizational directory.

   • Redirect URI: Select Single-page application from the list, and enter your Apicurio Registry web console application host. For example: https://test-registry.com/ui/

     Important

     You must register your Apicurio Registry application host as a Redirect URI. When logging in, users are redirected from Apicurio Registry to Azure AD for authentication, and you want to send them back to your application afterwards. Azure AD does not allow any redirect URLs that are not registered.

3. Click Register. You can view your app registration details by selecting Manage > App registrations > apicurio-registry-example.

4. Select Manage > Authentication and ensure that the application is configured with your redirect URLs and tokens as follows:

   • Redirect URIs: For example: https://test-registry.com/ui/
   • Implicit grant and hybrid flows: Click ID tokens (used for implicit and hybrid flows)
5. Select Azure AD > Admin > App registrations > Your app > Application (client) ID. For example: 123456a7-b8c9-012d-e3f4-5fg67h8i901
6. Select Azure AD > Admin > App registrations > Your app > Directory (tenant) ID. For example: https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0

7. In Apicurio Registry, configure the following environment variables with your Azure AD settings:

   Table 5.6. Configuration for Azure AD settings in Apicurio Registry

   Environment variable	Description	Setting
   KEYCLOAK_API_CLIENT_ID	The client application ID for the Apicurio Registry REST API	Your Azure AD Application (client) ID obtained in step 5. For example: 123456a7-b8c9-012d-e3f4-5fg67h8i901
   REGISTRY_OIDC_UI_CLIENT_ID	The client application ID for the Apicurio Registry web console.	Your Azure AD Application (client) ID obtained in step 5. For example: 123456a7-b8c9-012d-e3f4-5fg67h8i901
   REGISTRY_AUTH_URL_CONFIGURED	The URL for authentication in Azure AD.	Your Azure AD Application (tenant) ID obtained in step 6. For example: https://login.microsoftonline.com/1a2bc34d-567e-89f1-g0hi-1j2kl3m4no56/v2.0.

8. In Apicurio Registry, configure the following environment variables for Apicurio Registry-specific settings:

   Table 5.7. Configuration for Apicurio Registry-specific settings

   Environment variable	Description	Setting
   REGISTRY_AUTH_ENABLED	Enables authentication for Apicurio Registry.	true
   REGISTRY_UI_AUTH_TYPE	The Apicurio Registry authentication type.	oidc
   CORS_ALLOWED_ORIGINS	The host for your Apicurio Registry deployment for cross-origin resource sharing (CORS).	For example: https://test-registry.com
   REGISTRY_OIDC_UI_REDIRECT_URL	The host for your Apicurio Registry web console.	For example: https://test-registry.com/ui
   ROLE_BASED_AUTHZ_ENABLED	Enables role-based authorization in Apicurio Registry.	true
   QUARKUS_OIDC_ROLES_ROLE_CLAIM_PATH	The name of the claim in which Azure AD stores roles.	roles

   Note

   When you enable roles in Apicurio Registry, you must also create the same roles in Azure AD as application roles. The default roles expected by Apicurio Registry are sr-admin, sr-developer, and sr-readonly.

Procedure

1. Generate a keystore with a self-signed certificate. You can skip this step if you are using your own certificates.

   Copy to Clipboard Toggle word wrap

   openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout tls.key -out tls.crt

2. Create a new secret to hold the certificate and the private key.

   1. In the left navigation menu of the OpenShift web console, click Workloads > Secrets > Create Key/Value Secret.
   2. Use the following values:
      Name: https-cert-secret
      Key 1: tls.key
      Value 1: tls.key (uploaded file)
      Key 2: tls.crt
      Value 2: tls.crt (uploaded file)

   or create the secret using the following command:

   Copy to Clipboard Toggle word wrap

   oc create secret generic https-cert-secret --from-file=tls.key --from-file=tls.crt

3. Edit the spec.configuration.security.https section of the ApicurioRegistry CR for your Apicurio Registry deployment, for example:

   Copy to Clipboard Toggle word wrap

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry
   spec:
     configuration:
       # ...
       security:
         https:
           secretName: https-cert-secret

4. Verify that the connection is working:

   1. Connect into a pod on the cluster using SSH (you can use the Apicurio Registry pod):

      Copy to Clipboard Toggle word wrap

      oc rsh example-apicurioregistry-deployment-6f788db977-2wzpw

   2. Find the cluster IP of the Apicurio Registry pod from the Service resource (see the Location column in the web console). Afterwards, execute a test request (we are using self-signed certificate, so an insecure flag is required):

      Copy to Clipboard Toggle word wrap

      curl -k https://172.30.230.78:8443/health

Procedure

1. Add a second Route in addition to the HTTP route created by the Apicurio Registry Operator. For example:

   Copy to Clipboard Toggle word wrap

   kind: Route
   apiVersion: route.openshift.io/v1
   metadata:
     [...]
     labels:
       app: example-apicurioregistry
       [...]
   spec:
     host: example-apicurioregistry-default.apps.example.com
     to:
       kind: Service
       name: example-apicurioregistry-service-9whd7
       weight: 100
     port:
       targetPort: 8080
     tls:
       termination: edge
       insecureEdgeTerminationPolicy: Redirect
     wildcardPolicy: None

   Note

   Make sure the insecureEdgeTerminationPolicy: Redirect configuration property is set.

   If you do not specify a certificate, OpenShift will use a default. Alternatively, you can generate a custom self-signed certificate using the following commands:

   Copy to Clipboard Toggle word wrap

   openssl genrsa 2048 > tls.key &&
   openssl req -new -x509 -nodes -sha256 -days 365 -key tls.key -out tls.crt

   Then create a route using the OpenShift CLI:

   Copy to Clipboard Toggle word wrap

   oc create route edge \
     --service=example-apicurioregistry-service-9whd7 \
     --cert=tls.crt --key=tls.key \
     --hostname=example-apicurioregistry-default.apps.example.com \
     --insecure-policy=Redirect \
     -n default

Procedure

1. In the OpenShift Container Platform web console, log in using an account with cluster administrator privileges.
2. Click Installed Operators > Red Hat Integration - Service Registry Operator.
3. On the ApicurioRegistry tab, click the Operator custom resource for your deployment, for example, example-apicurioregistry.
4. In the main overview page, find the Deployment Name section and the corresponding DeploymentConfig name for your Apicurio Registry deployment, for example, example-apicurioregistry.
5. In the left navigation menu, click Workloads > Deployment Configs, and select your DeploymentConfig name.

6. Click the Environment tab, and enter your environment variables in the Single values env section, for example:

   • NAME: LIVENESS_STATUS_RESET
   • VALUE: 350

7. Click Save at the bottom.

   Alternatively, you can perform these steps using the OpenShift oc command. For more details, see the OpenShift CLI documentation.

Procedure

1. Use this curl command to obtain the current log level for the logger io.apicurio.registry.storage:

   Copy to Clipboard Toggle word wrap

   $ curl -i localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage
   HTTP/1.1 200 OK
   [...]
   Content-Type: application/json
   {"name":"io.apicurio.registry.storage","level":"INFO"}

2. Use this curl command to change the log level for the logger io.apicurio.registry.storage to DEBUG:

   Copy to Clipboard Toggle word wrap

   $ curl -X PUT -i -H "Content-Type: application/json" --data '{"level":"DEBUG"}' localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage
   HTTP/1.1 200 OK
   [...]
   Content-Type: application/json
   {"name":"io.apicurio.registry.storage","level":"DEBUG"}

3. Use this curl command to revert the log level for the logger io.apicurio.registry.storage to its default value:

   Copy to Clipboard Toggle word wrap

   $ curl -X DELETE -i localhost:8080/apis/registry/v2/admin/loggers/io.apicurio.registry.storage
   HTTP/1.1 200 OK
   [...]
   Content-Type: application/json
   {"name":"io.apicurio.registry.storage","level":"INFO"}

Procedure

1. When using the HTTP protocol, set your Apicurio Registry configuration to send events to a your application as follows:

   • registry.events.sink.my-custom-consumer=http://my-app-host:8888/events

2. If required, you can configure multiple event consumers as follows:

   • registry.events.sink.my-custom-consumer=http://my-app-host:8888/events
   • registry.events.sink.other-consumer=http://my-consumer.com/events

Procedure

1. When using the Kafka protocol, set your Kafka topic as follows:

   • registry.events.kafka.topic=my-registry-events

2. You can set the configuration for the Kafka producer by using the KAFKA_BOOTSTRAP_SERVERS environment variable:

   • KAFKA_BOOTSTRAP_SERVERS=my-kafka-host:9092

     Alternatively, you can set the properties for the kafka producer by using the registry.events.kafka.config prefix, for example: registry.events.kafka.config.bootstrap.servers=my-kafka-host:9092

3. If required, you can also set the Kafka topic partition to use to produce events:

   • registry.events.kafka.topic-partition=1