nifectl shadow Command Reference
Manage shadow versions.
Overview​
A shadow version runs a new image next to the live version without serving any users, so you can watch how it behaves before it goes live. The live version is never touched until you promote the shadow. The shadow commands create, compare, mirror traffic to, promote and stop a shadow version.
Creating a shadow when one already exists replaces it.
Subcommands​
| Subcommand | Description |
|---|---|
shadow create | Start a new image as the shadow version |
shadow status | Compare the live and shadow versions |
shadow activity | Show what the live and shadow pods have been doing |
shadow mirror-stats | Compare live and shadow under copied traffic |
shadow mirror | Copy live traffic to the shadow version |
shadow promote | Make the shadow the live version |
shadow stop | Remove the shadow version |
nifectl shadow <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)
-y, --yes Accept all confirmations (some subcommands)
-h, --help Help for shadow
Global Options​
-t, --access-token string Nife API Access Token
-j, --json JSON output format
-V, --verbose Verbose / debug output
shadow create​
Start a new image as the shadow version.
Run an image next to the live version without serving users. If the app already has a shadow, it is replaced.
Without --image, the shadow runs the image the live version is running now. Use that to try different settings (--env-arg, --replicas) on the same image, or give --image to try a new build.
nifectl shadow create [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)
--image string Docker image to run as the shadow (default: the image the live version runs)
--env-arg strings Environment variable for the shadow in NAME=VALUE format (repeatable)
--replicas int Number of shadow replicas (default: same as the backend default)
-y, --yes Accept all confirmations
Examples:
nifectl shadow create -a myapp
nifectl shadow create -a myapp --env-arg MODE=test --replicas 1
nifectl shadow create -a myapp --image myrepo/myapp:2.0
shadow status​
Compare the live and shadow versions.
Show the image, pods and health of the live version and of the shadow version, and when the shadow was created.
nifectl shadow 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)
shadow activity​
Show what the live and shadow pods have been doing.
Show each live and shadow pod (state, restarts, CPU, memory, last exit) and recent cluster events. Read from the cluster when you ask; nothing is stored.
nifectl shadow activity [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)
--minutes int How many minutes back to look (default 60, at most 240)
shadow mirror-stats​
Compare live and shadow under copied traffic.
Show requests, errors and response times of the live and shadow versions while traffic is being copied, and the requests where they answered differently.
nifectl shadow mirror-stats [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)
--minutes int How many minutes back to look (default 60, at most 240)
shadow mirror​
Copy live traffic to the shadow version.
Copy a share of live GET, HEAD and OPTIONS requests to the shadow so the two can be compared with nifectl shadow mirror-stats.
| Subcommand | Description |
|---|---|
shadow mirror enable | Start copying live traffic to the shadow |
shadow mirror disable | Stop copying live traffic to the shadow |
nifectl shadow mirror <subcommand> [flags]
shadow mirror enable​
Start copying live traffic to the shadow.
Copy a share of live GET, HEAD and OPTIONS requests to the shadow.
Modes:
proxy A small proxy is placed in front of the live pods. Live traffic passes
through it. The live pods are not touched, and turning copying off
sends traffic straight to them again. Per-request results are recorded.
capture A capture sidecar is added to the live pods, so they restart one by one
(a rolling update). No per-request results are recorded. If the live
pods do not become ready with the sidecar, it is removed again.
nifectl shadow mirror enable [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)
--mode string How to copy traffic: proxy or capture (default "proxy")
--percent int Share of requests to copy, 1-100 (default 100)
-y, --yes Accept all confirmations
Examples:
nifectl shadow mirror enable -a myapp --mode proxy --percent 50
shadow mirror disable​
Stop copying live traffic to the shadow.
Stop copying traffic. In proxy mode, traffic goes straight to the live pods again.
nifectl shadow mirror disable [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)
shadow promote​
Make the shadow the live version.
Make exactly the shadow image the live version (no rebuild) with a rolling update, then remove the shadow. The previous live image stays in your release history, so nifectl releases rollback still works.
The shadow must be healthy first. Use --force to skip that check.
nifectl shadow 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)
--force Promote even if the shadow does not look healthy
-y, --yes Accept all confirmations
shadow stop​
Remove the shadow version.
Delete the shadow and leave the live version as it is.
nifectl shadow stop [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)
-y, --yes Accept all confirmations
Best Practices​
- Run
nifectl shadow createwithout--imageto try new settings (--env-arg,--replicas) on the image that is live now. - Prefer
proxymode for mirroring: the live pods are not touched.capturemode restarts the live pods one by one. - Read
shadow statusandshadow mirror-statsbefore you promote. Promote needs a healthy shadow;--forceskips that check. - The previous live image stays in your release history after a promote, so
nifectl releases rollbackstill works.
See Also​
nifectl canary– Roll out to a share of pods firstnifectl bg– Blue-green deploymentsnifectl releases– Release history and rollbacknifectl– The Nife CLI home command
Summary​
Nifectl Shadow lets you watch a new version run beside the live one, compare them under real traffic, and promote only when you are sure.