Merge pull request #851 from fao89/dataplanedocs

Add dataplane docs

.github/workflows/docs.yaml

@@ -35,21 +35,22 @@ jobs:
       - name: Build docs
         run: |
           make docs
+          cp docs/index.html index.html
 
       - name: Prepare gh-pages branch
         run: |
-          git restore docs/assemblies/custom_resources.adoc
           git config user.name github-actions
           git config user.email [email protected]
 
           git branch -D gh-pages &>/dev/null || true
-          git checkout -b gh-pages 4cd0193fc6c5bc7e76f3a0148d0447fb0d7fbe6a
+          git checkout --orphan gh-pages
 
       - name: Commit asciidoc docs
         run: |
-          mkdir user dev
-          mv docs_build/ctlplane/index-upstream.html index.html
-          git add index.html
+          mkdir ctlplane dataplane
+          mv docs_build/openstack/ctlplane-upstream.html ctlplane/index.html
+          mv docs_build/openstack/dataplane-upstream.html dataplane/index.html
+          git add index.html ctlplane/index.html dataplane/index.html
           git commit -m "Rendered docs"
 
       - name: Push rendered docs to gh-pages

.pre-commit-config.yaml

@@ -25,6 +25,12 @@ repos:
       entry: make
       args: ['operator-lint']
       pass_filenames: false
+    - id: make-docs
+      name: make-docs
+      language: system
+      entry: make
+      args: ['docs']
+      pass_filenames: false
 
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0

Makefile

@@ -91,7 +91,7 @@ docs-dependencies: .bundle
 	bundle config set --local path 'local/bundle'; bundle install
 
 .PHONY: docs
-docs: manifests docs-dependencies crd-to-markdown  ## Build docs
+docs: manifests docs-dependencies crd-to-markdown  docs-kustomize-examples ## Build docs
 	CRD_MARKDOWN=$(CRD_MARKDOWN) MAKE=$(MAKE) ./docs/build_docs.sh
 
 .PHONY: docs-preview
@@ -106,6 +106,11 @@ docs-watch: docs-preview
 docs-clean:
 	rm -r docs_build
 
+.PHONY: docs-examples
+docs-kustomize-examples: export KUSTOMIZE_VERSION=v5.0.1
+docs-kustomize-examples: yq kustomize ## Generate updated docs from examples using kustomize
+	KUSTOMIZE=$(KUSTOMIZE) LOCALBIN=$(LOCALBIN) ./docs/kustomize_to_docs.sh
+
 ##@ General
 
 # The help target prints out all targets with their descriptions organized

docs/Makefile

@@ -1,16 +1,18 @@
 BUILD = upstream
 BUILD_DIR = ../docs_build
 ROOTDIR = $(realpath .)
-NAME = ctlplane
+NAME = openstack
 DEST_DIR = $(BUILD_DIR)/$(NAME)
-DEST_HTML = $(DEST_DIR)/index-$(BUILD).html
+CTLPLANE_HTML = $(DEST_DIR)/ctlplane-$(BUILD).html
+DATAPLANE_HTML = $(DEST_DIR)/dataplane-$(BUILD).html
 DEST_PDF = $(BUILD_DIR)/$(NAME)-$(BUILD).pdf
 IMAGES_DIR = $(DEST_DIR)/images
 IMAGES_TS = $(DEST_DIR)/.timestamp-images
-MAIN_SOURCE = user.adoc
+CTLPLANE_SOURCE = ctlplane.adoc
+DATAPLANE_SOURCE = dataplane.adoc
 OTHER_SOURCES = $(shell find ./assemblies -type f)
 IMAGES = $(shell find ./images -type f)
-ALL_SOURCES = $(MAIN_SOURCE) $(OTHER_SOURCES) $(IMAGES)
+ALL_SOURCES = $(CTLPLANE_SOURCE) $(OTHER_SOURCES) $(IMAGES)
 UNAME = $(shell uname)
 BUNDLE_EXEC ?= bundle exec
 
@@ -25,7 +27,7 @@ all: html
 
 html: html-latest
 
-html-latest: prepare $(IMAGES_TS) $(DEST_HTML)
+html-latest: prepare $(IMAGES_TS) $(CTLPLANE_HTML) $(DATAPLANE_HTML)
 
 pdf: prepare $(DEST_PDF)
 
@@ -45,7 +47,7 @@ watch-html:
 	done
 
 open-html: html
-	${BROWSER_OPEN} "file://$(realpath $(ROOTDIR)/$(DEST_HTML))"
+	${BROWSER_OPEN} "file://$(realpath $(ROOTDIR)/$(CTLPLANE_HTML))"
 
 open-pdf: pdf
 	${BROWSER_OPEN} "$(realpath $(ROOTDIR)/$(DEST_PDF))"
