Document the OpenSearch operator

deploy/helm/opensearch-operator/configs/properties.yaml

@@ -0,0 +1,5 @@
+---
+version: 0.1.0
+spec:
+  units: []
+properties: []

deploy/helm/opensearch-operator/crds/crds.yaml

@@ -136,9 +136,10 @@ spec:
                         nodeRoles:
                           items:
                             enum:
+                              - cluster_manager
+                              - coordinating_only
                               - data
                               - ingest
-                              - cluster_manager
                               - remote_cluster_client
                               - warm
                               - search
@@ -327,9 +328,10 @@ spec:
                               nodeRoles:
                                 items:
                                   enum:
+                                    - cluster_manager
+                                    - coordinating_only
                                     - data
                                     - ingest
-                                    - cluster_manager
                                     - remote_cluster_client
                                     - warm
                                     - search

docs/antora.yml

@@ -0,0 +1,3 @@
+---
+name: home
+version: "nightly"

docs/modules/opensearch/examples/getting_started/getting_started.sh

@@ -0,0 +1,109 @@
+#! /usr/bin/env bash
+set -euo pipefail
+
+# DO NOT EDIT THE SCRIPT
+# Instead, update the j2 template, and regenerate it for dev with `make render-docs`.
+
+# This script contains all the code snippets from the guide, as well as some assert tests
+# to test if the instructions in the guide work. The user *could* use it, but it is intended
+# for testing only.
+# The script will install the operators, create a OpenSearch instance and briefly open a port
+# forward and connect to the OpenSearch instance to make sure it is up and running.
+# No running processes are left behind (i.e. the port-forwarding is closed at the end)
+
+if [ $# -eq 0 ]
+then
+  echo "Installation method argument ('helm' or 'stackablectl') required."
+  exit 1
+fi
+
+cd "$(dirname "$0")"
+
+case "$1" in
+"helm")
+echo "Installing Operators with Helm"
+# tag::helm-install-operators[]
+helm install --wait commons-operator oci://oci.stackable.tech/sdp-charts/commons-operator --version 0.0.0-dev
+helm install --wait secret-operator oci://oci.stackable.tech/sdp-charts/secret-operator --version 0.0.0-dev
+helm install --wait listener-operator oci://oci.stackable.tech/sdp-charts/listener-operator --version 0.0.0-dev
+helm install --wait opensearch-operator oci://oci.stackable.tech/sdp-charts/opensearch-operator --version 0.0.0-dev
+# end::helm-install-operators[]
+;;
+"stackablectl")
+echo "installing Operators with stackablectl"
+# tag::stackablectl-install-operators[]
+stackablectl operator install \
+  commons=0.0.0-dev \
+  secret=0.0.0-dev \
+  listener=0.0.0-dev \
+  opensearch=0.0.0-dev
+# end::stackablectl-install-operators[]
+;;
+*)
+echo "Need to give 'helm' or 'stackablectl' as an argument for which installation method to use!"
+exit 1
+;;
+esac
+
+echo "Creating OpenSearch security plugin configuration"
+# tag::apply-security-config[]
+kubectl apply -f opensearch-security-config.yaml
+# end::apply-security-config[]
+
+echo "Creating OpenSearch cluster"
+# tag::apply-cluster[]
+kubectl apply -f opensearch.yaml
+# end::apply-cluster[]
+
+sleep 5
+
+for (( i=1; i<=15; i++ ))
+do
+  echo "Waiting for OpenSearchCluster to appear ..."
+  if eval kubectl get statefulset simple-opensearch-nodes-default; then
+    break
+  fi
+
+  sleep 1
+done
+
+echo "Waiting on OpenSearch StatefulSet ..."
+# tag::await-cluster[]
+kubectl rollout status --watch statefulset/simple-opensearch-nodes-default --timeout 600s
+# end::await-cluster[]
+
+# wait a bit for the port to open
+sleep 10
+
+echo "Starting port-forwarding of port 9200"
+# tag::port-forwarding[]
+kubectl port-forward services/simple-opensearch 9200 > /dev/null 2>&1 &
+# end::port-forwarding[]
+PORT_FORWARD_PID=$!
+# shellcheck disable=2064 # we want the PID evaluated now, not at the time the trap is
+trap "kill $PORT_FORWARD_PID" EXIT
+sleep 5
+
+echo "Using the REST API"
+# tag::rest-api[]
+export CREDENTIALS=admin:AJVFsGJBbpT6mChn
+
+curl \
+    --insecure \
+    --user $CREDENTIALS \
+    --request PUT \
+    --json '{"name": "Stackable"}' \
+    https://localhost:9200/sample_index/_doc/1
+
+# Output:
+# {"_index":"sample_index","_id":"1","_version":1,"result":"created","_shards":{"total":2,"successful":1,"failed":0},"_seq_no":0,"_primary_term":1}
+
+curl \
+    --insecure \
+    --user $CREDENTIALS \
+    --request GET \
+    https://localhost:9200/sample_index/_doc/1
+
+# Output:
+# {"_index":"sample_index","_id":"1","_version":1,"_seq_no":0,"_primary_term":1,"found":true,"_source":{"name": "Stackable"}}
+# end::rest-api[]

