portainer-deployer 0.0.6

A command-line tool to abstract some Portainer's features by using its API.

Portainer Deployer

---

Portainer API simplified through command-line interface.

📝 Table of Contents

• About
• Getting Started
• Configuring
• Usage
• Built Using
• Authors
• Acknowledgments
• Contributing

⚠️Important Notice⚠️

This is not an official Portainer software, it is just an Open Source tool to make an abstraction of Portainer's API.

🧐 About

Portainer Deployer is a Command-line interface tool developed in Python to abstract some Portainer's features by using its API. The principal use case for this application is to manage Stacks in the CI/CD process, making it faster and easy.

🏁 Getting Started

The first steps with Portainer Deployer are about installing and running your first commands. There are multiple installation methods, and they all will be listed in this section, but before you need to create the config directory and the config file.

$ mkdir -p /etc/pd-config # Or wherever you want
$ curl -o /etc/pd-config/default.conf https://raw.githubusercontent.com/Jorgmassih/portainer-deployer/main/portainer_deployer/app.conf.example
$ chgrp -R $USER /etc/pd-config && chmod -R 774 /etc/pd-config

This step should be executed before all installation methods. If you have already done that, you can skip to the next steps.

Note: Probably you will need to use sudo for creating the configuration folder and downloading the config template file

Installation

Python 3.8.x or greater is required for this project to run correctly.

You should be able to download it vía pip

$ python -m pip install --upgrade pip
$ python -m pip install portainer-deployer
$ portainer-deployer --version

If you want to avoid installing the portainer-deployer dependencies in your main python environment you can create a virtual environment before installing it:

$ mkdir ~/portainer-deployer-env && cd ~/portainer-deployer-env
$ python -m venv pd_env && source ./pd_env/bin/activate
$ python -m pip install --upgrade pip
$ python -m pip install portainer-deployer
$ portainer-deployer --version

For more information about virtual environments, please consult the Official Documentation.

Since Portainer Deployer is a command-line tool, you can invoke the application by running portainer-deployer after installation. We know that could be tedious to use the entire command to call the application, so, feel free to use an alias. e.g.

$ alias pd="portainer-deployer"

Docker installation

This is the recommended method in case you don't have the required Python version or simply any installation of Python.

If you want to use the tool but without installing it in your environment to avoid overlapping with other applications, or if you are a Windows user, this could be a fancy solution for you.

The idea is to create isolation for executing the applicatión in a recommended stable environment.

To get started with this method make sure you have a stable version of Docker installed by running docker -v and run the following snippet:

$ docker pull jorgmassih/portainer-deployer
$ docker run --rm -v path/to/config/file:/etc/pdcli/app.conf portainer-deployer --version # change --version for your desired command of portainer-deployer

Optionally you could use an alias for simplifying the command.

$ alias pd="docker run --rm -v path/to/config/file:/etc/pdcli/app.conf portainer-deployer"
$ pd --help

Binary installation will be available soon in the next releases. Please be patient.

Post Installation

Before starting using Portainer Deployer normally, you will need to set some configurations to set up the connection with Portainer API. This can be easily managed by running portainer-deployer config <config arguments goes here>. You can go more in deep the config section later.

Examples

Get all the Stacks from portainer

$ portainer-deployer get --all 

Get Stacks by its id

$ portainer-deployer get --id <random-id>

Deploy Stack from file by specifying its path

$ portainer-deployer deploy --path /path/to/my/docker-compose.yml --endpoint 45 --update-keys a.b.c=value e.f.g='[value2,value3...value4]' --name myStack

Deploy Stack passing string through standard input (stdin)

$ cat /path/to/my/docker-compose.yml | portainer-deployer deploy --endpoint 2 --name myStack

or

$ portainer-deployer deploy --endpoint 2 --name myStack "version: 3\n services:\n web:\n image:nginx"

Notice that using the stdin can be faster than specifying a path to be processed by the program, otherwise, specifying a path grants access to some features such as modifying some keys in runtime by using the arguments --update-keys or -u.

You can consult more information about allowed arguments and subcommands by running portainer-deployer --help or portainer-deployer -h.

🔧 Configuring

The first thing you need to set up is the configuration path by running portainer-deployer config --config-path <YOUR ABSOLUTE PATH TO CONFIG FILE>.

For example:

$ portainer-deployer config --config-path /etc/pd-config/default.conf 
Config path updated to: /etc/pd-config/default.conf

Note: setting the config path is just valid for all installation methods except Docker installation method.

Setting configurations in the config file

There are two ways to go ahead with the configuration, the first one is by using the config sub-command to set all necessary variables. Another one is by editing directly the config file. The first one mentioned is strongly recommended to avoid misconfigurations.

Using the config sub-command

By Entering portainer-deployer config --help in your shell you will receive:

$ portainer-deployer config --help                                                                                                                           
usage: portainer-deployer config [-h] [--set SET [SET ...] | --get GET | --config-path CONFIG_PATH]

