From 22882c535820fcf97d1c8f9f60f3aee788430b47 Mon Sep 17 00:00:00 2001 From: Michael Adam Date: Tue, 22 Aug 2023 12:00:45 +0200 Subject: [PATCH 1/3] multus: auto-update the validation job manifest file with help text Signed-off-by: Michael Adam this change introduces a new 'make target 'docs'that generates part of the documentation It particular, it runs the `helm-docs` target. Additionally, `make docs` updates the multus validation job manifest by inserting the output of `rook multus validation run --help` between two newly introduced markers. The result of running `make docs` is intended to be committed to git after running Fixes: #12706 Signed-off-by: Michael Adam Signed-off-by: Blaine Gardner Co-authored-by: Blaine Gardner Co-authored-by: Michael Adam Update build/deploy/generate-deploy-examples.sh Signed-off-by: Michael Adam --- Makefile | 3 ++ build/deploy/generate-deploy-examples.sh | 24 +++++++++++++++ deploy/examples/multus-validation.yaml | 39 +++++++++++++++++++----- 3 files changed, 58 insertions(+), 8 deletions(-) create mode 100755 build/deploy/generate-deploy-examples.sh diff --git a/Makefile b/Makefile index 3aaed22cc..44736d197 100644 --- a/Makefile +++ b/Makefile @@ -190,6 +190,9 @@ csv: csv-clean crds ## Generate a CSV file for OLM. csv-clean: ## Remove existing OLM files. @$(MAKE) -C images/ceph csv-clean +docs: helm-docs + @build/deploy/generate-deploy-examples.sh + crds: $(CONTROLLER_GEN) $(YQ) @echo Updating CRD manifests @build/crds/build-crds.sh $(CONTROLLER_GEN) $(YQ) diff --git a/build/deploy/generate-deploy-examples.sh b/build/deploy/generate-deploy-examples.sh new file mode 100755 index 000000000..ca276a49a --- /dev/null +++ b/build/deploy/generate-deploy-examples.sh @@ -0,0 +1,24 @@ +#! /usr/bin/env bash +set -e + +SCRIPT_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P) +MANIFEST_FILE=../../deploy/examples/multus-validation.yaml +SED=${SCRIPT_ROOT}/../../build/sed-in-place +if [[ ${SKIP_GEN} = true ]]; then + echo "SKIP_GEN is set, skipping manifest generation" + exit +fi +OUT_FILE="${SCRIPT_ROOT}/${MANIFEST_FILE}" +TMP_FILE="$(mktemp)" + +START_MARKER='# THE BELOW HELP TEXT IS AUTO-GENERATED BY `make docs`$' +END_MARKER='# THE ABOVE HELP TEXT IS AUTO-GENERATED BY `make docs`$' + +go run ${SCRIPT_ROOT}/../../cmd/rook/*.go multus validation run --help | awk '{print "# "$0}' | sed -e 's/[ \t]*$//' > ${TMP_FILE} + +${SED} -e "/$START_MARKER/,/$END_MARKER/{ /$START_MARKER/{ p ; r $TMP_FILE + + }; /$END_MARKER/p; d; }" ${OUT_FILE} + +rm -f ${TMP_FILE} + diff --git a/deploy/examples/multus-validation.yaml b/deploy/examples/multus-validation.yaml index fa3523294..403228caa 100644 --- a/deploy/examples/multus-validation.yaml +++ b/deploy/examples/multus-validation.yaml @@ -1,11 +1,34 @@ -################################################################################################################# -# We highly recommend validating your Multus configuration before you install Rook. -# This job aims to automate that operation by using the validation tool. Run this job after -# installing the rook operator and before installing any Custom Resources. -# Insert the NAD name for public network and cluster network in the Job definition below. -# If you want to use any other flags along with the basic command in the Job, -# add the `--help` flag in the end to see the list of flags available, and use accordingly. -################################################################################################################# +#################################################################################################### +# This manifest contains a Kubernetes Job and supporting definitions for running Rook's Multus +# validation tool. The Multus validation tool's help text is copied below. Modify the Job +# definition in this manifest based on the needs of your cluster. +#################################################################################################### +# THE BELOW HELP TEXT IS AUTO-GENERATED BY `make docs` +# +# Run a validation test that determines whether the current Multus and system +# configurations will support Rook with Multus. +# +# This should be run BEFORE Rook is installed. +# +# +# +# +# +#Flags: +# --cluster-network string The name of the Network Attachment Definition (NAD) that will be used for Ceph's cluster network. This should be a namespaced name in the form / if the NAD is defined in a different namespace from the cluster namespace. +# -c, --config string The validation test config file to use. This cannot be used with other flags. +# --daemons-per-node int The number of validation test daemons to run per node. It is recommended to set this to the maximum number of Ceph daemons that can run on any node in the worst case of node failure(s). The default value is set to the worst-case value for a Rook Ceph cluster with 3 portable OSDs, 3 portable monitors, and where all optional child resources have been created with 1 daemon such that they all might run on a single node in a failure scenario. If you aren't sure what to choose for this value, add 1 for each additional OSD beyond 3. (default 16) +# -h, --help help for run +# -n, --namespace string The namespace for validation test resources. It is recommended to set this to the namespace in which Rook's Ceph cluster will be installed. (default "rook-ceph") +# --nginx-image string The Nginx image used for the validation server and clients. (default "nginxinc/nginx-unprivileged:stable-alpine") +# --public-network string The name of the Network Attachment Definition (NAD) that will be used for Ceph's public network. This should be a namespaced name in the form / if the NAD is defined in a different namespace from the cluster namespace. +# --timeout-minutes timeoutMinutes The time to wait for resources to change to the expected state. For example, for the test web server to start, for test clients to become ready, or for test resources to be deleted. At longest, this may need to reflect the time it takes for client pods to to pull images, get address assignments, and then for each client to determine that its network connection is stable. Minimum: 1 minute. Recommended: 2 minutes or more. (default 3m0s) +# +#Global Flags: +# --log-level string logging level for logging/tracing output (valid values: ERROR,WARNING,INFO,DEBUG) (default "INFO") +# +# THE ABOVE HELP TEXT IS AUTO-GENERATED BY `make docs` +#################################################################################################### --- # Service account for job that validates multus configuration apiVersion: v1 From 585c9a51fc5964743a269267c3c76e307b2fb1ca Mon Sep 17 00:00:00 2001 From: Michael Adam Date: Tue, 22 Aug 2023 16:09:09 +0200 Subject: [PATCH 2/3] ci: update the docs check workflow to run `make docs` instead of `make helm-docs` Signed-off-by: Michael Adam --- .github/workflows/docs-check.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml index d5830c1be..7497b749f 100644 --- a/.github/workflows/docs-check.yml +++ b/.github/workflows/docs-check.yml @@ -33,12 +33,12 @@ jobs: with: python-version: 3.9 - - name: Run helm-docs + - name: Run docs run: | - make helm-docs + make docs DIFF=$(git diff) if [ ! -z "$DIFF" ]; then - echo "Please run 'make helm-docs' locally, commit the updated docs, and push the change. See https://rook.io/docs/rook/latest/Contributing/documentation/#running-helm-docs" + echo "Please run 'make docs' locally, commit the updated docs, and push the change. See https://rook.io/docs/rook/latest/Contributing/documentation/#running-helm-docs" fi git diff --exit-code From 8a6b7786e086afa2a97310909694b945c703d46c Mon Sep 17 00:00:00 2001 From: Michael Adam Date: Thu, 24 Aug 2023 11:34:01 +0200 Subject: [PATCH 3/3] multus: commit updated validation job manifest from `make docs` Signed-off-by: Michael Adam --- deploy/examples/multus-validation.yaml | 33 ++++++++++++++++---------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/deploy/examples/multus-validation.yaml b/deploy/examples/multus-validation.yaml index 403228caa..24105c863 100644 --- a/deploy/examples/multus-validation.yaml +++ b/deploy/examples/multus-validation.yaml @@ -10,23 +10,32 @@ # # This should be run BEFORE Rook is installed. # +# This is a fairly long-running test. It starts up a web server and many +# clients to verify that Multus network communication works properly. # +# It does *not* perform any load testing. Networks that cannot support high +# volumes of Ceph traffic may still encounter runtime issues. This may be +# particularly noticeable with high I/O load or during OSD rebalancing +# (see: https://docs.ceph.com/en/latest/architecture/#rebalancing). +# For example, during Rook or Ceph cluster upgrade. # +# Override the kube config file location by setting the KUBECONFIG environment variable. # +# Usage: +# rook multus validation run [--public-network=] [--cluster-network=] [flags] # -#Flags: -# --cluster-network string The name of the Network Attachment Definition (NAD) that will be used for Ceph's cluster network. This should be a namespaced name in the form / if the NAD is defined in a different namespace from the cluster namespace. -# -c, --config string The validation test config file to use. This cannot be used with other flags. -# --daemons-per-node int The number of validation test daemons to run per node. It is recommended to set this to the maximum number of Ceph daemons that can run on any node in the worst case of node failure(s). The default value is set to the worst-case value for a Rook Ceph cluster with 3 portable OSDs, 3 portable monitors, and where all optional child resources have been created with 1 daemon such that they all might run on a single node in a failure scenario. If you aren't sure what to choose for this value, add 1 for each additional OSD beyond 3. (default 16) -# -h, --help help for run -# -n, --namespace string The namespace for validation test resources. It is recommended to set this to the namespace in which Rook's Ceph cluster will be installed. (default "rook-ceph") -# --nginx-image string The Nginx image used for the validation server and clients. (default "nginxinc/nginx-unprivileged:stable-alpine") -# --public-network string The name of the Network Attachment Definition (NAD) that will be used for Ceph's public network. This should be a namespaced name in the form / if the NAD is defined in a different namespace from the cluster namespace. -# --timeout-minutes timeoutMinutes The time to wait for resources to change to the expected state. For example, for the test web server to start, for test clients to become ready, or for test resources to be deleted. At longest, this may need to reflect the time it takes for client pods to to pull images, get address assignments, and then for each client to determine that its network connection is stable. Minimum: 1 minute. Recommended: 2 minutes or more. (default 3m0s) -# -#Global Flags: -# --log-level string logging level for logging/tracing output (valid values: ERROR,WARNING,INFO,DEBUG) (default "INFO") +# Flags: +# --cluster-network string The name of the Network Attachment Definition (NAD) that will be used for Ceph's cluster network. This should be a namespaced name in the form / if the NAD is defined in a different namespace from the cluster namespace. +# -c, --config string The validation test config file to use. This cannot be used with other flags. +# --daemons-per-node int The number of validation test daemons to run per node. It is recommended to set this to the maximum number of Ceph daemons that can run on any node in the worst case of node failure(s). The default value is set to the worst-case value for a Rook Ceph cluster with 3 portable OSDs, 3 portable monitors, and where all optional child resources have been created with 1 daemon such that they all might run on a single node in a failure scenario. If you aren't sure what to choose for this value, add 1 for each additional OSD beyond 3. (default 16) +# -h, --help help for run +# -n, --namespace string The namespace for validation test resources. It is recommended to set this to the namespace in which Rook's Ceph cluster will be installed. (default "rook-ceph") +# --nginx-image string The Nginx image used for the validation server and clients. (default "nginxinc/nginx-unprivileged:stable-alpine") +# --public-network string The name of the Network Attachment Definition (NAD) that will be used for Ceph's public network. This should be a namespaced name in the form / if the NAD is defined in a different namespace from the cluster namespace. +# --timeout-minutes timeoutMinutes The time to wait for resources to change to the expected state. For example, for the test web server to start, for test clients to become ready, or for test resources to be deleted. At longest, this may need to reflect the time it takes for client pods to to pull images, get address assignments, and then for each client to determine that its network connection is stable. Minimum: 1 minute. Recommended: 2 minutes or more. (default 3m0s) # +# Global Flags: +# --log-level string logging level for logging/tracing output (valid values: ERROR,WARNING,INFO,DEBUG) (default "INFO") # THE ABOVE HELP TEXT IS AUTO-GENERATED BY `make docs` #################################################################################################### ---