Skip to content

Commit 3d573c8

Browse files
rkpattnaik780rkpattnaik780
authored
docs(rhoas cli): add getting started guide for context management (#504)
1 parent f2a8799 commit 3d573c8

File tree

1 file changed

+151
-0
lines changed

1 file changed

+151
-0
lines changed

‎docs/rhoas/rhoas-generate-config/README.adoc

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
//OpenShift Streams for Apache Kafka
2+
:base-url: https://github.com/redhat-developer/app-services-guides/tree/main/docs/
3+
:product-long-rhoas: OpenShift Application Services
4+
:rhoas-cli-base-url: https://github.com/redhat-developer/app-services-cli/tree/main/docs/
5+
:rhoas-cli-ref-url: commands
6+
:rhoas-cli-getting-started-url-generate-config: cli-generate-config/
7+
:samples-git-repo: https://github.com/redhat-developer/app-services-guides
8+
:product-kafka: Streams for Apache Kafka
9+
10+
[id="chap-generate-configurations-rhoas"]
11+
= Generating configurations for managed services using RHOAS CLI
12+
:context: getting-started-generate-configurations
13+
14+
[role="_abstract"]
15+
As a developer of applications and services, you can group service instances for specific use-cases, projects or environments and generate connection configuration details to connect applications to instances of managed services.
16+
17+
For example, suppose you have the following applications running locally in your machine:
18+
19+
* Application that publishes price updates for a variety of stocks
20+
* Application that consumes the price updates and publishes them on a web page
21+
22+
In addition to the applications, you have a Kafka instance in Streams for Apache Kafka. Each time the first application produces a price update, you want to use the Kafka instance to forward the update as an event to the second, consuming application.
23+
24+
You need to connect your applications to the Kafka Instance in OpenSift Streams for Apache Kafka.
25+
26+
In this scenario, you can use the RHOAS CLI to generate the connection configuration details required to connect to the Kafka instance.
27+
28+
== RHOAS Context
29+
30+
Service context is an abstraction for which configurations are generated. A service context contains references to service instances used for specific projects or environments. With the `generate-config` command you can generate connection configuration details for your applications to connect to the service instances specified in the context. This gives you the flexibility to quickly and seamlessly switch between sets of service instances and generate connection configurations.
31+
32+
This guide describes how to generate connection configurations to connect Quarkus application to Kafka Instance in OpenShift Streams for Apache Kafka:
33+
34+
* {base-url}{rhoas-cli-getting-started-url-generate-config}#proc-creating-context-cli_getting-started-generate-config[Create a service context]
35+
* {base-url}{rhoas-cli-getting-started-url-generate-config}#proc-creating-services-cli_getting-started-generate-config[Create services in service context]
36+
* {base-url}{rhoas-cli-getting-started-url-generate-config}#proc-generating-config-cli_getting-started-generate-config[Generating application configurations]
37+
38+
[id="ref-kafka-cli-prereqs_{context}"]
39+
== Prerequisites
40+
41+
[role="_abstract"]
42+
* You've installed the `rhoas` CLI. For more information, see {base-url}{rhoas-cli-installation-url}[_Installing the rhoas CLI_^].
43+
44+
[id="proc-creating-context-cli_{context}"]
45+
== Creating a service context
46+
47+
.Procedure
48+
49+
Enter the following command to create a context named `my-context`
50+
51+
.Creating a context
52+
[source,shell]
53+
----
54+
$ rhoas context create --name my-context
55+
----
56+
57+
[NOTE]
58+
====
59+
By default, the created context is set as the current context.
60+
All the service based commands are executed against the service instances set in the current context.
61+
====
62+
63+
[id="proc-creating-services-cli_{context}"]
64+
== Creating services in a context
65+
66+
.Procedure
67+
68+
. Creating a Kafka Instance
69+
+
70+
--
71+
[source,shell]
72+
----
73+
$ rhoas kafka create
74+
----
75+
[NOTE]
76+
====
77+
Creating a new service instance automatically sets it in the current context.
78+
====
79+
--
80+
. Check status of the current context
81+
+
82+
--
83+
After creating service(s) in the current context, their status can be checked using the `rhoas context status` command
84+
.View status of the current context
85+
[source,shell]
86+
----
87+
$ rhoas context status
88+
----
89+
--
90+
91+
[id="proc-generating-config-cli_{context}"]
92+
== Generating configurations for Quarkus applications
93+
94+
`rhoas generate-config` command generates application configurations that can be used to connect to the services set in context.
95+
The configurations can be saved in yaml, json, env file or as kubernetes secret. Connection configuration consists of credentials and endpoints that will be used by applications to connect to the services.
96+
97+
[role="_abstract"]
98+
For this quick start, you'll use the Quarkus sample code from the {product-kafka} {samples-git-repo}[Guides and Samples^] repository in GitHub.
99+
The quick start will walk you through how you can generate connection configurations for Quarkus applications using a single command.
100+
101+
.Procedure
102+
. On the command line, clone the {product-kafka} {samples-git-repo}[Guides and Samples^] repository from GitHub.
103+
+
104+
.Cloning the guides and samples repository
105+
[source,subs="+attributes"]
106+
----
107+
git clone {samples-git-repo} app-services-guides
108+
----
109+
. In your IDE, open the `code-examples/quarkus-kafka-quickstart` directory from the repository that you cloned.
110+
. Generate the application configurations for the Quarkus application.
111+
+
112+
--
113+
[source,shell]
114+
----
115+
$ rhoas generate-config --type env --output-file .env
116+
----
117+
--
118+
. Create the "prices" Kafka topic.
119+
+
120+
--
121+
[source,shell]
122+
----
123+
$ rhoas kafka topic create --name prices
124+
----
125+
--
126+
. Create ACLs for the service account created using the `rhoas generate-config` command.
127+
+
128+
--
129+
[source,shell]
130+
----
131+
$ rhoas kafka acl grant-access --producer --consumer --service-account <client_id> --topic prices --group all
132+
----
133+
--
134+
. Run the Quarkus application in dev mode.
135+
+
136+
--
137+
[source,shell]
138+
----
139+
./mvnw quarkus:dev
140+
----
141+
--
142+
143+
[role="_abstract"]
144+
The Quarkus application starts producing and consuming messages to and from the "prices" Kafka topic.
145+
After the application is running, in a web browser, go to http://localhost:8080/prices.html[^] and verify that the `Last price` is updated.
146+
147+
If the Quarkus application fails to run, review the error log in the terminal and address any problems. Also, review the steps to ensure that the Quarkus application and Kafka topic are configured correctly.
148+
149+
[role="_additional-resources"]
150+
.Additional resources
151+
* {rhoas-cli-base-url}{rhoas-cli-ref-url}[_CLI command reference (rhoas)_^]

0 commit comments

Comments
 (0)