Log in to the CLI.

$ rhoas login

The login command opens a sign-in process in your web browser.

Use the CLI to create a new service context.

$ rhoas context create --name development-context

The new context becomes the current (that is, active) context by default.

Create a new Kafka instance in Red Hat OpenShift Streams for Apache Kafka.

$ rhoas kafka create --name my-kafka-instance

The CLI automatically adds the Kafka instance to the current context.

Create a new Service Registry instance in Red Hat OpenShift Service Registry.

$ rhoas service-registry create --name my-registry-instance

The CLI also automatically adds the Service Registry instance to the current context.

Confirm that the Kafka and Service Registry instances are in the current context and are running.

$ rhoas context status

You see output that looks like the following example:

Service Context Name:	development-context
Context File Location:	/home/<user-name>/.config/rhoas/contexts.json

Kafka
-----------------------------------------------------------------------------
ID:                cafkr2jma40lhulbl1c0
Name:              my-kafka-instance
Status:            ready
Bootstrap URL:     kafka-inst-cafkr-jma--lhulbl-ca.bf2.kafka.rhcloud.com:443

Service Registry
------------------------------------------------------------------------------
ID:                0aa1dd8b-63d5-466c-9de8-7c03320a81c2
Name:              my-registry-instance
Status:            ready
Registry URL:      https://bu98.serviceregistry.rhcloud.com/t/0aa1dd8b-63d5-466c-9de8-7c03320a81c2

Create another service context.

$ rhoas context create --name production-context

The new service context becomes the current context.

Add the Kafka instance that you created earlier in the procedure to the new service context.

$ rhoas context set-kafka --name my-kafka-instance

The Kafka instance is now part of both of the service contexts that you created.

On the command line, clone the Red Hat OpenShift Application Services Guides and Samples repository from GitHub.

$ git clone https://github.com/redhat-developer/app-services-guides app-services-guides

In your IDE, open the code-examples/quarkus-service-registry-quickstart directory from the repository that you cloned.

You see that the sample Quarkus application has two components - a producer component and a consumer component. The producer component publishes a stream of quote values to a Kafka topic. The consumer component consumes these values and displays them on a web page.

On the command line, create the quotes topic required by the Quarkus application.

$ rhoas kafka topic create --name quotes

Ensure that you are using the service context that includes your Kafka and Service Registry instances, as shown in the following example:

$ rhoas context use --name development-context

In the guides and samples repository that you cloned, navigate to the directory for the Quarkus application.

$ cd ~/app-services-guides/code-examples/quarkus-service-registry-quickstart/

Create a service account for the Quarkus application to authenticate with the Kafka and Service Registry instances in the context. Save the credentials in an environment variables file in the directory for the producer component.

$ rhoas service-account create --file-format env --output-file ./producer/.env

Generate an environment variables file that contains the connection configuration information required by the producer component.

$ rhoas generate-config --type env --output-file ./producer/rhoas.env

Append the contents of the connection configuration file to the service account environment variables file.

$ cat ./producer/rhoas.env >> ./producer/.env

Copy the updated .env file to the directory for the consumer component, as shown in the following Linux example:

$ cp ./producer/.env ./consumer/.env

For a service context with single Kafka and Service Registry instances, the .env file looks like the following example:

## Generated by rhoas cli
RHOAS_SERVICE_ACCOUNT_CLIENT_ID=<client-id>
RHOAS_SERVICE_ACCOUNT_CLIENT_SECRET=<client-secret>
RHOAS_SERVICE_ACCOUNT_OAUTH_TOKEN_URL=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
## Generated by rhoas cli
## Kafka Configuration
KAFKA_HOST=kafka-inst-cafkr-jma--lhulbl-ca.bf2.kafka.rhcloud.com:443
## Service Registry Configuration
SERVICE_REGISTRY_URL=https://bu98.serviceregistry.rhcloud.com/t/0aa1dd8b-63d5-466c-9de8-7c03320a81c2
SERVICE_REGISTRY_CORE_PATH=/apis/registry/v2
SERVICE_REGISTRY_COMPAT_PATH=/apis/ccompat/v6

As shown in the example, the file that you generate contains the endpoints for your service instances, and the credentials required to connect to those instances.

Set Access Control List (ACL) permissions to enable the new service account to access resources in the Kafka instance.

$ rhoas kafka acl grant-access --producer --consumer --service-account <client-id> --topic quotes --group all

