Docs Home

Etcd

개요

OpenSQL의 클러스터 구성 정보와 설정 정보를 저장하는 etcd 설정 및 실행에 대해 설명한다.

환경 구성

3개 노드에 설치할 etcd 통신 관련 설정 항목은 필수 항목이다.

etcd.env 환경설정

# /etc/etcd/etcd.env 
# mandatory configuration
ETCD_NAME=<ETCD_NODE_NAME>

# Initial cluster configuration
ETCD_INITIAL_CLUSTER=<ETCD_NODE_NAME>=http://<NODE1_IP>:2380,<ETCD_NODE_NAME2>=http://<NODE2_IP>:2380, ...
ETCD_INITIAL_CLUSTER_STATE=new
ETCD_INITIAL_CLSUTER_TOKEN=etcd-cluster

# Peer configuration
ETCD_INITIAL_ADVERTISE_PEER_URLS=http://<NODE_IP>:2380
ETCD_LISTEN_PEER_URLS=http://<NODE_IP>:2380

# Client/server configuration
ETCD_ADVERTISE_CLIENT_URLS=http://<NODE_IP>:2379
ETCD_LISTEN_CLIENT_URLS=http://<NODE_IP>:2379,http://127.0.0.1:2379

#data dir
ETCD_DATA_DIR=/var/lib/etcd

멤버 및 클러스터 정보

Environment Variable
Example
Description

ETCD_NAME

node1

ETCD 클러스터 내에서 고유한 노드의 이름을 지정한다. 클러스터 내에 동일한 이름을 가지는 노드가 2개 이상 있어서는 안되며 후술할 클러스터 정보를 기술하는 항목에 지정된 노드 이름과 일치해야 한다.

ETCD_INITIAL_CLUSTER

node1=http://172.18.0.5:2380,

node2=http://172.18.0.6:2380,

node3=http://172.18.0.7:2380

쉼표 , 로 구분되는 클러스터 내 ETCD 노드의 Peer 간 통신을 위한 URL의 목록으로 ETCD 클러스터를 초기화할 때 사용된다. 각 노드별로 정의되는 ETCD_INITIAL_ADVERTISE_PEER_URLS 값과 일치해야 한다.

ETCD_INITIAL_CLUSTER_STATE

new

클러스터가 처음 시작되는 지 아니면 이미 존재하는 클러스터에 이 노드를 추가하는 지를 결정한다. 처음 시작되는 클러스터의 노드인 경우 new 를, 이미 구성된 클러스터에 새로 추가되는 노드인 경우 existing 을 사용한다.

ETCD_INITIAL_CLUSTER_TOKEN

my-etcd-cluster

ETCD 클러스터의 초기화에 사용되는 고유한 식별자로 동일한 토큰 값을 가지는 노드들이 클러스터에 참여할 수 있다.

ETCD_INITIAL_ADVERTISE_PEER_URLS

http://172.18.0.5:2380

ETCD 노드 간 서로 통신하기 위해 다른 노드에 공개(Advertise)할 이 노드의 피어 URL들의 목록. 다른 노드에서 이 노드에 접근하기 위한 URL이 지정되어야 한다.

ETCD_LISTEN_PEER_URLS

http://172.18.0.5:2380

피어간 통신을 위해 이 노드의 ETCD 서버가 Listen 할 URL들의 목록.

ETCD_LISTEN_CLIENT_URLS

http://172.18.0.5:2379,

https://192.168.0.31:2379,

http://127.0.0.1:2379

클라이언트와 통신을 위해 이 노드의 ETCD 서버가 Listen 할 URL들의 목록.

ETCD_ADVERTISE_CLIENT_URLS

https://192.168.0.31:2379

클라이언트에 공개(Advertise)할 이 노드의 서버 URL들의 목록. ETCD API를 이용해 클러스터 멤버 정보를 가져오는 경우 이 값이 Client Addrs 로 표시된다.

ETCD_DATA_DIR

/var/lib/etcd

ETCD의 data directory

TLS 인증

TLS 인증서를 발급하여 유효한 클라이언트 인증서를 가진 사용자만 ETCD에 접근할 수 있도록 제한하고 클라이언트와의 종단간 통신을 암호화하고자 하는 경우 아래 항목을 설정한다.

  • [클라이언트 - 서버]간 인증과 [서버 - 서버] 간 Peer 인증으로 나뉘며 두 경우에 같은 TLS 인증서 세트를 사용할 수 있다.

Environment Variable
Example
Description

ETCD_TRUSTED_CA_FILE

/etc/etcd/pki/etcd-ca.pem

[클라이언트-서버]간 통신에 사용할 TLS 인증서의 서명 주체이며, 루트 CA (인증기관) 의 인증서 경로를 지정한다.

ETCD_CERT_FILE

/etc/etcd/pki/node3.pem

[클라이언트-서버]간 통신에 사용할 인증서 경로를 지정한다.

ETCD_KEY_FILE

/etc/etcd/pki/node3-key.pem

[클라이언트-서버]간 통신에 사용할 Key 파일 경로를 지정한다.

ETCD_PEER_TRUSTED_CA_FILE

/etc/etcd/pki/etcd-ca.pem

[서버 -서버]간 Peer 통신에 사용할 TLS 인증서의 서명 주체이며, 루트 CA 인증서 경로를 지정한다.

ETCD_PEER_CERT_FILE

/etc/etcd/pki/node3-peer.pem

[서버-서버]간 Peer 통신에 사용할 인증서 경로를 지정한다.

ETCD_PEER_KEY_FILE

/etc/etcd/pki/node3-peer-key.pem

[서버-서버]간 Peer 통신에 사용할 Key 파일 경로를 지정한다.

3-노드 클러스터로 구성하는 etcd 환경설정 예시

