Portainer: продвинутые настройки — Stacks, Edge Agent и Keycloak и управление доступом

Базовой установки Portainer достаточно, если вы управляете одним Docker-хостом и работаете с ним самостоятельно.

Но в реальной инфраструктуре Portainer нередко используют для более сложных задач: управления несколькими серверами, подключения удалённых Docker-хостов за NAT, разграничения доступа между командами и интеграции с корпоративной системой авторизации.

В таких сценариях стандартной конфигурации уже недостаточно — требуются дополнительные настройки. В этой статье разберём:

• как разворачивать приложения через Stacks на основе Docker Compose;
• как подключать удалённые Docker-хосты через Edge Agent;
• как интегрировать Portainer с внешней аутентификацией через Keycloak / OIDC;
• как настраивать пользователей, команды и права доступа.

В качестве операционной системы используется Ubuntu 24.04 LTS. Все команды и примеры конфигураций приведены для неё. Для выполнения шагов потребуется уже установленный и доступный Portainer Server, а также доступ к серверу с правами root.

Разворачивание приложений через Stacks (Docker Compose)

В интерфейсе Portainer есть раздел Stacks — он предназначен для запуска и управления несколькими контейнерами через Docker Compose. Это удобно, когда нужно запускать не один контейнер вручную, а сразу целое приложение с готовой конфигурацией: образами, переменными окружения, томами, сетями и портами.

По сути, Stack — это Compose-проект, который Portainer разворачивает через веб-интерфейс. Такой способ оптимален для сопровождения: конфигурация хранится в одном YAML-файле, а управлять приложением можно без работы в консоли.

Создание и запуск Stack

Чтобы создать новый Stack, откройте нужное окружение, перейдите в раздел Stacks и нажмите Add stack.

В поле Name укажите имя стека, например demo-stack. Ниже, в редакторе Web editor, вставьте Compose-конфигурацию. Например:

services:
  nginx:
    image: nginx:latest
    container_name: nginx-demo
    restart: unless-stopped
    ports:
      - "8080:80"

  postgres:
    image: postgres:17
    container_name: postgres-demo
    restart: unless-stopped
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: strongpassword
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

В этом примере Portainer развернёт сразу два контейнера: веб-сервер Nginx и базу данных PostgreSQL. Для PostgreSQL также будут заданы переменные окружения и создан отдельный том для постоянного хранения данных.

После этого нажмите Deploy the stack. Portainer скачает нужные образы, создаст контейнеры и запустит приложение.

После успешного запуска стек появится в разделе Stacks. Здесь можно увидеть список созданных стеков, их имена, тип и уровень управления в столбце Control.

Если в Compose-конфигурации указан проброс портов, сервисы будут доступны снаружи по IP-адресу сервера и опубликованному порту. В нашем примере Nginx будет доступен по адресу http://<IP-адрес-сервера>:8080, а PostgreSQL — по локальному адресу 127.0.0.1:5432.

Если открыть раздел Containers, в столбце Stack можно посмотреть, к какому стеку относится каждый контейнер. Это удобно, когда приложение состоит из нескольких сервисов и ими нужно управлять как одной группой.

Таким образом, Stacks позволяют описывать приложение как единый Compose-файл и управлять всеми связанными контейнерами из интерфейса Portainer. Это упрощает запуск, обновление и сопровождение сервисов, особенно если приложение состоит из нескольких компонентов.

Подключение удалённых Docker-хостов через Edge Agent Standard

Для подключения удалённых Docker-хостов в Portainer можно использовать Edge Agent Standard. Этот вариант подходит для серверов, которые находятся за NAT, firewall или не имеют прямой входящей доступности по сети.

В отличие от обычного Agent, Edge Agent Standard сам инициирует соединение с сервером Portainer. Благодаря этому управляемый хост не требует открытия входящих портов для подключения со стороны Portainer.

Как работает Edge Agent Standard

В этой схеме используются два основных компонента:

• Portainer Server — центральный сервер управления с веб-интерфейсом;
• Edge Agent Standard — агент на удалённом Docker-хосте.

