From cf0122161fcb8036e8db078c2f3e1724cc93f436 Mon Sep 17 00:00:00 2001 From: Milan Fencik Date: Mon, 30 Mar 2026 19:51:00 +0100 Subject: [PATCH] add understackctl docs --- docs/operator-guide/understackctl.md | 370 +++++++++++++++++++++++++++ go/understackctl/README.md | 57 +---- mkdocs.yml | 1 + 3 files changed, 373 insertions(+), 55 deletions(-) create mode 100644 docs/operator-guide/understackctl.md diff --git a/docs/operator-guide/understackctl.md b/docs/operator-guide/understackctl.md new file mode 100644 index 000000000..7f49e7c50 --- /dev/null +++ b/docs/operator-guide/understackctl.md @@ -0,0 +1,370 @@ +# understackctl + +`understackctl` is the CLI tool for managing UnderStack deployments. It handles deployment repository scaffolding, secret generation, hardware definitions, node lifecycle workflows, and more. + +## Installation + +### Using go install + +If you have Go 1.24+ installed, you can install directly: + +```bash +go install github.com/rackerlabs/understack/go/understackctl@latest +``` + +This places the binary in your `$GOPATH/bin` (or `$HOME/go/bin` by default). Make sure that directory is in your `PATH`. + +### From source + +Requires Go 1.24+. + +```bash +git clone https://github.com/rackerlabs/understack.git +cd understack/go/understackctl +make build +``` + +The binary will be at `build/understackctl/understackctl`. Add it to your `PATH` or copy it somewhere convenient: + +```bash +cp build/understackctl/understackctl /usr/local/bin/ +``` + +### Cross-platform builds + +Build for Linux, macOS, and Windows (amd64/arm64/386): + +```bash +make build-all +``` + +Outputs are placed in `build/` as platform-specific directories. To create distributable archives: + +```bash +make package-all +``` + +This produces `.tar.gz` files (Linux/macOS) and `.zip` files (Windows). + +To generate SHA-256 checksums for all archives: + +```bash +make checksums +``` + +### From release binaries + +Download a pre-built binary from the [GitHub Releases](https://github.com/rackerlabs/understack/releases) page, extract it, and place it in your `PATH`. + +## Prerequisites + +Depending on which commands you use, you may need: + +- `kubectl` — Kubernetes cluster access +- `helm` (3.8+) — Helm chart rendering +- `kubeseal` — Sealed Secrets encryption +- `argo` — Argo Workflows CLI (for node commands) +- `git` — deploy repo operations +- A valid kubeconfig pointing at your target cluster + +## Environment Variables + +| Variable | Used by | Description | +|---|---|---| +| `UC_DEPLOY` | `deploy`, `device-type`, `flavor` | Path to the deployment repository | +| `DEPLOY_NAME` | secret generators, `quickstart` | Name of the deployment / cluster | + +## Commands + +### deploy + +Manage the deployment repository structure and configuration. All subcommands accept `--deploy-repo` (or the `UC_DEPLOY` env var) to specify the path to your deploy repo. + +#### deploy init + +```bash +understackctl deploy init [--type global|site|aio] [--git-remote origin] +``` + +Create a new cluster directory with a `deploy.yaml` configuration file. Fetches the current component list from the UnderStack repository and populates the global and/or site sections based on the cluster type. + +- `--type` (default: `aio`) — Cluster type. `global` includes only global components, `site` includes only site components, `aio` includes both. +- `--git-remote` (default: `origin`) — Git remote name used to detect the deploy repo URL. + +#### deploy update + +```bash +understackctl deploy update +``` + +Sync the cluster directory with `deploy.yaml`. Creates directories, `kustomization.yaml`, and `values.yaml` for newly enabled components. Removes directories for disabled components. + +#### deploy check + +```bash +understackctl deploy check +``` + +Validate that every enabled component has the required `kustomization.yaml` and `values.yaml` files. Reports any missing files and exits with an error if validation fails. + +#### deploy render + +```bash +understackctl deploy render [--chart-path ] [--version main] +``` + +Preview the rendered ArgoCD Applications by running `helm template` against the cluster's `deploy.yaml`. By default it clones the UnderStack repo to get the chart; use `--chart-path` to point at a local chart instead. + +- `--chart-path` — Path to a local ArgoCD Helm chart directory. If omitted, the chart is cloned from the UnderStack repo. +- `--version` (default: `main`) — Git ref (branch or tag) to use when cloning the default chart. + +#### deploy enable + +```bash +understackctl deploy enable --type global|site|aio +``` + +Enable a component in the cluster's `deploy.yaml`. The `--type` flag is required and determines which section(s) the component is added to. Using `aio` enables it in both `global` and `site`. + +#### deploy disable + +```bash +understackctl deploy disable --type global|site|aio +``` + +Disable a component in the cluster's `deploy.yaml`. The component directory is not removed until `deploy update` is run. + +#### deploy image-set + +```bash +understackctl deploy image-set [--no-digest] +``` + +Walk all YAML files in the cluster directory and update UnderStack container image tags to the specified version. Also updates `?ref=vX.Y.Z` references in `kustomization.yaml` files. By default, the sha256 digest is resolved from the container registry and pinned alongside the tag. + +- `--no-digest` — Write the tag only, skip the registry digest lookup. + +### device-type + +Manage hardware device type definitions. Requires `UC_DEPLOY` to be set. + +#### device-type add + +```bash +understackctl device-type add +``` + +Validate a device-type YAML file against the JSON schema and copy it into the deploy repo's `hardware/device-types/` directory. Updates the `kustomization.yaml` configMapGenerator entry automatically. + +#### device-type validate + +```bash +understackctl device-type validate +``` + +Validate a device-type YAML file against the JSON schema without adding it to the deployment. Useful for checking definitions before committing. + +#### device-type delete + +```bash +understackctl device-type delete +``` + +Remove a device-type definition by name and update the `kustomization.yaml` accordingly. + +#### device-type list + +```bash +understackctl device-type list +``` + +List all device-type definitions found in `hardware/device-types/`. + +#### device-type show + +```bash +understackctl device-type show +``` + +Display detailed information about a device-type including class, manufacturer, model, interfaces, and resource classes. + +### flavor + +Manage hardware flavor definitions for node matching. Requires `UC_DEPLOY` to be set. + +#### flavor add + +```bash +understackctl flavor add +``` + +Validate a flavor YAML file against the JSON schema and copy it into `hardware/flavors/`. Updates the `kustomization.yaml` configMapGenerator entry. + +#### flavor validate + +```bash +understackctl flavor validate +``` + +Validate a flavor definition against the JSON schema without adding it. + +#### flavor delete + +```bash +understackctl flavor delete +``` + +Remove a flavor definition by name and update `kustomization.yaml`. + +#### flavor list + +```bash +understackctl flavor list +``` + +List all flavor definitions in `hardware/flavors/`. + +#### flavor show + +```bash +understackctl flavor show +``` + +Display detailed information about a flavor including its resource class and trait requirements. + +### node + +Manage node lifecycle workflows by wrapping Argo Workflows. + +#### node enroll-server + +```bash +understackctl node enroll-server [flags] +``` + +Submit the `enroll-server` Argo workflow for a bare metal node. Requires the `argo` CLI to be installed and a valid kubeconfig. + +- `--old-password` — Existing node password (e.g. BMC password). +- `--firmware-update` — Perform a firmware update during enrollment. +- `--raid-configure` — Configure RAID during enrollment. +- `--external-cmdb-id` — External CMDB identifier for the node. +- `--log` — Stream workflow logs after submission. + +#### node inspect-server + +```bash +understackctl node inspect-server [--log] +``` + +Submit the `inspect-server` Argo workflow for a node. Takes a node ID (not an IP address). + +- `--log` — Stream workflow logs after submission. + +### node-update + +```bash +understackctl node-update +``` + +Label all Kubernetes cluster nodes with `openstack-control-plane=enabled`. Skips nodes that already have the label. Requires a valid kubeconfig. + +### nautobotop + +Nautobot Operator operations. + +#### nautobotop resync + +```bash +understackctl nautobotop resync [--name ] [--operator ] +``` + +Force a re-sync of the Nautobot custom resource by clearing its status and performing a rollout restart of the operator deployment. If `--name` or `--operator` are omitted, the command auto-detects them from the cluster and prompts for selection if multiple are found. + +- `--name`, `-n` — Name of the Nautobot CR (auto-detected if omitted). +- `--operator` — Operator deployment as `namespace/name` (auto-detected if omitted). + +### Secret Generation Commands + +These commands generate Kubernetes Sealed Secrets and configuration files for various services. They typically require `DEPLOY_NAME`, `DNS_ZONE`, and a running cluster with `kubeseal` available. + +#### argocd-secrets + +```bash +understackctl argocd-secrets +``` + +Generate ArgoCD repository and cluster secrets. Uses `DEPLOY_NAME`, `UC_DEPLOY_GIT_URL`, `UC_DEPLOY_SSH_FILE`, and `DNS_ZONE` environment variables. + +#### certmanager-secrets + +```bash +understackctl certmanager-secrets +``` + +Generate a cert-manager ClusterIssuer manifest. Uses `UC_DEPLOY_EMAIL` and `DNS_ZONE`. + +#### dex-secrets + +```bash +understackctl dex-secrets +``` + +Generate Dex OAuth2/OIDC client secrets for nautobot, argo, argocd, keystone, and grafana. Each client gets a randomly generated 32-character secret. + +#### openstack-secrets + +```bash +understackctl openstack-secrets +``` + +Generate a MariaDB sealed secret for the OpenStack namespace with random root and user passwords. + +#### other-secrets + +```bash +understackctl other-secrets +``` + +Generate secrets for keystone, ironic, placement, neutron, nova, glance, and horizon. Creates per-service sealed secrets for RabbitMQ, Keystone, and database passwords. Also generates the `secret-openstack.yaml` endpoints configuration file with all passwords populated. Attempts to load existing passwords from the cluster before generating new ones. + +#### helm-config + +```bash +understackctl helm-config +``` + +Generate Helm `values.yaml` files for dex, glance, ironic, and rook-cluster in the deploy repo. Uses `DEPLOY_NAME` and `DNS_ZONE`. + +### quickstart + +```bash +understackctl quickstart +``` + +Run all setup steps in sequence: node labeling, ArgoCD secrets, cert-manager secrets, Dex secrets, OpenStack service secrets, MariaDB secrets, and Helm configs. Requires `kubeseal` to be installed and all relevant environment variables to be set (`DEPLOY_NAME`, `UC_DEPLOY_GIT_URL`, `UC_DEPLOY_SSH_FILE`, `DNS_ZONE`, `UC_DEPLOY_EMAIL`). + +## Development + +To add a new command, create a constructor function: + +```go +func NewCmdMyCommand() *cobra.Command { + return &cobra.Command{ + Use: "mycommand", + Short: "This will run my command", + Run: myCommandFunction, + } +} +``` + +Then register it in `cmd/root/root.go`: + +```go +func init() { + rootCmd.AddCommand(mypkg.NewCmdMyCommand()) +} +``` + +## Contributing + +If you find any issues or have suggestions for improvements, please open an issue on the [GitHub repository](https://github.com/rackerlabs/understack). diff --git a/go/understackctl/README.md b/go/understackctl/README.md index 697f5b672..5f308c201 100644 --- a/go/understackctl/README.md +++ b/go/understackctl/README.md @@ -1,58 +1,5 @@ # understackctl -understackctl is a CLI tool for managing UnderStack deployments. +`understackctl` is the CLI tool for managing UnderStack deployments. -## Commands - -### deploy - -Manage deployment repository structure and configuration. - -```bash -# Initialize a new cluster configuration -understackctl deploy init --type - -# Sync manifest directories with deploy.yaml -understackctl deploy update - -# Validate configuration -understackctl deploy check -``` - -See the [Deploy Guide](https://rackerlabs.github.io/understack/deploy-guide/deploy-repo/) for details. - -### Other Commands - -Run `understackctl --help` to see all available commands. - -## Build - -* Local build: `make build` (builds for your local OS) -* Cross-platform build: `make build-all` (builds for Linux, macOS, Windows) - -## Development - -* To add a new command, create a function like this. - -```go -func NewCmdMyCommand() *cobra.Command { - return &cobra.Command{ - Use: "mycommand", - Short: "This will run my command", - Long: "This will run my command", - Run: myCommandFunction, - } -} -``` - -* After that register it to `cmd/root/root.go` - -```go -func init() { - rootCmd.AddCommand(deploy.NewCmdMyCommand()) -} -``` - -## Contributing - -If you find any issues or have suggestions for improvements, please open an issue on the [GitHub repository](https://github.com/rackerlabs/understack). +For installation, usage, and full command reference, see the [documentation](https://rackerlabs.github.io/understack/operator-guide/understackctl/). diff --git a/mkdocs.yml b/mkdocs.yml index 09f292cd9..e865f86d9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -246,6 +246,7 @@ nav: - operator-guide/server-firmware-update.md - 'Scripts and Tools': - operator-guide/scripts.md + - operator-guide/understackctl.md - 'User Guide': - user-guide/index.md - user-guide/openstack-cli.md