Skip to main content

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​

SubcommandDescription
shadow createStart a new image as the shadow version
shadow statusCompare the live and shadow versions
shadow activityShow what the live and shadow pods have been doing
shadow mirror-statsCompare live and shadow under copied traffic
shadow mirrorCopy live traffic to the shadow version
shadow promoteMake the shadow the live version
shadow stopRemove 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.

SubcommandDescription
shadow mirror enableStart copying live traffic to the shadow
shadow mirror disableStop 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 create without --image to try new settings (--env-arg, --replicas) on the image that is live now.
  • Prefer proxy mode for mirroring: the live pods are not touched. capture mode restarts the live pods one by one.
  • Read shadow status and shadow mirror-stats before you promote. Promote needs a healthy shadow; --force skips that check.
  • The previous live image stays in your release history after a promote, so nifectl releases rollback still works.

See Also​

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.