[Merged by Bors] - Getting started guide

docs/antora.yml

@@ -2,5 +2,6 @@ name: kafka
 version: "nightly"
 title: Stackable Operator for Apache Kafka
 nav:
+  - modules/getting_started/nav.adoc
   - modules/ROOT/nav.adoc
 prerelease: true

docs/modules/ROOT/nav.adoc

@@ -1,5 +1,4 @@
 * xref:dependencies.adoc[]
-* xref:installation.adoc[]
 * xref:configuration.adoc[]
 * xref:usage.adoc[]
 * Concepts

docs/modules/getting_started/examples/code/getting-started.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# The getting started guide script
+# It uses tagged regions which are included in the documentation
+# https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/
+#
+# There are two variants to go through the guide - using stackablectl or helm
+# The script takes either 'stackablectl' or 'helm' as an argument
+#
+# The script can be run as a test as well, to make sure that the tutorial works
+# It includes some assertions throughout, and at the end especially.
+
+if [ $# -eq 0 ]
+then
+  echo "Installation method argument ('helm' or 'stackablectl') required."
+  exit 1
+fi
+
+case "$1" in
+"helm")
+echo "Adding 'stackable-dev' Helm Chart repository"
+# tag::helm-add-repo[]
+helm repo add stackable-dev https://repo.stackable.tech/repository/helm-dev/
+# end::helm-add-repo[]
+echo "Installing Operators with Helm"
+# tag::helm-install-operators[]
+helm install --wait commons-operator stackable-dev/commons-operator --version 0.3.0-nightly
+helm install --wait secret-operator stackable-dev/secret-operator --version 0.6.0-nightly
+helm install --wait zookeeper-operator stackable-dev/zookeeper-operator --version 0.11.0-nightly
+helm install --wait kafka-operator stackable-dev/kafka-operator --version 0.7.0-nightly
+# end::helm-install-operators[]
+;;
+"stackablectl")
+echo "installing Operators with stackablectl"
+# tag::stackablectl-install-operators[]
+stackablectl operator install \
+  commons=0.3.0-nightly \
+  secret=0.6.0-nightly \
+  zookeeper=0.11.0-nightly \
+  kafka=0.7.0-nightly
+# end::stackablectl-install-operators[]
+;;
+*)
+echo "Need to provide 'helm' or 'stackablectl' as an argument for which installation method to use!"
+exit 1
+;;
+esac
+
+echo "Installing ZooKeeper from zookeeper.yaml"
+# tag::install-zookeeper[]
+kubectl apply -f zookeeper.yaml
+# end::install-zookeeper[]
+
+echo "Installing ZNode from kafka-znode.yaml"
+# tag::install-znode[]
+kubectl apply -f kafka-znode.yaml
+# end::install-znode[]
+
+sleep 5
+
+echo "Awaiting ZooKeeper rollout finish"
+# tag::watch-zookeeper-rollout[]
+kubectl rollout status --watch statefulset/simple-zk-server-default
+# end::watch-zookeeper-rollout[]
+
+echo "Install KafkaCluster from kafka.yaml"
+# tag::install-kafka[]
+kubectl apply -f kafka.yaml
+# end::install-kafka[]
+
+sleep 5
+
+echo "Awaiting Kafka rollout finish"
+# tag::watch-kafka-rollout[]
+kubectl rollout status --watch statefulset/simple-kafka-broker-default
+# end::watch-kafka-rollout[]
+
+echo "Starting port-forwarding of port 9092"
+# tag::port-forwarding[]
+kubectl port-forward svc/simple-kafka 9092 2>&1 >/dev/null &
+# end::port-forwarding[]
+PORT_FORWARD_PID=$!
+trap "kill $PORT_FORWARD_PID" EXIT
+
+sleep 5
+
+echo "Creating test data"
+# tag::kcat-create-data[]
+echo "some test data" > data
+# end::kcat-create-data[]
+
+echo "Writing test data"
+# tag::kcat-write-data[]
+kafkacat -b localhost:9092 -t test-data-topic -P data
+# end::kcat-write-data[]
+
+echo "Reading test data"
+# tag::kcat-read-data[]
+kafkacat -b localhost:9092 -t test-data-topic -C -e > read-data
+# end::kcat-read-data[]
+
+echo "Check contents"
+# tag::kcat-check-data[]
+cat read-data | grep "some test data"
+# end::kcat-check-data[]
+
+echo "Cleanup"
+# tag::kcat-cleanup-data[]
+rm data
+rm read-data
+# end::kcat-cleanup-data[]