Edge Agent сам инициирует соединение с сервером: периодически опрашивает Portainer Server (polling) и выполняет полученные команды. Для работы с локальным Docker агент использует сокет /var/run/docker.sock. Благодаря такой схеме на удалённом хосте не нужно открывать входящие порты — агент сам подключается к серверу, после чего удалённый хост становится доступен для управления из интерфейса Portainer.

На стороне Portainer Server должны быть открыты порты 443/tcp и 8000/tcp. В рассматриваемой схеме Portainer работает за Nginx: внешний HTTPS-трафик принимается на 443/tcp и проксируется на локальный порт 9443, а 8000/tcp используется для работы Edge Agent Standard.

Настройка firewall для Edge Agent

Если Edge Agent подключается не с локального сервера, а с удалённых Docker-хостов, их IP-адреса нужно добавить в переменную EDGE_AGENT_STANDARD в конфигурации nftables. Иначе подключения к порту 8000/tcp будут блокироваться файрволом.

Например:

define EDGE_AGENT_STANDARD = { 192.168.1.10, 192.168.1.11, 10.0.0.5 }

После изменения файла примените правила повторно:

nft -f /etc/nftables.conf

Если используется Debian или Ubuntu, конфигурация обычно находится в файле /etc/nftables.conf. На CentOS, Rocky Linux и AlmaLinux обычно используется /etc/sysconfig/nftables.conf.

Добавление Edge Agent Standard на удалённый хост 

Чтобы подключить удалённый Docker-хост через Edge Agent Standard, сначала нужно создать новое окружение в веб-интерфейсе Portainer. Для этого перейдите в раздел Environment-related — Environment, нажмите Add environment.

Выберите Docker Standalone, нажмите Start Wizard.

Затем выберите вариант подключения Edge Agent Standard и заполните параметры нового окружения:

• Name — произвольное имя окружения, под которым оно будет отображаться в интерфейсе Portainer;
• Portainer API server URL — IP-адрес сервера, доменное имя или FQDN вашего Portainer Server, доступное с удалённого Docker-хоста.

После этого нажмите Create.

В результате Portainer сгенерирует параметры для подключения агента:

• Edge ID — уникальный идентификатор подключаемого окружения;
• Edge Key — секретный токен, который агент будет использовать для авторизации на сервере.

Теперь перейдите на удалённый Docker-хост, который нужно подключить к Portainer, создайте отдельный каталог для файлов агента:

mkdir -p /opt/portainer_edge_agent/
cd /opt/portainer_edge_agent/

После этого создайте файл .env, в котором будут храниться параметры подключения, полученные в интерфейсе Portainer на предыдущем шаге.

EDGE_ID=<ваш-edge-id>
EDGE_KEY=<ваш-edge-key>

Файл .env содержит секретный токен, поэтому сразу ограничьте к нему доступ.

chmod 600 .env

Эта команда разрешает читать и изменять файл только его владельцу. Остальные пользователи системы не смогут открыть или изменить .env.

Далее создайте файл docker-compose.yml с конфигурацией контейнера агента. Ниже приведена готовая конфигурация Docker Compose для Edge Agent — скопируйте её и используйте на удалённом Docker-хосте.

Создайте директорию и файл в любом текстовом редакторе, например:

nano /opt/portainer_edge_agent/docker-compose.yml 

Вставьте в него содержимое:

services:
  portainer_edge_agent:
    container_name: portainer_edge_agent
    image: portainer/agent:2.39.3
    restart: always
    environment:
      EDGE: "1"
      EDGE_ID: ${EDGE_ID}
      EDGE_KEY: ${EDGE_KEY}
      EDGE_INSECURE_POLL: "0"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
      - /:/host
      - portainer_agent_data:/data

volumes:
  portainer_agent_data:
    name: portainer_agent_data

Если Portainer работает с самоподписанным сертификатом, установите EDGE_INSECURE_POLL: "1". Для доверенного TLS-сертификата этот параметр не нужен.

