[RFE] Add bro-tool CLI for support use

.github/workflows/ci.yaml

@@ -24,16 +24,37 @@ on:
     - 'CODEOWNERS'
     - 'LICENSE'
 jobs:
+  workspace-sync:
+    name: workspace sync check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
+        with:
+          go-version: 1.25
+      - name: Check go.work.sum is in sync
+        run: |
+          go work sync
+          git diff --exit-code go.work.sum || (echo "go.work.sum is out of sync — run 'make tidy' and commit the result" && exit 1)
+
   golangci:
-    name: lint
+    name: lint (${{ matrix.module }})
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        module:
+          - .
+          - cmd/tool
+          - tests
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
         with:
           go-version: 1.25
-      - name: golangci-lint
+      - name: golangci-lint (${{ matrix.module }})
         uses: golangci/golangci-lint-action@1e7e51e771db61008b38414a730f564565cf7c20 # v9.2.0
+        with:
+          working-directory: ${{ matrix.module }}
   build:
     name: CI Build
     strategy:

.gitignore

@@ -6,8 +6,11 @@
 *.swp
 .idea
 ./backup
-./backup-restore-operator
 backup-restore-operator
+operator
+!cmd/operator
+tool
+!cmd/tool
 /secretExamples
 test-backup-location-local/
 .DS_Store

.golangci.yaml

@@ -24,6 +24,10 @@ linters:
           - revive
         path: cmd/operator/version/version.go
         text: var-naming
+      - linters:
+          - revive
+        path: pkg/version/version.go
+        text: var-naming
     paths:
       - /zz_generated_
 formatters:

.goreleaser.yaml

@@ -16,9 +16,9 @@ builds:
         - -extldflags
         - -static
         - -s
-        - -X github.com/rancher/backup-restore-operator/cmd/operator/version.Version={{.Version}}
-        - -X github.com/rancher/backup-restore-operator/cmd/operator/version.GitCommit={{.Commit}}
-        - -X github.com/rancher/backup-restore-operator/cmd/operator/version.Date={{.Date}}
+        - -X github.com/rancher/backup-restore-operator/pkg/version.Version={{.Version}}
+        - -X github.com/rancher/backup-restore-operator/pkg/version.GitCommit={{.Commit}}
+        - -X github.com/rancher/backup-restore-operator/pkg/version.Date={{.Date}}
       flags:
         - -trimpath
       env:
@@ -35,15 +35,32 @@ builds:
       binary: backup-restore-operator
       ldflags:
         - -s
-        - -X github.com/rancher/backup-restore-operator/cmd/operator/version.Version={{.Version}}
-        - -X github.com/rancher/backup-restore-operator/cmd/operator/version.GitCommit={{.Commit}}
-        - -X github.com/rancher/backup-restore-operator/cmd/operator/version.Date={{.Date}}
+        - -X github.com/rancher/backup-restore-operator/pkg/version.Version={{.Version}}
+        - -X github.com/rancher/backup-restore-operator/pkg/version.GitCommit={{.Commit}}
+        - -X github.com/rancher/backup-restore-operator/pkg/version.Date={{.Date}}
       flags:
         - -trimpath
       env:
         - CGO_ENABLED=0
       skip: '{{ not (index .Env "GOOS_DARWIN_DEV") }}'
 
+    - id: bro-tool
+      main: ./cmd/tool/main.go
+      goos:
+        - linux
+        - darwin
+        - windows
+      binary: bro-tool
+      ldflags:
+        - -s
+        - -X github.com/rancher/backup-restore-operator/pkg/version.Version={{.Version}}
+        - -X github.com/rancher/backup-restore-operator/pkg/version.GitCommit={{.Commit}}
+        - -X github.com/rancher/backup-restore-operator/pkg/version.Date={{.Date}}
+      flags:
+        - -trimpath
+      env:
+        - CGO_ENABLED=0
+
 archives:
     - id: backup-restore-operator
       builds:

DEVELOPING.md

