From 4e2e4c6d66143ce6888885e16620366841b73fa5 Mon Sep 17 00:00:00 2001 From: Ievgenii Shepeliuk Date: Thu, 11 Mar 2021 19:41:56 +0200 Subject: [PATCH] fix: generate readme.md for helm from readme.adoc --- .github/workflows/release.yaml | 12 ++ .github/workflows/test.yaml | 27 ----- .gitignore | 2 +- .helmignore | 1 + README.md | 11 -- README2.md | 199 --------------------------------- adoc2md.sh | 4 +- 7 files changed, 16 insertions(+), 240 deletions(-) delete mode 100644 .github/workflows/test.yaml delete mode 100644 README.md delete mode 100644 README2.md diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 8cb394d..a0f7c45 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -14,6 +14,11 @@ jobs: uses: actions/checkout@v2 with: fetch-depth: 0 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: 2.7 + - run: | + gem install asciidoctor - name: nodejs 12 uses: actions/setup-node@v1 with: @@ -40,6 +45,13 @@ jobs: cat /tmp/cmak.version echo "::set-output name=cmakVersion::$(cat /tmp/cmak.version)" - uses: azure/setup-helm@v1 + - run: | + asciidoctor -b docbook -a leveloffset=+1 -o README.md.tmp README.adoc + - uses: docker://pandoc/ubuntu-core:2.12 + with: + args: --markdown-headings=atx --wrap=preserve -t gfm -f docbook -o README.md README.md.tmp + - run: | + ./adoc2md.sh - run: helm package . --version ${{ steps.cmakVersion.outputs.cmakVersion }} - name: upload artifact uses: actions/upload-artifact@v2 diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml deleted file mode 100644 index ef14522..0000000 --- a/.github/workflows/test.yaml +++ /dev/null @@ -1,27 +0,0 @@ -name: Test - -on: - workflow_dispatch - -jobs: - test_job: - name: Test - runs-on: ubuntu-18.04 - steps: - - uses: actions/checkout@v2 - - uses: docker://pandoc/core:2.9 - with: - args: "--help" - - uses: ruby/setup-ruby@v1 - with: - ruby-version: 2.7 - - run: | - gem install asciidoctor - - run: | - asciidoctor --version - pandoc --version - # - uses: actions/upload-artifact@v2 - # with: - # name: "README2" - # path: "README2.md" - diff --git a/.gitignore b/.gitignore index 2f27f23..b5801b6 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,4 @@ package-lock.json package.json .idea values-dev.yaml - +README.md diff --git a/.helmignore b/.helmignore index f02ef3d..b084293 100644 --- a/.helmignore +++ b/.helmignore @@ -33,3 +33,4 @@ venv skaffold.yaml values-lint.yaml node_modules +README.adoc diff --git a/README.md b/README.md deleted file mode 100644 index 87f4309..0000000 --- a/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# CMAK operator - -CMAK operator is a set of tools packaged as Helm chart, -that allows to install and configure [CMAK](https://github.com/yahoo/CMAK) -(previously Kafka Manager) into Kubernetes cluster. - -[CMAK](https://github.com/yahoo/CMAK) (previously Kafka Manager) is well-known -and mature tool for monitoring and managing [Apache Kafka](https://kafka.apache.org/) clusters. - -For detailled instructions about installation and configuration -check [CMAK operator homepage](https://github.com/eshepelyuk/cmak-operator). diff --git a/README2.md b/README2.md deleted file mode 100644 index a4b1a45..0000000 --- a/README2.md +++ /dev/null @@ -1,199 +0,0 @@ -# CMAK operator - -![Release](https://img.shields.io/github/v/tag/eshepelyuk/cmak-operator?logo=github&sort=semver&style=for-the-badge&label=current) -![Docker Hub](https://img.shields.io/docker/pulls/eshepelyuk/cmak-operator-cli?logo=docker&style=for-the-badge) -![Artifact HUB](https://img.shields.io/endpoint?style=for-the-badge&url=https://artifacthub.io/badge/repository/cmak-operator) -![MIT licence](https://img.shields.io/github/license/eshepelyuk/cmak-operator?logo=mit&style=for-the-badge) - -CMAK operator is a set of tools packaged as Helm chart, that allows to install -and configure [CMAK](https://github.com/yahoo/CMAK) -(previously Kafka Manager) into Kubernetes cluster. - -[CMAK](https://github.com/yahoo/CMAK) (previously Kafka Manager) -is well-known and mature tool for monitoring and managing -[Apache Kafka](https://kafka.apache.org/) clusters. - -## Installation - -CMAK operator could be installed only with [Helm 3](https://helm.sh/docs/). -Helm chart is published to public Helm repository, hosted on GitHub itself. - -It’s recommended to install CMAK operator into a dedicated namespace. - -Add Helm repository - - $ helm repo add cmak https://eshepelyuk.github.io/cmak-operator - $ helm repo update - -Install latest version - - $ helm install --create-namespace -n cmak-ns mycmak cmak/cmak-operator - -Search for available versions - - $ helm search repo cmak-operator --versions - NAME CHART VERSION APP VERSION DESCRIPTION - cmak/cmak-operator 0.2.1 3.0.0.5 CMAK operator for K8S. - cmak/cmak-operator 0.2.0 3.0.0.5 CMAK operator for K8S. - -Install specific version - - $ helm install --create-namespace -n cmak-ns --version 0.2.1 mycmak cmak/cmak-operator - -### Verify installation - -
- -By default, CMAK operator doesn’t create neither `Ingress` -nor any other K8S resources to expose UI via HTTP. - -
- -The simpliest test is to port forward CMAK UI HTTP port and access it from browser . - - $ kubectl port-forward -n cmak-ns service/cmak 9000:9000 - -Then, open in your browser. - -## Configuration - -### CMAK application - -CMAK uses configuration file -[/cmak/conf/application.conf](https://github.com/yahoo/CMAK/blob/master/conf/application.conf). -Every parameter could be overriden via JVM system property, i.e. `-DmyProp=myVal`. -Properties are passed to CMAK container via `values.yaml`. - -For example to enable basic auth add following to `values.yaml`. - -``` yaml -ui: - extraArgs: - - "-DbasicAuthentication.enabled=true" - - "-DbasicAuthentication.username=admin" - - "-DbasicAuthentication.password=password" -``` - -### Kafka clusters - -It’s extremely easy to configure multiple clusters in CMAK, -starting from cluster setup, connection settings and ending with authorization -using [Helm values files](https://helm.sh/docs/chart_template_guide/values_files/). - -Check [CMAK operator values](https://artifacthub.io/packages/helm/cmak-operator/cmak-operator?modal=values-schema) -for all available options and their description. - -Minimal values.yaml configuration for adding a several Kafka clusters to CMAK. - -``` yaml -cmak: - clusters: - - name: "cluster-stage" - curatorConfig: - zkConnect: "kafka01.stage:2181,kafka02.stage:2181" - - name: "cluster-prod" - curatorConfig: - zkConnect: "kafka01.prod:2181,kafka02.prod:2181,kafka03.prod:2181" -``` - -Connection settings could be configured for all clusters at once or per dedicated cluster. - -``` yaml -cmak: - clustersCommon: - curatorConfig: - zkMaxRetry: 100 - clusters: - - name: "cluster-stage" - kafkaVersion: "2.5.0" - curatorConfig: - zkConnect: "kafka01.stage:2181,kafka02.stage:2181" - - name: "cluster-prod" - kafkaVersion: "2.1.0" - enabled: false - curatorConfig: - zkConnect: "kafka01.prod:2181,kafka02.prod:2181,kafka03.prod:2181" -``` - -- this setting is applied to both clusters. - -- applied only to `cluster-stage`. - -- applied only to `cluster-prod`. - -Configuration should be passed to helm via command line during installation or upgrade. - -``` bash -$ helm install --create-namespace -n cmak-ns -f cmak-values.yaml mycmak cmak/cmak-operator -``` - -## Architecture - -![Component diagram](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/eshepelyuk/cmak-operator/master/arch.puml) - -CMAK operator comprises following components: - -- [CMAK](https://github.com/yahoo/CMAK/), - powered by [Docker image](https://hub.docker.com/r/hlebalbau/kafka-manager/) - from [@hleb-albau](https://github.com/hleb-albau/kafka-manager-docker). - -- [Apache ZooKeeper](https://zookeeper.apache.org/), - powered by [official Docker image](https://hub.docker.com/_/zookeeper/). - -- Custom [cmak2zk tool](https://hub.docker.com/repository/docker/eshepelyuk/cmak2zk), - used to configure Kafka clusters in CMAK from YAML files. - -Following desing choices were made. - -### Dedicated Zookeeper instance. - -TO BE DEFINED. - -### Not using REST for configuring CMAK clusters. - -TO BE DEFINED. - -### Reconciliation with CronJob. - -TO BE DEFINED. - -## Troubleshooting - -CMAK doesn’t configure clusters from Helm values -- CMAK settings are not applied immediately, but only after `reconcile.schedule` period had passed. - -- Check logs of cron job to see if there’s no connection failure to ZK. - -## Standalone cmak2zk tool - -`cmak2zk` was developed as a part of `CMAK operator` and actively used by the operator itself. -But the same time this tool could be used on its own outside of Helm charts and Kubernetes. - -Its purpose is to take Kafka cluster configuration for CMAK in YAML format -and populate CMAK compatible config in Zookeeper. -This allows to avoid manual configuration of CMAK and provides better possibilities -to use CMAK in declarative configuration or GitOps based flows. - -`cmak2zk` is distributed as docker image -[available at DockerHub](https://hub.docker.com/repository/docker/eshepelyuk/cmak2zk). - -To see available options, run the image without parameters. - - $ docker run eshepelyuk/cmak2zk:1.4.1 - Usage: cmak2zk.py [OPTIONS] ZK_URL YAML_CFG - ..... - -Example `docker-compose` and Kafka cluster configuration are located at `cmak2zk/examples`. -One could run them using commands below. - - $ curl -sLo clusters.yaml \ - https://raw.githubusercontent.com/eshepelyuk/cmak-operator/master/cmak2zk/examples/clusters.yaml - - $ curl -sLo docker-compose-cmak2zk.yaml \ - https://raw.githubusercontent.com/eshepelyuk/cmak-operator/master/cmak2zk/examples/docker-compose-cmak2zk.yaml - - $ docker-compose -f docker-compose-cmak2zk.yaml up - -Wait for some time until components are stabilizing, it may take up to 5 mins. -Then, open your browser at . -There should be two pre configured clusters, pointing to the same Kafka instance, running in Docker. diff --git a/adoc2md.sh b/adoc2md.sh index 92e52b6..a2e9bae 100755 --- a/adoc2md.sh +++ b/adoc2md.sh @@ -1,5 +1,5 @@ #!/bin/bash -asciidoctor -b docbook -a leveloffset=+1 -o - README.adoc | pandoc --markdown-headings=atx --wrap=preserve -t gfm -f docbook - > README2.md +# asciidoctor -b docbook -a leveloffset=+1 -o - README.adoc | pandoc --markdown-headings=atx --wrap=preserve -t gfm -f docbook - > README2.md -sed -i 's/^plantuml::arch.puml.*$/![Component diagram](http:\/\/www.plantuml.com\/plantuml\/proxy?cache=no\&src=https:\/\/raw.githubusercontent.com\/eshepelyuk\/cmak-operator\/master\/arch.puml)/g' README2.md +sed -i 's/^plantuml::arch.puml.*$/![Component diagram](http:\/\/www.plantuml.com\/plantuml\/proxy?cache=no\&src=https:\/\/raw.githubusercontent.com\/eshepelyuk\/cmak-operator\/master\/arch.puml)/g' README.md