Using stanctl commands

Edit online

Use the command-line interface (CLI) stanctl for installing and configuring Instana.

Note: Use stanctl --help to see all available commands.
Attention:

Self-Hosted Standard Edition 1.10.3 and earlier versions:

  • For online (non–air‑gapped) installations, most stanctl lifecycle commands, such as stanctl up will fail to run.
  • For air‑gapped installations, the stanctl commands continue to work.

Required action: Upgrade stanctl to 1.10.4 or later versions before you perform a lifecycle operation.

Example: On online deployments that run stanctl 1.10.3 or earlier versions, any workflow that stops services, such as a stanctl down command, before a backup, cannot complete because the subsequent stanctl up command fails. Upgrade stanctl to 1.10.4 or later versions before you start these steps.

Frequently used commands

Edit online

The following stanctl commands are frequently used.

  • stanctl agent
  • stanctl backend
  • stanctl up

For more information about a command, use the --help flag.

stanctl [command] --help

Flags for custom configuration values

Edit online

The stanctl command uses default values for some configurations.

To use custom values instead of the default values, you can use flags to pass configuration values to the stanctl commands. Use stanctl [command] --help to see the list of available configuration options.

For example, stanctl uses the default /mnt/instana/stanctl/analytics mount point for Analytics. If you want to use a custom mount point, you can use the --volume-analytics flag. See the following example:

stanctl up --volume-analytics <custom-path>

Configuring update strategy for upgrades

Edit online

You can configure the Standard Edition deployment update strategy for backend components during upgrades by using the --core-update-strategy flag in the stanct command.

Update strategies

Edit online

The stanctl command supports the following update strategies:

  • RollingUpdate (default for production)

    • Ensures zero downtime during upgrades.
    • Requires additional central processing unit (CPU) and memory to run old and new pods simultaneously.
    • Recommended for production systems with sufficient resources.

  • Recreate (default for demo)

    • Causes brief downtime (several minutes) during upgrades.
    • Does not require additional capacity.
    • Recommended for resource-constrained systems, single-node deployments, or Standard Edition installations that use lightweight Kubernetes distributions such as K3s.
Note: Demo installations use the Recreate strategy by default. Production installations use the RollingUpdate strategy by default. You can override these defaults by using the --core-update-strategy flag.

For more information on when to use this strategy, see Upgrade fails with "Insufficient CPU" or "Insufficient memory" errors.

Usage examples

Edit online

Use the Recreate strategy for resource-constrained environments:

stanctl up --core-update-strategy=Recreate

Explicitly specify the RollingUpdate strategy:

stanctl up --core-update-strategy=RollingUpdate

Environment variables

Edit online

You can store custom configuration values as environment variables either by exporting the values or by storing them in an environment file (.env).

The environment variable name of a configuration flag must start with STANCTL_. Use --help to see the environment variable name of a flag.

For example, if you run stanctl up --help, you see that the environment variable name for the --volume-analytics flag is STANCTL_VOLUME_ANALYTICS.

When you define environment variables for flags, the stanctl command automatically uses the environment variable values for configuration.

Consider the --volume-analytics example used in the previous section. If you defined an environment variable for the flag, you can run the stanctl up command without specifying the --volume-analytics flag. The command uses the environment variable value.

However, if you define the environment variable and also specify the flag with the command, stanctl uses the value from the flag and not from the environment variable.

Export environment variables

Edit online

You can set environment variables by using the export command. However, this setting is not persistent.

See the following examples:

  • export STANCTL_VOLUME_ANALYTICS=/data/analytics
  • export STANCTL_CORE_BASE_DOMAIN=instana.example.com
  • export STANCTL_INSTALL_TYPE=production

Use environment file

Edit online

Add the environment variables in a .env file.

STANCTL_VOLUME_ANALYTICS=/data/analytics
STANCTL_CORE_BASE_DOMAIN=instana.example.com
STANCTL_INSTALL_TYPE=production

You can run the stanctl commands from the directory of the .env file.

stanctl up

Or, use the --env-file flag to specify the path to the environment file.

stanctl up --env-file <path-to-the-.env-file>

Instana backend and image versions

Edit online

Before you install or upgrade Standard Edition, you can see the list of installable Instana backend versions and images.

  • To view the list of Instana backend versions, run the following command. The command excludes your current and older backend versions from the list.

    stanctl versions identify

    See the following example:

    $ stanctl versions identify
⠏ Identifying supported Instana versions  [0s] ✓
Identified the following Instana versions:
- 3.283.450-0
- 3.281.446-0
- 3.279.395-0

  • To view the images that are available with an Instana backend version, run the following commands:

    • To select an Instana backend version and then see the available images in that version, run the following command:

      stanctl versions list-images

      See the following example:

      $ stanctl versions list-images
? Select Instana version:

[Use arrows to move, type to filter]
 > 3.283.450-0
   3.281.446-0
   3.279.395-0
   Cancel

stanctl versions list-images
? Select Instana version:

3.283.450-0
artifact-public.instana.io/backend/acceptor:3.283.450-0
artifact-public.instana.io/backend/accountant:3.283.450-0
artifact-public.instana.io/backend/action-orchestration:3.283.450-0
artifact-public.instana.io/backend/action-reader:3.283.450-0
.
.
.

    • To see the available images in a specified Instana backend version, run the following command. The prompt to select a backend version is not displayed.

      stanctl versions list-images --instana-version <backend-version>

      See the following example:

      $ stanctl versions list-images --instana-version 3.283.450-0

artifact-public.instana.io/backend/acceptor:3.283.450-0
artifact-public.instana.io/backend/accountant:3.283.450-0
artifact-public.instana.io/backend/action-orchestration:3.283.450-0
artifact-public.instana.io/backend/action-reader:3.283.450-0
.
.
.