ETCD 명령어 가이드

Blog

ETCD 명령어 가이드

January 9, 2018·

TLS 인증서 기반 etcd 명령어 실행하기

Kubernetes와 같은 프로덕션 환경에서는 보안을 위해 TLS 인증서 기반으로 etcd를 설치하는 것이 일반적입니다. 이런 환경에서 etcdctl을 사용하려면 반드시 인증서 정보를 플래그로 넘겨줘야 합니다.

또한, etcd 3 버전의 API를 사용하려면 반드시 ETCDCTL_API=3 환경 변수를 설정해야 한다는 점을 기억하세요. 그렇지 않으면 기본적으로 v2 API가 사용됩니다.

ETCDCTL_API=3 etcdctl --endpoints=https://[127.0.0.1]:2379 \
    --cacert=/etc/kubernetes/pki/etcd/ca.crt \
    --cert=/etc/kubernetes/pki/etcd/healthcheck-client.crt \
    --key=/etc/kubernetes/pki/etcd/healthcheck-client.key \
    get foo

위 명령어에서 각 플래그의 의미는 다음과 같습니다:

--endpoints: etcd 서버의 주소
--cacert: CA 인증서 경로
--cert: 클라이언트 인증서 경로
--key: 클라이언트 키 경로

명령어 간소화하기: 별칭(alias) 활용

위에서 보듯이 TLS 인증서를 사용하는 환경에서 etcdctl 명령어는 상당히 깁니다. 매번 이렇게 긴 명령어를 입력하는 것은 번거롭기 때문에, 별칭(alias)을 만들어 사용하면 훨씬 편리합니다.

alias etcd3ctl="ETCDCTL_API=3 etcdctl --endpoints=https://[127.0.0.1]:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/healthcheck-client.crt --key=/etc/kubernetes/pki/etcd/healthcheck-client.key"

이제 etcd3ctl만 입력하면 위의 긴 명령어를 대체할 수 있습니다. 이 별칭을 .bashrc 또는 .zshrc 파일에 추가하면 터미널을 새로 열 때마다 자동으로 로드됩니다.

유용한 etcd 명령어 예제

전체 키 조회하기

etcd v3부터는 v2에 있던 ls 명령어가 제거되었습니다. 전체 키 목록을 조회하려면 루트 경로(/)에서 --prefix 플래그와 함께 get 명령어를 사용해야 합니다.

$ etcd3ctl get / --prefix --keys-only

/registry/apiregistration.k8s.io/apiservices/v1.
/registry/apiregistration.k8s.io/apiservices/v1.apps
/registry/apiregistration.k8s.io/apiservices/v1.authentication.k8s.io
/registry/clusterrolebindings/cluster-admin
/registry/clusterrolebindings/kubeadm:kubelet-bootstrap
/registry/clusterrolebindings/kubeadm:node-autoapprove-bootstrap
/registry/clusterroles/admin
/registry/clusterroles/cluster-admin
/registry/clusterroles/edit
/registry/clusterroles/kubeadm:get-nodes
/registry/deployments/kube-system/coredns
/registry/deployments/kube-system/metrics-server
/registry/deployments/kube-system/tiller-deploy
/registry/deployments/openebs/maya-apiserver
/registry/deployments/openebs/openebs-admission-server
/registry/deployments/openebs/openebs-localpv-provisioner
/registry/deployments/openebs/openebs-provisioner
/registry/deployments/openebs/openebs-snapshot-operator
/registry/deployments/weave/weave-scope-app
...

--keys-only 플래그는 키 값은 출력하지 않고 키 이름만 출력하도록 합니다. 이는 대량의 데이터를 가진 etcd에서 특히 유용합니다.

특정 키 조회하기

특정 키의 값을 조회하려면 단순히 get 명령어 다음에 키 이름을 지정하면 됩니다:

$ etcd3ctl get /registry/deployments/kube-system/coredns

etcd 클러스터 멤버 조회하기

etcd 클러스터의 멤버 목록을 확인하려면 다음 명령어를 사용합니다:

$ etcd3ctl member list
67fab7a197a31464, started, etcd-001, https://10.x.x.x:2380, https://10.x.x.x:2379
9ebdbf1241485ebd, started, etcd-002, https://10.y.y.y:2380, https://10.y.y.y:2379
f3aacf2611e12d71, started, etcd-003, https://10.z.z.z:2380, https://10.z.z.z:2379

출력 정보는 다음과 같은 순서로 표시됩니다:

멤버 ID
상태 (started, unstarted)
멤버 이름
피어 URL (멤버 간 통신에 사용)
클라이언트 URL (클라이언트와 통신에 사용)