노드 주소가 아래와 같고 etcd 노드들과 클러스터 구성을 하는 경우

  • node1 172.176.0.2

  • node2 172.176.0.3

  • node3 172.176.0.4

#/etc/etcd/etcd.env
## 이 서버의 etcd 노드 이름을 node1 로 지정
ETCD_NAME=node1

## 클러스터의 모든 etcd 노드 이름과 접근 가능한 peer url을 설정
ETCD_INITIAL_CLUSTER=node1=http://172.176.0.2:2380,node2=http://172.176.0.3:2380,node3=http://172.176.0.4:2380
ETCD_INITIAL_CLSUTER_TOKEN=etcd-cluster1
## 초기 클러스터 구성 시에는 3 노드 모두 'new' 로 설정하고 동작. 이후 existing으로 수정.
ETCD_INITIAL_CLUSTER_STATE=new

## etcd 노드간 통신하기 위해 사용하는 peer url을 지정. 기본 port는 2380임
ETCD_INITIAL_ADVERTISE_PEER_URLS=http://172.176.0.2:2380
ETCD_LISTEN_PEER_URLS=http://172.176.0.2:2380

# Client/server configuration
ETCD_ADVERTISE_CLIENT_URLS=http://172.176.0.2:2379
ETCD_LISTEN_CLIENT_URLS=http://172.176.0.2:2379,http://127.0.0.1:2379

# data dir
ETCD_DATA_DIR=/var/lib/etcd

실행

Systemd 로 etcd 실행하기

아래와 같이 3개의 노드에 각각 systemd 서비스 파일로 etcd 등록/관리한다.

$ sudo vim /usr/lib/systemd/system/etcd.service

[Unit]
Description=etcd
Documentation=https://github.com/coreos/etcd
Conflicts=etcd-member.service
Conflicts=etcd2.service

[Service]
EnvironmentFile=/etc/etcd/etcd.env
ExecStart=/usr/bin/etcd
Type=notify
TimeoutStartSec=0
Restart=on-failure
RestartSec=5s
LimitNOFILE=65536
Nice=-10
IOSchedulingClass=best-effort
IOSchedulingPriority=2
MemoryLow=200M

[Install]
WantedBy=multi-user.target

Systemd 서비스로 등록하는 예시는 아래와 같다. 명령줄 도구 systemctl 의 daemon-reload 명령어를 이용해 새로 정의한 etcd.service 서비스 정의를 포함해 Configuration을 갱신한다.

$ sudo systemctl daemon-reload

등록한 서비스는 아래 예시처럼 활성화 (Enable) 할 수 있다. 활성화된 서비스는 시스템 부팅 시 자동으로 시작된다.

$ sudo systemctl enable etcd.service
Created symlink from /etc/systemd/system/multi-user.target.wants/etcd.service to /usr/lib/systemd/system/etcd.service.

서비스를 아래 예시처럼 직접 시작하거나 중지, 재 시작할 수 있다. 활성화된 서비스도 명시적으로 사용자가 시작하거나 시스템을 재부팅하기 전까지는 동작하지 않으므로 필요에 따라 직접 실행한다.

$ sudo systemctl start etcd.service

## 서비스를 중지하는 예시
$ sudo systemctl stop etcd.service

## 서비스를 재시작하는 예시
$ sudo systemctl restart etcd.service

구동중인 서비스의 상태는 아래 예시와 같이 확인할 수 있다.

$ sudo systemctl status -l etcd
● etcd.service - etcd
   Loaded: loaded (/usr/lib/systemd/system/etcd.service; enabled; vendor preset: disabled)
   Active: active (running) since Mon 2025-03-17 16:49:45 KST; 3 weeks 2 days ago
     Docs: https://github.com/coreos/etcd
 Main PID: 4763 (etcd)
   CGroup: /system.slice/etcd.service
           └─4763 /usr/bin/etcd

Apr 09 17:46:30 node2 etcd[4763]: {"level":"warn","ts":"2025-04-09T17:46:30.542+0900","caller":"etcdserver/util.go:170","msg":"apply request took too long","took":"402.056395ms","expected-duration":"100ms","prefix":"read-only range ","request":"key:\"/service/opensql/\" range_end:\"/service/opensql\" ","response":"range_response_count:9 size:6173"}

Command 로 etcd 실행하기

또는 아래 예시처럼 명령줄에서 직접 실행할 수도 있다.

$ etcd --name 'node1' \
    --data-dir '/var/lib/etcd' \
    --initial-cluster 'node1=http://172.18.0.2:2380,node2=http://172.18.0.3:2380,node3=http://172.18.0.4:2380' \
    --initial-cluster-token 'etcd-cluster1'
    --initial-cluster-state 'new'

참고

Etcd 는 Systemd 로 등록하여 사용하는 것을 권장한다.

구성 확인

etcd 동작을 아래 명령어를 통해 3개 노드의 etcd 클러스터 상태를 확인한다.

$ etcdctl member list -w=table
+------------------+---------+-------+----------------------+-------------------------+------------+
|        ID        | STATUS  | NAME  |      PEER ADDRS      |      CLIENT ADDRS       | IS LEARNER |
+------------------+---------+-------+----------------------+-------------------------+------------+
| bfac432fd36a61d5 | started | etcd3 | http://opensql3:2380 | http://178.176.0.3:2379 |      false |
| c41cad57348d886f | started | etcd2 | http://opensql2:2380 | http://178.176.0.2:2379 |      false |
| dc3ff6e1d56a1012 | started | etcd1 | http://opensql1:2380 | http://178.176.0.4:2379 |      false |
+------------------+---------+-------+----------------------+-------------------------+------------+

PreviousComponents 설정/실행NextPatroni

Last updated