При необходимости можно также задать AGENT_SECRET — его значение должно совпадать на стороне Portainer Server и Edge Agent.

Запустите агент командой:

docker compose up -d

После запуска агент начнёт подключение к серверу, а новое окружение появится в списке Environments в интерфейсе Portainer.

После запуска Edge Agent в разделе Environments появился demo-agent со статусом heartbeat, что подтверждает успешное подключение агента к Portainer. На этом этапе также может отображаться сообщение No snapshot available, пока данные окружения ещё не загружены.

После следующей успешной синхронизации в интерфейсе появится информация о контейнерах, образах, томах, сетях и других ресурсах удалённого Docker-хоста.

Управление доступом и интеграция с Keycloak

Если Portainer используется не одним администратором, а командой, важно заранее настроить разграничение доступа: кто может входить в систему, какие окружения видеть и какие действия выполнять.

Для входа в Portainer можно использовать встроенную аутентификацию с локальными учётными записями или подключить внешнего провайдера идентификации через OAuth 2.0 / OpenID Connect (OIDC), например, Keycloak. Это позволит использовать единый вход (SSO) вместо локальных учётных записей. Такой вариант удобен, если пользователи уже управляются централизованно и вы не хотите создавать их вручную в каждом сервисе отдельно.

В этом разделе рассмотрим настройку единого входа через Keycloak, а также разберём, как устроены пользователи, команды, окружения и группы окружений и как настраивать права доступа на практике.

Настройка единого входа через Keycloak

Перед настройкой интеграции должен быть установлен и доступен Keycloak. Также потребуется доступ в административную консоль Keycloak и заранее созданный realm, в котором будут храниться пользователи и клиент Portainer. Если Keycloak ещё не установлен, сначала разверните его по инструкции: установка Keycloak на виртуальный сервер.

Настройка клиента в Keycloak

Сначала в Keycloak нужно создать отдельный клиент для Portainer. Именно через него Portainer будет перенаправлять пользователей на страницу входа и получать данные для авторизации.

Дальнейшие действия выполняются в веб-интерфейсе Keycloak. Откройте административную консоль Keycloak, выберите нужный realm, перейдите в раздел Clients и нажмите Create client.

Создайте отдельный клиент для Portainer. Через него Portainer будет перенаправлять пользователей на страницу входа Keycloak и получать данные для аутентификации.

При создании клиента заполните параметры по шагам.

На шаге General settings укажите:

• Client type: OpenID Connect;
• Client ID: portainer;
• Name: portainer.

Нажмите Next.

На шаге Capability config включите следующие параметры:

• Client authentication: on;
• Standard flow: on;
• Direct access grants: on;
• Service accounts roles: on.

Нажмите Next.

На шаге Login settings заполните поля адресом вашего Portainer Server:

• Home URL
• Valid redirect URIs
• Valid post logout URIs
• Web origins

В примере используется адрес: https://portainer.firstvds.ru/ Замените его на адрес вашего сервера Portainer. Чтобы сохранить настройки клиента, нажмите Save.

После создания клиента откройте вкладку Credentials и скопируйте Client Secret. Он понадобится на следующем шаге — при настройке Portainer.

Настройка OAuth в Portainer

Теперь настройте Portainer так, чтобы он использовал Keycloak как внешний провайдер аутентификации.

Для этого в интерфейсе Portainer перейдите в раздел: Settings > Authentication > OAuth. Включите параметры Use SSO и Automatic user provisioning.

Ниже в поле Provider выберите Custom и заполните параметры подключения к Keycloak. В таблице приведён пример значений — замените адрес Keycloak, имя realm, Client ID, Client Secret и адрес Portainer на свои. Используйте тот realm, в котором ранее был создан клиент Portainer.

Для сохранения настроек нажмите Save settings. После этого пользователи смогут входить в Portainer через Keycloak, а при первом успешном входе их учётные записи будут автоматически создаваться в системе.

Пользователи, команды и окружения: как устроен доступ в Portainer

После того как пользователи получили доступ к Portainer через Keycloak, следующим шагом нужно настроить права. Чтобы сделать это правильно, нужно понимать, какими сущностями оперирует Portainer.

