English | 中文
The command-line tool for OpenSaola — manage middleware lifecycle on Kubernetes: package installation, instance creation, status monitoring, version upgrades, and resource cleanup.
- kubectl-style — verb + resource type (
get/create/delete/describe), minimal learning curve - Interactive creation — TUI form guides baseline selection and parameter input, no manual YAML needed
- Bilingual —
--lang zh|enswitches all help text and output messages - Package management — build, install, upgrade, and uninstall middleware packages (zstd-compressed TAR)
- Image delivery — discover package images, export OCI/Docker archives, and import into offline registries
- Instance upgrades — annotation-driven rolling upgrades with
--waitfor completion - Multiple output formats —
table/yaml/json/wide/namefor easy scripting
Saola manages the following middleware through OpenSaola operator packages:
| Middleware | Description | Repository |
|---|---|---|
| MySQL | Relational database with master-slave and proxy modes | harmonycloud/mysql |
| PostgreSQL | Advanced relational database with high-availability | harmonycloud/postgresql |
| Apache Kafka | Distributed event streaming platform | harmonycloud/kafka |
| Redis | In-memory data store with sentinel and cluster modes | harmonycloud/redis |
| Elasticsearch | Distributed search and analytics engine | harmonycloud/elasticsearch |
| Apache ZooKeeper | Distributed coordination service | harmonycloud/zookeeper |
| RabbitMQ | Message broker with AMQP support | harmonycloud/rabbitmq |
git clone https://github.com/harmonycloud/saola-cli.git
cd saola-cli
make buildThe binary is at bin/saola. Copy it to your $PATH:
cp bin/saola /usr/local/bin/go install github.com/harmonycloud/saola-cli/cmd/saola@latest# 1. Install a middleware package
saola install ./redis-pkg --pkg-namespace middleware-operator --wait 5m
# 2. Interactively create Middleware and MiddlewareOperator
saola create
# 3. Check instance status
saola get middleware -n my-ns
saola get operator -n my-ns
# 4. View instance details
saola describe middleware my-redis -n my-ns
# 5. Upgrade instance version
saola upgrade middleware my-redis --to-version 2.0.0 -n my-ns --wait 5m
# 6. Delete instance
saola delete middleware my-redis -n my-nsThis example uses ./redis-pkg as the local package directory, registry.example.com/middleware as the source, and registry.internal.example.com/middleware as the destination. Replace these paths and addresses with your own. Install skopeo on both the export and import machines.
In the source environment:
# Validate the package and log in to the source registry
saola validate ./redis-pkg
skopeo login registry.example.com
# Preview candidates without downloading or checking image availability
saola images export ./redis-pkg -r registry.example.com/middleware --dry-run
# Export images, preserving multi-platform manifests by default
saola images export ./redis-pkg \
-r registry.example.com/middleware \
-o redis-images.tarCopy both redis-images.tar and redis-images.tar.lock.json to the destination environment, then run:
skopeo login registry.internal.example.com
saola images import redis-images.tar \
-r registry.internal.example.com/middleware --dry-run
saola images import redis-images.tar \
-r registry.internal.example.com/middlewareThe images are now in the destination registry. Configure the package's image repository for deployment separately. See the complete offline delivery example for the remaining steps.
Use the docker format for a single platform. The export machine needs Docker or nerdctl; this example uses Docker:
docker login registry.example.com
saola images export ./redis-pkg \
-r registry.example.com/middleware \
--format docker --platform linux/amd64 \
-o redis-amd64.tar
# Run on the destination machine after copying the archive
docker load -i redis-amd64.tarFor ARM64, use linux/arm64. To include both architectures, use --format docker-multi --platforms linux/amd64,linux/arm64: export requires skopeo, and the destination Docker must use the containerd image store. See image export and import for format details.
| Command | Description |
|---|---|
create |
Create Middleware / MiddlewareOperator from YAML or interactive TUI |
get |
List or view resources |
describe |
Show resource details (Spec, Status, Conditions) |
delete |
Delete resources |
run |
Trigger a MiddlewareAction (one-off operation) |
upgrade |
Upgrade package or Middleware / MiddlewareOperator instances |
install |
Install a middleware package to the cluster |
uninstall |
Uninstall a middleware package |
build |
Build a local directory into a zstd-compressed TAR (without installing) |
inspect |
View installed package contents and metadata |
images export <dir> |
Export package images as single-platform or multi-platform archives |
images import <archive> |
Push an OCI image archive to a target registry |
validate <dir> |
Validate a local package without a cluster connection |
disable package <name> |
Disable a package while retaining its Secret and published resources |
package (pkg) |
Package operations: build, validate, install, disable, uninstall, upgrade, list, inspect |
completion |
Generate Bash, Zsh, Fish, or PowerShell completion scripts |
help |
Show command help |
version |
Show version information |
Using get as an example — other verbs (describe/delete/upgrade) follow the same pattern:
| Subcommand | Alias | Description |
|---|---|---|
get middleware [name] |
mw |
List or view Middleware instances |
get operator [name] |
op |
List or view MiddlewareOperator instances |
get action [name] |
act |
List or view MiddlewareAction instances |
get baseline [name] |
bl |
View baselines from installed packages |
get package [name] |
pkg |
List or view installed packages |
get all |
- | Aggregate output of middleware + operator + action |
# Package upgrade (replace installed Package Secret)
saola upgrade <pkg-dir>
# Instance upgrade (trigger controller via annotation)
saola upgrade middleware <name> --to-version <version> [--baseline <bl>] [--wait 5m]
saola upgrade operator <name> --to-version <version> [--baseline <bl>] [--wait 5m]# Trigger an Action (e.g., backup, restore)
saola run <baseline> --middleware <mw-name> --params key1=val1,key2=val2 -n my-ns| Flag | Short | Default | Description |
|---|---|---|---|
--kubeconfig |
- | $KUBECONFIG or ~/.kube/config |
kubeconfig file path |
--context |
- | - | kubeconfig context |
--namespace |
-n |
- | Target namespace |
--pkg-namespace |
- | middleware-operator |
Namespace where package Secrets reside |
--lang |
- | zh |
Language: zh (Chinese) / en (English) |
--log-level |
- | info |
Log level: debug/info/warn/error |
--no-color |
- | false |
Disable colored output |
Resource commands also support:
| Flag | Short | Description |
|---|---|---|
--all-namespaces |
-A |
List resources across all namespaces |
--output |
-o |
Output format: table/yaml/json/wide/name |
--wait |
- | Timeout for waiting on operations (e.g., 5m) |
--dry-run |
- | Preview changes without executing |
| Variable | Description |
|---|---|
KUBECONFIG |
kubeconfig file path |
SAOLA_NAMESPACE |
Default namespace |
SAOLA_PKG_NAMESPACE |
Package Secret namespace (default: middleware-operator) |
CLI Flag > Environment Variable > Default Value
saola-cli/
├── cmd/saola/ # Entry point
├── internal/
│ ├── app/ # Root command registration
│ ├── cmd/ # All subcommand implementations
│ │ ├── action/ # MiddlewareAction
│ │ ├── baseline/ # Baseline queries
│ │ ├── build/ # Package building
│ │ ├── create/ # Resource creation (with interactive TUI)
│ │ ├── delete/ # Resource deletion
│ │ ├── describe/ # Resource details
│ │ ├── get/ # Resource listing
│ │ ├── inspect/ # Package inspection
│ │ ├── install/ # Package installation
│ │ ├── middleware/ # Middleware resource group
│ │ ├── operator/ # MiddlewareOperator resource group
│ │ ├── pkgcmd/ # Package management commands
│ │ ├── upgrade/ # Upgrades
│ │ ├── uninstall/ # Package uninstallation
│ │ ├── run/ # Action execution
│ │ └── version/ # Version info
│ ├── client/ # Kubernetes client wrapper
│ ├── config/ # Configuration management
│ ├── consts/ # Project constants
│ ├── lang/ # Bilingual support (zh/en)
│ ├── packager/ # TAR/zstd packaging
│ ├── printer/ # Output formatting (table/yaml/json)
│ ├── version/ # Version info injection
│ └── waiter/ # Async wait logic
├── Makefile
└── go.mod
# Build
make build # compile to bin/saola
# Test
make test # run unit tests
make lint # go vet static analysis
# Other
make tidy # tidy go modules
make clean # clean build artifactsVersion information is injected via ldflags:
saola version
# Version: v0.1.0
# Git Commit: 6bd4f94
# Build Date: 2026-03-31T07:46:11ZThe release workflow publishes Saola CLI independently:
- A push to
mainpublishes versiondev-<12-character-sha>as a workflow artifact only; it does not create a GitHub Release. - A
vMAJOR.MINOR.PATCHtag (optionally with a SemVer prerelease suffix) publishes an immutable GitHub Release with both Linux binaries,SHA256SUMS, SBOMs, signatures, and attestations. - OpenSaola resolves published final Releases from its own Docker workflow.
- No
OPENSAOLA_DISPATCH_TOKENis required and norepository_dispatchevent is sent.
Each release build contains static linux/amd64 and linux/arm64 binaries, SHA256SUMS, SPDX JSON SBOMs, and keyless Sigstore bundles. GitHub provenance attestations are associated with these files through GitHub's artifact attestation service; they are not files in dist/ or GitHub Release assets. Stable Release assets are immutable: an existing asset must match byte-for-byte, a published release cannot be repaired in place, and a draft is published only after every uploaded asset is downloaded and verified. The version, full commit SHA, and UTC build date are derived from the triggering commit. Local release artifacts can be reproduced with:
make release-build
make release-checksumsSaola manages the following Kubernetes custom resources via the OpenSaola operator:
| CRD | Short | Description |
|---|---|---|
| Middleware | mid |
Middleware instance |
| MiddlewareOperator | mo |
Operator instance managing a middleware type |
| MiddlewareAction | ma |
One-off operations (backup, restore, etc.) |
| MiddlewareBaseline | mb |
Default spec template for middleware |
| MiddlewareOperatorBaseline | mob |
Default spec template for operators |
| MiddlewarePackage | mp |
Packaged middleware distribution unit |
- Usage Guide | Usage Guide (English)
- Package Image Export and Import
- Testing Guide | Testing Guide (Chinese)
- OpenSaola Technical Documentation
- Package Authoring Guide
- Troubleshooting Guide
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Copyright 2025 The OpenSaola Authors.
Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.