Skopos™ Command Line Reference

This document describes the command line usage for the Skopos control utility, skopos.

It also describes how to run Skopos without using the control utility and the command line options available for the Skopos engine itself.

Command Line Options

Usage:

skopos [--globalopt ...] subcmd [--opt] [arg ...]

Global options:

  • --bind host:port - server socket, in the form 'host:port' (default :8100). If the host is omitted (e.g., --bind :8080), the wildcard address 0.0.0.0 is implied - this will attempt to connect to a Skopos engine running on any of the local interfaces.
  • --certfile - name of file with a CA certificate to use for validating the connection. Providing this option implies a secure (TLS) connection. When using a self-signed certificate, the same file can be given both to skopos and to the Skopos engine. If a secure connection is requested without --certfile (using --tls) and --tls-no-verify is not given, skopos will attempt to validate the connection using the OS default trusted CA certificates.
  • --tls - enable secure connection with default OS certificate authority bundle. This can be used if the Skopos engine was started with a certificate that is signed by a public CA.
  • --tls-no-verify - disable validation of server certificate. This option is implied when --bind specifies no hostname (local connection). NOTE if the Skopos engine is using a self-signed certificate and you are connecting to it remotely, it is preferable to have a copy of that certificate on the host running skopos and give the file name with --certfile, rather than use --tls-no-verify.
  • --version - print version and exit

Subcommands:

  • Load/Remove project:
    • load - load model and wait (for UI or CLI command)
    • run - load model and run immediately (same as load+start)
    • discover - discover applications running on the same infrastructure as Skopos
    • delete - remove an application from Skopos
  • Stack operations (docker syntax emulation):
    • stack - load, deploy, update or destroy a stack
  • Status:
    • list - list all applications (projects)
    • status - get the status of an application
  • Access:
    • login - log in and store an access token and the connection parameters for use in future skopos commands
    • logout - remove saved login token
  • Control:
    • start - start executing the plan
    • pause - pause plan execution
    • resume - resume paused plan execution
    • redo - (when paused on error) unpause and re-run the failed actions
    • ignore - (when paused on error) unpause and skip the failed actions; the actions are marked as 'completed' and the errors become warnings
    • abandon - stop a running deploy immediately
    • reset - re-evaluate state and generate a deployment plan if state differs from model
  • Low level commands:
    • get - raw API command - query
    • put - raw API command - set
    • post - raw API command - action

load and run Command Details

Both the load and the run command load a model descriptor, and any other provided resources such as target environment descriptors, whereupon:

  • load: waits for a start command
  • run: starts the deployment

Usage:

./skopos [--globalopt] load [--opt] FILE/URL ...

FILE/URL ... should include a model descriptor in YAML format. See the supported files schemes for descriptors section below for supported formats of the FILE/URL.

Options:

  • --bind host:port - server socket, in the form 'host:port' (default 0.0.0.0:8100)
  • --project string - project name (application instance identity) (default default). The project name must contain only alphanumeric characters or the characters _- (underscore and minus) and should not begin with a minus character.
  • --env file - target env description file (also in YAML format). If multiple environment files are specified, they are evaluated in the order provided. See the supported files schemes for descriptors section below for supported formats of the FILE/URL.
  • --profile string target environment profile: swarm, docker, ec2-asg, or emulator. The profile option loads as the first target environment description file a profile which sets the core plugin and standard attributes.
  • --vars file a file with key=value pairs on each line. The file's contents are read and converted to the form {"vars" : { "key":"value", ... } } and the resulting text is treated the same way as a file specified with --env. This is a simple alternative to be used for specifying replacement variables to be applied to the model, instead of having to create or edit a formatted YAML file. Files specified with either --env and --vars form a joint list and are interpreted in the order they are specified on the command line, with values from later files overwriting those found in earlier files.
  • --mode string - plan generation mode: deploy(default), teardown, preflight_only, postflight_only, postteardown_only
  • --autonomy string - auto-pilot autonomy mode: detect(default), deploy or off
  • --poll-interval seconds - poll interval for detecting state and image changes (for auto-pilot mode), default is 30 seconds
  • --replace-all - replace even instances that match component's target image in the model
  • --skip-autogates - skip autogate steps when generating plan
  • --skip-preflight - skip pre-flight steps when generating plan
  • --skip-postflight - skip post-flight steps when generating plan
  • --skip-postteardown - skip post-teardown steps when generating teardown plan

