mirror of
https://gitlab.com/psuapp/psu.git
synced 2024-08-30 18:12:34 +00:00
181 lines
7.7 KiB
Markdown
181 lines
7.7 KiB
Markdown
# Portainer Stack Utils
|
|
|
|
[](https://hub.docker.com/r/greenled/portainer-stack-utils/)
|
|
[](https://hub.docker.com/r/greenled/portainer-stack-utils/)
|
|
[](http://microbadger.com/images/greenled/portainer-stack-utils "Image size")
|
|
|
|
Bash script to deploy/update/undeploy stacks in a [Portainer](https://portainer.io/) instance from a [docker-compose](https://docs.docker.com/compose) [yaml file](https://docs.docker.com/compose/compose-file). Based on previous work by [@vladbabii](https://github.com/vladbabii) on [docker-how-to/portainer-bash-scripts](https://github.com/docker-how-to/portainer-bash-scripts).
|
|
|
|
## Supported Portainer API
|
|
|
|
Script was created for the latest Portainer API, which at the time of writing is [1.19.2](https://app.swaggerhub.com/apis/deviantony/Portainer/1.19.2).
|
|
|
|
## How to install
|
|
|
|
### Standalone
|
|
|
|
Just clone the repo and use the script:
|
|
|
|
```bash
|
|
git clone https://github.com/greenled/portainer-stack-utils.git
|
|
cd portainer-stack-utils
|
|
./psu -a deploy ...
|
|
```
|
|
|
|
For detailed instructions, see [How to use](#how-to-use) section.
|
|
|
|
#### Requirements
|
|
|
|
You will need these dependencies installed:
|
|
|
|
- [bash](https://www.gnu.org/software/bash/)
|
|
- [httpie](https://httpie.org/)
|
|
- [jq](https://stedolan.github.io/jq/)
|
|
|
|
For Debian and similar apt-powered systems: `apt install bash httpie jq`.
|
|
|
|
### Docker image
|
|
|
|
Use [the published Docker image](https://hub.docker.com/r/greenled/portainer-stack-utils/):
|
|
|
|
```bash
|
|
docker run -e ACTION=deploy greenled/portainer-stack-utils ...
|
|
```
|
|
|
|
See the [With envvars](#with-envvars) section for a list of all supported environment variables.
|
|
For detailed instructions, see [How to use](#how-to-use) section.
|
|
|
|
|
|
#### Tags
|
|
|
|
Published images are [tagged](https://hub.docker.com/r/greenled/portainer-stack-utils/tags/) matching [GitHub releases](https://github.com/greenled/portainer-stack-utils/releases):
|
|
|
|
- `latest`, `0.1.1` -> `0.1.1`
|
|
- `0.1.0` -> `0.1.0`
|
|
- ...
|
|
- `dev` -> `master`
|
|
|
|
## How to use
|
|
|
|
The provided `psu` script allows to deploy/update/undeploy Portainer stacks. Settings can be passed through envvars and/or flags. Both envvars and flags can be mixed but flags will always overwrite envvar values. When deploying a stack, if it doesn't exist a new one is created, otherwise it's updated (unless strict mode is active).
|
|
|
|
### With envvars
|
|
|
|
This is particularly useful for CI/CD pipelines using Docker containers.
|
|
|
|
- `ACTION` ("deploy" or "undeploy", required): Whether to deploy or undeploy the stack
|
|
- `PORTAINER_USER` (string, required): Username
|
|
- `PORTAINER_PASSWORD` (string, required): Password
|
|
- `PORTAINER_URL` (string, required): URL to Portainer
|
|
- `PORTAINER_STACK_NAME` (string, required): Stack name
|
|
- `DOCKER_COMPOSE_FILE` (string, required if action=deploy): Path to doker-compose file
|
|
- `ENVIRONMENT_VARIABLES_FILE` (string, optional, only used when action=deploy or action=update): Path to file with environment variables to be used by the stack. See [stack environment variables](#stack-environment-variables) below.
|
|
- `PORTAINER_PRUNE` ("true" or "false", optional): Whether to prune unused containers or not. Defaults to `"false"`.
|
|
- `PORTAINER_ENDPOINT` (int, optional): Which endpoint to use. Defaults to `1`.
|
|
- `HTTPIE_VERIFY_SSL` ("yes" or "no", optional): Whether to verify SSL certificate or not. Defaults to `"yes"`.
|
|
- `VERBOSE_MODE` ("true" or "false", optional): Whether to activate verbose output mode or not. Defaults to `"false"`. See [verbose mode](#verbose-mode) below.
|
|
- `DEBUG_MODE` ("true" or "false", optional): Whether to activate debug output mode or not. Defaults to `"false"`. See [debug mode](#debug-mode) below.
|
|
- `STRICT_MODE` ("true" or "false", optional): Whether to activate strict mode or not. Defaults to `"false"`. See [strict mode](#strict-mode) below.
|
|
|
|
#### Examples
|
|
|
|
```bash
|
|
export ACTION="deploy"
|
|
export PORTAINER_USER="admin"
|
|
export PORTAINER_PASSWORD="password"
|
|
export PORTAINER_URL="http://portainer.local"
|
|
export PORTAINER_STACK_NAME="mystack"
|
|
export DOCKER_COMPOSE_FILE="/path/to/docker-compose.yml"
|
|
export ENVIRONMENT_VARIABLES_FILE="/path/to/env_vars_file"
|
|
|
|
./psu
|
|
```
|
|
|
|
```bash
|
|
export ACTION="undeploy"
|
|
export PORTAINER_USER="admin"
|
|
export PORTAINER_PASSWORD="password"
|
|
export PORTAINER_URL="http://portainer.local"
|
|
export PORTAINER_STACK_NAME="mystack"
|
|
|
|
./psu
|
|
```
|
|
|
|
### With flags
|
|
|
|
This is more suitable for standalone script usage.
|
|
|
|
- `-a` ("deploy" or "undeploy", required): Whether to deploy or undeploy the stack
|
|
- `-u` (string, required): Username
|
|
- `-p` (string, required): Password
|
|
- `-l` (string, required): URL to Portainer
|
|
- `-n` (string, required): Stack name
|
|
- `-c` (string, required if action=deploy): Path to doker-compose file
|
|
- `-g` (string, optional, only used when action=deploy or action=update): Path to file with environment variables to be used by the stack. See [stack environment variables](#stack-environment-variables) below.
|
|
- `-r` ("true" or "false", optional): Whether to prune unused containers or not. Defaults to `"false"`.
|
|
- `-e` (int, optional): Which endpoint to use. Defaults to `1`.
|
|
- `-s` ("yes" or "no", optional): Whether to verify SSL certificate or not. Defaults to `"yes"`.
|
|
- `-v` ("true" or "false", optional): Whether to activate verbose output mode or not. Defaults to `"false"`. See [verbose mode](#verbose-mode) below.
|
|
- `-d` ("true" or "false", optional): Whether to activate debug output mode or not. Defaults to `"false"`. See [debug mode](#debug-mode) below.
|
|
- `-t` ("true" or "false", optional): Whether to activate strict mode or not. Defaults to `"false"`. See [strict mode](#strict-mode) below.
|
|
|
|
#### Examples
|
|
|
|
```bash
|
|
./psu -a deploy -u admin -p password -l http://portainer.local -n mystack -c /path/to/docker-compose.yml -g /path/to/env_vars_file
|
|
```
|
|
|
|
```bash
|
|
./psu -a undeploy -u admin -p password -l http://portainer.local -n mystack
|
|
```
|
|
|
|
### Stack environment variables
|
|
|
|
There can be set environment variables for each stack, be it a new deployment or an update. For example:
|
|
|
|
```bash
|
|
touch .env
|
|
echo "MYSQL_ROOT_PASSWORD=agoodpassword" >> .env
|
|
echo "ALLOWED_HOSTS=*" >> .env
|
|
./psu -a deploy -u admin -p password -l http://portainer.local -n django-stack -c /path/to/docker-compose.yml -g env_vars
|
|
```
|
|
|
|
Stack environment variables can be enabled through [ENVIRONMENT_VARIABLES_FILE envvar](#with-envvars) or [-g flag](#with-flags).
|
|
|
|
### Verbose mode
|
|
|
|
In verbose mode the script prints execution steps.
|
|
|
|
```text
|
|
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](#with-envvars) or [-v flag](#with-flags).
|
|
|
|
### 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](#with-envvars) or [-d flag](#with-flags).
|
|
|
|
### Strict mode
|
|
|
|
In strict mode the script never updates an existent stack nor removes an unexistent one, and instead exits with an error.
|
|
|
|
Strict mode can be enabled through [STRICT_MODE envvar](#with-envvars) or [-t flag](#with-flags).
|
|
|
|
## License
|
|
|
|
Source code contained by this project is licensed under the [GNU General Public License version 3](https://www.gnu.org/licenses/gpl-3.0.en.html).
|
|
|
|
See [LICENSE](LICENSE) file for reference.
|