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.21.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 --quiet --endpoint 5
psu stack deploy mystack --stack-file docker-compose.yml -e .env --verbose
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. --verbose), 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 --debug, -d).

Configuration

Each flag can be set inline (i.e. --debug), through an environment variable (i.e. PSU_DEBUG=true) and through a configuration file (see below). All three methods can be combined, but if a flag is set more than once the order of precedence is:

1. Inline flag
2. Environment variable
3. Configuration file

With inline flags

Each command has it's own flags. Run psu [COMMAND [SUBCOMMAND]] --help to see each command's flag set.

psu --help
psu stack --help
psu stack deploy --help

With environment variables

This is particularly useful for CI/CD pipelines.

Environment variables can be bound to flags following the PSU_[COMMAND_[SUBCOMMAND_]]FLAG naming pattern:

Command and subcommand	Flag	Environment variable	Comment
	--verbose	PSU_VERBOSE=true	All environment variables are prefixed with "PSU_"
stack list	--quiet	PSU_STACK_LIST_QUIET=true	Commands and subcommands are uppercased and joined with "_"
stack deploy	--env-file .env	PSU_STACK_DEPLOY_ENV_FILE=.env	Characters "-" in flag name are replaced with "_"

With configuration file

Flags can be bound to a configuration file. Use the --config flag to specify a configuration file to load flags from. By default the file $HOME/.psu.yaml is used if present.

Using Yaml

If you use a Yaml configuration file:

[command:
  [subcommand:]]
    flag: value

verbose: true
url: http://localhost:10000
insecure: true
stack:
  deploy:
    stack-file: docker-compose.yml
    env-file: .env
  list:
    quiet: true

This is valid too:

[command.[subcommand.]]flag: value

verbose: true
url: http://localhost:10000
insecure: true
stack.deploy.stack-file: docker-compose.yml
stack.deploy.env-file: .env
stack.list.quiet: true

Using Json

If you use a Json configuration file:

{
  ["command": {
    ["subcommand": {]]
      "flag": value
    [}]
  [}]
{

{
  "verbose": true,
  "url": "http://localhost:10000",
  "insecure": true,
  "stack": {
    "deploy": {
      "stack-file": "docker-compose.yml",
      "env-file": ".env"
    },
    "list": {
      "quiet": true
    }
  }
}

This is valid too:

{
  "[command.[subcommand.]]flag": value
}

{
"verbose": true,
"url": "http://localhost:10000",
"insecure": true,
"stack.deploy.stack-file": "docker-compose.yml",
"stack.deploy.env-file": ".env",
"stack.list.quiet": true
}

Stack environment variables

You will usually want to set some environment variables in your stacks. You can do so with the --env-file flag:

touch .env
echo "MYSQL_ROOT_PASSWORD=agoodpassword" >> .env
echo "ALLOWED_HOSTS=*" >> .env
psu stack deploy django-stack -c /path/to/docker-compose.yml -e .env

As every flag, this one can also be used with the PSU_STACK_DEPLOY_ENV_FILE environment variable and the psu.stack.deploy.env-file configuration key.

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.