psu/README.md

Portainer Stack Utils

Overview

Portainer Stack Utils is a CLI client for Portainer written in Go.

Supported Portainer API

This application was created for the latest Portainer API, which at the time of writing is 1.22.0.

How to install

Download the binaries for your platform from the releases page. The binaries have no external dependencies.

You can also install the source code with go and build the binaries yourself.

How to use

The application is built on a structure of commands, arguments and flags.

Commands represent actions, Args are things and Flags are modifiers for those actions:

APPNAME COMMAND ARG --FLAG

Here are some examples:

psu help
psu status --help
psu stack ls --endpoint primary --format "{{ .Name }}"
psu stack deploy mystack --stack-file docker-compose.yml -e .env --log-level debug
psu stack rm mystack

Commands can have subcommands, like stack ls and stack deploy in the previous example. They can also have aliases (i.e. create and up are aliases of deploy).

Some flags are global, which means they affect every command (i.e. --log-level), while others are local, which mean they only affect the command they belong to (i.e. --stack-file flag from deploy command). Also, some flags have a short version (i.e --insecure, -i).

Configuration

The program can be configured through inline flags (i.e. --user), environment variables (i.e. PSU_USER=admin) and/or configuration files, which translate into multi-level configuration keys in the form x[.y[.z[...]]]. Run psu config ls to see all available configuration options.

All three methods can be combined. If a configuration key is set in several places the order of precedence is:

1. Inline flags
2. Environment variables
3. Configuration file
4. Default values

Inline flags

Configuration can be set through inline flags. Valid combinations of commands and flags directly map to configuration keys:

Configuration key	Command	Flag
user	psu	--user
stack.list.format	psu stack list	--format
stack.deploy.env-file	stack deploy	--env-file

Run psu help COMMAND to see all available flags for a given command.

Environment variables

Configuration can be set through environment variables. Supported environment variables follow the PSU_[COMMAND_[SUBCOMMAND_]]FLAG naming pattern:

Configuration key	Environment variable
user	PSU_USER
stack.list.format	PSU_STACK_LIST_FORMAT
stack.deploy.env-file	PSU_STACK_DEPLOY_ENV_FILE

Note that all supported environment variables are prefixed with "PSU_" to avoid name clashing. Characters "-" and "." in configuration key names are replaced with "_" in environment variable names.

Configuration files

Configuration can be set through a configuration file. Supported file formats are JSON, TOML, YAML, HCL, envfile and Java properties config files. Use the --config global flag to specify a configuration file. File $HOME/.psu.yaml is used by default if present.

YAML configuration file

A Yaml configuration file should look like this:

log-level: debug
user: admin
insecure: true
stack.list.format: table
stack:
  deploy.env-file: .env
  deploy:
    stack-file: docker-compose.yml

Note that flat and nested keys are both valid.

JSON configuration file

A JSON configuration file should look like this:

{
  "log-level": "debug",
  "user": "admin",
  "insecure": true,
  "stack.list.format": "table",
  "stack": {
    "deploy.env-file": ".env",
    "deploy": {
      "stack-file": "docker-compose.yml"
    }
  }
}

Note that flat and nested keys are both valid.

Environment variables for deployed stacks

You will often want to set environment variables in your deployed stacks. You can do so through the stack.deploy.env-file configuration key. :

touch .env
echo "MYSQL_ROOT_PASSWORD=agoodpassword" >> .env
echo "ALLOWED_HOSTS=*" >> .env

# Using --env-file flag
psu stack deploy django-stack -c /path/to/docker-compose.yml -e .env

# Using PSU_STACK_DEPLOY_ENV_FILE environment variable
PSU_STACK_DEPLOY_ENV_FILE=.env
psu stack deploy django-stack -c /path/to/docker-compose.yml

# Using a config file
echo "stack.deploy.env-file: .env" > .config.yml
psu stack deploy django-stack -c /path/to/docker-compose.yml --config .config.yml

Verbose mode

In verbose mode the script prints execution steps.

2019/07/20 19:15:45 [Using config file: /home/johndoe/.psu.yaml]
2019/07/20 19:15:45 [Getting stack mystack...]
2019/07/20 19:15:45 [Getting auth token...]
2019/07/20 19:15:45 [Stack mystack not found. Deploying...]
2019/07/20 19:15:45 [Swarm cluster found with id qwe123rty456uio789asd123f]

Verbose mode can be enabled through the PSU_VERBOSE environment variable and the verbose configuration key.

Debug mode

In debug mode the script prints as much information as possible to help diagnosing a malfunction.

WARNING: Debug mode will print configuration values (with Portainer credentials) and Portainer API responses (with sensitive information like authentication token and stacks environment variables). Avoid using debug mode in CI/CD pipelines, as pipeline logs are usually recorded.

Debug mode can be enabled through the PSU_DEBUG environment variable and the debug configuration key.

Contributing

So, you want to contribute to the project:

• Fork it
• Download your fork to your PC (git clone https://github.com/your_username/portainer-stack-utils && cd portainer-stack-utils)
• Create your feature branch (git checkout -b my-new-feature)
• Make changes and add them (git add .)
• Commit your changes (git commit -m 'Add some feature')
• Push to the branch (git push origin my-new-feature)
• Create a new pull request

If you are submitting a complex feature, create a small design proposal on the issue tracker before you start.

License

Source code contained by this project is licensed under the GNU General Public License version 3. See LICENSE file for reference.