Supported files schemes for descriptors:

  • <path> path to a file on the system where the CLI is running, i.e., ./model.yaml
  • http:// http (or https) url to fetch the descriptor from, i.e., https://example.com/model.yaml
  • file:/// path to the descriptor on the filesystem where Skopos is running. This is useful when mapping descriptors inside the Skopos container and/or using sidecar pattern to fetch the latest descriptors. Example: file:///skopos/model.yaml
  • github:// fetch descriptor straight from the source code repository over Github's API in the format github://<owner>/<repo>/<path>[?ref=<branch-or-commit>]. ref can be set to the name of a branch, a tag or SHA hash of a commit. If not specified, the default branch (usually 'master') is used. Example: github://opsani/skopos-sample-app/env.yaml?ref=dev

The advantage of using the github:// form over getting Github's raw files over https is that the Github's API fetches the latest version of the file from the repository, while the raw files are served by a CDN and updates to files are delayed. The Github API is subject to Github's quotas (currently 60 queries per hour for unauthenticated access, used only when the file has changed).

The github:// schema supports authenticated access, which allows using higher quota limits and access to private github repositories (details about quota limits are available in the Github documentation: https://developer.github.com/v3/#rate-limiting). To enable authentication, you need to place a file with access credentials into /skopos/user/github.key (e.g., map a file into the Skopos container with -v my-auth-file://skopos/user/github.key on the command line). The file should contain either an access token (recommended; you create your token from the Github settings: https://github.com/settings/tokens) or a username and password separated by a colon. In either case, the file should contain nothing but the token or user:password string and either have no newlines or have a single newline as the last character.

run and start Command Options

The start command supports the following options, the same options are supported also by the run command in addition to those defined for load:

  • --wait - wait until the deploy operation completes and display progress along the way
  • --wait-timeout seconds - how long to wait for a deploy to complete when using the --wait option. 0 means forever (default 600)
  • -q - don't print deploy progress (used with --wait)
  • --interactive - automatically pause when an error occurs during a deploy
  • --save-effective-model filename - Save the effective model to filename
  • --save-effective-env filename - Save the effective environment to filename
  • --save-plan filename - Save the deploy plan to filename (even if automatically generated)
  • -t - alias for --transient
  • --transient - execute a transient deployment (no resident Skopos engine). See the transient deployments section below for details.

stack Command Details

The stack command provides emulation of the familiar docker stack command syntax used to deploy, update or destroy a stack. The supported stack sub-commands are:

  • load - load a stack into the Skopos engine (do not start deploy)
  • deploy - deploy or update a stack (alias up)
  • rm - destroy a stack (aliases remove and down)

The stack command supports the standard skopos global options, e.g., for bind and TLS control. By default stack operations run in the foreground and display progress.

stack load Command

Usage:

./skopos [--globalopt] stack load [--opt] STACK

STACK is the name of the stack, which is also the Skopos project name. The stack name must contain only alphanumeric characters or the characters _- (underscore and minus) and should not begin with a minus character.

Required Option:

  • -c - alias for --compose-file
  • --compose-file - Docker Compose file v2 or v3. Skopos can deploy both v2 and v3 compose files to either Docker (single host) or Docker Swarm. By default v2 compose files use the docker core plugin, while v3 compose files use the docker-swarm core plugin. This default may be over-ridden by the --profile option or by specifying a core plugin in a target environment description file.

See supported files schemes for descriptors for local and remote file specification formats.

Options:

  • --bind host:port - server socket, in the form 'host:port' (default 0.0.0.0:8100)
  • --env file - target env description file in YAML format. If multiple environment files are specified, they are evaluated in the order provided. See the supported files schemes for descriptors section above for supported formats.
  • --profile string target environment profile: swarm, docker, ec2-asg, or emulator. The profile option loads as the first target environment description file a profile which sets the core plugin and standard attributes.
  • --vars file a file with key=value pairs on each line. The file's contents are read and converted to the form {"vars" : { "key":"value", ... } } and the resulting text is treated the same way as a file specified with --env. This is a simple alternative to be used for specifying replacement variables to be applied to the model, instead of having to create or edit a formatted YAML file. Files specified with either --env and --vars form a joint list and are interpreted in the order they are specified on the command line, with values from later files overwriting those found in earlier files.
  • --autonomy string - auto-pilot autonomy mode: detect(default), deploy or off
  • --poll-interval seconds - poll interval for detecting state and image changes (for auto-pilot mode), default is 30 seconds
  • --force-recreate - recreate all container instances, even if their images have not changed
  • --skip-autogates - skip autogate steps when generating plan
  • --skip-preflight - skip pre-flight steps when generating plan
  • --skip-postflight - skip post-flight steps when generating plan
  • --skip-postteardown - skip post-teardown steps when generating teardown plan

