Skip to main content

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​

SubcommandDescription
canary statusShow the current canary deployment status
canary promotePromote the canary to primary
canary rollbackRoll back and remove the canary
canary update-trafficAdjust the canary traffic percentage
canary validateRun 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 status and nifectl canary validate before 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 rollback removes the canary and leaves the primary pods running unchanged, so it is safe to use whenever something looks wrong.
  • canary promote replaces all primary pods with the canary image and completes the rollout.

See Also​

Summary​

Nifectl Canary lets you roll a new image out gradually, check it against the primary, and promote or abort with one command.