docs/modules/opensearch/examples/getting_started/getting_started.sh.j2

@@ -0,0 +1,109 @@
+#! /usr/bin/env bash
+set -euo pipefail
+
+# DO NOT EDIT THE SCRIPT
+# Instead, update the j2 template, and regenerate it for dev with `make render-docs`.
+
+# This script contains all the code snippets from the guide, as well as some assert tests
+# to test if the instructions in the guide work. The user *could* use it, but it is intended
+# for testing only.
+# The script will install the operators, create a OpenSearch instance and briefly open a port
+# forward and connect to the OpenSearch instance to make sure it is up and running.
+# No running processes are left behind (i.e. the port-forwarding is closed at the end)
+
+if [ $# -eq 0 ]
+then
+  echo "Installation method argument ('helm' or 'stackablectl') required."
+  exit 1
+fi
+
+cd "$(dirname "$0")"
+
+case "$1" in
+"helm")
+echo "Installing Operators with Helm"
+# tag::helm-install-operators[]
+helm install --wait commons-operator oci://{{ helm.repo_url }}/{{ helm.repo_name }}/commons-operator --version {{ versions.commons }}
+helm install --wait secret-operator oci://{{ helm.repo_url }}/{{ helm.repo_name }}/secret-operator --version {{ versions.secret }}
+helm install --wait listener-operator oci://{{ helm.repo_url }}/{{ helm.repo_name }}/listener-operator --version {{ versions.listener }}
+helm install --wait opensearch-operator oci://{{ helm.repo_url }}/{{ helm.repo_name }}/opensearch-operator --version {{ versions.opensearch }}
+# end::helm-install-operators[]
+;;
+"stackablectl")
+echo "installing Operators with stackablectl"
+# tag::stackablectl-install-operators[]
+stackablectl operator install \
+  commons={{ versions.commons }} \
+  secret={{ versions.secret }} \
+  listener={{ versions.listener }} \
+  opensearch={{ versions.opensearch }}
+# end::stackablectl-install-operators[]
+;;
+*)
+echo "Need to give 'helm' or 'stackablectl' as an argument for which installation method to use!"
+exit 1
+;;
+esac
+
+echo "Creating OpenSearch security plugin configuration"
+# tag::apply-security-config[]
+kubectl apply -f opensearch-security-config.yaml
+# end::apply-security-config[]
+
+echo "Creating OpenSearch cluster"
+# tag::apply-cluster[]
+kubectl apply -f opensearch.yaml
+# end::apply-cluster[]
+
+sleep 5
+
+for (( i=1; i<=15; i++ ))
+do
+  echo "Waiting for OpenSearchCluster to appear ..."
+  if eval kubectl get statefulset simple-opensearch-nodes-default; then
+    break
+  fi
+
+  sleep 1
+done
+
+echo "Waiting on OpenSearch StatefulSet ..."
+# tag::await-cluster[]
+kubectl rollout status --watch statefulset/simple-opensearch-nodes-default --timeout 600s
+# end::await-cluster[]
+
+# wait a bit for the port to open
+sleep 10
+
+echo "Starting port-forwarding of port 9200"
+# tag::port-forwarding[]
+kubectl port-forward services/simple-opensearch 9200 > /dev/null 2>&1 &
+# end::port-forwarding[]
+PORT_FORWARD_PID=$!
+# shellcheck disable=2064 # we want the PID evaluated now, not at the time the trap is
+trap "kill $PORT_FORWARD_PID" EXIT
+sleep 5
+
+echo "Using the REST API"
+# tag::rest-api[]
+export CREDENTIALS=admin:AJVFsGJBbpT6mChn
+
+curl \
+    --insecure \
+    --user $CREDENTIALS \
+    --request PUT \
+    --json '{"name": "Stackable"}' \
+    https://localhost:9200/sample_index/_doc/1
+
+# Output:
+# {"_index":"sample_index","_id":"1","_version":1,"result":"created","_shards":{"total":2,"successful":1,"failed":0},"_seq_no":0,"_primary_term":1}
+
+curl \
+    --insecure \
+    --user $CREDENTIALS \
+    --request GET \
+    https://localhost:9200/sample_index/_doc/1
+
+# Output:
+# {"_index":"sample_index","_id":"1","_version":1,"_seq_no":0,"_primary_term":1,"found":true,"_source":{"name": "Stackable"}}
+# end::rest-api[]