stack deploy Command

Usage:

./skopos [--globalopt] stack deploy [--opt] STACK

STACK is the name of the stack, which is also the Skopos project name. The stack name must contain only alphanumeric characters or the characters _- (underscore and minus) and should not begin with a minus character.

Required Option:

  • -c - alias for --compose-file
  • --compose-file - Docker Compose file v2 or v3. Skopos can deploy both v2 and v3 compose files to either Docker (single host) or Docker Swarm. By default v2 compose files use the docker core plugin, while v3 compose files use the docker-swarm core plugin. This default may be over-ridden by the --profile option or by specifying a core plugin in a target environment description file.

See supported files schemes for descriptors for local and remote file specification formats.

Options:

  • --bind host:port - server socket, in the form 'host:port' (default 0.0.0.0:8100)
  • --env file - target env description file in YAML format. If multiple environment files are specified, they are evaluated in the order provided. See the supported files schemes for descriptors section above for supported formats.
  • --profile string target environment profile: swarm, docker, ec2-asg, or emulator. The profile option loads as the first target environment description file a profile which sets the core plugin and standard attributes.
  • --vars file a file with key=value pairs on each line. The file's contents are read and converted to the form {"vars" : { "key":"value", ... } } and the resulting text is treated the same way as a file specified with --env. This is a simple alternative to be used for specifying replacement variables to be applied to the model, instead of having to create or edit a formatted YAML file. Files specified with either --env and --vars form a joint list and are interpreted in the order they are specified on the command line, with values from later files overwriting those found in earlier files.
  • --autonomy string - auto-pilot autonomy mode: detect(default), deploy or off
  • --poll-interval seconds - poll interval for detecting state and image changes (for auto-pilot mode), default is 30 seconds
  • --force-recreate - recreate all container instances, even if their images have not changed
  • --skip-autogates - skip autogate steps when generating plan
  • --skip-preflight - skip pre-flight steps when generating plan
  • --skip-postflight - skip post-flight steps when generating plan
  • --skip-postteardown - skip post-teardown steps when generating teardown plan
  • -d - alias for --detach
  • --detach - run operation in the background
  • --timeout seconds - how long to wait for a deploy to complete if the operation is not detached. 0 means forever (default 0)
  • -q - don't print deploy progress
  • --interactive - automatically pause when an error occurs during a deploy
  • -t - alias for --transient
  • --transient - execute a transient deployment (no resident Skopos engine). See the transient deployments section below for details.

stack rm Command

Usage:

./skopos [--globalopt] stack rm [--opt] STACK

STACK is the name of the stack, which is also the Skopos project name.

Options:

  • --bind host:port - server socket, in the form 'host:port' (default 0.0.0.0:8100)
  • -d - alias for --detach
  • --detach - run operation in the background
  • --timeout seconds - how long to wait for the teardown to complete if the operation is not detached. 0 means forever (default 0)
  • -q - don't print teardown progress
  • --interactive - automatically pause when an error occurs during a teardown

login and logout Command Details

Usage:

./skopos [--globalopt] login USERNAME ./skopos logout

The login command will prompt for password and attempt to connect to the Skopos server and obtain a login token. If successful, the login token and all connection related options specified on the command line (--bind, --tls, --certfile, --tls-no-verify) are stored in a file in the current user's home directory (named $HOME/.skopos/login). The stored options become default for future skopos commands and need not be specified again, until skopos logout is executed.

The login command can be used even if the Skopos server is configured not to require login - in this case, the command will not prompt for password and will simply use the stored login file to remember the connection defaults for the convenience of future skopos command invocations.

skopos logout simply deletes the stored login file. It will succeed whether this file existed or not.

Transient Deployments

It is possible to run Skopos as a transient container that exists only for the duration of the deploy process and disappears right away after that - it acts as a single shell command executed synchronously. Such transient deployments do not require the Skopos engine (server) to be already running.

To execute a transient deployment, use the --transient option with the skopos run or skopos stack deploy CLI commands. Transient deployments:

  • require the docker command line client to be available on the PATH. Transient deployments execute docker run to run and remove the transient Skopos container.
  • ignore command line run options: autonomy, save*, poll-interval
  • ignore global command line client options: certfile, client-ca, client-cert
  • always run in the foreground and output progress
  • do not support a hostname for the --bind option (local access only)
  • require both the --autocert <val> and --bind :<port_number> global options in order to expose the transient Skopos server port to the host. Note that the --autocert option implies --tls and --tls-no-verify so that access to the bind port uses TLS.
  • respect the --logfile global option but default it to /var/log/skopos.log

