diff --git a/docs/reference/cli-reference.md b/docs/reference/cli-reference.md index c66d84e00..8dbb214a4 100644 --- a/docs/reference/cli-reference.md +++ b/docs/reference/cli-reference.md @@ -3,7 +3,7 @@ title: CLI Reference sidebar_position: 3 --- -This documentation is for the `up` CLI v0.43.0. +This documentation is for the `up` CLI v0.44.0. The latest version of `up` can be installed by running: @@ -114,6 +114,8 @@ import UpRepositoryPermissionGrant from '/cli/up_repository_permission_grant.md' import UpRepositoryPermissionList from '/cli/up_repository_permission_list.md'; import UpRepositoryPermissionRevoke from '/cli/up_repository_permission_revoke.md'; import UpRepositoryUpdate from '/cli/up_repository_update.md'; +import UpResource from '/cli/up_resource.md'; +import UpResourceCount from '/cli/up_resource_count.md'; import UpRobot from '/cli/up_robot.md'; import UpRobotCreate from '/cli/up_robot_create.md'; import UpRobotDelete from '/cli/up_robot_delete.md'; @@ -144,6 +146,10 @@ import UpSpaceLicenseShow from '/cli/up_space_license_show.md'; import UpSpaceList from '/cli/up_space_list.md'; import UpSpaceMirror from '/cli/up_space_mirror.md'; import UpSpaceUpgrade from '/cli/up_space_upgrade.md'; +import UpSupportBundle from '/cli/up_support-bundle.md'; +import UpSupportBundleCollect from '/cli/up_support-bundle_collect.md'; +import UpSupportBundleServe from '/cli/up_support-bundle_serve.md'; +import UpSupportBundleTemplate from '/cli/up_support-bundle_template.md'; import UpTeam from '/cli/up_team.md'; import UpTeamCreate from '/cli/up_team_create.md'; import UpTeamDelete from '/cli/up_team_delete.md'; @@ -492,6 +498,12 @@ import UpXrdGenerate from '/cli/up_xrd_generate.md'; ## up repository update +## up resource + + +## up resource count + + ## up robot @@ -582,6 +594,18 @@ import UpXrdGenerate from '/cli/up_xrd_generate.md'; ## up space upgrade +## up support-bundle + + +## up support-bundle collect + + +## up support-bundle serve + + +## up support-bundle template + + ## up team diff --git a/static/cli/up.md b/static/cli/up.md index 3db07080b..91f2b4222 100644 --- a/static/cli/up.md +++ b/static/cli/up.md @@ -19,6 +19,6 @@ Please report issues and feature requests at https://github.com/upbound/upbound. | ---- | ---------- | ----------- | | `--help` | `-h` | Show context-sensitive help. | | `--format` | | Format for get/list commands. Can be: json, yaml, default | -| `--quiet` | `-q` | Suppress all output. | +| `--quiet` | `-q` | Suppress all informational output. Command results will still be printed. | +| `--silent` | | Suppress all output. | | `--pretty` | | Pretty print output. | -| `--dry-run` | | dry-run output. | diff --git a/static/cli/up_controlplane_api-connector_install.md b/static/cli/up_controlplane_api-connector_install.md index ae07de9dd..bb62ea32a 100644 --- a/static/cli/up_controlplane_api-connector_install.md +++ b/static/cli/up_controlplane_api-connector_install.md @@ -44,6 +44,9 @@ up controlplane api-connector install --consumer-kubeconfig /path/to/kubeconfig | Flag | Short Form | Description | | ---- | ---------- | ----------- | +| `--set` | | Set parameters. | +| `--file` | `-f` | Parameters file. | +| `--bundle` | | Local bundle path. | | `--upgrade` | | Upgrade or downgrade the API Connector to --version, even if it is already installed. | | `--version` | | Version of the API Connector to install. If not provided, the latest, known to CLI, will be installed. | | `--name` | | Name of the related objects for named connection. If not provided, control plane name will be used with api-connector prefix. | @@ -52,6 +55,3 @@ up controlplane api-connector install --consumer-kubeconfig /path/to/kubeconfig | `--consumer-kubeconfig` | | Path to the kubeconfig file for the consumer cluster. If not provided, the default kubeconfig resolution will be used. | | `--consumer-context` | | Context to use in the kubeconfig file. If not provided, the current context will be used. | | `--helm-directory` | | Directory to store the Helm chart. If not provided, the default will be used. | -| `--set` | | Set parameters. | -| `--file` | `-f` | Parameters file. | -| `--bundle` | | Local bundle path. | diff --git a/static/cli/up_controlplane_connector_install.md b/static/cli/up_controlplane_connector_install.md index 4cb4c91e3..4e82761f9 100644 --- a/static/cli/up_controlplane_connector_install.md +++ b/static/cli/up_controlplane_connector_install.md @@ -20,10 +20,10 @@ Install mcp-connector into an App Cluster. | Flag | Short Form | Description | | ---- | ---------- | ----------- | +| `--set` | | Set parameters. | +| `--file` | `-f` | Parameters file. | +| `--bundle` | | Local bundle path. | | `--token` | | API token used to authenticate. If not provided, a new robot and a token will be created. | | `--cluster-name` | | Name of the cluster connecting to the control plane. If not provided, the namespace argument value will be used. | | `--installation-namespace` | `-n` | Kubernetes namespace for MCP Connector. Default is kube-system. | | `--control-plane-secret` | | Name of the secret that contains the kubeconfig for a control plane. | -| `--set` | | Set parameters. | -| `--file` | `-f` | Parameters file. | -| `--bundle` | | Local bundle path. | diff --git a/static/cli/up_controlplane_oidc-auth_aws.md b/static/cli/up_controlplane_oidc-auth_aws.md index 0827852f5..e46106689 100644 --- a/static/cli/up_controlplane_oidc-auth_aws.md +++ b/static/cli/up_controlplane_oidc-auth_aws.md @@ -67,3 +67,4 @@ up ctp oidc-auth aws example-project-aws-up-cli arn:aws:iam::aws:policy/Administ | `--provider-config-name` | | Provider AWS ProviderConfigName | | `--sub` | | Define the control plane name that the IAM Role trust policy will use in the 'sub' claim. Supports wildcards (using StringLike). | | `--yes` | | When set to true, automatically accepts any confirmation prompts. | +| `--dry-run` | | Print what changes would be made but do not take action. | diff --git a/static/cli/up_dependency_update-cache.md b/static/cli/up_dependency_update-cache.md index bacc6a8f4..805c2f3e4 100644 --- a/static/cli/up_dependency_update-cache.md +++ b/static/cli/up_dependency_update-cache.md @@ -42,3 +42,5 @@ Default is upbound.yaml. | ---- | ---------- | ----------- | | `--project-file` | `-f` | Path to project definition file. | | `--cache-dir` | | Directory used for caching package images. | +| `--git-token` | | Token for git HTTPS authentication (GitHub PAT, GitLab token, etc.). | +| `--git-username` | | Username for git HTTPS authentication. Use your Bitbucket username for Bitbucket app passwords. | diff --git a/static/cli/up_login.md b/static/cli/up_login.md index 9af52b143..68eaf4a45 100644 --- a/static/cli/up_login.md +++ b/static/cli/up_login.md @@ -77,3 +77,4 @@ up login --profile=production --organization=my-org | `--password` | `-p` | Password for specified user. '-' to read from stdin. | | `--token` | `-t` | Upbound API token (personal access token) used to execute command. '-' to read from stdin. | | `--use-device-code` | | Use authentication flow based on device code. We will also use this if it can't launch a browser in your behalf, e.g. in remote SSH | +| `--qr-code` | | Display a QR code for the login URL when using the device code login flow. | diff --git a/static/cli/up_project_build.md b/static/cli/up_project_build.md index 3f36be9ca..b4ba24042 100644 --- a/static/cli/up_project_build.md +++ b/static/cli/up_project_build.md @@ -21,3 +21,5 @@ Build a project into a Crossplane package. | `--build-cache-dir` | | Path to the build cache directory. | | `--max-concurrency` | | Maximum number of functions to build at once. | | `--cache-dir` | | Directory used for caching dependencies. | +| `--git-token` | | Token for git HTTPS authentication (GitHub PAT, GitLab token, etc.). | +| `--git-username` | | Username for git HTTPS authentication. Use your Bitbucket username for Bitbucket app passwords. | diff --git a/static/cli/up_project_run.md b/static/cli/up_project_run.md index 10d46ec8f..66c8ee90c 100644 --- a/static/cli/up_project_run.md +++ b/static/cli/up_project_run.md @@ -106,6 +106,13 @@ for example to test a v1 project on a v2 control plane: up project run --control-plane-version=v1.20.1-up.1 ``` +Apply `imageconfig.yaml` before installing the configuration and +`providerconfig.yaml` after installing the configuration: + +```shell +up project run --init-resources=imageconfig.yaml --extra-resources=providerconfig.yaml +``` + #### Usage @@ -133,3 +140,5 @@ up project run --control-plane-version=v1.20.1-up.1 | `--ingress` | | Enable ingress controller for the local dev control plane. | | `--ingress-port` | | Port mapping for the local dev control plane (e.g., '8080:80'). If not specified, a random available port will be selected when ingress is enabled. | | `--cluster-admin` | | Allow Crossplane cluster admin privileges in the local dev control plane. Defaults to true. | +| `--init-resources` | | Paths to additional resource manifests that should be applied before installing the project. | +| `--extra-resources` | | Paths to additional resource manifests that should be applied after installing the project. | diff --git a/static/cli/up_resource.md b/static/cli/up_resource.md new file mode 100644 index 000000000..3c77bb718 --- /dev/null +++ b/static/cli/up_resource.md @@ -0,0 +1,12 @@ +--- +mdx: + format: md +--- + +Gather information about resources in a cluster or control plane. + + + +#### Usage + +`up resource [flags]` diff --git a/static/cli/up_resource_count.md b/static/cli/up_resource_count.md new file mode 100644 index 000000000..7905d38f7 --- /dev/null +++ b/static/cli/up_resource_count.md @@ -0,0 +1,61 @@ +--- +mdx: + format: md +--- + +Count Crossplane resources in a cluster. + +The `up resource count` command counts Crossplane resources in a Kubernetes cluster, +providing a summary of managed resources, composite resources, claims, and composed resources. + +## Usage + +```bash +up resource count [flags] +``` + +### Examples + +```bash +# Count resources using the current kubeconfig context +up resource count + +# Count resources using a specific kubeconfig file +up resource count --kubeconfig /path/to/kubeconfig + +# Count resources using a specific context +up resource count --context my-cluster-context + +# Output in JSON format +up resource count --format json + +# Output in YAML format +up resource count --format yaml +``` + +## Resource Types + +The command counts the following Crossplane resource types: + +- **Managed Resources**: Resources directly managed by Crossplane providers (e.g., S3 Buckets, RDS Instances) +- **Composite Resources (XRs)**: Custom resources defined by CompositeResourceDefinitions +- **Composite Resource Claims (XRCs)**: Namespace-scoped claims for composite resources +- **Composed Resources**: Resources that are part of a composite resource's composition +- **Total Resources**: Sum of all counted resources + +## Notes + +- Resources are deduplicated to avoid double-counting +- ProviderConfig and related resources are excluded from the count +- The command discovers resources by examining CRDs owned by Crossplane providers and CompositeResourceDefinitions + + +#### Usage + +`up resource count [flags]` +#### Flags + +| Flag | Short Form | Description | +| ---- | ---------- | ----------- | +| `--kubeconfig` | | Path to kubeconfig file. | +| `--context` | | Kubeconfig context to use. | diff --git a/static/cli/up_space_init.md b/static/cli/up_space_init.md index 953d12a6b..8aa9e8cce 100644 --- a/static/cli/up_space_init.md +++ b/static/cli/up_space_init.md @@ -33,13 +33,13 @@ Initialize an Upbound Spaces deployment. | `--override-accounts-endpoint` | | Overrides the default accounts endpoint. | | `--kubeconfig` | | Override default kubeconfig path. | | `--kubecontext` | | Override default kubeconfig context. | +| `--set` | | Set parameters. | +| `--file` | `-f` | Parameters file. | +| `--bundle` | | Local bundle path. | | `--registry-repository` | | Set registry for where to pull OCI artifacts from. This is an OCI registry reference, i.e. a URL without the scheme or protocol prefix. | | `--registry-endpoint` | | Set registry endpoint, including scheme, for authentication. | | `--token-file` | | File containing authentication token. Expecting a JSON file. Example: {"accessId": "", "token": ""} | | `--registry-username` | | Set the registry username. | | `--registry-password` | | Set the registry password. | -| `--set` | | Set parameters. | -| `--file` | `-f` | Parameters file. | -| `--bundle` | | Local bundle path. | | `--yes` | | Answer yes to all questions | | `--public-ingress` | | For AKS,EKS,GKE expose ingress publically | diff --git a/static/cli/up_space_mirror.md b/static/cli/up_space_mirror.md index 41ddcf85b..b114281d3 100644 --- a/static/cli/up_space_mirror.md +++ b/static/cli/up_space_mirror.md @@ -49,3 +49,4 @@ up space mirror -v 1.9.0 --output-dir=/tmp/output --token-file=upbound-token.jso | `--output-dir` | `-t` | The local directory path where exported artifacts will be saved as .tgz files. | | `--destination-registry` | `-d` | The target container registry where the artifacts will be mirrored. | | `--version` | `-v` | **Required** The specific Spaces version for which the artifacts will be mirrored. | +| `--dry-run` | | Print what would be mirrored but do not take action. | diff --git a/static/cli/up_space_upgrade.md b/static/cli/up_space_upgrade.md index 5ccd3e792..d1a4067f0 100644 --- a/static/cli/up_space_upgrade.md +++ b/static/cli/up_space_upgrade.md @@ -33,13 +33,13 @@ Upgrade the Upbound Spaces deployment. | `--override-accounts-endpoint` | | Overrides the default accounts endpoint. | | `--kubeconfig` | | Override default kubeconfig path. | | `--kubecontext` | | Override default kubeconfig context. | +| `--set` | | Set parameters. | +| `--file` | `-f` | Parameters file. | +| `--bundle` | | Local bundle path. | | `--registry-repository` | | Set registry for where to pull OCI artifacts from. This is an OCI registry reference, i.e. a URL without the scheme or protocol prefix. | | `--registry-endpoint` | | Set registry endpoint, including scheme, for authentication. | | `--token-file` | | File containing authentication token. Expecting a JSON file. Example: {"accessId": "", "token": ""} | | `--registry-username` | | Set the registry username. | | `--registry-password` | | Set the registry password. | -| `--set` | | Set parameters. | -| `--file` | `-f` | Parameters file. | -| `--bundle` | | Local bundle path. | | `--yes` | | Answer yes to all questions | | `--rollback` | | Rollback to previously installed version on failed upgrade. | diff --git a/static/cli/up_support-bundle.md b/static/cli/up_support-bundle.md new file mode 100644 index 000000000..904ab558a --- /dev/null +++ b/static/cli/up_support-bundle.md @@ -0,0 +1,12 @@ +--- +mdx: + format: md +--- + +Collect support bundles for troubleshooting. + + + +#### Usage + +`up support-bundle [flags]` diff --git a/static/cli/up_support-bundle_collect.md b/static/cli/up_support-bundle_collect.md new file mode 100644 index 000000000..188fa8199 --- /dev/null +++ b/static/cli/up_support-bundle_collect.md @@ -0,0 +1,102 @@ +--- +mdx: + format: md +--- + +Collect a support bundle from the current kube context. + +The `up support-bundle collect` command allows you to collect diagnostic information from +your Kubernetes cluster or control plane for troubleshooting purposes. + +## Usage + +```bash +up support-bundle collect [flags] +``` + +### Examples + +```bash +# Collect a support bundle with default settings +up support-bundle collect + +# Collect a support bundle to a specific location +up support-bundle collect --output /tmp/my-support-bundle.tar.gz + +# Collect a support bundle with a custom configuration file +up support-bundle collect --config my-config.yaml + +# Collect a support bundle from specific namespaces +# By default, upbound-system, crossplane-system, and any control plane namespaces +# will be included. +up support-bundle collect --include-namespaces crossplane-system,upbound-system + +# Include namespaces using glob patterns +up support-bundle collect --include-namespaces upbound-* + +# Exclude certain namespaces from the support bundle +up support-bundle collect --exclude-namespaces kube-system + +# Exclude namespaces using glob patterns +up support-bundle collect --exclude-namespaces upbound-* + +# Collect only Crossplane resources (no logs, only CRDs and custom resources) +up support-bundle collect --crossplane-resources-only +``` + +## Configuration File + +You can provide a custom SupportBundle configuration file using the `--config` flag. +The configuration file can include both the SupportBundle spec and Redactors in a +single file using multi-document YAML format (separated by `---`). + +When using `--config`, the `--include-namespaces` and `--exclude-namespaces` flags +are ignored. The namespaces specified in the configuration file will be used instead. + +To generate a template configuration file that you can customize, use the +`up support-bundle template` command: + +```bash +# Generate a template and save it to a file +up support-bundle template > my-config.yaml + +# Then use it with the collect command +up support-bundle collect --config my-config.yaml +``` + +## Security + +All sensitive information is automatically redacted from the support bundle, +including: + +- Kubernetes secrets +- Passwords +- API keys +- IPv4 addresses in logs +- ConfigMap data fields +- EnvironmentConfig data fields +- Other sensitive data + +This ensures that support bundles can be safely shared for troubleshooting +purposes. You can customize redactors by including them in your configuration +file as a separate YAML document. + +**Important:** Before sharing a support bundle, always verify that no sensitive +data remains in the bundle. While automatic redaction covers common cases, you +should review the bundle contents to ensure all sensitive information has been +properly removed. + + +#### Usage + +`up support-bundle collect [flags]` +#### Flags + +| Flag | Short Form | Description | +| ---- | ---------- | ----------- | +| `--kubeconfig` | `-k` | Path to the kubeconfig file. If not provided, the default kubeconfig resolution will be used. | +| `--include-namespaces` | | Namespaces to include in the support bundle. Supports glob patterns (e.g., upbound-* to include all namespaces starting with "upbound-"). Multiple patterns can be specified. | +| `--exclude-namespaces` | | Namespaces to exclude from the support bundle. Supports glob patterns (e.g., upbound-* to exclude all namespaces starting with "upbound-"). Multiple patterns can be specified. | +| `--config` | `-c` | Path to a SupportBundle YAML configuration file. If provided, this will be used instead of the default configuration. Redactors can be included in the same file as a separate YAML document (multi-document YAML). | +| `--output` | `-o` | Output file path for the support bundle archive. If not specified, a timestamped filename will be used (e.g., upbound-support-bundle-20250105-163905.tar.gz). | +| `--crossplane-resources-only` | `-x` | Collect only Crossplane CRDs and custom resources. When this flag is set, log collectors are excluded and only Crossplane-related resources are included in the bundle. | diff --git a/static/cli/up_support-bundle_serve.md b/static/cli/up_support-bundle_serve.md new file mode 100644 index 000000000..966f3c3e1 --- /dev/null +++ b/static/cli/up_support-bundle_serve.md @@ -0,0 +1,61 @@ +--- +mdx: + format: md +--- + +Serve support bundle files via a local Kubernetes API server for live viewing. + +The `up support-bundle serve` command serves support bundle files over HTTP for live viewing. +It starts a local Kubernetes API server (not a full cluster), imports the support bundle resources, +and provides a kubeconfig file that allows you to interact with the bundle using standard +Kubernetes tools like `kubectl` or `k9s`. + +Note: This runs only the API server for viewing collected data, no workloads are actually running. + +## Usage + +```bash +up support-bundle serve [path] [flags] +``` + +### Examples + +```bash +# Serve a support bundle tar.gz file +up support-bundle serve ./upbound-support-bundle.tar.gz + +# Serve on a custom port +up support-bundle serve --port 9090 + +# Specify a custom kubeconfig output path +up support-bundle serve --kubeconfig-path ./my-kubeconfig +``` + +## Viewing the Bundle + +Once the server is running, you can use standard Kubernetes tools to view the bundle contents: + +```bash +kubectl --kubeconfig=./support-bundle-kubeconfig get pods --all-namespaces +kubectl --kubeconfig=./support-bundle-kubeconfig get all -A +kubectl --kubeconfig=./support-bundle-kubeconfig logs <pod-name> -n <namespace> +``` + + +#### Usage + +`up support-bundle serve [] [flags]` +#### Arguments + +| Argument | Description | +| -------- | ----------- | +| `` |**Optional** Path to support bundle directory or archive. | +#### Flags + +| Flag | Short Form | Description | +| ---- | ---------- | ----------- | +| `--host` | | Host to serve on. | +| `--port` | | Port to serve on. 0 means a random port will be chosen. | +| `--kubeconfig-path` | `-k` | Where to write the kubeconfig file. | +| `--envtest-arch` | `-a` | Arch value for Kubernetes API Server assets. | +| `--debug` | `-d` | Enable debug output. | diff --git a/static/cli/up_support-bundle_template.md b/static/cli/up_support-bundle_template.md new file mode 100644 index 000000000..3c49bf374 --- /dev/null +++ b/static/cli/up_support-bundle_template.md @@ -0,0 +1,43 @@ +--- +mdx: + format: md +--- + +Output the default SupportBundle YAML configuration template. + +The `up support-bundle template` command outputs the default SupportBundle YAML configuration +template that can be used as a starting point for custom support bundle configurations. + +## Usage + +```bash +up support-bundle template [flags] +``` + +### Examples + +```bash +# Output the default support bundle template +up support-bundle template + +# Output a template with specific namespaces +up support-bundle template --include-namespaces crossplane-system,upbound-system + +# Save the template to a file +up support-bundle template > my-support-bundle-config.yaml + +# Use the configuration file with the collect command +up support-bundle collect --config my-support-bundle-config.yaml +``` + + +#### Usage + +`up support-bundle template [flags]` +#### Flags + +| Flag | Short Form | Description | +| ---- | ---------- | ----------- | +| `--kubeconfig` | `-k` | Path to the kubeconfig file. If not provided, the default kubeconfig resolution will be used. | +| `--include-namespaces` | | Namespaces to include in the support bundle. Supports glob patterns (e.g., upbound-* to include all namespaces starting with "upbound-"). Multiple patterns can be specified. | +| `--exclude-namespaces` | | Namespaces to exclude from the support bundle. Supports glob patterns (e.g., upbound-* to exclude all namespaces starting with "upbound-"). Multiple patterns can be specified. | diff --git a/static/cli/up_uxp_install.md b/static/cli/up_uxp_install.md index 3ed24a6e8..10426c748 100644 --- a/static/cli/up_uxp_install.md +++ b/static/cli/up_uxp_install.md @@ -19,9 +19,9 @@ Install UXP. | Flag | Short Form | Description | | ---- | ---------- | ----------- | -| `--unstable` | | Allow installing unstable versions. | -| `--disable-web-ui` | | Disable the UXP web UI. | -| `--cluster-admin` | | Install UXP with cluster admin permissions. NOT FOR PRODUCTION PURPOSES. | | `--set` | | Set parameters. | | `--file` | `-f` | Parameters file. | | `--bundle` | | Local bundle path. | +| `--unstable` | | Allow installing unstable versions. | +| `--disable-web-ui` | | Disable the UXP web UI. | +| `--cluster-admin` | | Install UXP with cluster admin permissions. NOT FOR PRODUCTION PURPOSES. | diff --git a/static/cli/up_uxp_upgrade.md b/static/cli/up_uxp_upgrade.md index 7b59db5e6..aca32f3c3 100644 --- a/static/cli/up_uxp_upgrade.md +++ b/static/cli/up_uxp_upgrade.md @@ -19,9 +19,9 @@ Upgrade UXP. | Flag | Short Form | Description | | ---- | ---------- | ----------- | -| `--rollback` | | Rollback to previously installed version on failed upgrade. | -| `--force` | | Force upgrade even if versions are incompatible. | -| `--unstable` | | Allow installing unstable versions. | | `--set` | | Set parameters. | | `--file` | `-f` | Parameters file. | | `--bundle` | | Local bundle path. | +| `--rollback` | | Rollback to previously installed version on failed upgrade. | +| `--force` | | Force upgrade even if versions are incompatible. | +| `--unstable` | | Allow installing unstable versions. |