nifectl canary Command Reference
Manage canary deployments.
Overview​
The canary commands manage canary deployments. A new image runs on a small share of pods (10% by default) while the existing primary stays unchanged. They mirror the Strategies tab in the nife.io dashboard.
Deploy with --deployment_strategy canary, then check the canary, adjust its traffic, and either promote it or roll it back.
Subcommands​
| Subcommand | Description |
|---|---|
canary status | Show the current canary deployment status |
canary promote | Promote the canary to primary |
canary rollback | Roll back and remove the canary |
canary update-traffic | Adjust the canary traffic percentage |
canary validate | Run health and metrics checks on the canary |
nifectl canary <subcommand> [flags]
Options​
-a, --app string App name to operate on (env: NIFE_APP)
-c, --config string Path to an app config file or directory containing one (env: NIFE_APP_CONFIG)
-h, --help Help for canary
Global Options​
-t, --access-token string Nife API Access Token
-j, --json JSON output format
-V, --verbose Verbose / debug output
canary status​
Show the current canary deployment status.
Display canary vs primary versions, traffic split, and live metrics for the app, mirroring the Strategies tab in the nife.io dashboard.
nifectl canary status [flags]
Options:
-a, --app string App name to operate on (env: NIFE_APP)
-c, --config string Path to an app config file or directory containing one (env: NIFE_APP_CONFIG)
canary promote​
Promote the canary to primary.
Graduate the canary pods to the primary slot, replacing all primary pods with the canary image. This completes the rollout.
nifectl canary promote [flags]
Options:
-a, --app string App name to operate on (env: NIFE_APP)
-c, --config string Path to an app config file or directory containing one (env: NIFE_APP_CONFIG)
Examples:
nifectl canary promote -a myapp
canary rollback​
Roll back and remove the canary.
Remove canary pods and keep the existing primary pods running unchanged. Use this when the canary behaves unexpectedly and you want to abort.
nifectl canary rollback [flags]
Options:
-a, --app string App name to operate on (env: NIFE_APP)
-c, --config string Path to an app config file or directory containing one (env: NIFE_APP_CONFIG)
Examples:
nifectl canary rollback -a myapp
canary update-traffic​
Adjust the canary traffic percentage.
Change the percentage of traffic routed to canary pods (0-100). The primary receives the remainder. Mirrors the "Update Traffic" button in the nife.io dashboard.
nifectl canary update-traffic [flags]
Options:
-a, --app string App name to operate on (env: NIFE_APP)
-c, --config string Path to an app config file or directory containing one (env: NIFE_APP_CONFIG)
--canary int Percentage of traffic to send to canary (0-100). Prompts interactively if omitted.
Examples:
nifectl canary update-traffic -a myapp --canary 20
canary validate​
Run health and metrics checks on the canary.
Validate the canary by checking error rate, latency, and throughput against the primary. Mirrors the "Validate Canary" button in the dashboard.
nifectl canary validate [flags]
Options:
-a, --app string App name to operate on (env: NIFE_APP)
-c, --config string Path to an app config file or directory containing one (env: NIFE_APP_CONFIG)
Examples:
nifectl canary validate -a myapp
Best Practices​
- Check
nifectl canary statusandnifectl canary validatebefore promoting. Validation compares error rate, latency and throughput with the primary. - Raise traffic in steps with
nifectl canary update-traffic --canary 20(0–100) instead of jumping to a full rollout. canary rollbackremoves the canary and leaves the primary pods running unchanged, so it is safe to use whenever something looks wrong.canary promotereplaces all primary pods with the canary image and completes the rollout.
See Also​
nifectl bg– Blue-green deploymentsnifectl abtest– Run two versions side by sidenifectl shadow– Try a new version without serving usersnifectl– The Nife CLI home command
Summary​
Nifectl Canary lets you roll a new image out gradually, check it against the primary, and promote or abort with one command.