psu/docs
2021-11-25 17:54:43 +01:00
..
assets Merge GitLab integration 2020-01-17 12:56:02 +00:00
_coverpage.md Merge GitLab integration 2020-01-17 12:56:02 +00:00
_sidebar.md Fix License link and add a License page in docs. 2020-01-17 12:56:02 +00:00
.nojekyll Merge GitLab integration 2020-01-17 12:56:02 +00:00
index.html Fix documentation scrolling between pages 2021-11-25 17:54:43 +01:00
README.md Bump psu version to 1.2.0 2021-09-14 11:24:46 +02:00

Portainer Stack Utils Docs
CLI Commands

Available actions

Name Description
deploy Deploy/update the given stack.
rm Remove/undeploy the given stack.
ls List stacks already deployed.
status Check if the stack is running/deployed correctly.
services List services already deployed in the current stack.
tasks List tasks in the current stack.
tasks:healthy List tasks who are running correctly in the current stack.
containers List containers running in the current stack.
login Log in to a Portainer instance.
lint Validate the Docker compose/stack file.
inspect Display low-level information of the current stack.
system:info Display Docker system-wide information.
actions List available actions for this program.
help Display help message.
version Display this program version.

Aliased actions

Aliased action Equivalent action
auth login
docker:info system:info
list ls
ps tasks
ps:healthy tasks:healthy
remove rm
undeploy rm
update deploy
validate lint

Available options

Flag Option Description Used in action(s)
-l --url=URL URL of the Portainer instance deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-u --user=USERNAME Username of the Portainer instance deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-p --password=PASSWORD Password of the Portainer instance deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-n --name=STACK_NAME Stack name deploy, rm, status, services, tasks, tasks:healthy, containers, inspect
-c, -f --compose-file=FILE_PATH Path to docker compose/stack file (required if action=deploy) deploy, lint
-C, -F --compose-file-base64=[BASE64] Content of docker compose/stack file, encoded in base64, useful with Docker in Docker (only used when action=deploy) deploy, lint
-g --env-file=[FILE_PATH] Path to a file of environment variables, to be used by the stack (only used when action=deploy) deploy
-G --env-file-base64=[BASE64] Content of file with environment variables, encoded in base64, to be used by the stack, useful with Docker in Docker (only used when action=deploy) deploy
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1 deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-r --prune Whether to prune unused containers or not (only used when action=deploy). Defaults to false deploy
-T --timeout=[SECONDS] Timeout, number of seconds before thrown an error (only used when action=status|tasks|tasks:healthy). Defaults to 100 status, tasks, tasks:healthy
-j --detect-job=[true|false] Auto detect services who are jobs in the current stack. Defaults to true status, tasks, tasks:healthy
-S --service=[SERVICE_NAME] Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers) status, tasks, tasks:healthy, containers
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-v --verbose Increase the verbosity of messages. Defaults to false deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, lint, inspect, system:info, actions
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, lint, inspect, system:info, actions
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-q --quiet Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false ls, services, tasks, tasks:healthy, containers, inspect
-t --strict Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to false deploy, rm
-L --lint=[true|false] Validate the Docker compose/stack file before deploying the stack (only used when action=deploy). Defaults to true deploy
-h --help Display help message. To display help of a given action, run: psu <action> --help deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, lint, inspect, system:info, actions, version
-V --version Display the version of this program
-s --secure=[yes|no] DEPRECATED: Use the --insecure option instead. Enable or disable the host's SSL certificate verification. Defaults to yes deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-a --action=[ACTION_NAME] DEPRECATED: Use <action> argument instead. The name of the action to execute

Available environment variables