@@ -54,8 +56,11 @@ $(IMAGES_TS): $(IMAGES)
 	cp $? $(IMAGES_DIR)
 	touch $(IMAGES_TS)
 
-$(DEST_HTML): $(ALL_SOURCES)
-	$(BUNDLE_EXEC) asciidoctor -a source-highlighter=highlightjs -a highlightjs-languages="yaml,bash" -a highlightjs-theme="monokai" -a build=$(BUILD) -b xhtml5 -d book -o $@ $(MAIN_SOURCE)
+$(CTLPLANE_HTML): $(ALL_SOURCES)
+	$(BUNDLE_EXEC) asciidoctor -a source-highlighter=highlightjs -a highlightjs-languages="yaml,bash" -a highlightjs-theme="monokai" -a build=$(BUILD) -b xhtml5 -d book -o $@ $(CTLPLANE_SOURCE)
+
+$(DATAPLANE_HTML): $(ALL_SOURCES)
+	$(BUNDLE_EXEC) asciidoctor -a source-highlighter=highlightjs -a highlightjs-languages="yaml,bash" -a highlightjs-theme="monokai" --failure-level WARN -a build=$(BUILD) -b xhtml5 -d book -o $@ $(DATAPLANE_SOURCE)
 
 $(DEST_PDF): $(ALL_SOURCES)
-	$(BUNDLE_EXEC) asciidoctor-pdf -a build=$(BUILD) -d book -o $@ $(MAIN_SOURCE) $(IMAGES)
+	$(BUNDLE_EXEC) asciidoctor-pdf -a build=$(BUILD) -d book -o $@ $(CTLPLANE_SOURCE) $(IMAGES)

docs/assemblies/ansible.adoc

@@ -0,0 +1,82 @@
+= AnsibleEE runner variables
+
+Number of variables can be used to modify behavior of the AnsibleEE runner
+executing given job, such as timeouts and caching.
+These are expanded in the `env/settings` link:https://github.com/openstack-k8s-operators/edpm-ansible/blob/main/openstack_ansibleee/settings[file].
+And further documented in Ansible Runner link:https://ansible.readthedocs.io/projects/runner/en/stable/intro/#env-settings-settings-for-runner-itself[docs].
+
+All of these variables are left set to sensible defaults, nevertheless, some changes may be necessary,
+depending on particulars of individual deployments.
+
+= Ansible variables
+
+The list of ansible variables that can be set under `ansibleVars` is extensive.
+To understand what variables are available for each service, see the
+documentation in the <<create-openstackdataplaneservices,Create
+OpenStackDataPlaneServices>> section.
+
+Common configurations that can be enabled with `ansibleVars` are also
+documented at xref:common_configurations.adoc[Common Configurations].
+
+[NOTE]
+====
+In the case of `ansibleVars`, the value is merged with that of the value from
+the nodeTemplate. This makes it so that the entire value of `ansibleVars` from
+the nodeTemplate does not need to be reproduced for each node just to set a few
+node specific values.
+====
+
+== Importing ansible variables
+
+`ansibleVarsFrom` allows you to set ansible variables for an `OpenStackDataPlaneNodeSet` by
+referencing either a ConfigMap or a Secret. When you use `ansibleVarsFrom`, all the key-value
+pairs in the referenced ConfigMap or Secret are set as environment variables for the `OpenStackDataPlaneNodeSet`.
+You can also specify a common prefix string.
+
+.Example:
+Adding ansible variables from ConfigMap:
+
+. Create a ConfigMap containing the ansible variables
+
+    apiVersion: v1
+    kind: ConfigMap
+    metadata:
+      name: common-edpm-vars
+    data:
+      edpm_config_var1: value1
+      edpm_config_var2: value2
+
+. Update the `ansibleVarsFrom` with the ConfigMap name
+
+    ansibleVarsFrom:
+      - configMapRef:
+            name: common-edpm-vars
+
+.Example:
+Execute `subscription-manager register` from corresponding Secret
+
+. Create a Secret containing the credentials
+
+    apiVersion: v1
+    kind: Secret
+    metadata:
+      name: subscription-manager
+    data:
+      username: <base64 encoded username>
+      password: <base64 encoded password>
+
+. Update the `ansibleVarsFrom` with the Secret name, and `ansibleVars` with the variables generated from the Secret
+
+    ansibleVarsFrom:
+      - prefix: subscription_manager_
+        secretRef:
+          name: subscription-manager
+    ansibleVars:
+        edpm_bootstrap_command: |
+          subscription-manager register --username {{ subscription_manager_username }} --password {{ subscription_manager_password }}
+
++
+[NOTE]
+====
+Values defined by an ansibleVars with a duplicate key take precedence
+====