Development Commands

The commands you use during module development come from the SDK CLI embedded in your own module binary (cli.RegisterCommands in cmd/main.go), plus standard Go tooling. There is no code generator — components are written by hand, starting from the example-module template.

run

Run the module from source against a cluster:

go run ./cmd run --name my-module --version 0.0.1 \
  --kubeconfig ~/.kube/config --namespace tinysystems

Both --name and --version are required. The version must not start with v — the binary refuses to start with a v-prefixed version, matching the bare image tags in the module index.

On start, the binary registers a TinyModule CR, installs every component registered via registry.Register, starts leader election (one Lease per module), and begins reconciling TinyNodes in the namespace.

Set OTLP_DSN to export traces; set TINY_NATS_URL (and optionally TINY_NATS_TRANSPORT=jetstream) to use the NATS wire instead of gRPC for cross-module messages.

tools components-info

List the components the binary registers:

go run ./cmd tools components-info

With --json, it emits the discovery shape (name, description, info, tags — deliberately no ports) that a module repo's components.yaml carries:

go run ./cmd tools components-info --json > components.json

# Or from a built image at release time:
docker run --rm --entrypoint /manager ghcr.io/me/my-module:1.0.0 \
  tools components-info --json

The human mode also warns when an error port does not emit the canonical module.ErrorMessage shape ({context, error, retryable}).

tools rbac-values

Print the operator-chart rbac: values overlay derived from your module's registry.SetRequirements declaration:

docker run --rm --entrypoint /manager ghcr.io/me/my-module:1.0.0 \
  tools rbac-values > values.yaml

Generate your module's index values.yaml with this instead of writing it by hand — the install grants exactly what the code declares, so hand-maintained overlays drift into runtime 403s. A module that declares nothing emits nothing (no overlay file needed).

tools rbac-check

Static analysis of your module's source: resolves controller-runtime client calls and reports any not covered by the declared RBAC. Run it from the module root:

go run ./cmd tools rbac-check            # report only
go run ./cmd tools rbac-check --strict   # exit non-zero on gaps (for CI)

Two blind spots it documents itself: calls the SDK makes on your behalf (e.g. Service/Ingress updates for exposed ports), and dynamic resource access whose kind is only known at runtime — declare those manually.

pre-install / pre-delete

Helm lifecycle hooks the operator chart runs from your image. pre-install validates the install namespace: it refuses reserved namespaces (default, kube-system, ...) and requires the tinysystems.io/managed=true label. You rarely run these by hand; flags are --name/-n, --namespace, --kubeconfig/-k.

Standard Go tooling

Everything else is plain Go and Docker:

go test ./...                        # unit tests
go test -race -cover ./...          # with race detector and coverage
go vet ./... && golangci-lint run   # lint
docker build -t my-module:dev .     # build the image (see Building Modules)

Typical Session

# 1. Write a component under components/<name>/, register it via init()
# 2. Blank-import it in cmd/main.go
# 3. Test
go test ./components/myprocessor/...

# 4. Run against your dev cluster
go run ./cmd run --name my-module --version 0.0.1 --namespace tinysystems

# 5. Verify registration + error-port conformance
go run ./cmd tools components-info

# 6. Check RBAC coverage if the component touches the Kubernetes API
go run ./cmd tools rbac-check

Next Steps

• Module Scaffold - Project layout
• Local Testing - Testing strategies
• Building Modules - Production builds