Environment variable Description Used in action(s)
ACTION=ACTION_NAME The name of the action to execute n/a
PORTAINER_URL=URL URL of the Portainer instance deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
PORTAINER_USER=USERNAME Username of the Portainer instance deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
PORTAINER_PASSWORD=PASSWORD Password of the Portainer instance deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
PORTAINER_AUTH_TOKEN=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
PORTAINER_STACK_NAME=STACK_NAME Stack name deploy, rm, status, services, tasks, tasks:healthy, containers, inspect
DOCKER_COMPOSE_FILE=FILE_PATH Path to docker compose/stack file (required if action=deploy) deploy, lint
ENVIRONMENT_VARIABLES_FILE=[FILE_PATH] Path to a file of environment variables, to be used by the stack (only used when action=deploy) deploy
PORTAINER_ENDPOINT=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1 deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
PORTAINER_PRUNE=[true|false] Whether to prune unused containers or not (only used when action=deploy). Defaults to false deploy
TIMEOUT=[SECONDS] Timeout, number of seconds before thrown an error (only used when action=status|tasks|tasks:healthy). Defaults to 100 status, tasks, tasks:healthy
AUTO_DETECT_JOB=[true|false] Auto detect services who are jobs in the current stack. Defaults to true status, tasks, tasks:healthy
PORTAINER_SERVICE_NAME=[SERVICE_NAME] Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers) status, tasks, tasks:healthy, containers
HTTPIE_VERIFY_SSL=[yes|no] Enable or disable the host's SSL certificate verification. Defaults to yes deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
VERBOSE_MODE=[true|false] Increase the verbosity of messages. Defaults to false deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, lint, inspect, system:info, actions
DEBUG_MODE=[true|false] Print as much information as possible to help diagnosing a malfunction. Defaults to false deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, lint, inspect, system:info, actions
MASKED_VARIABLES=[true|extended|false] In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
QUIET_MODE=[true|false] Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false ls, services, tasks, tasks:healthy, containers, inspect
STRICT_MODE=[true|false] Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to false deploy, rm
DOCKER_COMPOSE_LINT=[true|false] Validate the Docker compose/stack file before deploying the stack (only used when action=deploy). Defaults to true deploy

Actions in details

deploy

Deploy/update the given stack.

Aliased action:

update

Usage:

psu deploy [options]

Examples:

psu deploy --user admin --password password --url https://portainer.local --name mystack --compose-file /path/to/docker-compose.yml --env-file /path/to/env_vars_file

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance
-n --name=STACK_NAME Stack name
-c, -f --compose-file=FILE_PATH Path to docker compose/stack file (required if action=deploy)

Optional options:

Flag Option Description
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1
-L --lint=[true|false] Validate the Docker compose/stack file before deploying the stack (only used when action=deploy). Defaults to true
-C, -F --compose-file-base64=[BASE64] Content of docker compose/stack file, encoded in base64, useful with Docker in Docker (only used when action=deploy)
-g --env-file=[FILE_PATH] Path to a file of environment variables, to be used by the stack (only used when action=deploy)
-G --env-file-base64=[BASE64] Content of file with environment variables, encoded in base64, to be used by the stack, useful with Docker in Docker (only used when action=deploy)
-r --prune Whether to prune unused containers or not (only used when action=deploy). Defaults to false
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-t --strict Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

rm

Remove/undeploy the given stack.

Aliased actions:

remove, undeploy

Usage:

psu rm [options]

Examples:

psu rm --user admin --password password --url https://portainer.local --name mystack

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance
-n --name=STACK_NAME Stack name

Optional options:

Flag Option Description
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-t --strict Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

ls

List stacks already deployed.

Aliased actions:

list

Usage:

psu ls [options]

Examples:

psu ls --user admin --password password --url https://portainer.local

Output a JSON array of the stacks already deployed:

[
  {
    "Id": "mystack_jpofkc0i9uo9wtx1zesuk649w",
    "Name": "mystack",
    "Type": "1",
    "EndpointID": "1",
    "EntryPoint": "docker-compose.yml",
    "SwarmID": "jpofkc0i9uo9wtx1zesuk649w",
    "ProjectPath": "/data/compose/mystack_jpofkc0i9uo9wtx1zesuk649w",
    "Env": [
      {
        "name": "MYSQL_ROOT_PASSWORD",
        "value": "password"
      }
    ]
  },
  {
    "Id": "mysecondstack_i0649w9uo9wtx1zesujpofkck",
    "Name": "mysecondstack",
    "Type": "1",
    "EndpointID": "1",
    "EntryPoint": "docker-compose.yml",
    "SwarmID": "i0649w9uo9wtx1zesujpofkck",
    "ProjectPath": "/data/compose/mysecondstack_i0649w9uo9wtx1zesujpofkck"
  },
  {
    "Id": "mythirdstack_w9uo9wtxi064ujpofkck91zes",
    "Name": "mythirdstack",
    "Type": "1",
    "EndpointID": "1",
    "EntryPoint": "docker-compose.yml",
    "SwarmID": "mythirdstack_w9uo9wtxi064ujpofkck91zes",
    "ProjectPath": "/data/compose/mythirdstack_mythirdstack_w9uo9wtxi064ujpofkck91zes"
  },
]

