diff --git a/.github/workflows/master.yaml b/.github/workflows/master.yaml index 16ef219..929952c 100644 --- a/.github/workflows/master.yaml +++ b/.github/workflows/master.yaml @@ -18,14 +18,16 @@ jobs: - uses: azure/setup-helm@v1 with: version: "3.3.4" + - uses: artis3n/setup-conftest@v0.1.1 - name: helm lint run: | helm lint . --strict helm lint . --strict -f test/linter/values-lint.yaml helm dep up test/linter/subchart && helm lint test/linter/subchart --strict - - uses: volesen/setup-skaffold@v1.1 - with: - version: 'v1.20.0' + # - name: conftest + # run: | + # conftest --version + # helm template . | conftest test --policy test/conftest/policy/ test --output table - - name: start k8s with k3d uses: AbsaOSS/k3d-action@v1.3.1 with: @@ -33,6 +35,9 @@ jobs: use-default-registry: true args: >- --config ./test/e2e/k3d.yaml + - uses: volesen/setup-skaffold@v1.1 + with: + version: 'v1.20.0' - name: build cmak-operator run: | set -x diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml new file mode 100644 index 0000000..ef14522 --- /dev/null +++ b/.github/workflows/test.yaml @@ -0,0 +1,27 @@ +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/README.adoc b/README.adoc index 694a988..9d0114d 100644 --- a/README.adoc +++ b/README.adoc @@ -37,21 +37,24 @@ 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 + [source] -.Add Helm repository ---- $ helm repo add cmak https://eshepelyuk.github.io/cmak-operator $ helm repo update ---- +Install latest version + [source] -.Install latest version ---- $ helm install --create-namespace -n cmak-ns mycmak cmak/cmak-operator ---- +Search for available versions + [source] -.Seach for available versions ---- $ helm search repo cmak-operator --versions NAME CHART VERSION APP VERSION DESCRIPTION @@ -59,8 +62,9 @@ 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 + [source] -.Install specific version ---- $ helm install --create-namespace -n cmak-ns --version 0.2.1 mycmak cmak/cmak-operator ---- @@ -68,7 +72,6 @@ $ helm install --create-namespace -n cmak-ns --version 0.2.1 mycmak cmak/cmak-op === Verify installation [IMPORTANT] -.Exposing CMAK UI ==== By default, CMAK operator doesn't create neither `Ingress` nor any other K8S resources to expose UI via HTTP. @@ -92,10 +95,9 @@ https://github.com/yahoo/CMAK/blob/master/conf/application.conf[/cmak/conf/appli 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 +For example to enable basic auth add following to `values.yaml`. [source,yaml] -.values.yaml ---- ui: extraArgs: @@ -113,7 +115,8 @@ using https://helm.sh/docs/chart_template_guide/values_files/[Helm values files] Check https://artifacthub.io/packages/helm/cmak-operator/cmak-operator?modal=values-schema[CMAK operator values] for all available options and their description. -. Minimal values.yaml configuration for adding a several Kafka clusters to CMAK. +Minimal values.yaml configuration for adding a several Kafka clusters to CMAK. + [source,yaml] ---- cmak: @@ -128,7 +131,6 @@ cmak: Connection settings could be configured for all clusters at once or per dedicated cluster. -. Configuring connection settings [source,yaml] ---- cmak: @@ -152,8 +154,7 @@ cmak: Configuration should be passed to helm via command line during installation or upgrade. -[source] -[subs="attributes"] +[source,bash] ---- $ helm install --create-namespace -n cmak-ns -f cmak-values.yaml mycmak cmak/cmak-operator ---- diff --git a/README2.md b/README2.md new file mode 100644 index 0000000..a4b1a45 --- /dev/null +++ b/README2.md @@ -0,0 +1,199 @@ +# 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 new file mode 100755 index 0000000..92e52b6 --- /dev/null +++ b/adoc2md.sh @@ -0,0 +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 + +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 diff --git a/test/conftest/policy/deployment.rego b/test/conftest/policy/deployment.rego new file mode 100644 index 0000000..63a0cba --- /dev/null +++ b/test/conftest/policy/deployment.rego @@ -0,0 +1,9 @@ +package main + +deny[msg] { + input.kind == "Deployment" + not input.spec.selector.matchLabels["app.kubernetes.io/name"] + not input.spec.selector.matchLabels["app.kubernetes.io/instance"] + + msg := "Containers must provide app.kubernetes.io/name and app.kubernetes.io/instance labels for pod selectors" +}