docs/modules/getting_started/examples/code/getting-started.sh.j2

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# The getting started guide script
+# It uses tagged regions which are included in the documentation
+# https://docs.asciidoctor.org/asciidoc/latest/directives/include-tagged-regions/
+#
+# There are two variants to go through the guide - using stackablectl or helm
+# The script takes either 'stackablectl' or 'helm' as an argument
+#
+# The script can be run as a test as well, to make sure that the tutorial works
+# It includes some assertions throughout, and at the end especially.
+
+if [ $# -eq 0 ]
+then
+  echo "Installation method argument ('helm' or 'stackablectl') required."
+  exit 1
+fi
+
+case "$1" in
+"helm")
+echo "Adding '{{ helm.repo_name }}' Helm Chart repository"
+# tag::helm-add-repo[]
+helm repo add {{ helm.repo_name }} {{ helm.repo_url }}
+# end::helm-add-repo[]
+echo "Installing Operators with Helm"
+# tag::helm-install-operators[]
+helm install --wait commons-operator {{ helm.repo_name }}/commons-operator --version {{ versions.commons }}
+helm install --wait secret-operator {{ helm.repo_name }}/secret-operator --version {{ versions.secret }}
+helm install --wait zookeeper-operator {{ helm.repo_name }}/zookeeper-operator --version {{ versions.zookeeper }}
+helm install --wait kafka-operator {{ helm.repo_name }}/kafka-operator --version {{ versions.kafka }}
+# end::helm-install-operators[]
+;;
+"stackablectl")
+echo "installing Operators with stackablectl"
+# tag::stackablectl-install-operators[]
+stackablectl operator install \
+  commons={{ versions.commons }} \
+  secret={{ versions.secret }} \
+  zookeeper={{ versions.zookeeper }} \
+  kafka={{ versions.kafka }}
+# end::stackablectl-install-operators[]
+;;
+*)
+echo "Need to provide 'helm' or 'stackablectl' as an argument for which installation method to use!"
+exit 1
+;;
+esac
+
+echo "Installing ZooKeeper from zookeeper.yaml"
+# tag::install-zookeeper[]
+kubectl apply -f zookeeper.yaml
+# end::install-zookeeper[]
+
+echo "Installing ZNode from kafka-znode.yaml"
+# tag::install-znode[]
+kubectl apply -f kafka-znode.yaml
+# end::install-znode[]
+
+sleep 5
+
+echo "Awaiting ZooKeeper rollout finish"
+# tag::watch-zookeeper-rollout[]
+kubectl rollout status --watch statefulset/simple-zk-server-default
+# end::watch-zookeeper-rollout[]
+
+echo "Install KafkaCluster from kafka.yaml"
+# tag::install-kafka[]
+kubectl apply -f kafka.yaml
+# end::install-kafka[]
+
+sleep 5
+
+echo "Awaiting Kafka rollout finish"
+# tag::watch-kafka-rollout[]
+kubectl rollout status --watch statefulset/simple-kafka-broker-default
+# end::watch-kafka-rollout[]
+
+echo "Starting port-forwarding of port 9092"
+# tag::port-forwarding[]
+kubectl port-forward svc/simple-kafka 9092 2>&1 >/dev/null &
+# end::port-forwarding[]
+PORT_FORWARD_PID=$!
+trap "kill $PORT_FORWARD_PID" EXIT
+
+sleep 5
+
+echo "Creating test data"
+# tag::kcat-create-data[]
+echo "some test data" > data
+# end::kcat-create-data[]
+
+echo "Writing test data"
+# tag::kcat-write-data[]
+kafkacat -b localhost:9092 -t test-data-topic -P data
+# end::kcat-write-data[]
+
+echo "Reading test data"
+# tag::kcat-read-data[]
+kafkacat -b localhost:9092 -t test-data-topic -C -e > read-data
+# end::kcat-read-data[]
+
+echo "Check contents"
+# tag::kcat-check-data[]
+cat read-data | grep "some test data"
+# end::kcat-check-data[]
+
+echo "Cleanup"
+# tag::kcat-cleanup-data[]
+rm data
+rm read-data
+# end::kcat-cleanup-data[]

docs/modules/getting_started/examples/code/install-operator-output.txt

@@ -0,0 +1,6 @@
+# tag::stackablectl-install-operators-output[]
+[INFO ] Installing commons operator in version 0.3.0-nightly
+[INFO ] Installing secret operator in version 0.6.0-nightly
+[INFO ] Installing zookeeper operator in version 0.11.0-nightly
+[INFO ] Installing kafka operator in version 0.7.0-nightly
+# end::stackablectl-install-operators-output[]

docs/modules/getting_started/examples/code/install-operator-output.txt.j2

@@ -0,0 +1,6 @@
+# tag::stackablectl-install-operators-output[]
+[INFO ] Installing commons operator in version {{ versions.commons }}
+[INFO ] Installing secret operator in version {{ versions.secret }}
+[INFO ] Installing zookeeper operator in version {{ versions.zookeeper }}
+[INFO ] Installing kafka operator in version {{ versions.kafka }}
+# end::stackablectl-install-operators-output[]

docs/modules/getting_started/examples/code/kafka-znode.yaml

@@ -0,0 +1,8 @@
+---
+apiVersion: zookeeper.stackable.tech/v1alpha1
+kind: ZookeeperZnode
+metadata:
+  name: simple-kafka-znode
+spec:
+  clusterRef:
+    name: simple-zk

docs/modules/getting_started/examples/code/kafka.yaml

@@ -0,0 +1,14 @@
+---
+apiVersion: kafka.stackable.tech/v1alpha1
+kind: KafkaCluster
+metadata:
+  name: simple-kafka
+spec:
+  version: 3.2.0-stackable0.1.0
+  zookeeperConfigMapName: simple-kafka-znode
+  config:
+    tls: null
+  brokers:
+    roleGroups:
+      default:
+        replicas: 3

docs/modules/getting_started/examples/code/zookeeper.yaml

@@ -0,0 +1,11 @@
+---
+apiVersion: zookeeper.stackable.tech/v1alpha1
+kind: ZookeeperCluster
+metadata:
+  name: simple-zk
+spec:
+  version: 3.8.0-stackable0.7.1
+  servers:
+    roleGroups:
+      default:
+        replicas: 3

docs/modules/getting_started/nav.adoc

@@ -0,0 +1,3 @@
+* xref:index.adoc[]
+** xref:installation.adoc[]
+** xref:first_steps.adoc[]