From 40d3615c8d722095138d6ac828eb5f7f91e6ffa2 Mon Sep 17 00:00:00 2001 From: Riccardo Forina Date: Thu, 21 Mar 2024 16:02:16 +0100 Subject: [PATCH 1/8] Add a top-level README --- README.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++ ui/README.md | 40 +++++++++++----------------- 2 files changed, 89 insertions(+), 25 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 000000000..f1566b769 --- /dev/null +++ b/README.md @@ -0,0 +1,74 @@ +# Console for Apache Kafka™ on Kubernetes + +This project is a web console designed to facilitate interactions with Apache Kafka™ instances on Kubernetes, leveraging the [Strimzi](https://strimzi.io) Cluster Operator. +It is composed of two main parts: + +- a REST API backend developed with Java Quarkus +- a user interface (UI) built with Next.js and [PatternFly](https://patternfly.org) + +### Getting started + +#### API + +Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system. + +```bash +cd api +``` + +Create a `.env` file containing the details about how the API should connect to the Kafka cluster. +For a Kafka cluster installed using [Strimzi's Quick Starts](https://strimzi.io/quickstarts/) it should look like this: + +```.dotenv +CONSOLE_KAFKA_MY_CLUSTER=kafka/my-cluster +CONSOLE_KAFKA_MY_CLUSTER_BOOTSTRAP_SERVERS=my-cluster-kafka-bootstrap:9092 +``` + +Then run the application. + +```bash +./mvn quarkus:dev -DskipTests +``` + +This should result in Quarkus starting up, with the REST APIs available on localhost port 8080: + +* [API documentation](http://localhost:8080/swagger-ui) + +#### UI + +```bash +cd ui +``` + +Create a `.env` file containing the details about where to find the API server, and some additional config. + +```.dotenv +BACKEND_URL=http://localhost:8080 +CONSOLE_METRICS_PROMETHEUS_URL=http://localhost:9090 +NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890= +LOG_LEVEL=info +``` + +[!WARNING] +Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started. + +Then run the application. + +```bash +npm install +npm run dev +``` + +This will start up the UI in development mode, hosted on port 3000 of your localhost: + +## [User Interface](http://localhost:3000) + +For more information on the UI, see the UI module's [README.md](ui/README.md). + +## Contributing + +We welcome contributions of all forms. Please see the CONTRIBUTING.md file for how to get started. Join us in enhancing the capabilities of this console for Apache Kafka™ on Kubernetes. + +## License + +This project is licensed under the Apache License 2.0 - see the LICENSE file for details. \ No newline at end of file diff --git a/ui/README.md b/ui/README.md index f4da3c4c1..f3056d995 100644 --- a/ui/README.md +++ b/ui/README.md @@ -1,34 +1,24 @@ -This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). - +This part of the project contains the user interface for the Kafka console, developed using Next.js and the [PatternFly](https://patternfly.org) UI library. ## Getting Started -First, run the development server: +Create a `.env` file containing the details about where to find the API server, and some additional config. -```bash -npm run dev -# or -yarn dev -# or -pnpm dev +```.dotenv +BACKEND_URL=http://localhost:8080 +CONSOLE_METRICS_PROMETHEUS_URL=http://localhost:9090 +NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890= +LOG_LEVEL=info ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. - -You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file. - -This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font. - -## Learn More +[!WARNING] +Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started. -To learn more about Next.js, take a look at the following resources: +Then run the application. -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. - -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! - -## Deploy on Vercel +```bash +npm run install +npm run dev +``` -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. -Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. From 3b827e2653b162a62e6f50b2c7060de56718ae2a Mon Sep 17 00:00:00 2001 From: Riccardo Forina Date: Thu, 21 Mar 2024 16:12:22 +0100 Subject: [PATCH 2/8] Update the README for the UI --- ui/README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 2 deletions(-) diff --git a/ui/README.md b/ui/README.md index f3056d995..17edece16 100644 --- a/ui/README.md +++ b/ui/README.md @@ -1,4 +1,7 @@ +# Console UI + This part of the project contains the user interface for the Kafka console, developed using Next.js and the [PatternFly](https://patternfly.org) UI library. + ## Getting Started Create a `.env` file containing the details about where to find the API server, and some additional config. @@ -13,12 +16,77 @@ LOG_LEVEL=info [!WARNING] Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started. -Then run the application. +Install the required dependencies. ```bash npm run install +``` + +Then run the application. + +```bash +npm run build +npm run start +``` + +Open [http://localhost:3000](http://localhost:3000) with your browser to see the console. + +## Build + +```bash +npm run build +``` + +This will create an optimized version of the application that can be deployed. + +## Developing the UI + +```bash npm run dev ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +This will start the UI in dev mode, hosted (by default) on port 3000. When running successfully, you should see output similar to: + +``` +strimzi-ui@0.1.0 dev +NODE_OPTIONS='-r next-logger' next dev | pino-pretty + +[16:11:06.206] INFO (console/14593): ▲ Next.js 14.1.4 +[16:11:06.206] INFO (console/14593): - Local: http://localhost:3000 +[16:11:06.206] INFO (console/14593): - Environments: .env.local +[16:11:06.206] INFO (next.js/14593): +prefix: "info" +[16:11:08.981] INFO (next.js/14593): Ready in 2.9s +prefix: "event" +``` + +You can then access the UI on port 3000 or your localhost. + +Note: you will need the REST API running for the UI to work. See the README at the root of this repository for examples of how to do that. + +### Develop the components in isolation using Storybook + +```bash +npm run storybook +``` + +This will start Storybook, hosted on port 6006. + +### Test the UI + +```bash +npm run build-storybook +http-serve -p 6006 storybook-static + +# in a different terminal +npm run test-storybook +``` + +This will build Storybook and run all the relative unit tests. + +```bash +npm run build +npm run test +``` +This will run Playwright against a production build of the application. \ No newline at end of file From 8e344a81736180600f5621dd377c1c46b6050445 Mon Sep 17 00:00:00 2001 From: Riccardo Forina Date: Thu, 21 Mar 2024 17:04:41 +0100 Subject: [PATCH 3/8] Update README.md Co-authored-by: Andrea Peruffo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f1566b769..3424e9605 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This project is a web console designed to facilitate interactions with Apache Ka It is composed of two main parts: - a REST API backend developed with Java Quarkus -- a user interface (UI) built with Next.js and [PatternFly](https://patternfly.org) +- a user interface (UI) built with Next.js and [PatternFly](https://patternfly.org) ### Getting started From ee4fd05ebef6aad9f058be732fe3695c8f26dde1 Mon Sep 17 00:00:00 2001 From: Riccardo Forina Date: Thu, 21 Mar 2024 17:45:25 +0100 Subject: [PATCH 4/8] Update CONTRIBUTING.md Add a CONTRIBUTING.md file for both the API and the UI module, and point the root one to them --- CONTRIBUTING.md | 58 +++---------------------- README.md | 62 ++------------------------- api/CONTRIBUTING.md | 71 +++++++++++++++++++++++++++++++ ui/.dockerignore | 2 +- ui/{README.md => CONTRIBUTING.md} | 24 +++++++---- 5 files changed, 97 insertions(+), 120 deletions(-) create mode 100644 api/CONTRIBUTING.md rename ui/{README.md => CONTRIBUTING.md} (73%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d47d73056..85cca9e55 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -## Contributing to the project +# Contributing to the project **Want to contribute? Great!** We try to make it easy, and all contributions, even the smaller ones, are more than welcome. @@ -42,58 +42,10 @@ All submissions, including submissions by project members, need to be reviewed b [GitHub Pull Request Review Process](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews) is followed for every pull request. -### Coding Guidelines +## Contribute to the API - * We decided to disallow `@author` tags in the Javadoc: they are hard to maintain - * Please properly squash your pull requests before submitting them. Fixup commits can be used temporarily during the review process but things should be squashed at the end to have meaningful commits. +Please check the [api/CONTRIBUTING.md](./api/CONTRIBUTING.md) file for detailed information about how to contribute to the API module. -### Continuous Integration - - kafka-admin-api CI is based on GitHub Actions, which means that everyone has the ability to automatically execute CI in their forks as part of the process of making changes. We ask that all non-trivial changes go through this process, so that the contributor gets immediate feedback, while at the same time keeping our CI fast and healthy for everyone. - -### Tests and documentation are not optional - -Don't forget to include tests in your pull requests. -Also don't forget the documentation (reference documentation, javadoc...). - -### Installing Checkstyle - -Project uses checkstyle mvn plugin that is executed during `mvn validate` pase. -Please follow your ide setup for checkstyle. For example for intelij: - -https://plugins.jetbrains.com/plugin/1065-checkstyle-idea - -## Regenerating OpenAPI file - -PRs that make changes in the API should update openapi file by executing: - -``` -mvn -Popenapi-generate process-classes -``` - -Please commit generated files along with the PR for review. - -### Interacting with local kafka - -1. Creating topic - -``` -kafka-topics.sh --create --bootstrap-server localhost:9092 --partitions=3 --replication-factor=1 --topic test --command-config ./hack/binscripts.properties -``` - -2. Produce messages using kcat -``` -kcat -b localhost:9092 -F ./hack/kcat.properties -P -t test -``` - - -4. Consume messages -``` - kcat -b localhost:9092 -F ./hack/kcat.properties -C -t test -``` - -6. Interact with the API to view results -` -curl -s -u admin:admin-secret http://localhost:8080/api/v1/consumer-groups | jq -` +## Contribute to the UI +Please check the [ui/CONTRIBUTING.md](./ui/CONTRIBUTING.md) file for detailed information about how to contribute to the UI module. diff --git a/README.md b/README.md index 3424e9605..3aa685e13 100644 --- a/README.md +++ b/README.md @@ -6,68 +6,14 @@ It is composed of two main parts: - a REST API backend developed with Java Quarkus - a user interface (UI) built with Next.js and [PatternFly](https://patternfly.org) -### Getting started +## Installing -#### API - -Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system. - -```bash -cd api -``` - -Create a `.env` file containing the details about how the API should connect to the Kafka cluster. -For a Kafka cluster installed using [Strimzi's Quick Starts](https://strimzi.io/quickstarts/) it should look like this: - -```.dotenv -CONSOLE_KAFKA_MY_CLUSTER=kafka/my-cluster -CONSOLE_KAFKA_MY_CLUSTER_BOOTSTRAP_SERVERS=my-cluster-kafka-bootstrap:9092 -``` - -Then run the application. - -```bash -./mvn quarkus:dev -DskipTests -``` - -This should result in Quarkus starting up, with the REST APIs available on localhost port 8080: - -* [API documentation](http://localhost:8080/swagger-ui) - -#### UI - -```bash -cd ui -``` - -Create a `.env` file containing the details about where to find the API server, and some additional config. - -```.dotenv -BACKEND_URL=http://localhost:8080 -CONSOLE_METRICS_PROMETHEUS_URL=http://localhost:9090 -NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890= -LOG_LEVEL=info -``` - -[!WARNING] -Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started. - -Then run the application. - -```bash -npm install -npm run dev -``` - -This will start up the UI in development mode, hosted on port 3000 of your localhost: - -## [User Interface](http://localhost:3000) - -For more information on the UI, see the UI module's [README.md](ui/README.md). +Please refer to the [install/README.md](./install/README.md) file for detailed information about how to install the Console. ## Contributing -We welcome contributions of all forms. Please see the CONTRIBUTING.md file for how to get started. Join us in enhancing the capabilities of this console for Apache Kafka™ on Kubernetes. +We welcome contributions of all forms. Please see the [CONTRIBUTING.md](./CONTRIBUTING.md) file for how to get started. +Join us in enhancing the capabilities of this console for Apache Kafka™ on Kubernetes. ## License diff --git a/api/CONTRIBUTING.md b/api/CONTRIBUTING.md new file mode 100644 index 000000000..10c6a702f --- /dev/null +++ b/api/CONTRIBUTING.md @@ -0,0 +1,71 @@ +# Contributing to the API + +## Before you start + +Please check the project's [contributing guide](../CONTRIBUTING.md) first. + +## Prerequisites + +Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system. +One option to get started is to follow [Strimzi's Quick Starts](https://strimzi.io/quickstarts/). + +You will also need a working installation of: + +- Java (v17) +- Maven (v3.8) + +### Coding Guidelines + + * We decided to disallow `@author` tags in the Javadoc: they are hard to maintain + * Please properly squash your pull requests before submitting them. Fixup commits can be used temporarily during the review process but things should be squashed at the end to have meaningful commits. + +### Continuous Integration + + kafka-admin-api CI is based on GitHub Actions, which means that everyone has the ability to automatically execute CI in their forks as part of the process of making changes. We ask that all non-trivial changes go through this process, so that the contributor gets immediate feedback, while at the same time keeping our CI fast and healthy for everyone. + +### Tests and documentation are not optional + +Don't forget to include tests in your pull requests. +Also don't forget the documentation (reference documentation, javadoc...). + +### Installing Checkstyle + +Project uses checkstyle mvn plugin that is executed during `mvn validate` pase. +Please follow your ide setup for checkstyle. For example for intelij: + +https://plugins.jetbrains.com/plugin/1065-checkstyle-idea + +## Regenerating OpenAPI file + +PRs that make changes in the API should update openapi file by executing: + +``` +mvn -Popenapi-generate process-classes +``` + +Please commit generated files along with the PR for review. + +### Interacting with local kafka + +1. Creating topic + +``` +kafka-topics.sh --create --bootstrap-server localhost:9092 --partitions=3 --replication-factor=1 --topic test --command-config ./hack/binscripts.properties +``` + +2. Produce messages using kcat +``` +kcat -b localhost:9092 -F ./hack/kcat.properties -P -t test +``` + + +4. Consume messages +``` + kcat -b localhost:9092 -F ./hack/kcat.properties -C -t test +``` + +6. Interact with the API to view results +` +curl -s -u admin:admin-secret http://localhost:8080/api/v1/consumer-groups | jq +` + diff --git a/ui/.dockerignore b/ui/.dockerignore index ac556e64f..b47531ad1 100644 --- a/ui/.dockerignore +++ b/ui/.dockerignore @@ -2,7 +2,7 @@ Dockerfile .dockerignore node_modules npm-debug.log -README.md +CONTRIBUTING.md .next .git .env.* diff --git a/ui/README.md b/ui/CONTRIBUTING.md similarity index 73% rename from ui/README.md rename to ui/CONTRIBUTING.md index 17edece16..f5289f076 100644 --- a/ui/README.md +++ b/ui/CONTRIBUTING.md @@ -1,21 +1,29 @@ -# Console UI +# Contributing to the UI This part of the project contains the user interface for the Kafka console, developed using Next.js and the [PatternFly](https://patternfly.org) UI library. +## Prerequisites + +Please make sure you have working installations of: + +- node (v18+) +- npm (v10+) + +To run a development version of the UI working in all its sections, you will need to install the console on a development cluster first. Please refer to the [install/README.md](../install/README.md) file for detailed instructions about how to do it. + +Alternatively, you can run the API module locally, but sections depending on the metrics exported on Prometheus will not work correctly. + ## Getting Started Create a `.env` file containing the details about where to find the API server, and some additional config. ```.dotenv -BACKEND_URL=http://localhost:8080 -CONSOLE_METRICS_PROMETHEUS_URL=http://localhost:9090 -NEXTAUTH_SECRET=abcdefghijklmnopqrstuvwxyz1234567890= +# the actual URLs will depend on how you installed the console +BACKEND_URL=http://api.my-cluster +CONSOLE_METRICS_PROMETHEUS_URL=http://prometheus.my-cluster LOG_LEVEL=info ``` -[!WARNING] -Please generate a valid and secure value for `NEXTAUTH_SECRET`. We suggest running `openssl rand -base64 32` to get started. - Install the required dependencies. ```bash @@ -89,4 +97,4 @@ npm run build npm run test ``` -This will run Playwright against a production build of the application. \ No newline at end of file +This will run Playwright against a production build of the application. From aef3a11349cc8c3fb992a6251c8c89b6a5266662 Mon Sep 17 00:00:00 2001 From: Riccardo Forina Date: Fri, 22 Mar 2024 17:13:13 +0100 Subject: [PATCH 5/8] Improve the API contributing doc --- api/CONTRIBUTING.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/api/CONTRIBUTING.md b/api/CONTRIBUTING.md index 10c6a702f..5ad66518f 100644 --- a/api/CONTRIBUTING.md +++ b/api/CONTRIBUTING.md @@ -49,22 +49,31 @@ Please commit generated files along with the PR for review. 1. Creating topic +Use the `kafka-topics.sh` tool to manage topics. kafka-topics.sh is part of the [Apache Kafka distribution](https://kafka.apache.org/downloads) and is found in the bin directory. + ``` kafka-topics.sh --create --bootstrap-server localhost:9092 --partitions=3 --replication-factor=1 --topic test --command-config ./hack/binscripts.properties ``` 2. Produce messages using kcat + +Use [`kcat`](https://github.com/edenhill/kcat) to produce messages. + ``` kcat -b localhost:9092 -F ./hack/kcat.properties -P -t test ``` 4. Consume messages + +Use [`kcat`](https://github.com/edenhill/kcat) to consume messages. + ``` - kcat -b localhost:9092 -F ./hack/kcat.properties -C -t test +kcat -b localhost:9092 -F ./hack/kcat.properties -C -t test ``` 6. Interact with the API to view results + ` curl -s -u admin:admin-secret http://localhost:8080/api/v1/consumer-groups | jq ` From 0731f53d6076024d09e6db50a86ae3425102c5bd Mon Sep 17 00:00:00 2001 From: Riccardo Forina Date: Tue, 16 Apr 2024 11:25:14 +0200 Subject: [PATCH 6/8] Ignore env files across all repo --- .gitignore | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.gitignore b/.gitignore index 66405b3c7..990c1aeb5 100644 --- a/.gitignore +++ b/.gitignore @@ -20,3 +20,7 @@ release.properties # VS Code .factorypath .vscode + + +# env files +.env* From 51abc53fa58f88a3a84f0d2ce50aabce0f80909e Mon Sep 17 00:00:00 2001 From: Riccardo Forina Date: Tue, 16 Apr 2024 11:25:46 +0200 Subject: [PATCH 7/8] Add CRs to quickly deploy the console on a local development environment --- quickstart/01-kafka.yaml | 29 ++++++++++ quickstart/02-console.yaml | 109 +++++++++++++++++++++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 quickstart/01-kafka.yaml create mode 100644 quickstart/02-console.yaml diff --git a/quickstart/01-kafka.yaml b/quickstart/01-kafka.yaml new file mode 100644 index 000000000..a2fa0e18d --- /dev/null +++ b/quickstart/01-kafka.yaml @@ -0,0 +1,29 @@ +apiVersion: kafka.strimzi.io/v1beta2 +kind: Kafka +metadata: + name: my-cluster +spec: + kafka: + version: 3.7.0 + replicas: 1 + listeners: + - name: plain + port: 9092 + type: internal + tls: false + config: + offsets.topic.replication.factor: 1 + transaction.state.log.replication.factor: 1 + transaction.state.log.min.isr: 1 + default.replication.factor: 1 + min.insync.replicas: 1 + inter.broker.protocol.version: "3.7" + storage: + type: ephemeral + zookeeper: + replicas: 3 + storage: + type: ephemeral + entityOperator: + topicOperator: {} + userOperator: {} diff --git a/quickstart/02-console.yaml b/quickstart/02-console.yaml new file mode 100644 index 000000000..063d8c3d2 --- /dev/null +++ b/quickstart/02-console.yaml @@ -0,0 +1,109 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: console-api +spec: + replicas: 1 + selector: + matchLabels: + app: console-api + template: + metadata: + labels: + app: console-api + spec: + containers: + - name: console-api + image: quay.io/eyefloaters/console-api:latest + ports: + - containerPort: 8080 + env: + - name: CONSOLE_KAFKA_MC + value: kafka/my-cluster + - name: CONSOLE_KAFKA_MC_BOOTSTRAP_SERVERS + value: my-cluster-kafka-0.my-cluster-kafka-brokers.kafka.svc:9092 +--- +apiVersion: v1 +kind: Service +metadata: + name: console-api +spec: + selector: + app: console-api + type: NodePort + ports: + - protocol: TCP + port: 8080 + name: api +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: ui +spec: + replicas: 1 + selector: + matchLabels: + app: ui + template: + metadata: + labels: + app: ui + spec: + containers: + - name: ui + image: quay.io/eyefloaters/console-ui:latest + ports: + - containerPort: 3000 + env: + - name: HOSTNAME + value: 0.0.0.0 + - name: NEXTAUTH_URL + value: http://localhost:3000 + - name: NEXTAUTH_URL_INTERNAL + value: http://console-ui:3000 + - name: NEXTAUTH_SECRET + value: changeme + - name: BACKEND_URL + value: "http://console-api:8080" +--- +apiVersion: v1 +kind: Service +metadata: + name: ui +spec: + selector: + app: ui + type: NodePort + ports: + - protocol: TCP + port: 3000 + name: web +--- +kind: ClusterRole +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: console-api-kafka-watch-all +rules: + - verbs: + - get + - watch + - list + apiGroups: + - kafka.strimzi.io + resources: + - kafkas + - kafkatopics +--- +kind: ClusterRoleBinding +apiVersion: rbac.authorization.k8s.io/v1 +metadata: + name: console-api-kafka-watch-all +subjects: + - kind: ServiceAccount + name: default + namespace: console +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: console-api-kafka-watch-all From 3e32a97d4e6605fca25d16aff0befbe9b5cd9db1 Mon Sep 17 00:00:00 2001 From: Michael Edgar Date: Wed, 15 May 2024 10:34:27 -0400 Subject: [PATCH 8/8] Minor updates - add links, delete outdated instructions Signed-off-by: Michael Edgar --- CONTRIBUTING.md | 2 +- README.md | 12 ++-- api/CONTRIBUTING.md | 57 ++----------------- quickstart/01-kafka.yaml | 29 ---------- quickstart/02-console.yaml | 109 ------------------------------------- ui/CONTRIBUTING.md | 4 +- 6 files changed, 14 insertions(+), 199 deletions(-) delete mode 100644 quickstart/01-kafka.yaml delete mode 100644 quickstart/02-console.yaml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 85cca9e55..abeafae93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ The DCO text is also included verbatim in the [dco.txt](dco.txt) file in the roo ## Reporting an issue -This project uses GitHub issues to manage the issues. Open an issue directly in GitHub. you can also open JIRA issues at https://issues.redhat.com/browse/MGDSTRM +This project uses GitHub issues to manage the issues. Open an issue directly in GitHub. If you believe you found a bug, and it's likely possible, please indicate a way to reproduce it, what you are seeing and what you would expect to see. diff --git a/README.md b/README.md index 3aa685e13..6fe6598dc 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,18 @@ # Console for Apache Kafka™ on Kubernetes -This project is a web console designed to facilitate interactions with Apache Kafka™ instances on Kubernetes, leveraging the [Strimzi](https://strimzi.io) Cluster Operator. -It is composed of two main parts: +This project is a web console designed to facilitate interactions with Apache Kafka™ instances on Kubernetes, leveraging the [Strimzi](https://strimzi.io) Cluster Operator. +It is composed of two main parts: -- a REST API backend developed with Java Quarkus -- a user interface (UI) built with Next.js and [PatternFly](https://patternfly.org) +- a REST API backend developed with Java and [Quarkus](https://quarkus.io/) +- a user interface (UI) built with [Next.js](https://nextjs.org/) and [PatternFly](https://patternfly.org) ## Installing -Please refer to the [install/README.md](./install/README.md) file for detailed information about how to install the Console. +Please refer to the [installation README](./install/README.md) file for detailed information about how to install the latest release of the console in a Kubernetes cluster. ## Contributing -We welcome contributions of all forms. Please see the [CONTRIBUTING.md](./CONTRIBUTING.md) file for how to get started. +We welcome contributions of all forms. Please see the [CONTRIBUTING](./CONTRIBUTING.md) file for how to get started. Join us in enhancing the capabilities of this console for Apache Kafka™ on Kubernetes. ## License diff --git a/api/CONTRIBUTING.md b/api/CONTRIBUTING.md index 5ad66518f..548405810 100644 --- a/api/CONTRIBUTING.md +++ b/api/CONTRIBUTING.md @@ -6,7 +6,7 @@ Please check the project's [contributing guide](../CONTRIBUTING.md) first. ## Prerequisites -Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system. +Ensure you have Kubernetes and Strimzi Cluster Operator installed on your system. Either [minikube](https://minikube.sigs.k8s.io/) or [OpenShifot Local](https://developers.redhat.com/products/openshift-local) are good options. One option to get started is to follow [Strimzi's Quick Starts](https://strimzi.io/quickstarts/). You will also need a working installation of: @@ -21,60 +21,13 @@ You will also need a working installation of: ### Continuous Integration - kafka-admin-api CI is based on GitHub Actions, which means that everyone has the ability to automatically execute CI in their forks as part of the process of making changes. We ask that all non-trivial changes go through this process, so that the contributor gets immediate feedback, while at the same time keeping our CI fast and healthy for everyone. +This project's CI is based on GitHub Actions, which means that everyone has the ability to automatically execute CI in their forks as part of the process of making changes. We ask that all non-trivial changes go through this process, so that the contributor gets immediate feedback, while at the same time keeping our CI fast and healthy for everyone. ### Tests and documentation are not optional -Don't forget to include tests in your pull requests. -Also don't forget the documentation (reference documentation, javadoc...). +Do not forget to include or update tests in your pull requests and update any related documentation (reference documentation, javadoc...). ### Installing Checkstyle -Project uses checkstyle mvn plugin that is executed during `mvn validate` pase. -Please follow your ide setup for checkstyle. For example for intelij: - -https://plugins.jetbrains.com/plugin/1065-checkstyle-idea - -## Regenerating OpenAPI file - -PRs that make changes in the API should update openapi file by executing: - -``` -mvn -Popenapi-generate process-classes -``` - -Please commit generated files along with the PR for review. - -### Interacting with local kafka - -1. Creating topic - -Use the `kafka-topics.sh` tool to manage topics. kafka-topics.sh is part of the [Apache Kafka distribution](https://kafka.apache.org/downloads) and is found in the bin directory. - -``` -kafka-topics.sh --create --bootstrap-server localhost:9092 --partitions=3 --replication-factor=1 --topic test --command-config ./hack/binscripts.properties -``` - -2. Produce messages using kcat - -Use [`kcat`](https://github.com/edenhill/kcat) to produce messages. - -``` -kcat -b localhost:9092 -F ./hack/kcat.properties -P -t test -``` - - -4. Consume messages - -Use [`kcat`](https://github.com/edenhill/kcat) to consume messages. - -``` -kcat -b localhost:9092 -F ./hack/kcat.properties -C -t test -``` - -6. Interact with the API to view results - -` -curl -s -u admin:admin-secret http://localhost:8080/api/v1/consumer-groups | jq -` - +Project uses checkstyle mvn plugin that is executed during `mvn validate` phase. Make sure to verify this +passes before pushing to Github. diff --git a/quickstart/01-kafka.yaml b/quickstart/01-kafka.yaml deleted file mode 100644 index a2fa0e18d..000000000 --- a/quickstart/01-kafka.yaml +++ /dev/null @@ -1,29 +0,0 @@ -apiVersion: kafka.strimzi.io/v1beta2 -kind: Kafka -metadata: - name: my-cluster -spec: - kafka: - version: 3.7.0 - replicas: 1 - listeners: - - name: plain - port: 9092 - type: internal - tls: false - config: - offsets.topic.replication.factor: 1 - transaction.state.log.replication.factor: 1 - transaction.state.log.min.isr: 1 - default.replication.factor: 1 - min.insync.replicas: 1 - inter.broker.protocol.version: "3.7" - storage: - type: ephemeral - zookeeper: - replicas: 3 - storage: - type: ephemeral - entityOperator: - topicOperator: {} - userOperator: {} diff --git a/quickstart/02-console.yaml b/quickstart/02-console.yaml deleted file mode 100644 index 063d8c3d2..000000000 --- a/quickstart/02-console.yaml +++ /dev/null @@ -1,109 +0,0 @@ -apiVersion: apps/v1 -kind: Deployment -metadata: - name: console-api -spec: - replicas: 1 - selector: - matchLabels: - app: console-api - template: - metadata: - labels: - app: console-api - spec: - containers: - - name: console-api - image: quay.io/eyefloaters/console-api:latest - ports: - - containerPort: 8080 - env: - - name: CONSOLE_KAFKA_MC - value: kafka/my-cluster - - name: CONSOLE_KAFKA_MC_BOOTSTRAP_SERVERS - value: my-cluster-kafka-0.my-cluster-kafka-brokers.kafka.svc:9092 ---- -apiVersion: v1 -kind: Service -metadata: - name: console-api -spec: - selector: - app: console-api - type: NodePort - ports: - - protocol: TCP - port: 8080 - name: api ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: ui -spec: - replicas: 1 - selector: - matchLabels: - app: ui - template: - metadata: - labels: - app: ui - spec: - containers: - - name: ui - image: quay.io/eyefloaters/console-ui:latest - ports: - - containerPort: 3000 - env: - - name: HOSTNAME - value: 0.0.0.0 - - name: NEXTAUTH_URL - value: http://localhost:3000 - - name: NEXTAUTH_URL_INTERNAL - value: http://console-ui:3000 - - name: NEXTAUTH_SECRET - value: changeme - - name: BACKEND_URL - value: "http://console-api:8080" ---- -apiVersion: v1 -kind: Service -metadata: - name: ui -spec: - selector: - app: ui - type: NodePort - ports: - - protocol: TCP - port: 3000 - name: web ---- -kind: ClusterRole -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: console-api-kafka-watch-all -rules: - - verbs: - - get - - watch - - list - apiGroups: - - kafka.strimzi.io - resources: - - kafkas - - kafkatopics ---- -kind: ClusterRoleBinding -apiVersion: rbac.authorization.k8s.io/v1 -metadata: - name: console-api-kafka-watch-all -subjects: - - kind: ServiceAccount - name: default - namespace: console -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: console-api-kafka-watch-all diff --git a/ui/CONTRIBUTING.md b/ui/CONTRIBUTING.md index f5289f076..d85599625 100644 --- a/ui/CONTRIBUTING.md +++ b/ui/CONTRIBUTING.md @@ -37,7 +37,7 @@ npm run build npm run start ``` -Open [http://localhost:3000](http://localhost:3000) with your browser to see the console. +Open [http://localhost:3000](http://localhost:3000) with your browser to see the console user interface. ## Build @@ -97,4 +97,4 @@ npm run build npm run test ``` -This will run Playwright against a production build of the application. +This will run Playwright against the built application.