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)
- 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 -n 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-ns| 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 |
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 <action-name> --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) |
--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)
- 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.