Procedure

1. Create a project for the installation, for example, service-registry:

   NAMESPACE="service-registry"
   oc new-project "$NAMESPACE"

2. Apply the file located in the install/ folder:

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

Procedure

1. Create an ApicurioRegistry custom resource (CR), with your database connection configured, for example:

   Example CR for SQL storage

   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. Create the ApicurioRegistry CR in the same namespace that the Operator is deployed

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

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.0.x: Includes patch updates only, such as 2.0.1 and 2.0.2. For example, an installation on 2.0.x automatically ignores 2.1.x.
     • 2.x: Includes all minor and patch updates, such as 2.1.0 and 2.0.1. For example, an installation on 2.0.x automatically upgrades to 2.1.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-1.7.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 Using 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 Service Registry. For example:

   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:

   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 Service Registry route to be created on OpenShift.

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

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

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 Service Registry storage.

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

   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 that Service Registry uses to store data is kafkasql-journal. This topic is created automatically by Service Registry. You can override this behavior or the default topic name by setting the appropriate environment variables (default values):

   • 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:

   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:
       retention.ms: 604800000
       segment.bytes: 1073741824

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

   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

   You must configure the authorization specifically for the topics and resources that the Service Registry requires. This is a simple permissive example.

6. Click Workloads and then Secrets to find two secrets that AMQ Streams creates for Service 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 Service Registry.

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry-kafkasql
   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 Service Registry storage.

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

   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 that Service Registry uses to store data is kafkasql-journal. This topic is created automatically by Service Registry. You can override this behavior or the default topic name by setting the appropriate environment variables (default values):

   • 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:

   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:
       retention.ms: 604800000
       segment.bytes: 1073741824

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

   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

   You must configure the authorization specifically for the topics and resources that the Service Registry requires. This is a simple permissive example.

6. Click Workloads and then Secrets to find two secrets that AMQ Streams creates for Service 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 Service Registry:

   apiVersion: registry.apicur.io/v1
   kind: ApicurioRegistry
   metadata:
     name: example-apicurioregistry-kafkasql
   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 or PostgreSQL Operator by Dev4Ddevs.com.
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 Service Registry and your PostgreSQL Operator are installed. For example, from the Project drop-down, select my-project.
3. Create a PostgreSQL database for your Service 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:

   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:

   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 Service Registry route to be created on OpenShift.

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

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

Procedure

1. Enter the following command to create the database:

    $ createdb -T template0 dbname

2. Enter the following command to restore the SQL dump

    $ 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 Service Registry deployment. You can use the default value, for example:

   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 ../auth URL value for later use when deploying Service 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:

   apiVersion: keycloak.org/v1alpha1
   kind: KeycloakRealm
   metadata:
     name: registry-keycloakrealm
   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:

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

      apiVersion: networking.k8s.io/v1beta1
      kind: Ingress
      metadata:
        name: keycloak-http
        labels:
          app: keycloak
      spec:
        rules:
          - host: keycloak-http.local
            http:
              paths:
                - path: /
                  pathType: ImplementationSpecific
                  backend:
                    serviceName: keycloak-http
                    servicePort: 8080

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

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

   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>/auth"
           # ^ Required
           # Keycloak server URL, must end with `/auth`.
           # 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.<namespace>.svc:9092'

Procedure

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

   keytool -genkey -trustcacerts -keyalg RSA -keystore registry-keystore.jks -storepass password

2. Create a new secret to hold the keystore and keystore password.

   1. In the left navigation menu of the OpenShift web console, click Workloads > Secrets > Create Key/Value Secret.

   2. Use the following values:
      Name: registry-keystore
      Key 1: keystore.jks
      Value 1: registry-keystore.jks (uploaded file)
      Key 2: password
      Value 2: password

      Note

      If you encounter a java.io.IOException: Invalid keystore format, the upload of the binary file did not work properly. As an alternative, encode the file as a base64 string using cat registry-keystore.jks | base64 -w0 > data.txt and edit the Secret resource as yaml to manually add the encoded file.

3. Edit the Deployment resource of the Service Registry instance. You can find the correct name in a status field of the Service Registry Operator.

   1. Add the keystore secret as a volume:

      template:
        spec:
          volumes:
          - name: registry-keystore-secret-volume
            secret:
            secretName: registry-keystore

   2. Add a volume mount:

      volumeMounts:
        - name: registry-keystore-secret-volume
          mountPath: /etc/registry-keystore
          readOnly: true

   3. Add JAVA_OPTIONS and KEYSTORE_PASSWORD environment variables:

      - name: KEYSTORE_PASSWORD
        valueFrom:
          secretKeyRef:
            name: registry-keystore
            key: password
      - name: JAVA_OPTIONS
          value: >-
           -Dquarkus.http.ssl.certificate.key-store-file=/etc/registry-keystore/keystore.jks
           -Dquarkus.http.ssl.certificate.key-store-file-type=jks
           -Dquarkus.http.ssl.certificate.key-store-password=$(KEYSTORE_PASSWORD)

      Note

      Order is important when using string interpolation.

   4. Enable the HTTPS port:

      ports:
        - containerPort: 8080
          protocol: TCP
        - containerPort: 8443
          protocol: TCP

4. Edit the Service resource of the Service Registry instance. You can find the correct name in a status field of the Service Registry Operator.

   ports:
     - name: http
       protocol: TCP
       port: 8080
       targetPort: 8080
     - name: https
       protocol: TCP
       port: 8443
       targetPort: 8443

5. Verify that the connection is working:

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

      oc rsh -n default example-apicurioregistry-deployment-vx28s-4-lmtqb

   2. Find the cluster IP of the Service 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):

      curl -k https://172.30.209.198:8443/health
      [...]

Procedure

1. Add a second Route in addition to the HTTP route created by the Service Registry Operator. See the following example:

   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. You can alternatively generate a custom self-signed certificate using the following commands:

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

   and then create a route using the OpenShift CLI:

   oc create route edge \
     --service=example-apicurioregistry-service-9whd7 \
     --cert=host.cert --key=host.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.
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 Service 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.