For example, to transiently deploy the the Pet Voting Application for Docker Swarm:

skopos run --transient --project sample-gates \
--env github://opsani/skopos-sample-gates/env-swarm.yaml \
--env github://opsani/skopos-sample-gates/env-quality-gates.yaml \
github://opsani/skopos-sample-gates/model.yaml

To expose the transient Skopos server on the host port 10001 during the above deployment, add the following global options: --autocert '*' --bind :10001 (i.e., after skopos and before the run sub-command)

Low Level Command Examples

The get operation supports the following paths and options:

  • /applications/<project>/model - get the current model (original, as loaded)
  • /applications/<project>/model?effective=1 - get the effective model, with all var substitutions performed
  • /applications/<project>/environment - get the current effective environment (merged from all input descriptors that were loaded)
  • /applications/<project>/plan - get the current deployment plan (generated or loaded)

The put operation supports the following paths and options:

  • /applications/<project>/model - replace the current model (input read from stdin) and re-evaluate variables.
  • /applications/<project>/environment - replace the current environment (input read from stdin). This would replace all environment files that were previously loaded and re-evaluate any variables in the model.

Running skopos directly from the Skopos container

Although having skopos installed as a separate binary is usually the way to go (faster, lighter, etc.), Skopos also makes it possible to run Skopos commands by using the Skopos container. This may be useful when integrating with CI/CD and other automation systems, as well as when using an operating system for which skopos binary is not available.

Instead of using the skopos binary:

skopos run -bind <host>:<port> -wait -project myproject -env /data/env.yaml /data/model.yaml

Run the following Docker command:

sudo docker run --rm -ti   \
   -v `realpath .`:/data/  \
   opsani/skopos run -bind <host>:<port> -wait -project myproject -env /data/env.yaml /data/model.yaml

Replace the <host> and <port> above with the host and port on which the Skopos engine API is available.

If the realpath utility is not installed or you want to provide a path to a directory other than the current working directory, replace `realpath .` with the absolute path to the directory where the model and environment reside. If they come from different directories, you can mount multiple volumes and refer to their in-container paths.

This approach is avialable for all skopos commands, not only for run. Also, for commands that don't need access to the host filesystem, it is possible to omit the -v option:

sudo docker run --rm -ti \
   opsani/skopos -bind <host>:<port> start -project myproject

Also see Transient Deployments

Engine Arguments

The Skopos engine container supports all of the above commands and options, as well as the following options that are available only with the engine, or have a different meaning for the engine:

  • --bind host:port - server socket to expose UI and API, in the form 'host:port'. The host can be empty to listen on all interfaces (default :8100)
  • --plugin plugin action <arguments> - execute a plugin action (used for debugging)
  • --certfile filename - the name of a file in PEM format containing a server certificate and a matching private key (the key must not be encrypted with a password, e.g., use -nodes option with openssl when creating the certificate key). If you create a self-signed certificate, the same exact file (or a copy of it without the private key) can be used with --certfile on the skopos client command line. Using this option starts the server in secure mode (TLS) and clients connecting to it should also use secure mode to connect. Other than a file name, the following special strings are accepted as value for --certfile: - means "read from standard input", allowing one to transfer a certificate to the Skopos container without having to map a file with docker's -v option. . (dot) makes the engine try to open one of these paths as a certificate file:
    • /skopos/user/config/server.pem (this is convenient to map together with other files into the /skopos/user directory, using a single -v option)
    • /run/secrets/skopos_server_cert (if Skopos is running as a Swarm service, this can be mapped with the --secret docker option)
  • --autocert hostname - enables secure mode (TSL) with an internally generated self-signed certificate. hostname specifies the hostname in the certificate (stored as the 'Common Name' string in the x509 data). It must match the name that would be used in the client commands or in the browser when accessing the GUI. It can be set to * (to generate a 'wildcard' certificate, matching any hostname). If the Skopos engine is being restarted with the same --autocert option as from a previous start, the existing generated cert file will be reused (this allows saving it once and keeping it on the client host(s) and in the browser's list of accepted certificates). NOTE --autocert and --certfile cannot be used together.
  • --assume-secure - configures the engine to run behind a 3-rd party HTTP forwarder/proxy that provides TLS termination. This allows login support to be enabled and makes all browser cookies to be sent with the 'Secure' flag, however the Skopos server endpoint is open in plain HTTP mode. This option is ignored if either --autocert or --certfile is specified (either of the latter turns on the built-in TLS server).
  • --use-login - enables login support. To use this option, the server must be in secure mode (one of the --certfile --autocert or --assume-secure options must be set).