The command you entered allows applications to use the service account to produce and consume messages in the quotes topic. Applications can use any consumer group.

Use Role-Based Access Control (RBAC) to enable the new service account to access the Service Registry instance and the artifacts (such as schemas) that it contains.

$ rhoas service-registry role add --role manager --service-account <client-id>

In the guides and samples repository, navigate to the directory for the producer component. Use Apache Maven to run the producer component in developer mode.

$ cd ~/app-services-guides/code-examples/quarkus-service-registry-quickstart/producer
$ mvn quarkus:dev

The producer component starts to generate quote values to the quotes topic in the Kafka instance.

The Quarkus application also created an Avro schema called quotes-value in the Service Registry instance. The producer and consumer components use the schema to ensure that message values conform to a defined format.

To view the contents of the quotes-value schema, run the following command:

$ rhoas service-registry artifact get --artifact-id quotes-value

You see output that looks like the following example:

{
  "type": "record",
  "name": "Quote",
  "namespace": "org.acme.kafka.quarkus",
  "fields": [
    {
      "name": "id",
      "type": {
        "type": "string",
        "avro.java.string": "String"
      }
    },
    {
      "name": "price",
      "type": "int"
    }
  ]
}

With the producer component still running, open a second command-line window or tab. In the guides and samples repository, navigate to the directory for the consumer component and run the component in developer mode.

$ cd ~/app-services-guides/code-examples/quarkus-service-registry-quickstart/consumer
$ mvn quarkus:dev

The consumer component starts to consume the stream of quote values from the quotes topic.

In a web browser, go to http://localhost:8080/quotes.html.

You see that the consumer component displays the stream of quote values on the web page. This output shows that the Quarkus application used the connection configuration information that you generated to connect to the Kafka and Service Registry instances in your service context.

On the command line, clone the Red Hat OpenShift Application Services Guides and Samples repository in GitHub.

git clone https://github.com/redhat-developer/app-services-guides app-services-guides

Log in to the rhoas CLI.

$ rhoas login

The login command opens a sign-in process in your web browser.

Check the service context that is currently in use.

$ rhoas context list

The CLI shows a check mark next to the service context that is currently in use.

(Optional) To switch to a different service context that includes your Kafka instance, use the following command. Replace <service-context> with your service context name.

$ rhoas context use --name <service-context>

Generate connection configuration information for the service context as an OpenShift ConfigMap and save this in a YAML file, as shown in the following example:

$ rhoas generate-config --type configmap --output-file ./rhoas-services.yaml

For a service context with a single Kafka instance, the contents of the ConfigMap file look like the following example:

apiVersion: v1
kind: ConfigMap
metadata:
    name: <service-context>-configuration
data:
    ## Kafka Configuration
    kafka_host: <host>:<port>

As indicated in the example, the name of the generated ConfigMap object has a format of <service-context>-configuration.

On the command line, create the prices topic required by the Quarkus application.

$ rhoas kafka topic create --name prices

Create a service account for the Quarkus application to authenticate with your Kafka instance by performing the following actions.

1. Create a new service account as an OpenShift secret and save this in a YAML file, as shown in the following example:

   $ rhoas service-account create --file-format secret --output-file ./rhoas-secrets.yaml

2. Open the YAML file for the secret in your IDE.

   The contents of the file look like the following example:

   Example secret file for service account credentials

   apiVersion: v1
   kind: Secret
   metadata:
     name: service-account-credentials
   type: Opaque
   stringData:
     RHOAS_SERVICE_ACCOUNT_CLIENT_ID: <client-id>
     RHOAS_SERVICE_ACCOUNT_CLIENT_SECRET: <client-secret>
     RHOAS_SERVICE_ACCOUNT_OAUTH_TOKEN_URL: <oauth-token-endpoint-uri>

   As indicated in the example, the generated secret has a default name of service-account-credentials.

3. Set Access Control List (ACL) permissions to enable the new service account to access resources in the Kafka instance.

   Example command for granting access to Kafka instance

   $ rhoas kafka acl grant-access --producer --consumer --service-account <client-id> --topic prices --group all

   The command you entered allows applications to use the service account to produce and consume messages in the prices topic. Applications can use any consumer group.

Log in to the OpenShift CLI using a token by performing the following actions.

1. Log in to the OpenShift web console as a user who has privileges to create a new project in the cluster.

2. In the upper-right corner of the console, click your user name and select Copy login command.

   A new page opens.

3. Click the Display Token link.

