Infra Management/Zabbix

zabbix7.4 & agent2로 docker 모니터링, mysql, postgresql 모니터링 방법 정리

bluebamus 2025. 7. 30.

- github 저장소 : https://github.com/bluebamus/database-pgdog-postgresql-mysql

- 레거시 환경에서 구축 실패 로그를 기록함

- agent2를 이용하여 성공적으로 연동한 케이스를 부가적으로 각 항목의 하단에 추가함

- 스크립트 사용 및 직접 설치가 아닌 아닌, Dockerfile 및 docker-compose를 사용하는 경우의 프로젝트 트리

.
├── config
│   ├── mysql
│   │   └── backup
│   ├── pgdog
│   └── postgresql
│       └── backup
├── data
│   ├── mysql
│   │   ├── #innodb_redo
│   │   ├── #innodb_temp
│   │   ├── mysql
│   │   ├── performance_schema
│   │   └── sys
│   └── postgresql  [error opening dir]
└── logs
    ├── mysql
    └── postgresql

1. docker 모니터링 설정 - 직접 설치 / 실패함

1.1. 클라이언트 호스트의 docker.sock 파일에 권한 할당

- 클라이언트 호스트에 agent2가 Docker API에 접근할 수 있도록 권한을 할당해 줘야 한다.

- docker.sock에 접근 권한을 usermod를 이용해 할당해 줘야 한다.

- zabbix 사용자를 Docker 그룹에 추가하여 해당 사용자가 Docker 관련 명령어를 실행할 수 있도록 권한을 할당한다.

sudo usermod -aG docker zabbix

1.2. 시스템 재시작

systemctl restart zabbix-agent2

1.3. 문제점

- 2025/07/27일 기준 arm cpu 버전의 mysql에서는 zabbx-agent2가 패키지 버전 지원 문제로 설치가 안된다.

- docker 내부에 설치시 실패함

- agent를 설치하면 해결할 수 있다.

2. docker template를 호스트에 설치한다.

- Docker by Zabbix agent 2 템플릿을 docker가 설치된 호스트에 설치한다.

3. docker 내부 서비스 모니터링 설정을 위한 docker-compose 업데이트

- docker 내부 서비스는 실제 서버와 같이 agent2와 플러그인 설치 후 웹 서버에서 템플릿을 추가로 설치하는 것으로 기존과 동일한 방법으로 설치 및 설정을 한다.

3.1. mysql, postgresql 모니터링 설정을 위한 docker-compose.yml 예시

- 포트를 외부와 연결한다.

services:
  postgresql:
    image: postgres:latest
    restart: always
    environment:
      POSTGRES_DB: mydatabase
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword
    ports:
      - "5432:5432"
    networks:
      - backend-network

  mysql:
    image: mysql:latest
    restart: always
    environment:
      MYSQL_DATABASE: mydatabase
      MYSQL_USER: myuser
      MYSQL_PASSWORD: mypassword
      MYSQL_ROOT_PASSWORD: rootpassword
    ports:
      - "3306:3306"
    networks:
      - backend-network

networks:
  backend-network:
    driver: bridge

4. MySQL 컨테이너에 모니터링 설치하기 - 연동 실패 / 우분투 18.04 / zabbix 7.4 agent 설치

4.1. agent 설치하기

- arm cpu의 경우 패키지 호환 문제로 7.4 버전의 agfent2 설치가 안된다.

- 여러 이유로 문제가 발생하는 경우, agent를 설치하면 해결될 수 있다.

- 레거시 시스템을 구축해야 했기에 ubuntu 18.04/mysql 5.4를 설치하였고 arm cpu였기에 agent를 설치했다.

1. 리포지토리 구성 패키지 다운로드

Ubuntu 18.04 전용 Zabbix Release 패키지 파일명은 zabbix-release_7.4-1+ubuntu18.04_all.deb이며, 다음 명령어로 다운로드합니다.
Zabbix Repository