엔드포인트 상태 확인하기

etcd 엔드포인트의 상태를 확인하는 명령어는 다음과 같습니다:

$ etcd3ctl endpoint health
https://[127.0.0.1]:2379 is healthy: successfully committed proposal: took = 1.13549ms

더 자세한 상태 정보를 확인하려면:

$ etcd3ctl endpoint status
https://[127.0.0.1]:2379, f3aacf2611e12d71, 3.3.10, 4.6 MB, false, 6, 6880100

출력 정보는 다음과 같은 순서로 표시됩니다:

엔드포인트 URL
멤버 ID
etcd 버전
DB 크기
리더 여부
Raft 인덱스
Raft 용어(term)

백업 생성하기

etcd 데이터를 백업하는 것은 매우 중요합니다. 다음 명령어로 스냅샷을 생성할 수 있습니다:

$ etcd3ctl snapshot save /path/to/backup/etcd-snapshot.db
Snapshot saved at /path/to/backup/etcd-snapshot.db

백업 상태를 확인하려면:

$ etcd3ctl snapshot status /path/to/backup/etcd-snapshot.db -w table
+----------+----------+------------+------------+
|   HASH   | REVISION | TOTAL KEYS | TOTAL SIZE |
+----------+----------+------------+------------+
| fe01cf57 |    10000 |       1300 | 25 MB      |
+----------+----------+------------+------------+

키-값 쓰기 및 삭제하기

새로운 키-값을 설정하려면:

$ etcd3ctl put /my/test/key "Hello, etcd!"
OK

키를 삭제하려면:

$ etcd3ctl del /my/test/key
1  # 삭제된 키의 수

감시(Watch) 기능 사용하기

특정 키나 접두사에 대한 변경 사항을 실시간으로 감시할 수 있습니다:

$ etcd3ctl watch /my/test/key

키 접두사로 여러 키를 감시:

$ etcd3ctl watch /my/test --prefix

고급 명령어 사용법

JSON 형식으로 출력하기

명령어 결과를 JSON 형식으로 출력하려면 -w json 플래그를 사용합니다:

$ etcd3ctl get /my/key -w json
{"header":{"cluster_id":14841639068965178418,"member_id":10276657743932975437,"revision":15,"raft_term":4},"kvs":[{"key":"L215L2tleQ==","create_revision":14,"mod_revision":15,"version":2,"value":"SGVsbG8gV29ybGQ="}],"count":1}

키와 값은 Base64로 인코딩되어 있습니다. 이를 디코딩하면 원래 값을 확인할 수 있습니다.

트랜잭션 사용하기

etcd는 원자적 트랜잭션을 지원합니다. 다음은 간단한 트랜잭션 예제입니다:

$ etcd3ctl txn -i
compares:
value("/my/key") = "current-value"

success requests (get, put, del):
put /my/key "new-value"

failure requests (get, put, del):
get /my/key

이 트랜잭션은 /my/key의 현재 값이 “current-value"인 경우에만 새 값을 설정합니다.

리스(Lease) 기능 사용하기

리스는 TTL(Time To Live)이 있는 키-값 쌍을 생성할 때 사용합니다:

# 10초 리스 생성
$ etcd3ctl lease grant 10
lease 694d5765fc71500b granted with TTL(10s)

# 리스를 사용하여 키-값 설정
$ etcd3ctl put --lease=694d5765fc71500b /my/temp/key "temporary value"
OK

# 리스 목록 확인
$ etcd3ctl lease list
found 1 leases
694d5765fc71500b

# 리스 정보 확인
$ etcd3ctl lease timetolive 694d5765fc71500b
lease 694d5765fc71500b granted with TTL(10s), remaining(5s)

요약

이 포스트에서는 TLS 인증서 기반 etcd 환경에서 자주 사용하는 명령어들을 살펴보았습니다. 별칭(alias)을 통해 복잡한 명령어를 간소화하는 방법도 알아보았습니다. etcd를 효과적으로 관리하기 위해서는 이러한 명령어들의 사용법을 숙지하는 것이 중요합니다.

특히 Kubernetes 환경에서는 etcd가 모든 클러스터 데이터를 저장하는 핵심 컴포넌트이므로, 정기적인 백업과 상태 확인을 통해 안정적인 시스템 운영을 유지하는 것이 필수적입니다.

참고 문서

Last updated on March 24, 2025

ETCD 메트릭 모니터링 가이드 리눅스 디스크 관리 명령어 가이드: df와 du