diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0d06af56..3aa7d999 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -71,3 +71,9 @@ repos: entry: cargo xtask gen-ctl-readme stages: [commit, merge-commit, manual] pass_filenames: false + - id: gen-docs + name: gen-docs + language: system + entry: cargo xtask gen-docs + stages: [commit, merge-commit, manual] + pass_filenames: false diff --git a/Cargo.lock b/Cargo.lock index 7119623a..e96566ac 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3612,6 +3612,7 @@ dependencies = [ "snafu", "stackable-cockpitd", "stackablectl", + "tera", ] [[package]] diff --git a/docs/modules/cockpit/pages/index.adoc b/docs/modules/cockpit/pages/index.adoc index 06accaa4..0bd09183 100644 --- a/docs/modules/cockpit/pages/index.adoc +++ b/docs/modules/cockpit/pages/index.adoc @@ -1,6 +1,10 @@ = Stackable Cockpit -This is a visual dashboard to monitor and control Stackable Data Platform clusters. +IMPORTANT: The Stackable Cockpit is currently an early preview, and is not yet a fully supported component of the +Stackable Data Platform. -IMPORTANT: The Stackable Cockpit is currently an early preview, and is not yet a - fully supported component of the Stackable Data Platform. +The `Cockpit` application is a browser-based management tool which interacts with the Stackable data platform. Currently +it can display deployed stacklets and their status. The display can be compared with the +xref:management:stackablectl:commands/stacklet.adoc#list-stacklets[`stackablectl stacklet list`] command output. + +The installation is described in the xref:installation.adoc[installation guide]. diff --git a/docs/modules/stackablectl/nav.adoc b/docs/modules/stackablectl/nav.adoc index db667849..a67dfb4c 100644 --- a/docs/modules/stackablectl/nav.adoc +++ b/docs/modules/stackablectl/nav.adoc @@ -8,7 +8,7 @@ *** xref:commands/operator.adoc[operator] *** xref:commands/release.adoc[release] *** xref:commands/stack.adoc[stack] -*** xref:commands/stacklets.adoc[stacklets] +*** xref:commands/stacklet.adoc[stacklets] ** xref:customization/index.adoc[] *** xref:customization/add-demo.adoc[] *** xref:customization/add-stack.adoc[] diff --git a/docs/modules/stackablectl/pages/commands/cache.adoc b/docs/modules/stackablectl/pages/commands/cache.adoc index 773e8ef1..8c953be7 100644 --- a/docs/modules/stackablectl/pages/commands/cache.adoc +++ b/docs/modules/stackablectl/pages/commands/cache.adoc @@ -1,85 +1,34 @@ = stackablectl cache -// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! -[source,console] ----- -$ stackablectl cache -Interact with locally cached files - -Usage: cache [OPTIONS] - -Commands: - list List cached files - clean Clean cached files - help Print this message or the help of the given subcommand(s) - -Options: - -l, --log-level - Log level this application uses - - --no-cache - Do not cache the remote (default) demo, stack and release files - - Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually - '$HOME/.cache/stackablectl' when not explicitly set. - - --offline - Do not request any remote files via the network - - -h, --help - Print help (see a summary with '-h') - - -V, --version - Print version - -File options: - -d, --demo-file - Provide one or more additional (custom) demo file(s) +The `cache` command let's you interact with locally cached files. The `stackablectl` tool retrieves release, demo, and +stack definitions from a dedicated GitHub repository. It additionally retrieves Helm / YAML manifests from various other +sources. These files are downloaded once and then cached for one hour. In this time period, the files are not downloaded +again, but instead the locally cached (stored on disk) files are used. Users can opt out of caching by providing the +`--no-cache` flag. - Demos are loaded in the following order: Remote (default) demo file, custom - demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and - lastly demo files provided via the '-d/--demo-file' argument(s). If there are - demos with the same name, the last demo definition will be used. +== General Usage - Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" - to provide multiple additional demo files. +include::management:stackablectl:partial$commands/cache.adoc[] - -s, --stack-file - Provide one or more additional (custom) stack file(s) +== Listing Cached Files - Stacks are loaded in the following order: Remote (default) stack file, custom - stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and - lastly demo files provided via the '-s/--stack-file' argument(s). If there are - stacks with the same name, the last stack definition will be used. +To list currently cached files, use `stackablectl cache list`: - Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" - to provide multiple additional stack files. - - -r, --release-file - Provide one or more additional (custom) release file(s) - - Releases are loaded in the following order: Remote (default) release file, - custom release files provided via the 'STACKABLE_RELEASE_FILES' environment - variable, and lastly release files provided via the '-r/--release-file' - argument(s). If there are releases with the same name, the last release - definition will be used. - - Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" - to provide multiple additional release files. - -Helm repository options: - --helm-repo-stable - Provide a custom Helm stable repository URL - - [default: https://repo.stackable.tech/repository/helm-stable/] - - --helm-repo-test - Provide a custom Helm test repository URL - - [default: https://repo.stackable.tech/repository/helm-test/] +[source,console] +---- +$ stackablectl cache list +┌────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬────────────────┐ +│ FILE ┆ LAST SYNC │ +╞════════════════════════════════════════════════════════════════════════════════════════════════════════════════╪════════════════╡ +│ $HOME/.cache/stackablectl/https---raw-githubusercontent-com-stackabletech-stackablectl-main-stacks-stacks-v2-y ┆ 3 seconds ago │ +│ aml-17447ade21bb02fe827b33ef32404e7cb3866ee169837dead6dfdcd7f7241e07 ┆ │ +├╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤ +│ $HOME/.cache/stackablectl/https---raw-githubusercontent-com-stackabletech-stackablectl-main-demos-demos-v2-yam ┆ 22 seconds ago │ +│ l-a140c16c241efa6dbee780d48843a1975bd1069ee8dd8f936123ffb8ee700739 ┆ │ +└────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴────────────────┘ +---- - --helm-repo-dev - Provide a custom Helm dev repository URL +== Cleaning Cached Files - [default: https://repo.stackable.tech/repository/helm-dev/] ----- +To clean currently cached files, use `stackablectl cache clean`. This will remove **all** cached files, regardless if +the files are expired. To only delete outdated files, add the `--outdated` flag. diff --git a/docs/modules/stackablectl/pages/commands/completions.adoc b/docs/modules/stackablectl/pages/commands/completions.adoc index 07922e3c..45677dfd 100644 --- a/docs/modules/stackablectl/pages/commands/completions.adoc +++ b/docs/modules/stackablectl/pages/commands/completions.adoc @@ -1,86 +1,6 @@ = stackablectl completions -// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! -[source,console] ----- -$ stackablectl completions -Generate shell completions for this tool +The `completions` command allows you to generate shell completions on-the-fly. Usually this is not needed, as we provide +pre-generated files for that. A guide on how to install these files can be found xref:installation.adoc#shell-comps[here]. -Usage: completions [OPTIONS] - -Commands: - bash Generate shell completions for Bash - fish Generate shell completions for Fish - zsh Generate shell completions for ZSH - help Print this message or the help of the given subcommand(s) - -Options: - -l, --log-level - Log level this application uses - - --no-cache - Do not cache the remote (default) demo, stack and release files - - Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually - '$HOME/.cache/stackablectl' when not explicitly set. - - --offline - Do not request any remote files via the network - - -h, --help - Print help (see a summary with '-h') - - -V, --version - Print version - -File options: - -d, --demo-file - Provide one or more additional (custom) demo file(s) - - Demos are loaded in the following order: Remote (default) demo file, custom - demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and - lastly demo files provided via the '-d/--demo-file' argument(s). If there are - demos with the same name, the last demo definition will be used. - - Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" - to provide multiple additional demo files. - - -s, --stack-file - Provide one or more additional (custom) stack file(s) - - Stacks are loaded in the following order: Remote (default) stack file, custom - stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and - lastly demo files provided via the '-s/--stack-file' argument(s). If there are - stacks with the same name, the last stack definition will be used. - - Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" - to provide multiple additional stack files. - - -r, --release-file - Provide one or more additional (custom) release file(s) - - Releases are loaded in the following order: Remote (default) release file, - custom release files provided via the 'STACKABLE_RELEASE_FILES' environment - variable, and lastly release files provided via the '-r/--release-file' - argument(s). If there are releases with the same name, the last release - definition will be used. - - Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" - to provide multiple additional release files. - -Helm repository options: - --helm-repo-stable - Provide a custom Helm stable repository URL - - [default: https://repo.stackable.tech/repository/helm-stable/] - - --helm-repo-test - Provide a custom Helm test repository URL - - [default: https://repo.stackable.tech/repository/helm-test/] - - --helm-repo-dev - Provide a custom Helm dev repository URL - - [default: https://repo.stackable.tech/repository/helm-dev/] ----- +include::management:stackablectl:partial$commands/completions.adoc[] diff --git a/docs/modules/stackablectl/pages/commands/demo.adoc b/docs/modules/stackablectl/pages/commands/demo.adoc index e5c77b8a..ba931a9d 100644 --- a/docs/modules/stackablectl/pages/commands/demo.adoc +++ b/docs/modules/stackablectl/pages/commands/demo.adoc @@ -6,90 +6,7 @@ Stackable data platform, which will provide the required products for the demo. == General Usage -// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! -[source,console] ----- -$ stackablectl demo -Interact with demos, which are end-to-end usage demonstrations of the Stackable data platform - -Usage: demo [OPTIONS] - -Commands: - list List available demos - describe Print out detailed demo information - install Install a specific demo - help Print this message or the help of the given subcommand(s) - -Options: - -l, --log-level - Log level this application uses - - --no-cache - Do not cache the remote (default) demo, stack and release files - - Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually - '$HOME/.cache/stackablectl' when not explicitly set. - - --offline - Do not request any remote files via the network - - -h, --help - Print help (see a summary with '-h') - - -V, --version - Print version - -File options: - -d, --demo-file - Provide one or more additional (custom) demo file(s) - - Demos are loaded in the following order: Remote (default) demo file, custom - demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and - lastly demo files provided via the '-d/--demo-file' argument(s). If there are - demos with the same name, the last demo definition will be used. - - Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" - to provide multiple additional demo files. - - -s, --stack-file - Provide one or more additional (custom) stack file(s) - - Stacks are loaded in the following order: Remote (default) stack file, custom - stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and - lastly demo files provided via the '-s/--stack-file' argument(s). If there are - stacks with the same name, the last stack definition will be used. - - Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" - to provide multiple additional stack files. - - -r, --release-file - Provide one or more additional (custom) release file(s) - - Releases are loaded in the following order: Remote (default) release file, - custom release files provided via the 'STACKABLE_RELEASE_FILES' environment - variable, and lastly release files provided via the '-r/--release-file' - argument(s). If there are releases with the same name, the last release - definition will be used. - - Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" - to provide multiple additional release files. - -Helm repository options: - --helm-repo-stable - Provide a custom Helm stable repository URL - - [default: https://repo.stackable.tech/repository/helm-stable/] - - --helm-repo-test - Provide a custom Helm test repository URL - - [default: https://repo.stackable.tech/repository/helm-test/] - - --helm-repo-dev - Provide a custom Helm dev repository URL - - [default: https://repo.stackable.tech/repository/helm-dev/] ----- +include::management:stackablectl:partial$commands/demo.adoc[] == Browse Available Demos @@ -228,7 +145,7 @@ everything should settle down. === Listing Deployed Stacklets -After installing your demo you can use the xref:commands/stacklets.adoc[`stackablectl stacklets`] command to list the +After installing your demo you can use the xref:commands/stacklet.adoc[`stackablectl stacklets`] command to list the installed stacklets as follows: [source,console] diff --git a/docs/modules/stackablectl/pages/commands/index.adoc b/docs/modules/stackablectl/pages/commands/index.adoc index 1d9d38df..f694d4cf 100644 --- a/docs/modules/stackablectl/pages/commands/index.adoc +++ b/docs/modules/stackablectl/pages/commands/index.adoc @@ -1,90 +1,3 @@ == General Usage -// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! -[source,console] ----- -$ stackablectl -Command line tool to interact with the Stackable Data Platform - -Usage: stackablectl [OPTIONS] - -Commands: - operator Interact with single operator instead of the full platform - release Interact with all operators of the platform which are released together - stack Interact with stacks, which are ready-to-use product combinations - stacklets Interact with deployed stacklets, which are bundles of resources and containers required to run the product - demo Interact with demos, which are end-to-end usage demonstrations of the Stackable data platform - completions Generate shell completions for this tool - cache Interact with locally cached files - help Print this message or the help of the given subcommand(s) - -Options: - -l, --log-level - Log level this application uses - - --no-cache - Do not cache the remote (default) demo, stack and release files - - Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually - '$HOME/.cache/stackablectl' when not explicitly set. - - --offline - Do not request any remote files via the network - - -h, --help - Print help (see a summary with '-h') - - -V, --version - Print version - -File options: - -d, --demo-file - Provide one or more additional (custom) demo file(s) - - Demos are loaded in the following order: Remote (default) demo file, custom - demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and - lastly demo files provided via the '-d/--demo-file' argument(s). If there are - demos with the same name, the last demo definition will be used. - - Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" - to provide multiple additional demo files. - - -s, --stack-file - Provide one or more additional (custom) stack file(s) - - Stacks are loaded in the following order: Remote (default) stack file, custom - stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and - lastly demo files provided via the '-s/--stack-file' argument(s). If there are - stacks with the same name, the last stack definition will be used. - - Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" - to provide multiple additional stack files. - - -r, --release-file - Provide one or more additional (custom) release file(s) - - Releases are loaded in the following order: Remote (default) release file, - custom release files provided via the 'STACKABLE_RELEASE_FILES' environment - variable, and lastly release files provided via the '-r/--release-file' - argument(s). If there are releases with the same name, the last release - definition will be used. - - Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" - to provide multiple additional release files. - -Helm repository options: - --helm-repo-stable - Provide a custom Helm stable repository URL - - [default: https://repo.stackable.tech/repository/helm-stable/] - - --helm-repo-test - Provide a custom Helm test repository URL - - [default: https://repo.stackable.tech/repository/helm-test/] - - --helm-repo-dev - Provide a custom Helm dev repository URL - - [default: https://repo.stackable.tech/repository/helm-dev/] ----- +include::management:stackablectl:partial$commands/index.adoc[] diff --git a/docs/modules/stackablectl/pages/commands/operator.adoc b/docs/modules/stackablectl/pages/commands/operator.adoc index a20c84f3..3ec09e67 100644 --- a/docs/modules/stackablectl/pages/commands/operator.adoc +++ b/docs/modules/stackablectl/pages/commands/operator.adoc @@ -11,92 +11,7 @@ operators from an official Stackable release. == General Usage -// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! -[source,console] ----- -$ stackablectl operator -Interact with single operator instead of the full platform - -Usage: operator [OPTIONS] - -Commands: - list List available operators - describe Print out detailed operator information - install Install one or more operators - uninstall Uninstall one or more operators - installed List installed operators - help Print this message or the help of the given subcommand(s) - -Options: - -l, --log-level - Log level this application uses - - --no-cache - Do not cache the remote (default) demo, stack and release files - - Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually - '$HOME/.cache/stackablectl' when not explicitly set. - - --offline - Do not request any remote files via the network - - -h, --help - Print help (see a summary with '-h') - - -V, --version - Print version - -File options: - -d, --demo-file - Provide one or more additional (custom) demo file(s) - - Demos are loaded in the following order: Remote (default) demo file, custom - demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and - lastly demo files provided via the '-d/--demo-file' argument(s). If there are - demos with the same name, the last demo definition will be used. - - Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" - to provide multiple additional demo files. - - -s, --stack-file - Provide one or more additional (custom) stack file(s) - - Stacks are loaded in the following order: Remote (default) stack file, custom - stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and - lastly demo files provided via the '-s/--stack-file' argument(s). If there are - stacks with the same name, the last stack definition will be used. - - Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" - to provide multiple additional stack files. - - -r, --release-file - Provide one or more additional (custom) release file(s) - - Releases are loaded in the following order: Remote (default) release file, - custom release files provided via the 'STACKABLE_RELEASE_FILES' environment - variable, and lastly release files provided via the '-r/--release-file' - argument(s). If there are releases with the same name, the last release - definition will be used. - - Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" - to provide multiple additional release files. - -Helm repository options: - --helm-repo-stable - Provide a custom Helm stable repository URL - - [default: https://repo.stackable.tech/repository/helm-stable/] - - --helm-repo-test - Provide a custom Helm test repository URL - - [default: https://repo.stackable.tech/repository/helm-test/] - - --helm-repo-dev - Provide a custom Helm dev repository URL - - [default: https://repo.stackable.tech/repository/helm-dev/] ----- +include::management:stackablectl:partial$commands/operator.adoc[] == Listing Available Operators diff --git a/docs/modules/stackablectl/pages/commands/release.adoc b/docs/modules/stackablectl/pages/commands/release.adoc index bffde9a2..148f2228 100644 --- a/docs/modules/stackablectl/pages/commands/release.adoc +++ b/docs/modules/stackablectl/pages/commands/release.adoc @@ -5,91 +5,7 @@ A release is a bundle of operators of a specific stable version. The stable vers proven to work hand in hand. If you want to install a single individual operator, look at the xref:commands/operator.adoc[] command. -// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! -[source,console] ----- -$ stackablectl release -Interact with all operators of the platform which are released together - -Usage: release [OPTIONS] - -Commands: - list List available releases - describe Print out detailed release information - install Install a specific release - uninstall Uninstall a release - help Print this message or the help of the given subcommand(s) - -Options: - -l, --log-level - Log level this application uses - - --no-cache - Do not cache the remote (default) demo, stack and release files - - Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually - '$HOME/.cache/stackablectl' when not explicitly set. - - --offline - Do not request any remote files via the network - - -h, --help - Print help (see a summary with '-h') - - -V, --version - Print version - -File options: - -d, --demo-file - Provide one or more additional (custom) demo file(s) - - Demos are loaded in the following order: Remote (default) demo file, custom - demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and - lastly demo files provided via the '-d/--demo-file' argument(s). If there are - demos with the same name, the last demo definition will be used. - - Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" - to provide multiple additional demo files. - - -s, --stack-file - Provide one or more additional (custom) stack file(s) - - Stacks are loaded in the following order: Remote (default) stack file, custom - stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and - lastly demo files provided via the '-s/--stack-file' argument(s). If there are - stacks with the same name, the last stack definition will be used. - - Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" - to provide multiple additional stack files. - - -r, --release-file - Provide one or more additional (custom) release file(s) - - Releases are loaded in the following order: Remote (default) release file, - custom release files provided via the 'STACKABLE_RELEASE_FILES' environment - variable, and lastly release files provided via the '-r/--release-file' - argument(s). If there are releases with the same name, the last release - definition will be used. - - Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" - to provide multiple additional release files. - -Helm repository options: - --helm-repo-stable - Provide a custom Helm stable repository URL - - [default: https://repo.stackable.tech/repository/helm-stable/] - - --helm-repo-test - Provide a custom Helm test repository URL - - [default: https://repo.stackable.tech/repository/helm-test/] - - --helm-repo-dev - Provide a custom Helm dev repository URL - - [default: https://repo.stackable.tech/repository/helm-dev/] ----- +include::management:stackablectl:partial$commands/release.adoc[] == Browsing Available Releases diff --git a/docs/modules/stackablectl/pages/commands/stack.adoc b/docs/modules/stackablectl/pages/commands/stack.adoc index 6e6ee220..36963875 100644 --- a/docs/modules/stackablectl/pages/commands/stack.adoc +++ b/docs/modules/stackablectl/pages/commands/stack.adoc @@ -1,87 +1,91 @@ = stackablectl stack :page-aliases: stackablectl::commands/stack.adoc -// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! -[source,console] ----- -$ stackablectl stack -Interact with stacks, which are ready-to-use product combinations - -Usage: stack [OPTIONS] - -Commands: - list List available stacks - describe Describe a specific stack - install Install a specific stack - help Print this message or the help of the given subcommand(s) - -Options: - -l, --log-level - Log level this application uses - - --no-cache - Do not cache the remote (default) demo, stack and release files +A stack is a collection of ready-to-use Stackable data products as well as required third-party services like Postgresql +or MinIO. It is tied to a specific release of the Stackable data platform, which will provide the required operators for +the stack. - Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually - '$HOME/.cache/stackablectl' when not explicitly set. +== General Usage - --offline - Do not request any remote files via the network +include::management:stackablectl:partial$commands/stack.adoc[] - -h, --help - Print help (see a summary with '-h') +== Listing Available Stacks - -V, --version - Print version +To list available stacks, use `stackablectl stack list`. -File options: - -d, --demo-file - Provide one or more additional (custom) demo file(s) - - Demos are loaded in the following order: Remote (default) demo file, custom - demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and - lastly demo files provided via the '-d/--demo-file' argument(s). If there are - demos with the same name, the last demo definition will be used. - - Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" - to provide multiple additional demo files. - - -s, --stack-file - Provide one or more additional (custom) stack file(s) - - Stacks are loaded in the following order: Remote (default) stack file, custom - stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and - lastly demo files provided via the '-s/--stack-file' argument(s). If there are - stacks with the same name, the last stack definition will be used. +[source,console] +---- +$ stackablectl stack list +┌────┬────────────────────────────────────┬─────────┬─────────────────────────────────────────────────────────────────────────────────────────────────────┐ +│ # ┆ STACK ┆ RELEASE ┆ DESCRIPTION │ +╞════╪════════════════════════════════════╪═════════╪═════════════════════════════════════════════════════════════════════════════════════════════════════╡ +│ 1 ┆ monitoring ┆ 23.7 ┆ Stack containing Prometheus and Grafana │ +├╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤ +│ 2 ┆ ... ┆ ... ┆ ... │ +├╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤ +│ 13 ┆ openldap ┆ 23.7 ┆ An OpenLDAP instance with two users (alice:alice, bob:bob) and TLS enabled. The bind user │ +│ ┆ ┆ ┆ credentials are: ldapadmin:ldapadminpassword. The LDAP AuthenticationClass is called 'ldap' and the │ +│ ┆ ┆ ┆ SecretClass for the bind credentials is called 'ldap-bind-credentials'. The stack already creates │ +│ ┆ ┆ ┆ an appropriate Secret, so referring to the 'ldap' AuthenticationClass in your ProductCluster should │ +│ ┆ ┆ ┆ be enough. │ +└────┴────────────────────────────────────┴─────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────┘ +---- - Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" - to provide multiple additional stack files. +Detailed information of a stack can be queried with the `stackableclt stack describe` command. - -r, --release-file - Provide one or more additional (custom) release file(s) +[source,console] +---- +$ stackablectl stack describe monitoring + STACK monitoring + DESCRIPTION Stack containing Prometheus and Grafana + RELEASE 23.7 + OPERATORS commons + LABELS monitoring, prometheus, grafana + PARAMETERS NAME DESCRIPTION DEFAULT VALUE + grafanaAdminPassword Password of the Grafana admin user adminadmin +---- - Releases are loaded in the following order: Remote (default) release file, - custom release files provided via the 'STACKABLE_RELEASE_FILES' environment - variable, and lastly release files provided via the '-r/--release-file' - argument(s). If there are releases with the same name, the last release - definition will be used. +== Installing a Stack - Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" - to provide multiple additional release files. +=== Using Existing Kubernetes Cluster -Helm repository options: - --helm-repo-stable - Provide a custom Helm stable repository URL +If you want to access a Kubernetes cluster, make sure your https://kubernetes.io/docs/tasks/tools/#kubectl[`kubectl`] +Kubernetes client is configured to interact with the Kubernetes cluster. After that run the following command: - [default: https://repo.stackable.tech/repository/helm-stable/] +[source,console] +---- +$ stackablectl stack install logging +Installed stack logging - --helm-repo-test - Provide a custom Helm test repository URL +Use "stackablectl operator installed" to display the installed operators +Use "stackablectl stacklet list" to display the installed stacklets +---- - [default: https://repo.stackable.tech/repository/helm-test/] +=== Using Local Kind Cluster - --helm-repo-dev - Provide a custom Helm dev repository URL +If you don't have a Kubernetes cluster available, `stackablectl` can spin up a https://kind.sigs.k8s.io/[kind] +Kubernetes cluster for you. Make sure you have `kind` installed and run the following command: - [default: https://repo.stackable.tech/repository/helm-dev/] +[source,console] +---- +$ stackablectl stack install logging --cluster kind +Creating cluster "stackable-data-platform" ... + ✓ Ensuring node image (kindest/node:v1.26.3) 🖼 + ✓ Preparing nodes 📦 📦 + ✓ Writing configuration 📜 + ✓ Starting control-plane 🕹️ + ✓ Installing CNI 🔌 + ✓ Installing StorageClass 💾 + ✓ Joining worker nodes 🚜 +Set kubectl context to "kind-stackable-data-platform" +You can now use your cluster with: + +kubectl cluster-info --context kind-stackable-data-platform + +Have a nice day! 👋 + +Installed stack logging + +Use "stackablectl operator installed" to display the installed operators +Use "stackablectl stacklet list" to display the installed stacklets ---- diff --git a/docs/modules/stackablectl/pages/commands/stacklet.adoc b/docs/modules/stackablectl/pages/commands/stacklet.adoc new file mode 100644 index 00000000..044aa587 --- /dev/null +++ b/docs/modules/stackablectl/pages/commands/stacklet.adoc @@ -0,0 +1,39 @@ += stackablectl stacklets +:page-aliases: stackablectl::commands/services.adoc + +The `stacklet` command allows you to interact with deployed stacklets, which are bundles of resources and containers +required to run the product. + +== General Usage + +include::management:stackablectl:partial$commands/stacklet.adoc[] + +[#iist-stacklets] +== Listing Deployed Stacklets + +[source,console] +---- +$ stackablectl stacklet list + +┌──────────┬───────────────┬───────────┬──────────────────────────────────────────────┬─────────────────────────────────┐ +│ PRODUCT ┆ NAME ┆ NAMESPACE ┆ ENDPOINTS ┆ CONDITIONS │ +╞══════════╪═══════════════╪═══════════╪══════════════════════════════════════════════╪═════════════════════════════════╡ +│ hive ┆ hive ┆ default ┆ ┆ Available, Reconciling, Running │ +├╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤ +│ opa ┆ opa ┆ default ┆ ┆ Available, Reconciling, Running │ +├╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤ +│ superset ┆ superset ┆ default ┆ external-superset http://172.18.0.3:31974 ┆ Available, Reconciling, Running │ +├╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤ +│ trino ┆ trino ┆ default ┆ coordinator-metrics 172.18.0.3:30788 ┆ Available, Reconciling, Running │ +│ ┆ ┆ ┆ coordinator-https https://172.18.0.3:31010 ┆ │ +├╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤ +│ minio ┆ minio-console ┆ default ┆ http http://172.18.0.3:32650 ┆ │ +└──────────┴───────────────┴───────────┴──────────────────────────────────────────────┴─────────────────────────────────┘ + +Use "stackablectl stacklet credentials [OPTIONS] " to display credentials for deployed stacklets. +---- + +More information about the conditions displayed in the last column can be found in +xref:home:contributor:adr/ADR027-status.adoc[ADR 27: Resource Status]. An empty conditions column indicates that the +displayed stacklet is not part of the SDP and most likely an external product. Such products don't contain the required +status field. See the xref:home:demos:index.adoc[demo page] for more information on supported products. diff --git a/docs/modules/stackablectl/pages/index.adoc b/docs/modules/stackablectl/pages/index.adoc index 248acc52..78e1320b 100644 --- a/docs/modules/stackablectl/pages/index.adoc +++ b/docs/modules/stackablectl/pages/index.adoc @@ -5,8 +5,8 @@ The `stackablectl` command line tool interacts with the Stackable data platform. operators as well as platform releases. It also ships with a set of pre-built xref:commands/demo.adoc[`demos`] that utilize different data products of the Platform, e.g. an end-to-end data pipeline. -The installation of `stackablectl` is described in xref:installation.adoc[installation guide]. To get started, please -follow the xref:quickstart.adoc[quickstart guide]. +The installation of `stackablectl` is described in the xref:installation.adoc[installation guide]. To get started, +please follow the xref:quickstart.adoc[quickstart guide]. In general, use `stackablectl --help` to find out more about how to use the tool or specific options. Every subcommand supports the help flag. For example, `stackablectl release install --help` will show the usage test for installing a diff --git a/docs/modules/stackablectl/pages/installation.adoc b/docs/modules/stackablectl/pages/installation.adoc index e5ec9231..95c92b72 100644 --- a/docs/modules/stackablectl/pages/installation.adoc +++ b/docs/modules/stackablectl/pages/installation.adoc @@ -84,6 +84,7 @@ access it from anywhere if you like: cp target/release/stackablectl /usr/local/bin ---- +[#shell-comps] == Shell Completions We provide completions for `stackablectl` for major shells out there. Currently, ZSH, Fish and Bash are supported. The diff --git a/docs/modules/stackablectl/partials/commands/cache.adoc b/docs/modules/stackablectl/partials/commands/cache.adoc new file mode 100644 index 00000000..7c3f98f1 --- /dev/null +++ b/docs/modules/stackablectl/partials/commands/cache.adoc @@ -0,0 +1,82 @@ +// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! +[source,console] +---- +Interact with locally cached files + +Usage: stackablectl cache [OPTIONS] + +Commands: + list List cached files + clean Clean cached files + help Print this message or the help of the given subcommand(s) + +Options: + -l, --log-level + Log level this application uses + + --no-cache + Do not cache the remote (default) demo, stack and release files + + Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually + '$HOME/.cache/stackablectl' when not explicitly set. + + --offline + Do not request any remote files via the network + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version + +File options: + -d, --demo-file + Provide one or more additional (custom) demo file(s) + + Demos are loaded in the following order: Remote (default) demo file, custom + demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and + lastly demo files provided via the '-d/--demo-file' argument(s). If there are + demos with the same name, the last demo definition will be used. + + Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" + to provide multiple additional demo files. + + -s, --stack-file + Provide one or more additional (custom) stack file(s) + + Stacks are loaded in the following order: Remote (default) stack file, custom + stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and + lastly demo files provided via the '-s/--stack-file' argument(s). If there are + stacks with the same name, the last stack definition will be used. + + Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" + to provide multiple additional stack files. + + -r, --release-file + Provide one or more additional (custom) release file(s) + + Releases are loaded in the following order: Remote (default) release file, + custom release files provided via the 'STACKABLE_RELEASE_FILES' environment + variable, and lastly release files provided via the '-r/--release-file' + argument(s). If there are releases with the same name, the last release + definition will be used. + + Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" + to provide multiple additional release files. + +Helm repository options: + --helm-repo-stable + Provide a custom Helm stable repository URL + + [default: https://repo.stackable.tech/repository/helm-stable/] + + --helm-repo-test + Provide a custom Helm test repository URL + + [default: https://repo.stackable.tech/repository/helm-test/] + + --helm-repo-dev + Provide a custom Helm dev repository URL + + [default: https://repo.stackable.tech/repository/helm-dev/] +---- diff --git a/docs/modules/stackablectl/partials/commands/completions.adoc b/docs/modules/stackablectl/partials/commands/completions.adoc new file mode 100644 index 00000000..256b8481 --- /dev/null +++ b/docs/modules/stackablectl/partials/commands/completions.adoc @@ -0,0 +1,83 @@ +// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! +[source,console] +---- +Generate shell completions for this tool + +Usage: stackablectl completions [OPTIONS] + +Commands: + bash Generate shell completions for Bash + fish Generate shell completions for Fish + zsh Generate shell completions for ZSH + help Print this message or the help of the given subcommand(s) + +Options: + -l, --log-level + Log level this application uses + + --no-cache + Do not cache the remote (default) demo, stack and release files + + Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually + '$HOME/.cache/stackablectl' when not explicitly set. + + --offline + Do not request any remote files via the network + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version + +File options: + -d, --demo-file + Provide one or more additional (custom) demo file(s) + + Demos are loaded in the following order: Remote (default) demo file, custom + demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and + lastly demo files provided via the '-d/--demo-file' argument(s). If there are + demos with the same name, the last demo definition will be used. + + Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" + to provide multiple additional demo files. + + -s, --stack-file + Provide one or more additional (custom) stack file(s) + + Stacks are loaded in the following order: Remote (default) stack file, custom + stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and + lastly demo files provided via the '-s/--stack-file' argument(s). If there are + stacks with the same name, the last stack definition will be used. + + Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" + to provide multiple additional stack files. + + -r, --release-file + Provide one or more additional (custom) release file(s) + + Releases are loaded in the following order: Remote (default) release file, + custom release files provided via the 'STACKABLE_RELEASE_FILES' environment + variable, and lastly release files provided via the '-r/--release-file' + argument(s). If there are releases with the same name, the last release + definition will be used. + + Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" + to provide multiple additional release files. + +Helm repository options: + --helm-repo-stable + Provide a custom Helm stable repository URL + + [default: https://repo.stackable.tech/repository/helm-stable/] + + --helm-repo-test + Provide a custom Helm test repository URL + + [default: https://repo.stackable.tech/repository/helm-test/] + + --helm-repo-dev + Provide a custom Helm dev repository URL + + [default: https://repo.stackable.tech/repository/helm-dev/] +---- diff --git a/docs/modules/stackablectl/partials/commands/demo.adoc b/docs/modules/stackablectl/partials/commands/demo.adoc new file mode 100644 index 00000000..cbd25a6c --- /dev/null +++ b/docs/modules/stackablectl/partials/commands/demo.adoc @@ -0,0 +1,83 @@ +// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! +[source,console] +---- +Interact with demos, which are end-to-end usage demonstrations of the Stackable data platform + +Usage: stackablectl demo [OPTIONS] + +Commands: + list List available demos + describe Print out detailed demo information + install Install a specific demo + help Print this message or the help of the given subcommand(s) + +Options: + -l, --log-level + Log level this application uses + + --no-cache + Do not cache the remote (default) demo, stack and release files + + Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually + '$HOME/.cache/stackablectl' when not explicitly set. + + --offline + Do not request any remote files via the network + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version + +File options: + -d, --demo-file + Provide one or more additional (custom) demo file(s) + + Demos are loaded in the following order: Remote (default) demo file, custom + demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and + lastly demo files provided via the '-d/--demo-file' argument(s). If there are + demos with the same name, the last demo definition will be used. + + Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" + to provide multiple additional demo files. + + -s, --stack-file + Provide one or more additional (custom) stack file(s) + + Stacks are loaded in the following order: Remote (default) stack file, custom + stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and + lastly demo files provided via the '-s/--stack-file' argument(s). If there are + stacks with the same name, the last stack definition will be used. + + Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" + to provide multiple additional stack files. + + -r, --release-file + Provide one or more additional (custom) release file(s) + + Releases are loaded in the following order: Remote (default) release file, + custom release files provided via the 'STACKABLE_RELEASE_FILES' environment + variable, and lastly release files provided via the '-r/--release-file' + argument(s). If there are releases with the same name, the last release + definition will be used. + + Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" + to provide multiple additional release files. + +Helm repository options: + --helm-repo-stable + Provide a custom Helm stable repository URL + + [default: https://repo.stackable.tech/repository/helm-stable/] + + --helm-repo-test + Provide a custom Helm test repository URL + + [default: https://repo.stackable.tech/repository/helm-test/] + + --helm-repo-dev + Provide a custom Helm dev repository URL + + [default: https://repo.stackable.tech/repository/helm-dev/] +---- diff --git a/docs/modules/stackablectl/partials/commands/index.adoc b/docs/modules/stackablectl/partials/commands/index.adoc new file mode 100644 index 00000000..b54a62c6 --- /dev/null +++ b/docs/modules/stackablectl/partials/commands/index.adoc @@ -0,0 +1,87 @@ +// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! +[source,console] +---- +Command line tool to interact with the Stackable Data Platform + +Usage: stackablectl [OPTIONS] + +Commands: + operator Interact with single operator instead of the full platform + release Interact with all operators of the platform which are released together + stack Interact with stacks, which are ready-to-use product combinations + stacklet Interact with deployed stacklets, which are bundles of resources and containers required to run the product + demo Interact with demos, which are end-to-end usage demonstrations of the Stackable data platform + completions Generate shell completions for this tool + cache Interact with locally cached files + help Print this message or the help of the given subcommand(s) + +Options: + -l, --log-level + Log level this application uses + + --no-cache + Do not cache the remote (default) demo, stack and release files + + Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually + '$HOME/.cache/stackablectl' when not explicitly set. + + --offline + Do not request any remote files via the network + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version + +File options: + -d, --demo-file + Provide one or more additional (custom) demo file(s) + + Demos are loaded in the following order: Remote (default) demo file, custom + demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and + lastly demo files provided via the '-d/--demo-file' argument(s). If there are + demos with the same name, the last demo definition will be used. + + Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" + to provide multiple additional demo files. + + -s, --stack-file + Provide one or more additional (custom) stack file(s) + + Stacks are loaded in the following order: Remote (default) stack file, custom + stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and + lastly demo files provided via the '-s/--stack-file' argument(s). If there are + stacks with the same name, the last stack definition will be used. + + Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" + to provide multiple additional stack files. + + -r, --release-file + Provide one or more additional (custom) release file(s) + + Releases are loaded in the following order: Remote (default) release file, + custom release files provided via the 'STACKABLE_RELEASE_FILES' environment + variable, and lastly release files provided via the '-r/--release-file' + argument(s). If there are releases with the same name, the last release + definition will be used. + + Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" + to provide multiple additional release files. + +Helm repository options: + --helm-repo-stable + Provide a custom Helm stable repository URL + + [default: https://repo.stackable.tech/repository/helm-stable/] + + --helm-repo-test + Provide a custom Helm test repository URL + + [default: https://repo.stackable.tech/repository/helm-test/] + + --helm-repo-dev + Provide a custom Helm dev repository URL + + [default: https://repo.stackable.tech/repository/helm-dev/] +---- diff --git a/docs/modules/stackablectl/partials/commands/operator.adoc b/docs/modules/stackablectl/partials/commands/operator.adoc new file mode 100644 index 00000000..585f43d3 --- /dev/null +++ b/docs/modules/stackablectl/partials/commands/operator.adoc @@ -0,0 +1,85 @@ +// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! +[source,console] +---- +Interact with single operator instead of the full platform + +Usage: stackablectl operator [OPTIONS] + +Commands: + list List available operators + describe Print out detailed operator information + install Install one or more operators + uninstall Uninstall one or more operators + installed List installed operators + help Print this message or the help of the given subcommand(s) + +Options: + -l, --log-level + Log level this application uses + + --no-cache + Do not cache the remote (default) demo, stack and release files + + Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually + '$HOME/.cache/stackablectl' when not explicitly set. + + --offline + Do not request any remote files via the network + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version + +File options: + -d, --demo-file + Provide one or more additional (custom) demo file(s) + + Demos are loaded in the following order: Remote (default) demo file, custom + demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and + lastly demo files provided via the '-d/--demo-file' argument(s). If there are + demos with the same name, the last demo definition will be used. + + Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" + to provide multiple additional demo files. + + -s, --stack-file + Provide one or more additional (custom) stack file(s) + + Stacks are loaded in the following order: Remote (default) stack file, custom + stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and + lastly demo files provided via the '-s/--stack-file' argument(s). If there are + stacks with the same name, the last stack definition will be used. + + Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" + to provide multiple additional stack files. + + -r, --release-file + Provide one or more additional (custom) release file(s) + + Releases are loaded in the following order: Remote (default) release file, + custom release files provided via the 'STACKABLE_RELEASE_FILES' environment + variable, and lastly release files provided via the '-r/--release-file' + argument(s). If there are releases with the same name, the last release + definition will be used. + + Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" + to provide multiple additional release files. + +Helm repository options: + --helm-repo-stable + Provide a custom Helm stable repository URL + + [default: https://repo.stackable.tech/repository/helm-stable/] + + --helm-repo-test + Provide a custom Helm test repository URL + + [default: https://repo.stackable.tech/repository/helm-test/] + + --helm-repo-dev + Provide a custom Helm dev repository URL + + [default: https://repo.stackable.tech/repository/helm-dev/] +---- diff --git a/docs/modules/stackablectl/partials/commands/release.adoc b/docs/modules/stackablectl/partials/commands/release.adoc new file mode 100644 index 00000000..00f190e7 --- /dev/null +++ b/docs/modules/stackablectl/partials/commands/release.adoc @@ -0,0 +1,84 @@ +// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! +[source,console] +---- +Interact with all operators of the platform which are released together + +Usage: stackablectl release [OPTIONS] + +Commands: + list List available releases + describe Print out detailed release information + install Install a specific release + uninstall Uninstall a release + help Print this message or the help of the given subcommand(s) + +Options: + -l, --log-level + Log level this application uses + + --no-cache + Do not cache the remote (default) demo, stack and release files + + Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually + '$HOME/.cache/stackablectl' when not explicitly set. + + --offline + Do not request any remote files via the network + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version + +File options: + -d, --demo-file + Provide one or more additional (custom) demo file(s) + + Demos are loaded in the following order: Remote (default) demo file, custom + demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and + lastly demo files provided via the '-d/--demo-file' argument(s). If there are + demos with the same name, the last demo definition will be used. + + Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" + to provide multiple additional demo files. + + -s, --stack-file + Provide one or more additional (custom) stack file(s) + + Stacks are loaded in the following order: Remote (default) stack file, custom + stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and + lastly demo files provided via the '-s/--stack-file' argument(s). If there are + stacks with the same name, the last stack definition will be used. + + Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" + to provide multiple additional stack files. + + -r, --release-file + Provide one or more additional (custom) release file(s) + + Releases are loaded in the following order: Remote (default) release file, + custom release files provided via the 'STACKABLE_RELEASE_FILES' environment + variable, and lastly release files provided via the '-r/--release-file' + argument(s). If there are releases with the same name, the last release + definition will be used. + + Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" + to provide multiple additional release files. + +Helm repository options: + --helm-repo-stable + Provide a custom Helm stable repository URL + + [default: https://repo.stackable.tech/repository/helm-stable/] + + --helm-repo-test + Provide a custom Helm test repository URL + + [default: https://repo.stackable.tech/repository/helm-test/] + + --helm-repo-dev + Provide a custom Helm dev repository URL + + [default: https://repo.stackable.tech/repository/helm-dev/] +---- diff --git a/docs/modules/stackablectl/partials/commands/stack.adoc b/docs/modules/stackablectl/partials/commands/stack.adoc new file mode 100644 index 00000000..6b0282b1 --- /dev/null +++ b/docs/modules/stackablectl/partials/commands/stack.adoc @@ -0,0 +1,83 @@ +// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! +[source,console] +---- +Interact with stacks, which are ready-to-use product combinations + +Usage: stackablectl stack [OPTIONS] + +Commands: + list List available stacks + describe Describe a specific stack + install Install a specific stack + help Print this message or the help of the given subcommand(s) + +Options: + -l, --log-level + Log level this application uses + + --no-cache + Do not cache the remote (default) demo, stack and release files + + Cached files are saved at '$XDG_CACHE_HOME/stackablectl', which is usually + '$HOME/.cache/stackablectl' when not explicitly set. + + --offline + Do not request any remote files via the network + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version + +File options: + -d, --demo-file + Provide one or more additional (custom) demo file(s) + + Demos are loaded in the following order: Remote (default) demo file, custom + demo files provided via the 'STACKABLE_DEMO_FILES' environment variable, and + lastly demo files provided via the '-d/--demo-file' argument(s). If there are + demos with the same name, the last demo definition will be used. + + Use "stackablectl [OPTIONS] -d path/to/demos1.yaml -d path/to/demos2.yaml" + to provide multiple additional demo files. + + -s, --stack-file + Provide one or more additional (custom) stack file(s) + + Stacks are loaded in the following order: Remote (default) stack file, custom + stack files provided via the 'STACKABLE_STACK_FILES' environment variable, and + lastly demo files provided via the '-s/--stack-file' argument(s). If there are + stacks with the same name, the last stack definition will be used. + + Use "stackablectl [OPTIONS] -s path/to/stacks1.yaml -s path/to/stacks2.yaml" + to provide multiple additional stack files. + + -r, --release-file + Provide one or more additional (custom) release file(s) + + Releases are loaded in the following order: Remote (default) release file, + custom release files provided via the 'STACKABLE_RELEASE_FILES' environment + variable, and lastly release files provided via the '-r/--release-file' + argument(s). If there are releases with the same name, the last release + definition will be used. + + Use "stackablectl [OPTIONS] -r path/to/releases1.yaml -r path/to/releases2.yaml" + to provide multiple additional release files. + +Helm repository options: + --helm-repo-stable + Provide a custom Helm stable repository URL + + [default: https://repo.stackable.tech/repository/helm-stable/] + + --helm-repo-test + Provide a custom Helm test repository URL + + [default: https://repo.stackable.tech/repository/helm-test/] + + --helm-repo-dev + Provide a custom Helm dev repository URL + + [default: https://repo.stackable.tech/repository/helm-dev/] +---- diff --git a/docs/modules/stackablectl/pages/commands/stacklets.adoc b/docs/modules/stackablectl/partials/commands/stacklet.adoc similarity index 93% rename from docs/modules/stackablectl/pages/commands/stacklets.adoc rename to docs/modules/stackablectl/partials/commands/stacklet.adoc index e00a2eab..219f22b6 100644 --- a/docs/modules/stackablectl/pages/commands/stacklets.adoc +++ b/docs/modules/stackablectl/partials/commands/stacklet.adoc @@ -1,10 +1,6 @@ -= stackablectl stacklets -:page-aliases: stackablectl::commands/services.adoc - // Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! [source,console] ---- -$ stackablectl stacklets Interact with deployed stacklets, which are bundles of resources and containers required to run the product. @@ -12,11 +8,12 @@ Each stacklet consists of init containers, app containers, sidecar containers and additional Kubernetes resources like StatefulSets, ConfigMaps, Services and CRDs. -Usage: stacklets [OPTIONS] +Usage: stackablectl stacklet [OPTIONS] Commands: - list List deployed services - help Print this message or the help of the given subcommand(s) + credentials Display credentials for a stacklet + list List deployed stacklets + help Print this message or the help of the given subcommand(s) Options: -l, --log-level diff --git a/rust/xtask/Cargo.toml b/rust/xtask/Cargo.toml index 35581ffc..54be1ea4 100644 --- a/rust/xtask/Cargo.toml +++ b/rust/xtask/Cargo.toml @@ -14,3 +14,4 @@ serde_json.workspace = true snafu.workspace = true stackable-cockpitd = { path = "../stackable-cockpitd" } stackablectl = { path = "../stackablectl" } +tera.workspace = true diff --git a/rust/xtask/src/docs.rs b/rust/xtask/src/docs.rs index 21437b23..c13f5f94 100644 --- a/rust/xtask/src/docs.rs +++ b/rust/xtask/src/docs.rs @@ -1,14 +1,15 @@ -use std::{fs, path::Path}; +use std::{ + fs::{self}, + path::Path, +}; use clap::CommandFactory; -use once_cell::sync::Lazy; -use regex::Regex; use snafu::{ResultExt, Snafu}; use stackablectl::cli::Cli; const COMMANDS: &[&str] = &[ "completions", - "stacklets", + "stacklet", "operator", "release", "stack", @@ -17,11 +18,7 @@ const COMMANDS: &[&str] = &[ ".", ]; -static CODE_LISTING_PATTERN: Lazy = Lazy::new(|| { - Regex::new(r"(?m)// Autogenerated by cargo xtask gen-docs\. DO NOT CHANGE MANUALLY!\n\[source,console\]\n----\n\$ stackablectl.*\n").unwrap() -}); -const DOCS_BASE_PATH: &str = "docs/modules/stackablectl/pages/commands"; -const USAGE_END_STRING: &str = "\n----"; +const DOCS_BASE_PATH: &str = "docs/modules/stackablectl/partials/commands"; #[derive(Debug, Snafu)] pub enum GenDocsError { @@ -30,10 +27,22 @@ pub enum GenDocsError { #[snafu(display("io error"))] Io { source: std::io::Error }, + + #[snafu(display("templating error"))] + TemplateError { source: tera::Error }, } pub fn generate() -> Result<(), GenDocsError> { let mut cli = Cli::command(); + cli.build(); + + let mut renderer = tera::Tera::default(); + renderer + .add_raw_template( + "command_partial", + include_str!("templates/command.adoc.tpl"), + ) + .context(TemplateSnafu)?; for command_page_name in COMMANDS { let usage_text = if command_page_name == &"." { @@ -68,17 +77,16 @@ pub fn generate() -> Result<(), GenDocsError> { } )); - let mut doc_page = fs::read_to_string(&page_path).context(IoSnafu)?; - - let m = CODE_LISTING_PATTERN.find(&doc_page).unwrap(); - let usage_start = m.end(); - let usage_end = doc_page[usage_start..].find(USAGE_END_STRING).unwrap(); + let mut context = tera::Context::new(); + context.insert("output", &usage_text); - doc_page.replace_range( - usage_start..usage_start + usage_end, - usage_text.to_string().trim(), - ); - fs::write(page_path, doc_page).context(IoSnafu)?; + fs::write( + page_path, + renderer + .render("command_partial", &context) + .context(TemplateSnafu)?, + ) + .context(IoSnafu)? } Ok(()) diff --git a/rust/xtask/src/templates/command.adoc.tpl b/rust/xtask/src/templates/command.adoc.tpl new file mode 100644 index 00000000..e0e61f83 --- /dev/null +++ b/rust/xtask/src/templates/command.adoc.tpl @@ -0,0 +1,5 @@ +// Autogenerated by cargo xtask gen-docs. DO NOT CHANGE MANUALLY! +[source,console] +---- +{{ output }} +----