With the quiet mode enabled:

psu ls --user admin --password password --url https://portainer.local --quiet

Output the name of the stacks already deployed:

mystack
mysecondstack
mythirdstack

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance

Optional options:

Flag Option Description
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1
-q --quiet Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

status

Check if the stack is running/deployed correctly

If your stack has some services who acts as jobs, see the --detect-job option for more details.

This action is very useful in CI/CD pipelines, it's equivalent to the kubectl rollout status command of Kubernetes.

Usage:

psu status [options]

Examples:

psu status --user admin --password password --url https://portainer.local --name mystack

This command outputs nothing if the stack is correctly running or deployed.

It also has an exit code (or exit status). The exit code value return based on a command or program will successfully execute (return 0) or not (return 1 or higher).

psu status --user admin --password password --url https://portainer.local --name mystack --timeout 20

if [ $? -eq 0 ]; then
  echo "[OK] This stack is running/deployed correctly"
else
  echo "[ERROR] This stack isn't running/deployed correctly!"
fi

For more informations about exit code, you can read this article and this Wikipedia page

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance
-n --name=STACK_NAME Stack name

Optional options:

Flag Option Description
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1
-S --service=[SERVICE_NAME] Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers)
-j --detect-job=[true|false] Auto detect services who are jobs in the current stack. Defaults to true
-T --timeout=[SECONDS] Timeout, number of seconds before thrown an error (only used when action=status|tasks|tasks:healthy). Defaults to 100
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

services

List services already deployed in the current stack.

Usage:

psu services [options]

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance
-n --name=STACK_NAME Stack name

Optional options:

Flag Option Description
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1
-q --quiet Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

tasks

List tasks in the current stack.

If your stack has some services who acts as jobs, see the --detect-job option for more details.

Usage:

psu tasks [options]

Aliased action:

ps

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance
-n --name=STACK_NAME Stack name

Optional options:

Flag Option Description
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1
-S --service=[SERVICE_NAME] Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers)
-j --detect-job=[true|false] Auto detect services who are jobs in the current stack. Defaults to true
-T --timeout=[SECONDS] Timeout, number of seconds before thrown an error (only used when action=status|tasks|tasks:healthy). Defaults to 100
-q --quiet Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

tasks:healthy

List tasks who are running correctly in the current stack.

If your stack has some services who acts as jobs, see the --detect-job option for more details.

Usage:

psu tasks:healthy [options]

Aliased action:

ps:healthy

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance
-n --name=STACK_NAME Stack name

Optional options:

Flag Option Description
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1
-S --service=[SERVICE_NAME] Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers)
-j --detect-job=[true|false] Auto detect services who are jobs in the current stack. Defaults to true
-T --timeout=[SECONDS] Timeout, number of seconds before thrown an error (only used when action=status|tasks|tasks:healthy). Defaults to 100
-q --quiet Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

containers

List containers running in the current stack.

Usage:

psu containers [options]

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance
-n --name=STACK_NAME Stack name

Optional options:

Flag Option Description
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1
-S --service=[SERVICE_NAME] Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers)
-q --quiet Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

login

Log in to a Portainer instance.

Usage:

psu login [options]

Aliased action:

auth

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance

Optional options:

Flag Option Description
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

lint

Validate the Docker compose/stack file.

Usage:

psu lint [options]

Aliased action:

validate

Required options:

Flag Option Description
-c, -f --compose-file=FILE_PATH Path to docker compose/stack file (required if action=deploy)

Optional options:

Flag Option Description
-C, -F --compose-file-base64=[BASE64] Content of docker compose/stack file, encoded in base64, useful with Docker in Docker (only used when action=deploy)
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

inspect

Display low-level information of the current stack.

Usage:

psu inspect [options]

Examples:

psu inspect --user admin --password password --url https://portainer.local --name mystack

Output the JSON object of the stack if it's already deployed:

{
  "Id": "mystack_jpofkc0i9uo9wtx1zesuk649w",
  "Name": "mystack",
  "Type": "1",
  "EndpointID": "1",
  "EntryPoint": "docker-compose.yml",
  "SwarmID": "jpofkc0i9uo9wtx1zesuk649w",
  "ProjectPath": "/data/compose/mystack_jpofkc0i9uo9wtx1zesuk649w",
  "Env": [
    {
      "name": "MYSQL_ROOT_PASSWORD",
      "value": "password"
    }
  ]
}

With the quiet mode enabled:

psu inspect --user admin --password password --url https://portainer.local --name mystack --quiet

Output the stack name if it's already deployed:

mystack

Check if the stack is already deployed:

stack_exist=$(psu inspect --user admin --password password --url https://portainer.local --name mystack)

if [ -n "$stack_exist" ]; then
  echo OK
else
  echo KO
fi

## OR check the exit code of the last executed command:
stack_exist=$(psu inspect --user admin --password password --url https://portainer.local --name mystack)

status=$?
if $(exit $status); then
  echo OK
else
  echo KO
fi

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance
-n --name=STACK_NAME Stack name

Optional options:

Flag Option Description
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1
-q --quiet Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

system:info

Display Docker system-wide information.

Usage:

psu system:info [options]

Aliased action:

docker:info

Required options:

Flag Option Description
-l --url=URL URL of the Portainer instance
-u --user=USERNAME Username of the Portainer instance
-p --password=PASSWORD Password of the Portainer instance

Optional options:

Flag Option Description
-A --auth-token=[AUTH_TOKEN] Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e --endpoint=[ENDPOINT_ID] Which Docker endpoint to use. Defaults to 1
-i --insecure Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m --masked-variables In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

actions

List available actions for this program.

Optional options:

Flag Option Description
-v --verbose Increase the verbosity of messages. Defaults to false
-d --debug Print as much information as possible to help diagnosing a malfunction. Defaults to false
-h --help Display help message. To display help of a given action, run: psu <action> --help

help

Display help message.

version

Display this program version.

Optional options:

Flag Option Description
-h --help Display help message. To display help of a given action, run: psu <action> --help

Options in details

Stack environment variables

There can be set environment variables for each stack, be it a new deployment or an update. For example:

touch .env
echo "MYSQL_ROOT_PASSWORD=agoodpassword" >> .env
echo "ALLOWED_HOSTS=*" >> .env
psu deploy --user admin --password password --url https://portainer.local --name mystack --compose-file docker-compose.yml --env-file .env

Stack environment variables can be enabled through ENVIRONMENT_VARIABLES_FILE envvar or --env-file option or -g flag.

Verbose mode

In verbose mode the script prints execution steps.

Getting auth token...
Getting stack mystack...
Stack mystack not found.
Getting Docker info...
Getting swarm cluster (if any)...
Swarm cluster found.
Preparing stack JSON...
Creating stack mystack...

Verbose mode can be enabled through VERBOSE_MODE envvar or --verbose option or -v flag.

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 DEBUG_MODE envvar or --debug option or -d flag.

Strict mode

In strict mode the script never updates an existent stack nor removes an inexistent one, and instead exits with an error.

Strict mode can be enabled through STRICT_MODE envvar or --strict option or -t flag.

Quiet mode

In quiet mode the script prints the minimum of informations or nothing.

It's inspired by the --quiet option of docker images command.

Quiet mode can be enabled through QUIET_MODE envvar or --quiet option or -q flag.

detect-job option

The --detect-job option (true by default) detects if a service has a restart policy set to none and considered this service as a Job. If set to false, to considering a service as a Job, you need to set a container's label named job-name with the value you want (e.g. my-job-service-name) in the Docker compose/stack file.

See the Job definition section for more details.

Glossary

Job

Docker (or Portainer) doesn't have a true Job mechanism like Kubernetes.

But psu use an equivalent Docker behavior, based on filtering tasks status with a specific container's label (job-name). Or when, in your Docker compose/stack file, a service deploy.restart_policy.condition option is set to none.

The psu definition of a job is a Swarm service who ensures that all its specified task(s) successfully terminate.

Using a job is useful when you want to have a service who run a script (e.g. database migration). And shutdown this service when its script is successfully executed.

See the service named job in the docker-stack-web-app.yml file, for a real use case. It has both a container's label job-name and a restart policy set to none.