@@ -2,6 +2,66 @@
 
 Developer tips, tricks, and workflows for the [rancher/backup-restore-operator](https://github.com/rancher/backup-restore-operator).
 
+### Go Workspace (go.work)
+
+This repository uses a [Go workspace](https://go.dev/ref/mod#workspaces) (`go.work`) to manage three independent Go modules together:
+
+| Module | Path |
+|---|---|
+| `github.com/rancher/backup-restore-operator` | `.` (root) |
+| `github.com/rancher/backup-restore-operator/cmd/tool` | `./cmd/tool` |
+| `github.com/rancher/backup-restore-operator/tests` | `./tests` |
+
+The workspace means you can run `go` commands from the repository root and have them resolve cross-module dependencies without needing to publish anything.
+
+#### Day-to-day commands
+
+```bash
+# Build everything in the workspace (operator + bro-tool)
+make build
+
+# Build just bro-tool (from repo root via workspace)
+go build -C cmd/tool -o bin/bro-tool .
+
+# Test everything in the workspace
+go test ./...
+
+# Tidy all modules and sync go.work.sum in one step
+make tidy
+
+# Tidy a single module manually (run from that module's directory)
+cd cmd/tool && go mod tidy
+
+# Update go.work.sum after any go.mod change
+go work sync
+```
+
+#### Adding dependencies
+
+Always add dependencies to the **correct module's** `go.mod`, not the root. The rule of thumb:
+
+- Dependency only used by `bro-tool` → `cd cmd/tool && go get <pkg>`
+- Dependency only used by integration tests → `cd tests && go get <pkg>`
+- Dependency used by the operator itself → `go get <pkg>` from the root
+
+Never add `bro-tool`- or test-only dependencies to the root module. The root module is the BRO operator binary; bloating it affects the production image.
+
+#### Workspace vs. standalone
+
+The `go.work` file is checked in and should always be present for local development. Each sub-module also carries a `replace` directive in its own `go.mod` (e.g. `cmd/tool/go.mod` replaces the root module with `../../`) so the modules still resolve correctly in contexts where `go.work` is not active — such as individual module CI jobs or `go get` from external consumers.
+
+If you ever need to test a module in true standalone mode (without the workspace), use `GOWORK=off`:
+
+```bash
+GOWORK=off go build ./...
+```
+
+#### IDE / gopls
+
+Most editors using `gopls` pick up `go.work` automatically and provide full cross-module navigation and type checking. If your editor shows unresolved imports across modules, check that gopls is running from the repository root (where `go.work` lives), not from inside a sub-module directory.
+
+---
+
 ### Developer Installation
 
 To test your local changes, `cd` to the root of the cloned repository, and execute the following commands:

README.md

@@ -136,3 +136,13 @@ Refer to [DEVELOPING.md](./DEVELOPING.md) for developer tips, tricks, and workfl
 ### Troubleshooting
 
 Refer to [troubleshooting.md](./docs/troubleshooting.md) for troubleshooting commands.
+
+---
+
+### bro-tool
+
+`bro-tool` is an unofficial companion CLI for support engineers and developers. It lets you inspect BRO ResourceSet configuration and check resource coverage **without a live cluster**.
+
+> **No Warranty.** `bro-tool` is provided as-is and is **not** a supported SUSE/Rancher product. It carries no SLA and is not covered by any support agreement. This is in contrast to BRO itself, which is a supported product for paying customers.
+
+Refer to [docs/bro-tool.md](./docs/bro-tool.md) for full usage documentation.

cmd/operator/main.go

@@ -2,13 +2,14 @@ package main
 
 import (
 	"flag"
+	"fmt"
 	"os"
 
+	"github.com/rancher/backup-restore-operator/pkg/version"
 	"github.com/rancher/wrangler/v3/pkg/kubeconfig"
 	"github.com/rancher/wrangler/v3/pkg/signals"
 	"github.com/sirupsen/logrus"
 
-	"github.com/rancher/backup-restore-operator/cmd/operator/version"
 	"github.com/rancher/backup-restore-operator/pkg/operator"
 	backuputil "github.com/rancher/backup-restore-operator/pkg/util"
 )
@@ -27,12 +28,14 @@ var (
 	ChartNamespace                  string
 	Debug                           bool
 	Trace                           bool
+	PrintVersion                    bool
 )
 
 func init() {
 	flag.StringVar(&KubeConfig, "kubeconfig", "", "Path to a kubeconfig. Only required if out-of-cluster.")
 	flag.BoolVar(&Debug, "debug", false, "Enable debug logging.")
 	flag.BoolVar(&Trace, "trace", false, "Enable trace logging.")
+	flag.BoolVar(&PrintVersion, "version", false, "Print version information and exit.")
 
 	flag.Parse()
 	OperatorPVEnabled = os.Getenv("DEFAULT_PERSISTENCE_ENABLED")
@@ -43,6 +46,11 @@ func init() {
 }
 
 func main() {
+	if PrintVersion {
+		fmt.Println(version.FmtVersionInfo("backup-restore-operator"))
+		return
+	}
+
 	logrus.SetFormatter(&logrus.TextFormatter{FullTimestamp: true, ForceColors: true, TimestampFormat: LogFormat})
 	if Debug {
 		logrus.SetLevel(logrus.DebugLevel)

cmd/tool/README.md

@@ -0,0 +1,62 @@
+# bro-tool
+
+`bro-tool` is a CLI helper for the [backup-restore-operator (BRO)](../../README.md). It provides one-off operations for managing backup and restore resources outside of the operator's control loop.
+
+## Versioning and compatibility
+
+`bro-tool` is built and versioned alongside BRO. Each release of `bro-tool` is fully compatible with the BRO version it was built for.
+
+**Newer tool, older BRO:** A newer `bro-tool` can generally interact with older BRO installations and data. Logical compatibility is maintained across versions where possible.
+
+**Older tool, newer BRO:** An older `bro-tool` is only expected to work with newer BRO versions within the same major version. Cross-major-version use is unsupported.
+
+In short: prefer keeping `bro-tool` at the same version as your BRO installation, and upgrade the tool before downgrading it.
+
+## Usage
+
+```
+bro-tool [flags] <command> [command flags]
+```
+
+Run `bro-tool --help` to list available commands and flags.
+
+### Subcommands
+
+1. `bro-tool resource-set:view` - View the resources managed by a specific BRO version.
+   - `--version` - The BRO version to view - will pull from GitHub or Charts repo.
+   - `--path` - The path to the rancher backup chart to use.
+   - `--output` - Output format: yaml, json, or table
+2. `bro-tool resource-set:check` - Validate that a specific k8s resource is covered by a ResourceSet rule
+   - `--version` - The BRO version to check against - will pull from GitHub or Charts repo.
+   - `--path` - The path to the rancher backup chart to use. 
+   - `--resource` - The k8s resource to check - should be in the format "kind/name"
+   - `--resource-path` - The path to the k8s resource to check - should be in the format `path/to/resource.yaml
+3. `bro-tool resource-set:diff` - Compare two ResourceSets and identify differences in managed resources
+   - Takes two positional arguments: Either a version or path
+     - First argument: The base to compare against
+     - Second argument: The target to compare against
+
+### How
+
+Each command should follow a similar pattern:
+- Parse inputs and validate,
+- If needed fetch remote resources (use a bro-tool cache dir when possible),
+- Render the helm template and extract the ResourceSet resources,
+- Extract the actual Rules from the ResourceSet resources,
+- Do sub-command specific work.
+
+So that should help define what core/foundation code this new subpackage needs.
+As that should be easy to share between all the sub-commands we have in mind so far.
+
+And obviously, the new dependency of helm and such can apply only to the tool due to our multi-module setup.
+
+- The `resource-set:view` subcommand is basically just the core workflow + pretty print options.
+- The `resource-set:check` subcommand is the core workflow + taking user input to do a matcher validation.
+- The `resource-set:diff` subcommand is the core workflow + do it again with another version + diffing both.
+
+## Dev Rules
+
+Anything for the new bro tool alone should be added to `cmd/tool/go.mod` only and not other go modules.
+None of the bro-tool code is considered part of the BRO project; rather, bro-tool is a consumer of BRO built along side it.
+The bro-tool code is not considered a public API for reuse outside bro-tool.
+The bro-tool is provided as-is and is not intended for production use – it is a tool for development, testing and debugging.

cmd/tool/go.mod

@@ -0,0 +1,81 @@
+module github.com/rancher/backup-restore-operator/cmd/tool
+
+go 1.25.0
+
+replace github.com/rancher/backup-restore-operator => ../../
+
+require (
+	github.com/rancher/backup-restore-operator v0.0.0
+	github.com/sirupsen/logrus v1.9.4
+	helm.sh/helm/v3 v3.20.0
+	k8s.io/apimachinery v0.35.0
+	k8s.io/client-go v0.35.0
+	sigs.k8s.io/yaml v1.6.0
+)
+
+require (
+	dario.cat/mergo v1.0.2 // indirect
+	github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 // indirect
+	github.com/BurntSushi/toml v1.6.0 // indirect
+	github.com/Masterminds/goutils v1.1.1 // indirect
+	github.com/Masterminds/semver/v3 v3.4.0 // indirect
+	github.com/Masterminds/sprig/v3 v3.3.0 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/cyphar/filepath-securejoin v0.6.1 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/emicklei/go-restful/v3 v3.12.2 // indirect
+	github.com/evanphx/json-patch v5.9.11+incompatible // indirect
+	github.com/fxamacker/cbor/v2 v2.9.0 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-openapi/jsonpointer v0.21.0 // indirect
+	github.com/go-openapi/jsonreference v0.21.0 // indirect
+	github.com/go-openapi/swag v0.23.0 // indirect
+	github.com/gobwas/glob v0.2.3 // indirect
+	github.com/google/gnostic-models v0.7.0 // indirect
+	github.com/google/go-cmp v0.7.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/huandu/xstrings v1.5.0 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/mailru/easyjson v0.9.0 // indirect
+	github.com/mitchellh/copystructure v1.2.0 // indirect
+	github.com/mitchellh/reflectwalk v1.0.2 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/prometheus/client_golang v1.23.2 // indirect
+	github.com/prometheus/client_model v0.6.2 // indirect
+	github.com/prometheus/common v0.66.1 // indirect
+	github.com/prometheus/procfs v0.16.1 // indirect
+	github.com/rancher/lasso v0.2.6 // indirect
+	github.com/rancher/wrangler/v3 v3.4.0 // indirect
+	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
+	github.com/shopspring/decimal v1.4.0 // indirect
+	github.com/spf13/cast v1.7.0 // indirect
+	github.com/x448/float16 v0.8.4 // indirect
+	go.yaml.in/yaml/v2 v2.4.3 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
+	golang.org/x/crypto v0.47.0 // indirect
+	golang.org/x/net v0.49.0 // indirect
+	golang.org/x/oauth2 v0.30.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/sys v0.40.0 // indirect
+	golang.org/x/term v0.39.0 // indirect
+	golang.org/x/text v0.33.0 // indirect
+	golang.org/x/time v0.12.0 // indirect
+	google.golang.org/protobuf v1.36.8 // indirect
+	gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	k8s.io/api v0.35.0 // indirect
+	k8s.io/apiextensions-apiserver v0.35.0 // indirect
+	k8s.io/klog/v2 v2.130.1 // indirect
+	k8s.io/kube-openapi v0.0.0-20250910181357-589584f1c912 // indirect
+	k8s.io/utils v0.0.0-20251002143259-bc988d571ff4 // indirect
+	sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect
+	sigs.k8s.io/randfill v1.0.0 // indirect
+	sigs.k8s.io/structured-merge-diff/v6 v6.3.2-0.20260122202528-d9cc6641c482 // indirect
+)