docs/modules/opensearch/examples/getting_started/install_output.txt

@@ -0,0 +1,4 @@
+Installed commons=0.0.0-dev operator
+Installed secret=0.0.0-dev operator
+Installed listener=0.0.0-dev operator
+Installed opensearch=0.0.0-dev operator

docs/modules/opensearch/examples/getting_started/install_output.txt.j2

@@ -0,0 +1,4 @@
+Installed commons={{ versions.commons }} operator
+Installed secret={{ versions.secret }} operator
+Installed listener={{ versions.listener }} operator
+Installed opensearch={{ versions.opensearch }} operator

docs/modules/opensearch/examples/getting_started/opensearch-security-config.yaml

@@ -0,0 +1,94 @@
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: opensearch-security-config
+stringData:
+  action_groups.yml: |
+    ---
+    _meta:
+      type: actiongroups
+      config_version: 2
+  allowlist.yml: |
+    ---
+    _meta:
+      type: allowlist
+      config_version: 2
+
+    config:
+      enabled: false
+  audit.yml: |
+    ---
+    _meta:
+      type: audit
+      config_version: 2
+
+    config:
+      enabled: false
+  config.yml: |
+    ---
+    _meta:
+      type: config
+      config_version: 2
+
+    config:
+      dynamic:
+        authc:
+          basic_internal_auth_domain:
+            description: Authenticate via HTTP Basic against internal users database
+            http_enabled: true
+            transport_enabled: true
+            order: 1
+            http_authenticator:
+              type: basic
+              challenge: true
+            authentication_backend:
+              type: intern
+        authz: {}
+  internal_users.yml: |
+    ---
+    _meta:
+      type: internalusers
+      config_version: 2
+
+    admin:
+      hash: $2y$10$xRtHZFJ9QhG9GcYhRpAGpufCZYsk//nxsuel5URh0GWEBgmiI4Q/e
+      reserved: true
+      backend_roles:
+        - admin
+      description: OpenSearch admin user
+
+    kibanaserver:
+      hash: $2y$10$vPgQ/6ilKDM5utawBqxoR.7euhVQ0qeGl8mPTeKhmFT475WUDrfQS
+      reserved: true
+      description: OpenSearch Dashboards user
+  nodes_dn.yml: |
+    ---
+    _meta:
+      type: nodesdn
+      config_version: 2
+  roles.yml: |
+    ---
+    _meta:
+      type: roles
+      config_version: 2
+  roles_mapping.yml: |
+    ---
+    _meta:
+      type: rolesmapping
+      config_version: 2
+
+    all_access:
+      reserved: false
+      backend_roles:
+        - admin
+
+    kibana_server:
+      reserved: true
+      users:
+        - kibanaserver
+  tenants.yml: |
+    ---
+    _meta:
+      type: tenants
+      config_version: 2