4. In the Log in with this token section, copy the full oc login command shown.

5. On the command line, right-click and select Paste.

   You see output confirming that you are logged in to your OpenShift cluster and the current project that you are using. By default, this is the project in which you will deploy the Quarkus application.

6. (Optional) To change to another, existing project, use the following command:

   $ oc project <project>

7. (Optional) To create a new project in which to deploy the Quarkus application, use the following command:

   $ oc new-project <project>

Use the OpenShift CLI to apply the ConfigMap and secret files to the current project in your OpenShift cluster.

$ oc apply -f ./rhoas-services.yaml
$ oc apply -f ./rhoas-secrets.yaml

When you apply the YAML files, the OpenShift CLI shows the names of the ConfigMap and Secret objects that it creates in your OpenShift project, as shown in the following example output:

configmap/my-service-context-configuration created
secret/service-account-credentials created

In your IDE, open the deployment.yaml file in the code-examples/helm-kafka-example/templates directory of the repository that you cloned.

The deployment.yaml file is a template file that is part of the Helm chart for the example Quarkus application. The template defines environment variables for the connection information required to connect to your Kafka instance. The environment variables (KAFKA_HOST,RHOAS_SERVICE_ACCOUNT_OAUTH_TOKEN_URL, RHOAS_SERVICE_ACCOUNT_CLIENT_ID, and RHOAS_SERVICE_ACCOUNT_CLIENT_SECRET) are shown in the following sample from the template file:

spec:
  containers:
    - env:
        - name: KAFKA_HOST
          valueFrom:
            configMapKeyRef:
              name: {{ .Values.rhoas.config }}
              key: kafka_host
        - name: RHOAS_SERVICE_ACCOUNT_OAUTH_TOKEN_URL
          valueFrom:
            secretKeyRef:
              name:  {{ .Values.rhoas.secret }}
              key: RHOAS_SERVICE_ACCOUNT_OAUTH_TOKEN_URL
        - name: RHOAS_SERVICE_ACCOUNT_CLIENT_ID
          valueFrom:
            secretKeyRef:
              name:  {{ .Values.rhoas.secret }}
              key: RHOAS_SERVICE_ACCOUNT_CLIENT_ID
        - name: RHOAS_SERVICE_ACCOUNT_CLIENT_SECRET
          valueFrom:
            secretKeyRef:
              name:  {{ .Values.rhoas.secret }}
              key: RHOAS_SERVICE_ACCOUNT_CLIENT_SECRET

The template uses parameters called rhoas.config and rhoas.secret to reference the names of your ConfigMap and Secret objects. You specify the names of your ConfigMap and Secret objects as values for these parameters in a later step, when you install the Helm chart. Also, as you saw previously, the ConfigMap and Secret objects that you created contain parameters that correspond directly to the key values defined in the template.

On the command line, navigate to the code-examples/helm-kafka-example directory of the repository that you cloned.

$ cd app-services-guides/code-examples/helm-kafka-example

Deploy the Helm chart, specifying the names of the ConfigMap and Secret objects that you created in your OpenShift project.

$ helm install . --generate-name --set-string rhoas.config=<configmap>,rhoas.secret=service-account-credentials

You use the --set-string option to specify the names of the ConfigMap and Secret objects directly in the helm install command. You pass these values to the rhoas.config and rhoas.secret parameters that are defined in the template for the Helm chart.

When you install the Helm chart, Helm automatically processes the contents of the chart /templates directory. Helm uses the templates to generate manifests for deployment of the application and creation of a service for the application. Helm provides these manifests to OpenShift.

When the Helm chart is installed, get the service endpoint for the application on OpenShift.

$ oc get service

You see output like the following example:

NAME                                TYPE           CLUSTER-IP       EXTERNAL-IP                                                               PORT(S)          AGE
rhoas-quarkus-kafka-quickstart      LoadBalancer   172.30.128.12    a81b115a35629488685b6ed3cf322fbf-1904626303.us-east-2.elb.amazonaws.com   8080:31110/TCP   11m

The output indicates that the Quarkus application is successfully running on your OpenShift cluster.

On the command line, copy the value shown under EXTERNAL-IP.

In a web browser, go to <external-ip-value>:8080/prices.html.

You see that the web page continuously updates the Last price value. The continuously updating output shows that the Quarkus application is using the connection configuration information that you generated to connect to the Kafka instance defined in your service context. The application uses the prices topic that you created to produce and consume messages.