wget https://repo.zabbix.com/zabbix/7.4/release/ubuntu/pool/main/z/zabbix-release/zabbix-release_7.4-1+ubuntu18.04_all.deb
``` :contentReference[oaicite:2]{index=2}

## 2. 리포지토리 패키지 설치  
다운로드한 `.deb` 파일을 dpkg로 설치하여 Zabbix 공식 저장소를 `/etc/apt/sources.list.d/zabbix.list`에 등록합니다. :contentReference[oaicite:3]{index=3}  
```bash
sudo dpkg -i zabbix-release_7.4-1+ubuntu18.04_all.deb
``` :contentReference[oaicite:4]{index=4}

## 3. 패키지 인덱스 갱신  
등록된 Zabbix 저장소의 메타데이터를 가져오기 위해 APT 인덱스를 업데이트합니다. :contentReference[oaicite:5]{index=5}  
```bash
sudo apt update
``` :contentReference[oaicite:6]{index=6}

## 4. Zabbix Agent 설치  
APT 저장소에서 공식 `zabbix-agent` 패키지를 설치합니다. :contentReference[oaicite:7]{index=7}  
```bash
sudo apt install -y zabbix-agent
``` :contentReference[oaicite:8]{index=8}

4.2. 템플릿 conf 복사하기

- agent와 agent2의 큰 차이로 plugin의 기본 설치 유무가 될 수 있다.

- agent2의 경우 /etc/zabbix/zabbix_agent2.d/plugins.d/에 기본적인 템플릿 conf 파일이 있다.

- agent의 경우는 centos와 ubuntu의 설치 결과가 달랐다.

- agent의 경우 기본적으로 설치되는 템플릿 conf가 없다.

- ubuntu : /etc/zabbix/zabbix_agentd.conf.d

- centos : /etc/zabbix/zabbix_agentd.d

- git으로 zabbix를 clone하여 템플릿을 복사한다.

- git command : git clone https://github.com/zabbix/zabbix

- backup을 컨테이너 볼륨으로 설정하고 폴더를 복사했다. backup 폴더를 제외하고 참고하며 된다.

- path : /backup/zabbix/templates/db/mysql_agent/

- file : template_db_mysql.conf

- conf 내용을 업데이트 한다.

- 참고 사이트 : https://sbcode.net/zabbix/setup_mysql_database_monitoring/

- 다음 항목을 복사한다.

UserParameter=mysql.ping[*], mysqladmin -h"$1" -P"$2" ping
UserParameter=mysql.get_status_variables[*], mysql -h"$1" -P"$2" -sNX -e "show global status"
UserParameter=mysql.version[*], mysqladmin -s -h"$1" -P"$2" version
UserParameter=mysql.db.discovery[*], mysql -h"$1" -P"$2" -sN -e "show databases"
UserParameter=mysql.dbsize[*], mysql -h"$1" -P"$2" -sN -e "SELECT COALESCE(SUM(DATA_LENGTH + INDEX_LENGTH),0) FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA='$3'"
UserParameter=mysql.replication.discovery[*], mysql -h"$1" -P"$2" -sNX -e "show slave status"
UserParameter=mysql.slave_status[*], mysql -h"$1" -P"$2" -sNX -e "show slave status"

4.3. MySQL에 모니터링 전용 사용자 생성

- 기본 설정

- 계정 생성과 관련해서 local만 설정하는 경우, 외부 허용을 설정하는 경우가 있다.

- 에이전트가 접속하는 것이면 로컬 계정으로 충분할 것이다.

- 확인이 필요함

# 외부 접속 권한 사용자
CREATE USER 'zbx_monitor'@'%' IDENTIFIED BY '<password>';
GRANT REPLICATION CLIENT,PROCESS,SHOW DATABASES,SHOW VIEW ON *.* TO 'zbx_monitor'@'%';
FLUSH PRIVILEGES;


# 내부 접속 권한 사용자
CREATE USER 'zbx_monitor'@'localhost' IDENTIFIED BY '<password>';
GRANT REPLICATION CLIENT,PROCESS,SHOW DATABASES,SHOW VIEW ON *.* TO 'zbx_monitor'@'localhost';
FLUSH PRIVILEGES;


-- 외부 접속(모든 호스트) 권한
CREATE USER 'zbx_monitor'@'%' IDENTIFIED BY '<password>';
GRANT REPLICATION CLIENT,PROCESS,SHOW DATABASES,SHOW VIEW ON *.* TO 'zbx_monitor'@'%';

-- 내부 접속(로컬호스트) 권한
CREATE USER 'zbx_monitor'@'localhost' IDENTIFIED BY '<password>';
GRANT REPLICATION CLIENT,PROCESS,SHOW DATABASES,SHOW VIEW ON *.* TO 'zbx_monitor'@'localhost';

FLUSH PRIVILEGES;

mysql -uroot -p -e "
CREATE USER 'zbx_monitor'@'%' IDENTIFIED BY '비밀번호';
GRANT REPLICATION CLIENT,PROCESS,SHOW DATABASES,SHOW VIEW ON *.* TO 'zbx_monitor'@'%';
CREATE USER 'zbx_monitor'@'localhost' IDENTIFIED BY '비밀번호';
GRANT REPLICATION CLIENT,PROCESS,SHOW DATABASES,SHOW VIEW ON *.* TO 'zbx_monitor'@'localhost';
FLUSH PRIVILEGES;"

- 복제 메트릭을 수집하려면 MariaDB Enterprise Server 10.5.8-5 이상 및 MariaDB Community Server 10.5.9 이상에서 모니터링 사용자에게 SLAVE MONITOR 권한이 설정되어 있어야 한다.

GRANT REPLICATION CLIENT,PROCESS,SHOW DATABASES,SHOW VIEW,SLAVE MONITOR ON *.* TO 'zbx_monitor'@'%';

4.4. docker-compose.yml에 mysql의 command 업데이트 하기

- 스크립트를 사용해 agent를 설치하고 에이전트를 프로세스로 띄운다.

#!/bin/bash

apt update && apt install wget vim -y

cd ~/

wget https://repo.zabbix.com/zabbix/7.4/release/ubuntu/pool/main/z/zabbix-release/zabbix-release_7.4-1+ubuntu18.04_all.deb

dpkg -i zabbix-release_7.4-1+ubuntu18.04_all.deb

apt update

apt install -y zabbix-agent

cp /backup/zabbix_agentd.conf /etc/zabbix/
cp /backup/template_db_mysql.conf /etc/zabbix/zabbix_agentd.conf.d/

su -s /bin/bash zabbix -c 'zabbix_agentd -f'

4.5. .my.cnf를 생성한다.

- /var/lib/zabbix에 .my.cnf를 만들고 계정 정보를 입력한다.

[client]
protocol=tcp
user='zbx_monitor'
password='test!'

4.6. 서버에서 ping test를 한다.

zabbix_get -s 134.185.109.20 -p 10057 -k 'mysql.version["localhost","3306"]'

4.7. 문제 발생 및 작업 중단

- 컨테이너 내부에서 서비스 포트 테스트

nmap -Pn -p 10057,10058 127.0.0.1

- 사실 agent2를 설치하면 더 쉽게 해결될것 같은데, 환경 문제로 설치가 불가하다.

- docker 모니터링을 하고 있기 때문에 서비스 모니터링은 중단한다.

- 해결 방안으로, 차라리 Dockerfile을 만들어 zabbix-agent가 내부적으로 실행되도록 만드는 방법을 고민할 필요가 있을것 같다. supervisord를 사용하여 시작과 함께 동작하게 만드는 것이 방법일 것 같다.

5. percona/mysql 8.0 / zabbix 7.4 agent2로 설치하기 - docker-compose & dockerfile-mysql

- 스크립트로 연동 테스트를 성공했으나 최종 Dockerfile로 만드는게 최선이라 생각해 다시 작업을 수행했다.

- 테스트 결과 docker내 설치시 zabbix_agent2.conf의 ListenPort를 오리지널 서버 혹은 다른 컨테이너와 다른 포트로 설정하고 zabbix server의 호스트 생성시 agent에 설정해 줘야 한다.

- 참고 문서 : https://www.zabbix.com/documentation/current/en/manual/guides/monitor_mysql

5.1. Dockerfile

- 오라클 클라우드 arm 서버이기 때문에 이미지는 percona/percona-server:8.0.35-aarch64를 사용하였다.

- 문서의 내용을 그대로 따라했다. repo는 이미지의 os를 참고해 오라클 리눅스 9 기반으로 설치했다.

- zabbix_agent2.conf는 사전에 준비하여 볼륨으로 연동했다.

- github에서 받거나, 볼륨을 연결하여 컨테이너를 한번 실행하여 복사해 둔다.

- Server, ListenPort, Hostname를 설정한다.

- mysql은 초기 실행시 초기화가 필요하다. dockerfile에 추가되었다.

- 이미지를 기반으로 커스텀 작업을 추가하는 경우, ENTRYPOINT 등으로 실행시켜야 하는 모든 프로세스를 정의 해 줘야 한다. 이 Dockerfile에는 zabbix_agent2와 mysql을 실행하며 mysql은 --user=mysql을 사용해 사용자를 변경한다.

- 작업에서 Dockerfile의 파일 이름을 Dockerfile-mysql로 정의했다.

FROM percona/percona-server:8.0.35-aarch64

# root 사용자로 전환
USER root

# 필수 도구 설치 및 Zabbix Agent2 레포지토리 등록
RUN dnf update -y \
    && dnf install -y wget vim \
    && wget https://repo.zabbix.com/zabbix/7.4/release/oracle/9/noarch/zabbix-release-7.4-3.el9.noarch.rpm \
    && rpm -ivh zabbix-release-7.4-3.el9.noarch.rpm \
    && dnf update -y \
    && dnf install -y zabbix-agent2 \
    && rm -f zabbix-release-7.4-3.el9.noarch.rpm \
    && dnf clean all

# Zabbix 설정 파일 복사 (빌드 컨텍스트 내 backup 디렉터리에 위치)
COPY ./config/mysql/backup/zabbix_agent2.conf /etc/zabbix/zabbix_agent2.conf

RUN mkdir -p /var/lib/mysql && \
    chown -R mysql:mysql /var/lib/mysql && \
    mysqld --initialize-insecure --user=mysql --datadir=/var/lib/mysql && \
    chown -R mysql:mysql /var/lib/mysql

# 컨테이너 기동 시 Zabbix Agent2를 포그라운드로 실행하고 MySQL 서버를 시작
ENTRYPOINT ["bash", "-c", "zabbix_agent2 -f & exec mysqld --user=mysql"]

5.2. init.sql에 필수 사용자 생성

-- Zabbix 모니터링용 계정 생성
CREATE USER 'zbx_monitor'@'%' IDENTIFIED BY 'test!';
GRANT REPLICATION CLIENT, PROCESS, SHOW DATABASES, SHOW VIEW ON *.* TO 'zbx_monitor'@'%';

5.3. docker-compose

  mysql:
    # image: percona/percona-server:8.0.35-aarch64
    build:
      context: .
      dockerfile: Dockerfile-mysql
    logging:
      driver: "json-file"
      options:
        max-file: "5"
        max-size: "100m"
    container_name: mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: test!  
      TZ: Asia/Seoul
    ports:
      - "3306:3306"
      - "10057:10057" # zabbix_agent2.conf의 ListenPort도 맞춰줘야 한다.
    volumes:
      - ./data/mysql:/var/lib/mysql # 선택
      - ./config/mysql/my.cnf:/etc/my.cnf # 선택
      - ./config/mysql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro # 필수
      - ./config/mysql/backup:/backup # 선택
      - ./logs/mysql:/var/log/mysql # 선택
    networks:
      - db_network

5.4. zabbix 서버 설정

- 호스트를 생성한다. 호스트 네임은 zabbix_agent2.conf의 Hostname와 동일하게 맞춰준다.

- MySQL by Zabbix agent2 템플릿을 설치하고 interface에 agent를 추가한다. 이때 컨테이너에의 zabbix_agent2.conf에 설정한 포트를 정의해준다.

- 매크로 탭을 눌러 mysql 정보를 업데이트 한다.

- MYSQL.DSN에 ip와 port를 입력한다. 예) tcp://111.111.111.11:3306

- MYSQL.PASSWORD에 암호를 입력한다.

- MYSQL.USER에 mysql에 생성한 사용자 정보를 입력한다.

6. PostgreSQL 컨테이너에 모니터링 설치하기

- 참고 가이드 : https://www.zabbix.com/integrations/postgresql#postgresql_agent2

6.1. debian12 버전에 agent2 설치

설치 절차
1. Zabbix 저장소 패키지 다운로드

wget https://repo.zabbix.com/zabbix/7.4/release/debian/pool/main/z/zabbix-release/zabbix-release_latest+debian12_all.deb

– Debian12용 리포지토리 설정 파일을 가져옵니다.
Zabbix
initMAX s.r.o.
2. 저장소 패키지 설치

sudo dpkg -i zabbix-release_latest+debian12_all.deb

– /etc/apt/sources.list.d/zabbix.list 에 공식 리포지토리가 등록됩니다.
Zabbix
initMAX s.r.o.
3. 패키지 인덱스 갱신

sudo apt update

– 새로 등록된 Zabbix 저장소의 메타데이터를 가져옵니다.
Zabbix
initMAX s.r.o.
4. Zabbix-Agent2 설치

sudo apt install -y zabbix-agent2

apt install -y zabbix-agent2-plugin-postgresql

– Zabbix 공식 패키지에서 에이전트를 설치합니다.
initMAX s.r.o.
Zabbix
5. 에이전트 서비스 시작 및 자동 실행 설정

sudo systemctl start zabbix-agent2
sudo systemctl enable zabbix-agent2

6.2. PostgreSQL에 모니터링 전용 사용자 생성

- 기본 설정

- 계정 생성과 관련해서 local만 설정하는 경우, 외부 허용을 설정하는 경우가 있다.

- 에이전트가 접속하는 것이면 로컬 계정으로 충분할 것이다.

- 확인이 필요함

- 접속 방법

psql -U postgres -d postgres -h localhost

- 10 버전 이상

CREATE USER zbx_monitor WITH PASSWORD '<PASSWORD>' INHERIT;
GRANT pg_monitor TO zbx_monitor;

- 9.5 버전 이하

CREATE USER zbx_monitor WITH PASSWORD '<PASSWORD>';
GRANT SELECT ON pg_stat_database TO zbx_monitor;

-- To collect WAL metrics, the user must have a `superuser` role.
ALTER USER zbx_monitor WITH SUPERUSER;

- 확인 방법

select * from pg_catalog.pg_user;

6.3. pg_hba.conf 설정

- 셋 중 하나만 설정 하면 된다.

host    all        zbx_monitor   localhost    trust
host    all        zbx_monitor   127.0.0.1/32 md5
host    all        zbx_monitor   ::1/128      scram-sha-256 # 가장 권장되는 설정 (보안성 높음)

host    all    zbx_monitor    127.0.0.1/32    scram-sha-256 # 이렇게도 가능

- trust 방식은 피하는게 좋다고 한다. - 패스워드 없이 접속 가능
- scram-sha-256을 사용하는걸 추천한다. - 가장 안전한 인증 방식
- IP 주소를 구체적으로 지정하는게 좋다. - 127.0.0.1/32처럼 명확한 범위 설정

- 운영체제가 localhost를 ::1(IPv6)로 먼저 해석하는 경우, IPv4 전용 레코드(127.0.0.1/32)만 정의하면 IPv6 연결이 차단될 수 있다.

- 설정 예시

- IPv4 전용 환경:

host all zbx_monitor 127.0.0.1/32 md5

- IPv6 전용 환경:

host all zbx_monitor ::1/128 scram-sha-256

- 듀얼 스택 환경:

host all zbx_monitor 127.0.0.1/32 md5
host all zbx_monitor ::1/128 scram-sha-256

7. postgres:17.5 / zabbix 7.4 agent2로 설치하기 - docker-compose & dockerfile-postgres

- 참고 문서 : https://www.zabbix.com/integrations/postgresql#postgresql_agent2

7.1. Dockerfile

- Dockerfile-postgresql로 저장한다.

- mkdir -p /run/zabbix를 필수로 해줘야 한다.

FROM postgres:17.5

# 필수 도구 설치 및 Zabbix Agent2 레포지토리 등록
RUN apt update -y \
    && apt install -y wget vim \
    && wget https://repo.zabbix.com/zabbix/7.4/release/debian/pool/main/z/zabbix-release/zabbix-release_latest+debian12_all.deb \
    && dpkg -i zabbix-release_latest+debian12_all.deb \
    && apt update -y \
    && apt install -y zabbix-agent2 zabbix-agent2-plugin-postgresql \
    && rm -f zabbix-release_latest+debian12_all.deb \
    && apt clean all

# Zabbix 설정 파일 복사 (빌드 컨텍스트 내 backup 디렉터리에 위치)
COPY ./config/postgresql/backup/zabbix_agent2.conf /etc/zabbix/zabbix_agent2.conf

RUN mkdir -p /run/zabbix

# 컨테이너 기동 시 Zabbix Agent2를 포그라운드로 실행하고 MySQL 서버를 시작
ENTRYPOINT ["bash", "-c", "zabbix_agent2 -f & exec docker-entrypoint.sh postgres"]

7.2. init.sql에 필수 사용자 생성

- 모니터링 사용자 생성

-- Zabbix 모니터링용 MySQL 계정 생성 및 권한 부여
CREATE USER zbx_monitor WITH PASSWORD 'test!' INHERIT;
GRANT pg_monitor TO zbx_monitor;

7.3. pg_hba.conf 구성

- 하단에 localhost와 127.0.0.1에 대한 구성을 해준다.

- 자세한건 6.3 항목을 참고한다.

- localhost는 필요시 삭제해도 무방하다.

host       all        zbx_monitor     localhost               trust
host       all        zbx_monitor     ::1/128                 scram-sha-256

7.4. zabbix_agent2 설정

- Server : zabbix server ip

- ListenIP : 컨테이너에서 사용할 리스닝 포트 예) 10055

- Hostname : 호스트 네임 (서버와 동일하게 설정)

7.5. docker-compose

  postgres:
    # image: postgres:17.5
    build:
      context: .
      dockerfile: Dockerfile-postgresql
    logging:
      driver: "json-file"
      options:
        max-file: "5"
        max-size: "100m"
    container_name: postgres
    restart: always
    ports:
      - "5432:5432"
      - "10055:10055"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: test!
      POSTGRES_DB: postgres
      TZ: Asia/Seoul
    volumes:
      - ./data/postgresql:/var/lib/postgresql/data
      - ./config/postgresql/postgresql.conf:/var/lib/postgresql/data/postgresql.conf
      - ./config/postgresql/backup/pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf
      - ./config/postgresql/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
      - ./config/postgresql/backup:/backup
      - ./logs/postgresql:/var/log/postgresql
    networks:
      - db_network

7.6. zabbix 서버 설정

- 호스트 생성시 PostgreSQL by Zabbix agent 2 템플릿을 설치한다.

- 호스트 생성시 2개 항목에 대한 매크로만 설정해주면 된다.

- reference :

https://blog.zabbix.com/setting-up-zabbix-agent-2-for-postgresql-monitoring-and-revealing-how-it-works/13208/

Setting up Zabbix Agent 2 for PostgreSQL monitoring and revealing how it works - Zabbix Blog

This article will recall the most important theses about the plugin for PostgreSQL monitoring for Zabbix Agent 2. Here…

blog.zabbix.com

저작자표시 비영리 동일조건 (새창열림)

'Infra Management > Zabbix' 카테고리의 다른 글

오라클 클라우드에 zabbix-agent2 7.4 & ubuntu24.04 설치 및 설정 (2)	2025.07.25
[인프런] GZS - 우리도 자빅스(Zabbix) - 그라파나, 슬랙 연동 (2) (5)	2025.07.15
[인프런] GZS - 우리도 자빅스(Zabbix) - 그라파나, 슬랙 연동 (1) (2)	2025.07.14