feat: add resource {reconcile,suspend,resume} commands

cmd/crossplane/resource/resource.go

@@ -24,6 +24,9 @@ import (
 
 // Cmd contains commands for working with Crossplane resources.
 type Cmd struct {
-	Trace    trace.Cmd    `cmd:"" help:"Trace a Crossplane resource for troubleshooting."`
-	Validate validate.Cmd `cmd:"" help:"Validate Crossplane resources."`
+	Trace     trace.Cmd          `cmd:"" help:"Trace a Crossplane resource for troubleshooting."`
+	Validate  validate.Cmd       `cmd:"" help:"Validate Crossplane resources."`
+	Suspend   trace.SuspendCmd   `cmd:"" help:"Suspend crossplane resource reconciliation."`
+	Resume    trace.ResumeCmd    `cmd:"" help:"Resume reconciliation for suspended crossplane resources."`
+	Reconcile trace.ReconcileCmd `cmd:"" help:"Trigger an immediate reconcilication for a crossplane resource."`
 }

cmd/crossplane/trace/help/reconcile.md

@@ -0,0 +1,120 @@
+The `resource reconcile` command triggers an immediate reconciliation of a Crossplane resource (Claim, Composite, or
+Managed Resource).
+
+The command requires a resource type and a resource name:
+
+```shell
+crossplane resource reconcile <resource kind> <resource name>
+```
+
+Kubernetes-style `<kind>/<name>` input works too: for example, `crossplane
+resource reconcile example.crossplane.io/my-xr`.
+
+You can further specify the kind as `TYPE[.VERSION][.GROUP]` if needed; for
+example, `mykind.example.org` or `mykind.v1alpha1.example.org`.
+
+By default, `crossplane resource reconcile` uses the Kubernetes configuration at
+`~/.kube/config`. Override with the `KUBECONFIG` environment variable.
+
+By default the trigger only applies to the requested resource. Using `--cascade` this can be propagated
+to all sub resources recursively and can also be combined with `--watch` to follow the status.
+
+```shell
+crossplane resource reconcile <resource kind> <resource name> --cascade --watch
+```
+
+## Output options
+
+By default, `reconcile` prints to the terminal as a tree, truncating the `Ready` and
+`Status` messages to 64 characters.
+
+Change the format with `-o` (`--output`): `wide`, `json`, `yaml`, or `dot` (for
+a [Graphviz](https://graphviz.org/docs/layouts/dot/) graph).
+
+### Wide output
+
+Use `--output=wide` to print the full `Ready` and `Status` messages even when
+they exceed 64 characters, and other kind-specific printer columns.
+
+### Graphviz dot output
+
+Use `--output=dot` to print a textual
+[Graphviz dot](https://graphviz.org/docs/layouts/dot/) graph. Pipe to `dot` to
+render an image:
+
+```shell
+crossplane resource reconcile cluster.aws.platformref.upbound.io platform-ref-aws -o dot | dot -Tpng -o graph.png
+```
+
+## Print connection secrets
+
+Use `--show-connection-secrets` to include connection-secret names alongside the
+other resources. Secret values are never printed. Output includes the secret
+name and namespace.
+
+## Print package dependencies
+
+The `--show-package-dependencies` flag controls how the display of package
+dependencies:
+
+- `unique` (default): include each required package only once.
+- `all`: show every package that requires the same dependency.
+- `none`: hide all package dependencies.
+
+## Print package revisions
+
+The `--show-package-revisions` flag controls the display of package revisions:
+
+- `active` (default): show only the active revisions.
+- `all`: show all revisions, including inactive ones.
+- `none`: hide all revisions.
+
+## Examples
+
+Reconcile a `MyKind` resource named `my-res` in the namespace `my-ns`:
+
+```shell
+crossplane resource reconcile mykind my-res -n my-ns
+```
+
+Reconcile all `MyKind` resources in the namespace `my-ns`:
+
+```shell
+crossplane resource reconcile mykind -n my-ns
+```
+
+Wide format with full errors, condition messages, and kind-specific columns:
+
+```shell
+crossplane resource reconcile mykind my-res -n my-ns -o wide
+```
+
+Show connection secret names alongside the resources:
+
+```shell
+crossplane resource reconcile mykind my-res -n my-ns --show-connection-secrets
+```
+
+Output a Graphviz dot graph and pipe to dot to generate a PNG:
+
+```shell
+crossplane resource reconcile mykind my-res -n my-ns -o dot | dot -Tpng -o output.png
+```
+
+Output all retrieved resources as JSON and pipe to jq for color:
+
+```shell
+crossplane resource reconcile mykind my-res -n my-ns -o json | jq
+```
+
+Output debug logs to stderr while piping a dot graph to dot:
+
+```shell
+crossplane resource reconcile mykind my-res -n my-ns -o dot --verbose | dot -Tpng -o output.png
+```
+
+Watch a resource continuously until its deletion:
+
+```shell
+crossplane resource reconcile mykind my-res -n my-ns --watch
+```

cmd/crossplane/trace/help/resume.md

@@ -0,0 +1,120 @@
+The `resource resume` resumes any paused Crossplane resources (Claim, Composite, or
+Managed Resource).
+
+The command requires a resource type and a resource name:
+
+```shell
+crossplane resource resume <resource kind> <resource name>
+```
+
+Kubernetes-style `<kind>/<name>` input works too: for example, `crossplane
+resource resume example.crossplane.io/my-xr`.
+
+You can further specify the kind as `TYPE[.VERSION][.GROUP]` if needed; for
+example, `mykind.example.org` or `mykind.v1alpha1.example.org`.
+
+By default, `crossplane resource resume` uses the Kubernetes configuration at
+`~/.kube/config`. Override with the `KUBECONFIG` environment variable.
+
+By default the trigger only applies to the requested resource. Using `--cascade` this can be propagated
+to all sub resources recursively and can also be combined with `--watch` to follow the status.
+
+```shell
+crossplane resource reconcile <resource kind> <resource name> --cascade --watch
+```
+
+## Output options
+
+By default, `resume` prints to the terminal as a tree, truncating the `Ready` and
+`Status` messages to 64 characters.
+
+Change the format with `-o` (`--output`): `wide`, `json`, `yaml`, or `dot` (for
+a [Graphviz](https://graphviz.org/docs/layouts/dot/) graph).
+
+### Wide output
+
+Use `--output=wide` to print the full `Ready` and `Status` messages even when
+they exceed 64 characters, and other kind-specific printer columns.
+
+### Graphviz dot output
+
+Use `--output=dot` to print a textual
+[Graphviz dot](https://graphviz.org/docs/layouts/dot/) graph. Pipe to `dot` to
+render an image:
+
+```shell
+crossplane resource resume cluster.aws.platformref.upbound.io platform-ref-aws -o dot | dot -Tpng -o graph.png
+```
+
+## Print connection secrets
+
+Use `--show-connection-secrets` to include connection-secret names alongside the
+other resources. Secret values are never printed. Output includes the secret
+name and namespace.
+
+## Print package dependencies
+
+The `--show-package-dependencies` flag controls how the display of package
+dependencies:
+
+- `unique` (default): include each required package only once.
+- `all`: show every package that requires the same dependency.
+- `none`: hide all package dependencies.
+
+## Print package revisions
+
+The `--show-package-revisions` flag controls the display of package revisions:
+
+- `active` (default): show only the active revisions.
+- `all`: show all revisions, including inactive ones.
+- `none`: hide all revisions.
+
+## Examples
+
+Resume a `MyKind` resource named `my-res` in the namespace `my-ns`:
+
+```shell
+crossplane resource resume mykind my-res -n my-ns
+```
+
+Resume all `MyKind` resources in the namespace `my-ns`:
+
+```shell
+crossplane resource resume mykind -n my-ns
+```
+
+Wide format with full errors, condition messages, and kind-specific columns:
+
+```shell
+crossplane resource resume mykind my-res -n my-ns -o wide
+```
+
+Show connection secret names alongside the resources:
+
+```shell
+crossplane resource resume mykind my-res -n my-ns --show-connection-secrets
+```
+
+Output a Graphviz dot graph and pipe to dot to generate a PNG:
+
+```shell
+crossplane resource resume mykind my-res -n my-ns -o dot | dot -Tpng -o output.png
+```
+
+Output all retrieved resources as JSON and pipe to jq for color:
+
+```shell
+crossplane resource resume mykind my-res -n my-ns -o json | jq
+```
+
+Output debug logs to stderr while piping a dot graph to dot:
+
+```shell
+crossplane resource resume mykind my-res -n my-ns -o dot --verbose | dot -Tpng -o output.png
+```
+
+Watch a resource continuously until its deletion:
+
+```shell
+crossplane resource resume mykind my-res -n my-ns --watch
+```

cmd/crossplane/trace/help/suspend.md

@@ -0,0 +1,120 @@
+The `resource suspend` command pauses the reconciliation a Crossplane resource (Claim, Composite, or
+Managed Resource).
+
+The command requires a resource type and a resource name:
+
+```shell
+crossplane resource suspend <resource kind> <resource name>
+```
+
+Kubernetes-style `<kind>/<name>` input works too: for example, `crossplane
+resource suspend example.crossplane.io/my-xr`.
+
+You can further specify the kind as `TYPE[.VERSION][.GROUP]` if needed; for
+example, `mykind.example.org` or `mykind.v1alpha1.example.org`.
+
+By default, `crossplane resource suspend` uses the Kubernetes configuration at
+`~/.kube/config`. Override with the `KUBECONFIG` environment variable.
+
+By default the trigger only applies to the requested resource. Using `--cascade` this can be propagated
+to all sub resources recursively and can also be combined with `--watch` to follow the status.
+
+```shell
+crossplane resource reconcile <resource kind> <resource name> --cascade --watch
+```
+
+## Output options
+
+By default, `suspend` prints to the terminal as a tree, truncating the `Ready` and
+`Status` messages to 64 characters.
+
+Change the format with `-o` (`--output`): `wide`, `json`, `yaml`, or `dot` (for
+a [Graphviz](https://graphviz.org/docs/layouts/dot/) graph).
+
+### Wide output
+
+Use `--output=wide` to print the full `Ready` and `Status` messages even when
+they exceed 64 characters, and other kind-specific printer columns.
+
+### Graphviz dot output
+
+Use `--output=dot` to print a textual
+[Graphviz dot](https://graphviz.org/docs/layouts/dot/) graph. Pipe to `dot` to
+render an image:
+
+```shell
+crossplane resource suspend cluster.aws.platformref.upbound.io platform-ref-aws -o dot | dot -Tpng -o graph.png
+```
+
+## Print connection secrets
+
+Use `--show-connection-secrets` to include connection-secret names alongside the
+other resources. Secret values are never printed. Output includes the secret
+name and namespace.
+
+## Print package dependencies
+
+The `--show-package-dependencies` flag controls how the display of package
+dependencies:
+
+- `unique` (default): include each required package only once.
+- `all`: show every package that requires the same dependency.
+- `none`: hide all package dependencies.
+
+## Print package revisions
+
+The `--show-package-revisions` flag controls the display of package revisions:
+
+- `active` (default): show only the active revisions.
+- `all`: show all revisions, including inactive ones.
+- `none`: hide all revisions.
+
+## Examples
+
+Suspend a `MyKind` resource named `my-res` in the namespace `my-ns`:
+
+```shell
+crossplane resource suspend mykind my-res -n my-ns
+```
+
+Suspend all `MyKind` resources in the namespace `my-ns`:
+
+```shell
+crossplane resource suspend mykind -n my-ns
+```
+
+Wide format with full errors, condition messages, and kind-specific columns:
+
+```shell
+crossplane resource suspend mykind my-res -n my-ns -o wide
+```
+
+Show connection secret names alongside the resources:
+
+```shell
+crossplane resource suspend mykind my-res -n my-ns --show-connection-secrets
+```
+
+Output a Graphviz dot graph and pipe to dot to generate a PNG:
+
+```shell
+crossplane resource suspend mykind my-res -n my-ns -o dot | dot -Tpng -o output.png
+```
+
+Output all retrieved resources as JSON and pipe to jq for color:
+
+```shell
+crossplane resource suspend mykind my-res -n my-ns -o json | jq
+```
+
+Output debug logs to stderr while piping a dot graph to dot:
+
+```shell
+crossplane resource suspend mykind my-res -n my-ns -o dot --verbose | dot -Tpng -o output.png
+```
+
+Watch a resource continuously until its deletion:
+
+```shell
+crossplane resource suspend mykind my-res -n my-ns --watch
+```