About Deployment Management with atscalectl
atscalectl is the official command-line tool for operating AtScale deployments running on Kubernetes. It provides operational workflows for managing AtScale environments, including:
- Deployment health checks
- Database backup and restore operations
- Retrieval of deployment credentials
- Collection of logs and troubleshooting information
For instructions on installing atscalectl, see Install atscalectl.
Commands
atscalectl provides the following commands.
| Command | Description |
|---|---|
| status | The status command shows the current state of an AtScale deployment running on Kubernetes. |
| backup | The backup command creates a backup of an AtScale deployment, including the PostgreSQL databases and Kubernetes configuration resources. |
| restore | The restore command restores the AtScale PostgreSQL databases from a backup directory created by atscalectl backup. |
| secrets get | The secrets get command retrieves deployment credentials and sensitive configuration values from Kubernetes secrets belonging to an AtScale deployment. |
| logs collect | The logs collect command exports logs from AtScale Kubernetes components into local files for troubleshooting and support cases. |
| version | The version command displays the atscalectl version and build information. |
| completion | The completion command generates shell completion scripts for atscalectl, allowing command names, subcommands, and flags to be completed using the Tab key. |
| uninstall | The uninstall command removes an AtScale Helm release and its Kubernetes resources from the cluster. |
Global flags
The following flags are supported by all atscalectl commands.
| Flag | Default Value | Description |
|---|---|---|
--kubeconfig | $KUBECONFIG or ~/.kube/config | Path to the kubeconfig file. |
--context | Current context | The Kubernetes context the command will run in. |
-n, --namespace | atscale | The AtScale namespace the command will run in. |
--release-name | Auto-detected | The name of the Helm release the command will run on. |
-o, --output | table | Format for the command's output (table, json, yaml, csv). For more information, see Output formats below. |
-v, --verbose | false | Enables verbose logging. |
--no-color | false | Disables colors in output. |
Output formats
All commands support multiple output formats. For example:
atscalectl status
atscalectl status -o json
atscalectl status -o yaml
atscalectl status -o csv
Diagnostic messages are written to stderr, allowing for clean output redirection:
atscalectl status -o json > status.json
Exit codes
atscalectl commands exit with one of the following codes.
| Code | Description |
|---|---|
0 | The command completed successfully. |
1 | The command failed, or a health check detected an unhealthy deployment. |
Security considerations
Backups
Be aware that backups may contain database contents, Kubernetes secrets, and credentials required for restoring the backup. You should store backup files with the same security controls as the original environment.
When uploading backups to Amazon S3, AtScale recommends you use S3 server-side encryption and proper Amazon Web Services IAM permissions.
For more information, see atscalectl backup.
Credentials
The secrets get command masks secret values by default. Use --reveal only when required and avoid exposing credentials in shared terminals or logs. For more information, see atscalectl secrets get.
AWS credentials
When uploading backups to Amazon S3, AWS credentials are never passed as command-line arguments. S3 operations use the standard AWS credential chain:
- IRSA when running inside AWS infrastructure
- Environment variables or AWS profiles when running locally
For more information, see atscalectl backup.
Important notes for working with all commands
Kubernetes context
All atscalectl commands need to know the Kubernetes context to run in. The current context is used by default. Before running atscalectl commands, you should verify the current Kubernetes context with:
kubectl config current-context
For production environments, always pass --context <context> explicitly.
When working with multiple Kubernetes clusters, you must always specify the context explicitly with the --context global flag, as shown below. This is especially important for destructive operations like restore, database operations, and environment maintenance.
atscalectl status \
--context <context> \
--namespace <namespace>
AtScale namespace
All atscalectl commands need to know the AtScale namespace to run in. By default, this is atscale. If your AtScale installation is in another namespace, you need to specify it explicitly with the --namespace global flag:
atscalectl status --namespace <namespace>
You can also use the flag's short form, -n:
atscalectl status -n <namespace>
AtScale Helm release
Most atscalectl commands require the AtScale Helm release name to locate the correct pods and secrets. This is detected automatically when there is only one Helm release in the namespace.
If you have multiple releases in the same namespace, commands will stop with an error:
could not auto-detect release name: multiple helm releases found in namespace "atscale": [atscale test] — specify --release-name
If this occurs, you must specify the release manually with the --release-name global flag:
atscalectl --release-name <name> status
Common usage examples
Check deployment health
atscalectl status
For more information, see atscalectl status.
Create a backup before an upgrade
atscalectl backup --mode full --output-dir <dir>
For more information, see atscalectl backup.
Collect troubleshooting logs
atscalectl logs collect --since 1h --output-dir <dir>
For more information, see atscalectl logs collect.
Troubleshooting atscalectl
When reporting issues, you should provide the version of atscalectl you're using:
atscalectl version
When applicable, you should also provide your AtScale logs:
atscalectl logs collect
Be sure to review collected logs before sharing externally, as they may contain environment-specific information.