Пользователи

Пользователи — это отдельные учётные записи людей, которые входят в Portainer. У каждого пользователя свой логин и собственный набор прав. Учётные записи можно создавать вручную в самом Portainer или автоматически получать из внешнего провайдера, например, как в нашем случае через Keycloak.

В Portainer CE доступны две базовые роли:

• Administrator — полный доступ ко всем функциям Portainer;
• Standard User — стандартный пользователь с ограниченными правами.

Более детальная модель RBAC с дополнительными ролями доступна в платной версии Portainer Business.

Команды

Команды (Teams) нужны для того, чтобы не назначать права каждому пользователю по отдельности. Вместо этого можно объединить пользователей в группу, например, по проекту, отделу или роли, а затем выдать доступ сразу всей команде. Это особенно удобно, когда состав участников со временем меняется.

Окружения

Окружения (Environments) — это управляемые среды, подключённые к Portainer. В их роли могут выступать отдельные Docker-хосты, кластеры Docker Swarm или Kubernetes. Для каждого окружения можно отдельно указать, кто из пользователей или команд имеет к нему доступ.

Группы окружений

Группы окружений (Environment Groups) позволяют объединить несколько окружений в логические наборы. Например, можно создать отдельные группы для production, staging или тестовых серверов. После этого права удобнее назначать не на каждое окружение по отдельности, а сразу на группу.

Как настраивать доступ на практике

Обычно настройка доступа строится по следующей схеме: сначала пользователи попадают в Portainer, затем их объединяют в команды, после чего командам назначают доступ к нужным окружениям или группам окружений.

Создание пользователей

Если используется Keycloak, вручную создавать пользователей не требуется: при первом входе через SSO учётная запись будет создана автоматически. Если внешняя аутентификация не настроена, пользователей можно добавить локально через интерфейс Portainer.

Создание команд

После появления пользователей в системе имеет смысл объединить их в команды. Для этого откройте раздел User-related — Teams. Укажите название, выберите руководителя группы из существующих пользователей и нажмите Create team.

Создание групп окружений

Если у вас несколько серверов или кластеров, их удобно предварительно сгруппировать. Для этого откройте Environment-related — Groups и нажмите Add group. 

Задайте имя группы, опционально описание и теги. Добавьте в группу нужные окружения, в примере был добавлен docker-prod01 через кнопку Add, далее нажимаем Create. Такой подход особенно полезен, если несколько окружений относятся к одному проекту или контуру.

Назначение прав доступа

После этого можно переходить к назначению прав. Доступ можно выдавать как на уровне отдельного окружения, так и на уровне группы окружений.

Для отдельного окружения

Откройте раздел Environment-related — Environments, выберите нужное окружение и перейдите в Manage access. Там можно выбрать конкретного пользователя или целую команду и сохранить изменения.

Для группы окружений

Откройте Environment-related — Groups, выберите нужную группу и также используйте раздел Manage access. Права, назначенные группе, будут применяться ко всем окружениям внутри неё.

Практические рекомендации

1. Используйте команды вместо отдельных пользователей. На практике удобнее строить доступ не вокруг отдельных пользователей, а вокруг команд. Это упрощает сопровождение: если человек приходит в проект или уходит из него, достаточно просто добавить его в команду или удалить из неё.
2. Группируйте окружения по назначению. Если окружений много, лучше заранее объединять их в группы по назначению, проекту или уровню среды — например, отдельно production и отдельно staging. Это позволяет управлять правами централизованно и не повторять одни и те же действия для каждого хоста вручную.

Мы рассмотрели несколько продвинутых возможностей Portainer: развертывание приложений через Stacks, подключение удалённых Docker-хостов с помощью Edge Agent, а также базовое управление доступом через пользователей, команды и интеграцию с Keycloak / OIDC.

В результате Portainer можно использовать не только как веб-интерфейс для локального Docker, но и как централизованную панель управления несколькими серверами и приложениями с единым входом и разграничением прав доступа.