optional arguments:
  -h, --help            Show help message and exit.
  --set SET [SET ...], -s SET [SET ...]
                        Set a config value specifying the section, key and value. e.g. --set section.url='http://localhost:9000'
  --get GET, -g GET     Get a config value. e.g. --get section.port
  --config-path CONFIG_PATH, -c CONFIG_PATH
                        Set Portainer Deployer absulute config path. e.g. --config-path /abusolute/path/to/default.conf

Notice that you have to use the nomenclature of section.key='new value'.

The following table list the available sections:

Section	Description
PORTAINER	All concerning configuration to Portainer API connection.

Also, here is a list of all keys of the variables that can be set and gotten:

Key	Choices/Defaults	Description
url		Portainer URL to connect. e.g. https://10.0.0.3
username		Username to connect to the API.
token		Token given by Portainer to connect to the API.
verify_ssl	yes, no	In case of "no" skip ssl verification.

Examples

Set Portainer url

$ portainer-deployer config --set portainer.url='https://localhost:9443'

Get Portainer username

$ portainer-deployer config --get portainer.username

In the case of you try to set a variable not listed before, the operation won't take effect.

Editing the config file

This method consists in editing the file you set by running portainer-deployer config --config-path <YOUR PATH> at the moment of installation, therefore you need the right privileges to access that file.

The config file is written in INI format and looks like this:

# app.conf
[PORTAINER]
url = https://your-portainer.host.lab
username = <YOUR PORTAINER USERNAME>
token = <YOUR PORTAINER TOKEN>
verify_ssl = yes #It can be yes or not, [T,t]rue or [F,f]alse

Note: If you are using the Docker installation method make sure to create a volume with the configuration file inside.

🎈 Usage

Portainer Deployer is composed of 4 main sub-commands:

• get
• deploy
• remove
• config (explained in the past section)

In this reading, we are going to focus on get, deploy and remove sub-commands.

The get sub-command

By running portainer-deployer get you will be able to retrieve stacks information from Portainer by name or id, you can retreive information of all stacks by setting the --all argument.

The command portainer-deployer get -h will result in:

$ portainer-deployer get --help                                                                        
usage: portainer-deployer get [-h] [--id ID | --name NAME | --all]

Get stack info from Portainer.

optional arguments:
  -h, --help            Show help message and exit.
  --id ID               Id of the stack to look for
  --name NAME, -n NAME  Name of the stack to look for
  --all, -a             Gets all stacks

The deploy sub-command

This one allows to post stacks and run them in Portainer, it can be done by passing the string as stdin or passing the path to the yml file.

$ portainer-deployer deploy --help
usage: portainer-deployer deploy [-h] [--path PATH] [--name NAME] [--update-keys UPDATE_KEYS [UPDATE_KEYS ...]] --endpoint ENDPOINT [stack]

positional arguments:
  stack                 Docker Compose string for the stack

optional arguments:
  -h, --help            Show help message and exit.
  --path PATH, -p PATH  The path to Docker Compose file for the stack. An alternative is to pass the stack as a string.
  --name NAME, -n NAME  Name of the stack to look for.
  --update-keys UPDATE_KEYS [UPDATE_KEYS ...], -u UPDATE_KEYS [UPDATE_KEYS ...]
                        Modify the stack file by passing a list of key=value pairs, where the key is in dot notation. i.e. a.b.c=value1 d='[value2, value3]'
  --redeploy, -R        Re-deply in case of stacks exists.
  -y                    Accept redeploy and do not ask for confirmation before redeploying the stack.
  --endpoint ENDPOINT, -e ENDPOINT
                        Endpoint Id to deploy the stack.

You can redeploy a stack by using the --redeploy flag. This is useful to update an image rebuild. This feature requires a confirmation and can be accepted automatically and skipped with the -y flag.

The remove sub-command

This sub-command allows you to remove a stack from Portainer by setting its id or name and the endpoint as well.

$ portainer-deployer remove --help
usage: portainer-deployer remove [-h] [--id ID | --name NAME] [--endpoint ENDPOINT] [-y]

Remove a stack from Portainer.

optional arguments:
  -h, --help            Show help message and exit.
  --id ID               Id of the stack remove
  --name NAME, -n NAME  Name of the stack to remove
  --endpoint ENDPOINT, -e ENDPOINT
                        Endpoint Id from the stack to remove.
  -y                    Accept removal action and do not ask for confirmation.

This sub-command also has a confirmation step, and can be accepted automatically and skipped with the -y flag.

⛏️ Built Using

• Python 🐍 - Core Programming Language
• argparse - Main Python library for parsing arguments

✍️ Authors

• @jorgmassih👨‍💻 - Idea & Initial work

🎉 Acknowledgements

• Portainer and its development team
• My College Professor Rodrigo Orizondo (@yoyirod) 🕊️🙏 for the inspiration
• The DevOps community

🤝 Contributing

I'm open to contributions! If you are interested in collaborating, you can reach out to me via the info on my bio.