From 79693305843e1dc6bc8c33c51ad41b42512bf77e Mon Sep 17 00:00:00 2001 From: yeikel Date: Fri, 18 Apr 2025 17:28:21 -0400 Subject: [PATCH] docs: use syntax formatting consistently --- configuration/audit-log.md | 2 +- configuration/authentication/aws-iam.md | 2 +- .../authentication/basic-authentication.md | 6 +-- .../authentication/ldap-active-directory.md | 2 +- configuration/authentication/sasl_scram.md | 2 +- configuration/configuration-file.md | 12 +++++- configuration/configuration-wizard.md | 5 +-- configuration/data-masking.md | 2 +- .../helm-charts/configuration/ssl-example.md | 12 +++--- configuration/helm-charts/quick-start.md | 23 +++++++----- configuration/helm-charts/resource-limits.md | 6 +-- configuration/helm-charts/sticky-sessions.md | 2 +- .../misc-configuration-properties.md | 2 +- .../rbac-role-based-access-control/README.md | 16 ++++---- configuration/serialization-serde.md | 2 +- development/building/prerequisites.md | 37 +++++++++++-------- development/building/with-docker.md | 10 ++--- development/building/without-docker.md | 2 +- development/setting-up-git.md | 2 +- faq/authentication.md | 2 +- faq/faq.md | 2 +- overview/getting-started.md | 4 +- quick-start/demo-run.md | 2 +- quick-start/persistent-start.md | 6 ++- .../permissions/msk-+serverless-setup.md | 8 ++-- 25 files changed, 94 insertions(+), 77 deletions(-) diff --git a/configuration/audit-log.md b/configuration/audit-log.md index 1ef0304..5ce5ce2 100644 --- a/configuration/audit-log.md +++ b/configuration/audit-log.md @@ -6,7 +6,7 @@ Logging can be done to either kafka topic and/or console. See all the available configuration properties: -``` +```yaml kafka: clusters: - name: local diff --git a/configuration/authentication/aws-iam.md b/configuration/authentication/aws-iam.md index 0e89389..9364481 100644 --- a/configuration/authentication/aws-iam.md +++ b/configuration/authentication/aws-iam.md @@ -21,7 +21,7 @@ Please replace #### Running From Docker Image -``` +```bash docker run -p 8080:8080 \ -e KAFKA_CLUSTERS_0_NAME=local \ -e KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS= \ diff --git a/configuration/authentication/basic-authentication.md b/configuration/authentication/basic-authentication.md index 2d881fd..343bb05 100644 --- a/configuration/authentication/basic-authentication.md +++ b/configuration/authentication/basic-authentication.md @@ -6,7 +6,7 @@ description: Basic username+password authentication In order to enable basic username+passworda authentication add these properties: -``` +```properties AUTH_TYPE: "LOGIN_FORM" SPRING_SECURITY_USER_NAME: admin SPRING_SECURITY_USER_PASSWORD: pass @@ -14,8 +14,8 @@ In order to enable basic username+passworda authentication add these properties: YAML config counterpart: -``` -auth. +```yaml +auth: type: LOGIN_FORM spring: diff --git a/configuration/authentication/ldap-active-directory.md b/configuration/authentication/ldap-active-directory.md index e21e420..3720d25 100644 --- a/configuration/authentication/ldap-active-directory.md +++ b/configuration/authentication/ldap-active-directory.md @@ -1,6 +1,6 @@ # LDAP / Active Directory -``` +```yaml auth: type: LDAP spring: diff --git a/configuration/authentication/sasl_scram.md b/configuration/authentication/sasl_scram.md index 79f41b3..8de4e27 100644 --- a/configuration/authentication/sasl_scram.md +++ b/configuration/authentication/sasl_scram.md @@ -17,7 +17,7 @@ Please replace #### Running From Docker Image -``` +```bash docker run -p 8080:8080 \ -e KAFKA_CLUSTERS_0_NAME= \ -e KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS= \ diff --git a/configuration/configuration-file.md b/configuration/configuration-file.md index bd79c72..19536f3 100644 --- a/configuration/configuration-file.md +++ b/configuration/configuration-file.md @@ -16,11 +16,19 @@ Rather than writing your config from a scratch, it would be more convenient to u #### Providing a config path for the app instance: -**Docker**: `docker run -it -p 8080:8080 -e spring.config.additional-location=/tmp/config.yml -v /tmp/kui/config.yml:/tmp/config.yml ghcr.io/kafbat/kafka-ui` +**Docker**: + +```bash +docker run -it \ + -p 8080:8080 \ + -e spring.config.additional-location=/tmp/config.yml \ + -v /tmp/kui/config.yml:/tmp/config.yml \ + ghcr.io/kafbat/kafka-ui +``` **Docker compose**: -``` +```yaml services: kafbat-ui: container_name: kafbat-ui diff --git a/configuration/configuration-wizard.md b/configuration/configuration-wizard.md index d740658..0e024f4 100644 --- a/configuration/configuration-wizard.md +++ b/configuration/configuration-wizard.md @@ -10,7 +10,7 @@ Since version 0.6 we added an ability to change cluster configs in runtime. This Sample docker compose configuration: -``` +```yaml services: kafbat-ui: container_name: kafbat-ui @@ -23,8 +23,7 @@ services: DYNAMIC_CONFIG_ENABLED: 'true' KAFKA_CLUSTERS_0_NAME: wizard_test KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka0:29092 - - ... + # ... ``` You can even omit all vars other than `DYNAMIC_CONFIG_ENABLED` to start the application with empty configs and setup it up after startup. diff --git a/configuration/data-masking.md b/configuration/data-masking.md index bbb4d46..1152737 100644 --- a/configuration/data-masking.md +++ b/configuration/data-masking.md @@ -109,7 +109,7 @@ kafka: Same configuration in env-vars fashion: -``` +```properties ... KAFKA_CLUSTERS_0_MASKING_0_TYPE: REMOVE KAFKA_CLUSTERS_0_MASKING_0_FIELDS_0: "id" diff --git a/configuration/helm-charts/configuration/ssl-example.md b/configuration/helm-charts/configuration/ssl-example.md index 297be6c..e11e85d 100644 --- a/configuration/helm-charts/configuration/ssl-example.md +++ b/configuration/helm-charts/configuration/ssl-example.md @@ -9,14 +9,14 @@ To implement SSL for kafbat-ui you need to provide JKS files into the pod. Here To create configmap use following command.\ -``` +```bash kubectl create configmap ssl-files --from-file=kafka.truststore.jks --from-file=kafka.keystore.jks ``` If you have specified namespace use command.\ -``` +```bash kubectl create configmap ssl-files --from-file=kafka.truststore.jks --from-file=kafka.keystore.jks -n {{namespace} ``` @@ -26,7 +26,7 @@ kubectl create configmap ssl-files --from-file=kafka.truststore.jks --from-file= Encode secret with base64(You can use this tool https://www.base64encode.org/). Create secret.yaml file with the following content -``` +```yml apiVersion: v1 kind: Secret metadata: @@ -41,7 +41,7 @@ data: ### Create ssl-values.yaml file with the following content. -``` +```yml existingSecret: "ssl-secret" @@ -64,12 +64,12 @@ volumes: ### Install chart with command -``` +```bash helm install kafbat-ui kafbat-ui/helm-charts -f ssl-values.yaml ``` If you have specified namespace for configmap and secret please use this command -``` +```bash helm install kafbat-ui kafbat-ui/helm-charts -f ssl-values.yaml -n {namespace} ``` diff --git a/configuration/helm-charts/quick-start.md b/configuration/helm-charts/quick-start.md index 7b7a03c..6a80ac9 100644 --- a/configuration/helm-charts/quick-start.md +++ b/configuration/helm-charts/quick-start.md @@ -9,16 +9,16 @@ description: Quick Start with Helm Chart 1. Clone/Copy Chart to your working directory 2. Execute command - ``` +```bash helm repo add kafbat-ui https://kafbat.github.io/helm-charts helm install kafbat-ui kafbat-ui/kafka-ui - ``` +``` #### Passing Kafbat-UI configuration as Dict Create values.yml file -``` +```yaml yamlApplicationConfig: kafka: clusters: @@ -34,13 +34,15 @@ yamlApplicationConfig: Install by executing command -> helm install kafbat-ui kafbat-ui/kafka-ui -f values.yml +```bash +helm install kafbat-ui kafbat-ui/kafka-ui -f values.yml +``` #### Passing configuration file as ConfigMap Create config map -``` +```yaml apiVersion: v1 kind: ConfigMap metadata: @@ -63,13 +65,15 @@ This ConfigMap will be mounted to the Pod Install by executing the command -> helm install kafbat-ui kafbat-ui/kafka-ui --set yamlApplicationConfigConfigMap.name="kafka-ui-configmap",yamlApplicationConfigConfigMap.keyName="config.yml" +```bash +helm install kafbat-ui kafbat-ui/kafka-ui --set yamlApplicationConfigConfigMap.name="kafka-ui-configmap",yamlApplicationConfigConfigMap.keyName="config.yml" +``` #### Passing environment variables as ConfigMap Create config map -``` +```yaml apiVersion: v1 kind: ConfigMap metadata: @@ -80,7 +84,8 @@ data: AUTH_TYPE: "DISABLED" MANAGEMENT_HEALTH_LDAP_ENABLED: "FALSE" ``` - Install by executing the command -> helm install kafbat-ui kafbat-ui/kafka-ui --set existingConfigMap="kafbat-ui-helm-values" +```bash +helm install kafbat-ui kafbat-ui/kafka-ui --set existingConfigMap="kafbat-ui-helm-values" +``` diff --git a/configuration/helm-charts/resource-limits.md b/configuration/helm-charts/resource-limits.md index aaf3086..a56f1ea 100644 --- a/configuration/helm-charts/resource-limits.md +++ b/configuration/helm-charts/resource-limits.md @@ -10,7 +10,7 @@ There are two options: To set or change resource limits for pods you need to create the file `values.yaml` and add the following lines: -``` +```yaml resources: limits: cpu: 200m @@ -22,7 +22,7 @@ resources: Specify `values.yaml` file during chart install -``` +```bash helm install kafka-ui kafka-ui/kafka-ui -f values.yaml ``` @@ -30,6 +30,6 @@ helm install kafka-ui kafka-ui/kafka-ui -f values.yaml To set limits via CLI you need to specify limits with helm install command. -``` +```bash helm install kafka-ui kafka-ui/kafka-ui --set resources.limits.cpu=200m --set resources.limits.memory=512Mi --set resources.requests.memory=256Mi --set resources.requests.cpu=200m ``` diff --git a/configuration/helm-charts/sticky-sessions.md b/configuration/helm-charts/sticky-sessions.md index 21dbc58..76075d6 100644 --- a/configuration/helm-charts/sticky-sessions.md +++ b/configuration/helm-charts/sticky-sessions.md @@ -6,7 +6,7 @@ The solution for this would be using sticky session/session affinity. An example: -``` +```properties nginx.ingress.kubernetes.io/affinity: cookie nginx.ingress.kubernetes.io/affinity-mode: balanced nginx.ingress.kubernetes.io/session-cookie-expires: "172800" diff --git a/configuration/misc-configuration-properties.md b/configuration/misc-configuration-properties.md index 8219afe..8f88550 100644 --- a/configuration/misc-configuration-properties.md +++ b/configuration/misc-configuration-properties.md @@ -10,7 +10,7 @@ A reminder: any of these properties can be converted into yaml config properties becomes -``` +```yaml kafka: clusters: - bootstrapServers: xxx diff --git a/configuration/rbac-role-based-access-control/README.md b/configuration/rbac-role-based-access-control/README.md index 3bb70c7..fccf03f 100644 --- a/configuration/rbac-role-based-access-control/README.md +++ b/configuration/rbac-role-based-access-control/README.md @@ -17,7 +17,7 @@ First of all, you have to decide if either: This is how you include one more file to start with a docker-compose example: -``` +```yaml services: kafbat-ui: container_name: kafbat-ui @@ -38,7 +38,7 @@ Alternatively, you can append the roles file contents to your main config file. In the roles file we define roles, duh. Every role has access to defined clusters: -``` +```yaml rbac: roles: - name: "memelords" @@ -53,7 +53,7 @@ rbac: A role also has a list of _subjects_ which are the entities we will use to assign roles to. They are provider-dependant, in general, they can be users, groups, or some other entities (github orgs, google domains, LDAP queries, etc.) In this example we define a role `memelords` that will contain all the users within the Google domain `memelord.lol` and, additionally, a GitHub user `Haarolean`. You can combine as many subjects as you want within a role. -``` +```yaml - name: "memelords" subjects: - provider: oauth_google @@ -68,7 +68,7 @@ The subject value is either a fixed string or a regular expression identifying a Regular expression works for any combination of `provider` and `type`. In this example, we define a role `admins` that will contain all the users with an oauth role ending with `-ADMIN`. -``` +```yaml - name: "admins" subjects: - provider: oauth @@ -100,7 +100,7 @@ The next thing which is present in your roles file is, surprisingly, permissions 2. The resource value is either a fixed string or a regular expression identifying a resource. Value is not applicable to `clusterconfig` and `ksql` resources. Please do not fill it out. 3. Actions It's a list of actions (the possible values depend on the resource, see the lists below) that will be applied to the certain permission. Also, note, there's a special action for any of the resources called "all", it will virtually grant all the actions within the corresponding resource. An example for enabling viewing and creating topics whose name start with "derp": -``` +```yaml permissions: - resource: topic value: "derp.*" @@ -126,7 +126,7 @@ A list of all the actions for the corresponding resources (please note neither r **A complete file example:** -``` +```yaml rbac: roles: - name: "memelords" @@ -222,7 +222,7 @@ rbac: **A read-only setup:** -``` +```yaml rbac: roles: - name: "readonly" @@ -260,7 +260,7 @@ rbac: **An admin-group setup example:** -``` +```yaml rbac: roles: - name: "admins" diff --git a/configuration/serialization-serde.md b/configuration/serialization-serde.md index d498784..ab7f8aa 100644 --- a/configuration/serialization-serde.md +++ b/configuration/serialization-serde.md @@ -20,7 +20,7 @@ Base64 (RFC4648) binary data representation. Can be useful in case if the actual Class name: `io.kafbat.ui.serdes.builtin.HexSerde` -``` +```yaml kafka: clusters: - name: Cluster1 diff --git a/development/building/prerequisites.md b/development/building/prerequisites.md index df659ba..e844db7 100644 --- a/development/building/prerequisites.md +++ b/development/building/prerequisites.md @@ -14,20 +14,25 @@ This page explains how to get the software you need to use on Linux or macOS for 1. Install `OpenJDK 21` package or newer: -``` +```bash sudo apt update sudo apt install openjdk-21-jdk ``` -* Check java version using the command `java -version`. +* Check the java version using the command `java -version`. -``` +```bash openjdk version "21.0.5" 2024-10-15 OpenJDK Runtime Environment (build 21.0.5+8-Ubuntu-2ubuntu120.04) OpenJDK 64-Bit Server VM (build 21.0.5+8-Ubuntu-2ubuntu120.04, mixed mode, sharing) ``` -Note: In case OpenJDK 21 is not set as your default Java, run `sudo update-alternatives --config java` command to list all installed Java versions. +Note: In case OpenJDK 21 is not set as your default Java, run +```bash +sudo update-alternatives --config java +``` + +command to list all installed Java versions. ``` Selection Path Priority Status @@ -45,13 +50,13 @@ you can set it as the default by entering the selection number for it in the lis 2. Install `git`: -``` +```bash sudo apt install git ``` 3. Install `docker`: -``` +```bash sudo apt update sudo apt install -y apt-transport-https ca-certificates curl software-properties-common curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - @@ -62,7 +67,7 @@ sudo apt -y install docker-ce To execute the `docker` Command without `sudo`: -``` +```bash sudo usermod -aG docker ${USER} su - ${USER} sudo chmod 666 /var/run/docker.sock @@ -73,32 +78,32 @@ sudo chmod 666 /var/run/docker.sock 1. Install [brew](https://brew.sh/). 2. Install brew cask: -```sh +```bash brew cask ``` 3. Install openjdk 21 via Homebrew: -```sh +```bash brew install openjdk@21 ``` 4. Verify Installation -```sh +```bash java -version ``` Note: In case OpenJDK 21 is not set as your default Java, you can consider including it in your `$PATH` after installation -```sh +```bash export PATH="$(/usr/libexec/java_home -v 21)/bin:$PATH" export JAVA_HOME="$(/usr/libexec/java_home -v 21)" ``` If java_home doesn't recognize homebrew installed java you can run below cmd to symlink brew installed java path to jvm -```sh +```bash sudo ln -sfn $(brew --prefix openjdk@21)/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-21.jdk ``` @@ -120,26 +125,26 @@ Edit docker daemon settings within docker dashboard 1. Open the Docker configuration file in a text editor using the following command: -``` +```bash sudo nano /etc/default/docker ``` 2. Add the following line to the file to allocate 4GB of memory to Docker: -``` +```properties DOCKER_OPTS="--default-ulimit memlock=-1:-1 --memory=4g --memory-swap=-1" ``` 3. Save the file and exit the text editor. 4. Restart the Docker service using the following command: -``` +```bash sudo service docker restart ``` 5. Verify that the memory limit has been set correctly by running the following command: -``` +```bash docker info | grep -i memory ``` diff --git a/development/building/with-docker.md b/development/building/with-docker.md index 46341f8..806cad2 100644 --- a/development/building/with-docker.md +++ b/development/building/with-docker.md @@ -8,7 +8,7 @@ Once you installed the prerequisites and cloned the repository, run the followin * Build a docker image with the app -``` +```bash ./gradlew clean build \ # -x skips goals, in this cases tests. Tests take time, run them separately if needed. -x test \ @@ -27,7 +27,7 @@ A successful build should produce a docker image named `ghcr.io/kafbat/kafka-ui` * Start the app using docker image built in step 1 along with Kafka clusters: -``` +```bash docker-compose -f ./.dev/dev.yaml up -d ``` @@ -35,13 +35,13 @@ docker-compose -f ./.dev/dev.yaml up -d * If you want to start only kafka clusters (to run the `kafbat-ui` app via `spring-boot:run`): -``` +```bash docker-compose -f ./documentation/compose/kafka-clusters-only.yaml up -d ``` * Then start the app. -``` +```bash ./gradlew bootRun -x test # or @@ -53,7 +53,7 @@ docker-compose -f ./documentation/compose/kafka-clusters-only.yaml up -d * Using Helm Charts -``` +```bash helm repo add kafbat https://ui.charts.kafbat.io helm install kafbat-ui kafbat/kafka-ui ``` diff --git a/development/building/without-docker.md b/development/building/without-docker.md index ff29ab3..d3dfa40 100644 --- a/development/building/without-docker.md +++ b/development/building/without-docker.md @@ -12,7 +12,7 @@ Once you installed the prerequisites and cloned the repository, run the followin **Execute the jar** -``` +```bash java -Dspring.config.additional-location= --add-opens java.rmi/javax.rmi.ssl=ALL-UNNAMED -jar ``` diff --git a/development/setting-up-git.md b/development/setting-up-git.md index 1112e46..557f582 100644 --- a/development/setting-up-git.md +++ b/development/setting-up-git.md @@ -2,7 +2,7 @@ Set your git credentials: -``` +```bash git config --global user.name "Mona Lisa" git config --global user.email "monalisa@louvre.net" ``` diff --git a/faq/authentication.md b/faq/authentication.md index 3bd503f..7a7492e 100644 --- a/faq/authentication.md +++ b/faq/authentication.md @@ -4,6 +4,6 @@ Add the following env/config property and check your logs upon authentication: -``` +```bash LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY_LDAP_USERDETAILS: "TRACE" ``` diff --git a/faq/faq.md b/faq/faq.md index eeddba2..3b3dfbc 100644 --- a/faq/faq.md +++ b/faq/faq.md @@ -48,7 +48,7 @@ Sure! Swagger declaration is located [here](https://github.com/kafbat/kafka-ui/b ### My OIDC / OAuth provider uses self-signed certificates, how do I add them to the truststore? -``` +```yaml server: ssl: trust-store: classpath:keycloak-truststore.jks diff --git a/overview/getting-started.md b/overview/getting-started.md index 9071868..c0db8da 100644 --- a/overview/getting-started.md +++ b/overview/getting-started.md @@ -4,7 +4,7 @@ To run Kafbat UI, you can use either a pre-built Docker image or build it (or a ### Quick start (Demo run) -``` +```bash docker run -it -p 8080:8080 -e DYNAMIC_CONFIG_ENABLED=true ghcr.io/kafbat/kafka-ui ``` @@ -14,7 +14,7 @@ The command is sufficient to try things out. When you're done trying things out, ### Persistent installation -``` +```yaml services: kafbat-ui: container_name: kafbat-ui diff --git a/quick-start/demo-run.md b/quick-start/demo-run.md index ddbb1c0..19f3602 100644 --- a/quick-start/demo-run.md +++ b/quick-start/demo-run.md @@ -8,7 +8,7 @@ description: Quick start (demo run) 2. Ensure your kafka cluster is available from the machine you're planning to run the app on 3. Run the following: -``` +```bash docker run -it -p 8080:8080 -e DYNAMIC_CONFIG_ENABLED=true ghcr.io/kafbat/kafka-ui ``` diff --git a/quick-start/persistent-start.md b/quick-start/persistent-start.md index 7518c48..27f7543 100644 --- a/quick-start/persistent-start.md +++ b/quick-start/persistent-start.md @@ -4,7 +4,7 @@ Please ensure the target volume (`~/kui/config.yml`) of your config file does ex Create a yml file with the following contents: -``` +```yaml services: kafbat-ui: container_name: kafbat-ui @@ -19,4 +19,6 @@ services: Run the compose via: -`docker-compose -f .yml up -d` +```bash +docker-compose -f .yml up -d +``` diff --git a/quick-start/prerequisites/permissions/msk-+serverless-setup.md b/quick-start/prerequisites/permissions/msk-+serverless-setup.md index c7baaa8..da6ad65 100644 --- a/quick-start/prerequisites/permissions/msk-+serverless-setup.md +++ b/quick-start/prerequisites/permissions/msk-+serverless-setup.md @@ -4,7 +4,7 @@ This guide has been written for MSK Serverless but is applicable for MSK in gene ### Authentication options for Kafbat-UI: -``` +```properties KAFKA_CLUSTERS_0_PROPERTIES_SECURITY_PROTOCOL=SASL_SSL KAFKA_CLUSTERS_0_PROPERTIES_SASL_MECHANISM=AWS_MSK_IAM KAFKA_CLUSTERS_0_PROPERTIES_SASL_JAAS_CONFIG='software.amazon.msk.auth.iam.IAMLoginModule required;' @@ -42,11 +42,9 @@ environment: [ name: "KAFKA_CLUSTERS_0_PROPERTIES_SASL_JAAS_CONFIG", value: "software.amazon.msk.auth.iam.IAMLoginModule required awsDebugCreds=true;" }, -], +] ``` - - ### Creating an instance 1. Go to the MSK page @@ -63,7 +61,7 @@ environment: [ 3. Click "JSON" 4. Paste the following policy example in the editor, and replace "MSK ARN" with the ARN of your MSK cluster -``` +```json { "Version": "2012-10-17", "Statement": [