Configure Portainer Stacks from Outside: A Guide to Config Files

Portainer is a popular management tool for Docker and Kubernetes environments. It provides an easy-to-use web interface for managing containers, images, networks, and volumes. One of the most powerful features of Portainer is the ability to create and manage stacks, which are groups of related containers that can be deployed together. In this article, we will show you how to configure Portainer stacks from outside using configuration files.

Prerequisites

Before we begin, make sure you have the following:

• A Portainer instance running in Docker or Kubernetes
• Access to the Portainer API (usually at /api or /api/v2.1)
• A text editor to create and edit the configuration files

Creating a Stack Configuration File

A stack configuration file is a JSON or YAML file that defines the services, networks, and volumes that make up the stack. Here is an example of a simple stack configuration file in JSON format:

{
  "version": "1.0.0",
  "services": {
    "web": {
      "image": "nginx:latest",
      "ports": ["80:80"],
      "networks": ["webnet"]
    },
    "db": {
      "image": "postgres:latest",
      "environment": ["POSTGRES_PASSWORD=mysecretpassword"],
      "networks": ["dbnet"]
    }
  },
  "networks": {
    "webnet": {},
    "dbnet": {}
  }
}

This stack configuration file defines two services, web and db, based on the nginx:latest and postgres:latest images, respectively. The web service is accessible from the host at port 80, and is connected to the webnet network. The db service is configured with an environment variable, and is connected to the dbnet network. The networks section defines two networks, webnet and dbnet, which are empty by default.

Applying the Stack Configuration File

Once you have created your stack configuration file, you can apply it to your Portainer instance using the POST /api/stacks/{stack_id}/config endpoint. Here is an example of how to use this endpoint with the stack configuration file from the previous section:

curl -X POST \
  http:///api/stacks/my-stack-id/config \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d @/stack.json

Replace with the URL of your Portainer instance, with a valid API token, and /stack.json with the path to your stack configuration file. The my-stack-id parameter is optional, and can be used to specify the ID of the stack. If you don't provide this parameter, Portainer will create a new stack with a generated ID.

If the stack configuration file is valid, Portainer will create the stack and its services, networks, and volumes. You can view the stack in the Portainer web interface, and manage it using the API or the web interface. If there are any errors in the stack configuration file, Portainer will return an error message, and the stack will not be created.

Updating the Stack Configuration File

You can update the stack configuration file at any time by using the PUT /api/stacks/{stack_id}/config endpoint. Here is an example of how to use this endpoint to update the stack configuration file from the previous section:

curl -X PUT \
  http:///api/stacks/my-stack-id/config \
  -H 'Authorization: Bearer ' \
  -H 'Content-Type: application/json' \
  -d @/stack.json

This request is similar to the POST request, except that it uses the PUT method, and the my-stack-id parameter is required. Portainer will update the stack configuration file with the new values, and restart the affected services. If there are any errors in the stack configuration file, Portainer will return an error message, and the stack configuration will not be updated.

In this article, we have shown you how to configure Portainer stacks from outside using configuration files. By using the Portainer API and the stack configuration file, you can automate the deployment and management of complex Docker stacks, and integrate them into your CI/CD pipelines. This feature is a powerful tool for DevOps teams, and can help you to improve your productivity and reduce your operational costs.

References