diff --git a/cluster-sample-topology.yml b/cluster-sample-topology.yml index 228760b..152eb8f 100644 --- a/cluster-sample-topology.yml +++ b/cluster-sample-topology.yml @@ -1,16 +1,17 @@ # For more configuration options, see: # https://github.com/naver/arcus-memcached/blob/master/docs/administration/commandline_args.md +# 192.0.2.0/24 is reserved for documentation. Replace it with addresses from your environment. servicecode: my-cluster # required path: /home/arcus/arcus-memcached # required -zookeeper: zk1:2181,zk2:2181,zk3:2181 # required (comma-separated ensemble) +zookeeper: 192.0.2.11:2181,192.0.2.12:2181,192.0.2.13:2181 # required (comma-separated ensemble) servers: - - address: cache1:11211 # required (host:port) - - address: cache2:11211 - - address: cache3:11211 + - address: 192.0.2.21:11211 # required (host:port) + - address: 192.0.2.22:11211 + - address: 192.0.2.23:11211 config: # optional - per-node override - options: "-l 192.168.1.3" # optional - override global options (-p, -P, -z, -d are not allowed) + options: "-m 128 -v" # optional - override global options (-p, -P, -z, -d are not allowed) global_config: options: "-t 4 -c 1024 -b 1024 -B auto -m 64" # memcached command-line arguments @@ -20,7 +21,7 @@ global_config: # Community and enterprise servers cannot be mixed in the same cluster. # # servers: -# - address: cache1:11211 +# - address: 192.0.2.21:11211 # group: { name: g1, role: master, port: 33533 } -# - address: cache2:11211 -# group: { name: g1, role: slave, port: 33533 } \ No newline at end of file +# - address: 192.0.2.22:11211 +# group: { name: g1, role: slave, port: 33533 } diff --git a/docs/cluster/cluster-guide.md b/docs/cluster/cluster-guide.md new file mode 100644 index 0000000..7a9d2cf --- /dev/null +++ b/docs/cluster/cluster-guide.md @@ -0,0 +1,391 @@ +# Arcus 클러스터 운영 가이드 + +이 문서는 arcusctl을 사용해 community 또는 enterprise Arcus 클러스터를 배포하고 시작, 상태 확인, 중지 및 삭제하는 방법을 설명합니다. + +배포에 필요한 SSH 환경과 운영 장비의 상태 저장 방식은 [arcusctl 시작하기](getting-started.md)를 먼저 참고하세요. + +## 운영 흐름 + +Arcus 클러스터는 다음 순서로 배포하고 관리합니다. + +```text +ZooKeeper 준비 + → 토폴로지 작성 + → deploy + → start + → status / list + → stop + → delete +``` + +> [!IMPORTANT] +> 클러스터 토폴로지에는 실행 중인 ZooKeeper 앙상블 주소가 필요합니다. +> +> `deploy`와 `start`는 분리되어 있습니다. 배포가 성공해도 캐시 서버는 자동으로 시작되지 않습니다. + +## 명령 요약 + +| 명령 | 대상 | 주요 동작 | +| -------------------------------------------------- | ----------------------------------- | ---------------------------------------------------- | +| `arcusctl cluster deploy ` | 새 클러스터 | 바이너리와 ZNode 배포 및 운영 장비에 메타데이터 저장 | +| `arcusctl cluster start [options]` | 전체, 특정 캐시 서버 또는 특정 그룹 | 캐시 서버 시작 | +| `arcusctl cluster status ` | 전체 클러스터 | 캐시 서버 실행 및 ZooKeeper 등록 상태 출력 | +| `arcusctl cluster list` | 운영 장비의 `home` | 관리 중인 클러스터 목록 출력 | +| `arcusctl cluster stop [options]` | 전체, 특정 캐시 서버 또는 특정 그룹 | 캐시 서버 중지 | +| `arcusctl cluster delete [--purge]` | 전체 클러스터 | ZNode와 메타데이터 삭제 및 선택적으로 설치 파일 삭제 | + +## 토폴로지 작성 + +저장소의 [cluster-sample-topology.yml](../../cluster-sample-topology.yml)을 복사한 뒤 환경에 맞게 수정할 수 있습니다. + +### Community 예시 + +```yaml +servicecode: my-cluster +path: /home/arcus/arcus-memcached +zookeeper: 192.0.2.11:2181,192.0.2.12:2181,192.0.2.13:2181 + +servers: + - address: 192.0.2.21:11211 + + - address: 192.0.2.22:11211 + + - address: 192.0.2.23:11211 + config: + options: "-m 128 -v" + +global_config: + options: "-t 4 -c 1024 -b 1024 -B auto -m 64" +``` + +### Enterprise 예시 + +```yaml +servicecode: my-repl-cluster +path: /home/arcus/arcus-memcached +zookeeper: 192.0.2.11:2181,192.0.2.12:2181,192.0.2.13:2181 + +servers: + - address: 192.0.2.21:11211 + group: + name: g1 + role: master + port: 33533 + + - address: 192.0.2.22:11211 + group: + name: g1 + role: slave + port: 33533 + +global_config: + options: "-t 8 -m 128" +``` + +### 기본 필드 + +| 필드 | 설명 | 필수 | +| -------------------------- | --------------------------------------------- | ------ | +| `servicecode` | 클러스터를 식별하는 고유 이름 | 예 | +| `path` | 원격 장비에 Arcus를 설치할 기본 경로 | 예 | +| `zookeeper` | 쉼표로 구분한 ZooKeeper 앙상블 주소 | 예 | +| `servers` | 하나 이상의 캐시 서버 목록 | 예 | +| `servers[].address` | `:` 형식의 고유한 캐시 서버 주소 | 예 | +| `servers[].config.options` | 특정 캐시 서버에 추가할 실행 옵션 | 아니요 | +| `global_config.options` | 모든 캐시 서버에 공통으로 적용할 실행 옵션 | 아니요 | +| `servers[].group` | Enterprise 캐시 서버의 replication group 설정 | 조건부 | + +하나의 토폴로지에 Community edition 캐시 서버와 Enterprise edition 캐시 서버를 함께 정의할 수 없습니다. + +> [!WARNING] +> `-p`, `-P`, `-z`, `-d` 옵션은 arcusctl이 직접 구성합니다. 토폴로지의 `options`에는 해당 옵션을 지정하지 마세요. + +### Group 필드 + +Enterprise edition에서는 모든 캐시 서버에 `group`을 지정해야 합니다. + +| 필드 | 설명 | +| ------ | ------------------------- | +| `name` | Replication group 이름 | +| `role` | `master` 또는 `slave` | +| `port` | Replication에 사용할 포트 | + +Enterprise 토폴로지에는 다음 규칙이 적용됩니다. + +- 각 group에는 `master`가 정확히 하나 있어야 합니다. +- 각 group에는 `slave`를 하나만 지정하거나 생략할 수 있습니다. +- Replication 포트는 `1`부터 `65535` 사이여야 합니다. + +## `cluster deploy` + +새 Arcus 클러스터를 배포합니다. + +### 명령 형식 + +```sh +arcusctl cluster deploy +``` + +### 실행 예시 + +```sh +arcusctl cluster deploy 1.16.0 cluster-topology.yml +``` + +`deploy`는 다음 순서로 동작합니다. + +1. 토폴로지 필드, 캐시 서버 주소 중복 및 enterprise group 구성을 검증합니다. +2. 같은 서비스코드가 현재 `home`이나 ZooKeeper에 이미 등록되어 있는지 확인합니다. +3. Edition, 버전, 캐시 서버 주소 및 설치 경로를 출력하고 사용자에게 진행 여부를 확인합니다. +4. Arcus 소스 아카이브를 내려받거나 운영 장비의 기존 아카이브를 재사용합니다. +5. 각 원격 장비에 의존성을 설치하고 Arcus를 빌드합니다. +6. ZooKeeper에 서비스코드와 캐시 서버 mapping ZNode를 생성합니다. +7. 사용한 버전과 토폴로지 원본을 운영 장비의 `home`에 저장합니다. + +### 아카이브 준비 + +Community 아카이브는 다음 위치에 내려받거나 기존 파일을 재사용합니다. + +```text +/images/arcus-community/arcus-memcached-.tar.gz +``` + +Enterprise 아카이브는 자동으로 내려받지 않습니다. 배포 전에 다음 위치에 직접 준비해야 합니다. + +```text +/images/arcus-enterprise/arcus-memcached-.tar.gz +``` + +### 원격 장비의 설치 경로 + +Arcus는 원격 장비의 다음 경로에 버전별로 설치됩니다. + +```text +// +├── bin/memcached +├── lib/ +├── src/ +└── arcus-memcached-.tar.gz +``` + +같은 토폴로지에 동일한 원격 장비의 캐시 서버가 여러 개 있으면 빌드는 원격 장비마다 한 번만 수행합니다. + +대상 경로에 `bin/memcached`가 이미 존재하면 기존 설치를 재사용합니다. + +### ZooKeeper 등록 + +Edition에 따라 다음 ZNode를 생성합니다. + +Community edition은 `/arcus`를 root로 사용합니다. + +```text +/arcus/cache_list/ +/arcus/client_list/ +/arcus/cache_server_mapping/:/ +``` + +Enterprise edition은 `/arcus_repl`을 root로 사용합니다. + +```text +/arcus_repl/cache_list/ +/arcus_repl/client_list/ +/arcus_repl/cache_server_mapping/:/^^: +/arcus_repl/group_list// +``` + +> [!WARNING] +> 배포 중 오류가 발생해도 완료된 작업은 자동으로 롤백되지 않습니다. +> 일부 원격 장비에 설치 파일이 남거나 ZooKeeper에 일부 ZNode가 생성될 수 있으므로 오류 메시지를 확인하고 직접 정리해야 합니다. + +## `cluster start` + +캐시 서버를 시작합니다. + +### Community + +전체 캐시 서버를 토폴로지에 선언된 순서대로 시작합니다. + +```sh +arcusctl cluster start +``` + +특정 캐시 서버만 시작하려면 토폴로지에 작성한 전체 주소를 지정합니다. + +```sh +arcusctl cluster start --node : +``` + +### 실행 예시 + +```sh +arcusctl cluster start my-cluster +arcusctl cluster start my-cluster --node 192.0.2.22:11211 +``` + +Community 클러스터에서는 `--group`을 사용할 수 없습니다. + +### Enterprise + +전체 클러스터를 시작하면 모든 `master`를 먼저 시작한 뒤 `slave`를 시작합니다. + +```sh +arcusctl cluster start +``` + +특정 group만 시작할 수도 있습니다. + +```sh +arcusctl cluster start --group +``` + +### 실행 예시 + +```sh +arcusctl cluster start my-repl-cluster +arcusctl cluster start my-repl-cluster --group g1 +``` + +Enterprise 클러스터에서는 `--node`를 사용할 수 없습니다. + +한 캐시 서버에서 오류가 발생하면 명령은 해당 지점에서 중단됩니다. 앞선 캐시 서버는 이미 실행 중일 수 있으므로 `status`로 전체 상태를 확인하세요. + +## `cluster status` + +Arcus 클러스터의 상태를 확인합니다. + +### 명령 형식 + +```sh +arcusctl cluster status +``` + +### 실행 예시 + +```sh +arcusctl cluster status my-cluster +``` + +Community edition과 Enterprise edition 모두 캐시 서버별로 상태를 출력합니다. Enterprise edition에서는 각 캐시 서버의 `GROUP`과 `ROLE` 정보도 함께 표시합니다. + +| 상태 | 의미 | 값 | +| ---------------- | ----------------------------------------------- | -------------------- | +| `PROCESS_STATUS` | 원격 장비에서 해당 캐시 서버의 실행 여부 | `running`, `stopped` | +| `ZK_REGISTERED` | ZooKeeper에 캐시 서버 mapping이 존재하는지 여부 | `yes`, `no` | + +## `cluster list` + +현재 `home`에서 관리하는 Arcus 클러스터 목록을 출력합니다. + +### 명령 및 실행 예시 + +```sh +arcusctl cluster list +``` + +다음 정보를 표시합니다. + +- 서비스코드 +- Arcus 버전 +- Edition +- 캐시 서버 수 +- 배포 시간 + +`list`는 실행 중인 캐시 서버를 자동으로 탐색하지 않습니다. 현재 `home`에 저장된 메타데이터를 기준으로 목록을 출력합니다. + +## `cluster stop` + +캐시 서버를 중지합니다. + +### Community + +전체 캐시 서버를 토폴로지에 선언된 순서대로 중지합니다. + +```sh +arcusctl cluster stop +``` + +특정 캐시 서버만 중지할 수도 있습니다. + +```sh +arcusctl cluster stop --node : +``` + +### 실행 예시 + +```sh +arcusctl cluster stop my-cluster +arcusctl cluster stop my-cluster --node 192.0.2.22:11211 +``` + +### Enterprise + +전체 클러스터를 중지하면 모든 `slave`를 먼저 중지한 뒤 `master`를 중지합니다. + +```sh +arcusctl cluster stop +``` + +특정 group만 중지할 수도 있습니다. + +```sh +arcusctl cluster stop --group +``` + +### 실행 예시 + +```sh +arcusctl cluster stop my-repl-cluster +arcusctl cluster stop my-repl-cluster --group g1 +``` + +한 캐시 서버에서 오류가 발생하면 명령은 해당 지점에서 중단됩니다. 앞선 캐시 서버는 이미 중지되었을 수 있으므로 `status`로 전체 상태를 확인하세요. + +## `cluster delete` + +Arcus 클러스터와 관련 정보를 삭제합니다. + +### 명령 형식 + +ZooKeeper 등록 정보와 운영 장비의 메타데이터만 삭제합니다. + +```sh +arcusctl cluster delete +``` + +원격 장비의 설치 디렉터리까지 삭제하려면 `--purge`를 지정합니다. + +```sh +arcusctl cluster delete --purge +``` + +### 실행 예시 + +```sh +arcusctl cluster delete my-cluster +arcusctl cluster delete my-cluster --purge +``` + +`delete`는 다음 순서로 동작합니다. + +1. 모든 캐시 서버가 중지되어 있는지 확인합니다. +2. 삭제 대상을 출력하고 사용자에게 진행 여부를 확인합니다. +3. ZooKeeper에서 서비스코드, client, mapping 및 group ZNode를 제거합니다. +4. `--purge`를 지정한 경우 원격 장비의 설치 디렉터리를 제거합니다. +5. 운영 장비의 `home`에서 클러스터 메타데이터와 토폴로지를 제거합니다. + +운영 장비에서는 다음 디렉터리를 제거합니다. + +```text +/clusters/arcus/ +``` + +`--purge`를 지정하면 원격 장비에서 다음 디렉터리도 제거합니다. + +```text +/ +``` + +같은 `home`에서 관리하는 다른 클러스터가 동일한 원격 장비, 설치 경로 및 버전을 사용하면 해당 원격 장비의 설치 디렉터리는 제거하지 않습니다. + +> [!CAUTION] +> `--purge`는 원격 장비에서 `/` 전체를 제거합니다. 다른 프로그램과 공유하지 않는 전용 경로를 사용하세요. diff --git a/docs/cluster/getting-started.md b/docs/cluster/getting-started.md new file mode 100644 index 0000000..3dc1fbf --- /dev/null +++ b/docs/cluster/getting-started.md @@ -0,0 +1,200 @@ +# arcusctl 시작하기 + +이 문서는 ZooKeeper 앙상블과 Arcus 클러스터를 처음 배포하기 전에 준비해야 할 실행 환경과 arcusctl의 상태 관리 방식을 설명합니다. + +## 동작 방식 + +arcusctl은 원격 장비에 별도 에이전트를 설치하지 않습니다. 운영 장비에서 SSH와 SCP를 사용해 토폴로지에 선언된 원격 장비를 직접 관리합니다. + +```text +운영 장비 + ├─ SSH/SCP ───────> ZooKeeper 서버가 실행되는 원격 장비 + ├─ SSH/SCP ───────> 캐시 서버가 실행되는 원격 장비 + └─ ZooKeeper 연결 ─> Arcus 클러스터 ZNode 등록·조회·삭제 +``` + +## 용어 + +| 용어 | 의미 | +| -------------- | ---------------------------------------------------------- | +| 운영 장비 | arcusctl을 실행하고 메타데이터 및 아카이브를 저장하는 장비 | +| 원격 장비 | arcusctl이 SSH와 SCP로 관리하는 장비 | +| ZooKeeper 서버 | `myid`로 구분되는 ZooKeeper 프로세스 | +| 캐시 서버 | `:`로 구분되는 Arcus memcached 프로세스 | + +## 실행 환경 준비 + +### 운영 장비 + +arcusctl을 실행하는 운영 장비에는 다음 항목이 필요합니다. + +| 항목 | 용도 | +| ------ | ---------------------------------------------- | +| `ssh` | 원격 장비에서 명령 실행 | +| `scp` | 아카이브와 설정 파일 전송 | +| `wget` | ZooKeeper 및 Arcus Community 아카이브 다운로드 | + +arcusctl은 운영체제에 설치된 OpenSSH의 `ssh`, `scp` 명령을 사용하므로 현재 사용자의 `~/.ssh/config` 설정 항목이 원격 장비 연결에 적용됩니다. + +또한, SSH 연결을 비대화형으로 실행하므로 배포하기 전에 다음 명령이 별도의 사용자 입력 없이 성공하는지 확인하세요. + +```sh +ssh -o BatchMode=yes -o ConnectTimeout=10 hostname +``` + +> [!NOTE] +> 토폴로지의 `host`에는 IP 주소 또는 hostname을 사용할 수 있습니다. +> hostname을 사용하는 경우 운영 장비와 해당 주소를 사용하는 모든 원격 장비에서 이름을 해석할 수 있고 서로 통신할 수 있어야 합니다. + +### 원격 장비 + +모든 원격 장비에는 OpenSSH 설정에 지정된 포트로 접속할 수 있어야 합니다. 별도의 Port 설정이 없다면 기본 22번 포트를 사용합니다. + +공통 요구사항은 다음과 같습니다. + +- 토폴로지에 지정한 설치 경로를 만들고 수정할 수 있는 권한 +- 아카이브 압축 해제를 위한 `tar` +- 토폴로지에 선언한 포트를 사용할 수 있는 환경 + +대상별 추가 요구사항은 다음과 같습니다. + +- ZooKeeper 서버가 실행되는 원격 장비 + - ZooKeeper 버전과 호환되는 Java 런타임 + - 토폴로지의 `path`, `data_dir`을 만들고 수정할 수 있는 권한 + - `data_log_dir`을 별도로 지정했다면 해당 경로를 만들고 수정할 수 있는 권한 + +- 캐시 서버가 실행되는 원격 장비 + - 소스 아카이브의 의존성을 설치할 수 있는 환경 + - `configure`, `make`, `make install`을 실행할 수 있는 셸, 컴파일러 및 빌드 도구 + +## 운영 장비의 상태 및 아카이브 + +`home`은 arcusctl이 운영 장비에 아카이브와 배포 상태를 저장하는 기준 디렉터리입니다. 기본값은 `~/.arcusctl`입니다. + +설정 파일의 `home` 또는 `ARCUSCTL_HOME` 환경 변수로 다른 경로를 지정할 수 있습니다. + +```text +~/.arcusctl/ +├── images/ +│ ├── arcus-community/ +│ │ └── arcus-memcached-.tar.gz +│ ├── arcus-enterprise/ +│ │ └── arcus-memcached-.tar.gz +│ └── zookeeper/ +│ └── apache-zookeeper--bin.tar.gz +└── clusters/ + ├── arcus/ + │ └── / + │ ├── meta.yml + │ └── topology.yml + └── zookeeper/ + └── / + ├── meta.yml + └── topology.yml +``` + +각 파일과 디렉터리의 용도는 다음과 같습니다. + +- `images/`: 내려받거나 사용자가 준비한 아카이브 +- `meta.yml`: 리소스 이름, 버전 및 배포 시간 등의 메타데이터 +- `topology.yml`: `deploy`에 사용한 토폴로지 원본 + +> [!IMPORTANT] +> `start`, `stop`, `status`, `list`, `delete`는 `home`에 저장된 배포 정보를 기준으로 동작합니다. +> 원본 토폴로지 파일을 수정해도 이미 등록된 앙상블이나 클러스터에는 반영되지 않습니다. + +## 원격 장비의 설치 구조 + +토폴로지의 `path`는 설치 기준 경로이며, Arcus Memcached와 ZooKeeper 바이너리는 버전별 디렉터리에 설치됩니다. + +**Arcus Memcached** + +```text +/ +└── / + ├── bin/ + ├── lib/ + ├── src/ + └── memcached-.pid +``` + +**ZooKeeper** + +```text +/ +├── / +│ ├── bin/ +│ ├── conf/ +│ ├── lib/ +│ └── logs/ +├── conf/ +│ └── / +│ └── zk/ +│ ├── zoo.cfg +│ └── zoo.cfg.dynamic +└── data/ + └── / + └── zk/ +``` + +ZooKeeper의 `data_dir`을 생략하면 `/data/`을 사용합니다. `data_dir` 또는 `data_log_dir`을 직접 지정하면 각 경로 아래에 `zk` 디렉터리를 생성합니다. + + +## 기본 운영 흐름 + +ZooKeeper와 Arcus 클러스터 모두 설치와 프로세스 실행이 분리되어 있습니다. + +```text +토폴로지 작성 + → deploy + → start + → status / list + → stop + → delete +``` + +1. 토폴로지 YAML 파일을 작성합니다. +2. `deploy`로 아카이브, 설정 및 관리 정보를 배포합니다. +3. `start`로 프로세스를 실행합니다. +4. `status`로 ZooKeeper 서버 또는 캐시 서버의 상태를 확인합니다. +5. 필요한 경우 `list`로 현재 `home`에서 관리하는 리소스 목록을 확인합니다. +6. 삭제하기 전에 `stop`을 실행하고 `status`로 모든 프로세스가 중지되었는지 확인합니다. +7. 리소스 종류와 삭제 범위를 확인한 뒤 `delete`를 실행합니다. + +## 삭제 시 주의사항 + +> [!NOTE] +> `delete`와 `delete --purge` 모두 운영 장비의 `images`에 저장된 아카이브를 삭제하지 않습니다. + +기본 `delete`는 버전별 바이너리를 보존합니다. `--purge` 옵션을 지정하면 다른 앙상블 또는 클러스터가 공유하지 않는 바이너리까지 삭제합니다. + +**ZooKeeper 앙상블** + +- `arcusctl zk delete ` + - 원격 장비의 `/conf//zk` 설정 디렉터리를 제거합니다. + - 각 ZooKeeper 서버의 `/zk`를 제거합니다. + - 각 ZooKeeper 서버의 `/zk`를 제거합니다. + - 운영 장비의 `home`에서 앙상블 메타데이터와 토폴로지를 제거합니다. + - 원격 장비의 `/` 바이너리는 보존합니다. + +- `arcusctl zk delete --purge` + - 기본 `zk delete` 작업을 수행합니다. + - 다른 앙상블이 같은 원격 장비의 동일한 `/`을 사용하는지 확인합니다. + - 해당 설치를 공유하는 다른 앙상블이 없는 원격 장비에서만 `/`을 제거합니다. + +**Arcus 클러스터** + +- `arcusctl cluster delete ` + - ZooKeeper에 등록된 클러스터 ZNode를 제거합니다. + - 운영 장비의 `home`에서 클러스터 메타데이터와 토폴로지를 제거합니다. + - 원격 장비의 `/` 바이너리는 보존합니다. + +- `arcusctl cluster delete --purge` + - 기본 `cluster delete` 작업을 수행합니다. + - 다른 클러스터가 같은 원격 장비의 동일한 `/`을 사용하는지 확인합니다. + - 해당 설치를 공유하는 다른 클러스터가 없는 원격 장비에서만 `/`을 제거합니다. + +자세한 토폴로지 작성 방법과 명령별 동작은 다음 문서를 참고하세요. + +- [ZooKeeper 운영 가이드](zk-guide.md) +- [Arcus 클러스터 운영 가이드](cluster-guide.md) diff --git a/docs/cluster/zk-guide.md b/docs/cluster/zk-guide.md new file mode 100644 index 0000000..5196b9a --- /dev/null +++ b/docs/cluster/zk-guide.md @@ -0,0 +1,376 @@ +# ZooKeeper 운영 가이드 + +이 문서는 arcusctl을 사용해 ZooKeeper 앙상블을 배포하고 시작, 상태 확인, 중지 및 삭제하는 방법을 설명합니다. + +배포에 필요한 SSH 환경과 운영 장비의 상태 저장 방식은 [arcusctl 시작하기](getting-started.md)를 먼저 참고하세요. + +## 운영 흐름 + +ZooKeeper 앙상블은 다음 순서로 배포하고 관리합니다. + +```text +토폴로지 작성 + → deploy + → start + → status / list + → stop + → delete +``` + +> [!IMPORTANT] +> `deploy`와 `start`는 분리되어 있습니다. 배포가 성공해도 ZooKeeper 서버는 자동으로 시작되지 않습니다. + +## 명령 요약 + +| 명령 | 대상 | 주요 동작 | +| --------------------------------------------- | ----------------------------- | ------------------------------------------------------------------- | +| `arcusctl zk deploy ` | 새 앙상블 | 아카이브, 설정, 데이터 디렉터리 배포 및 운영 장비에 메타데이터 저장 | +| `arcusctl zk start [--node ]` | 전체 또는 특정 ZooKeeper 서버 | ZooKeeper 서버 시작 | +| `arcusctl zk status ` | 전체 앙상블 | 각 ZooKeeper 서버의 실행 상태와 역할 출력 | +| `arcusctl zk list` | 운영 장비의 `home` | 관리 중인 앙상블 목록 출력 | +| `arcusctl zk stop [--node ]` | 전체 또는 특정 ZooKeeper 서버 | ZooKeeper 서버 중지 | +| `arcusctl zk delete [--purge]` | 전체 앙상블 | 설정, 데이터, 메타데이터 삭제 및 선택적으로 설치 파일 삭제 | + +## 토폴로지 작성 + +저장소의 [zk-sample-topology.yml](../../zk-sample-topology.yml)을 복사한 뒤 환경에 맞게 수정할 수 있습니다. + +> [!NOTE] +> 예시에 사용된 `192.0.2.0/24` 대역은 문서 작성용으로 예약된 IP 주소입니다. 실제 환경에서는 각 원격 장비의 IP 주소로 변경하세요. + +```yaml +name: my-ensemble +path: /home/arcus/zookeeper + +servers: + - myid: 1 + address: 192.0.2.11:2181:2888:3888 + config: + data_log_dir: /data/zookeeper/txlog-1 + + - myid: 2 + address: 192.0.2.12:2181:2888:3888 + + - myid: 3 + address: 192.0.2.13:2181:2888:3888 + +global_config: + tick_time: 2000 + init_limit: 10 + sync_limit: 5 + data_dir: /var/lib/zk/data + data_log_dir: /var/lib/zk/datalog + properties: + maxClientCnxns: "60" + autopurge.snapRetainCount: "10" + autopurge.purgeInterval: "24" +``` + +### 기본 필드 + +| 필드 | 설명 | 필수 | +| ------------------- | --------------------------------------------------------------------- | ------ | +| `name` | 앙상블을 식별하는 고유 이름 | 예 | +| `path` | ZooKeeper를 설치할 원격 장비의 기준 경로 | 예 | +| `servers` | 하나 이상의 ZooKeeper 서버 목록 | 예 | +| `servers[].myid` | 앙상블 안에서 중복되지 않는 ZooKeeper 서버 ID | 예 | +| `servers[].address` | `:::` 형식의 고유 주소 | 예 | +| `servers[].config` | 특정 ZooKeeper 서버에 추가하거나 덮어쓸 설정 | 아니요 | +| `global_config` | 모든 ZooKeeper 서버에 공통으로 적용할 설정 | 아니요 | + +### ZooKeeper 설정 + +| 필드 | 설명 | 기본값 | +| -------------- | ---------------------------------------------------------- | ------------------------- | +| `tick_time` | ZooKeeper의 기본 `tick` 시간 | `2000` | +| `init_limit` | follower가 leader에 연결하고 동기화할 수 있는 `tick` 수 | `10` | +| `sync_limit` | follower와 leader 사이의 요청 및 응답에 허용되는 `tick` 수 | `5` | +| `data_dir` | 스냅샷과 `myid`를 저장할 기준 디렉터리 | `/data/` | +| `data_log_dir` | 트랜잭션 로그를 저장할 기준 디렉터리 | 해당 서버의 `data_dir` | +| `properties` | 추가할 `zoo.cfg` 속성 | 없음 | + +ZooKeeper 서버별 `servers[].config`는 `global_config`에 병합됩니다. + +- ZooKeeper 서버 설정에 값이 있으면 같은 이름의 전역 설정을 덮어씁니다. +- `properties`는 키 단위로 추가하거나 덮어씁니다. +- 전역 설정과 서버별 설정에서 모두 `data_dir`을 생략하면 `/data/`을 사용합니다. +- 전역 설정과 서버별 설정에서 모두 `data_log_dir`을 생략하면 해당 ZooKeeper 서버의 최종 `data_dir`을 사용합니다. + +각 ZooKeeper 서버의 실제 데이터 및 로그 경로에는 `myid`가 붙습니다. + +```text +/zk +/zk +``` + +기본 설정을 사용하는 경우 실제 경로는 다음과 같습니다. + +```text +/data//zk +``` + +## `zk deploy` + +새 ZooKeeper 앙상블을 배포합니다. + +### 명령 형식 + +```sh +arcusctl zk deploy +``` + +### 실행 예시 + +```sh +arcusctl zk deploy 3.5.9 zk-topology.yml +``` + +`deploy`는 다음 순서로 동작합니다. + +1. 토폴로지 YAML 파일을 읽고 전역 설정과 ZooKeeper 서버별 설정을 병합합니다. +2. 앙상블 이름, 설치 기준 경로, ZooKeeper 서버 수, `myid` 및 주소 중복을 검증합니다. +3. 같은 이름의 앙상블이 현재 `home`에 이미 등록되어 있는지 확인합니다. +4. 원격 장비 주소, 포트 및 버전별 설치 경로를 출력하고 사용자에게 진행 여부를 확인합니다. +5. Apache ZooKeeper 아카이브를 내려받거나 운영 장비의 기존 아카이브를 재사용합니다. +6. 원격 장비별로 아카이브를 복사하고 `/`에 압축을 해제합니다. +7. ZooKeeper 서버별 설정, 데이터 및 로그 디렉터리를 생성하고 `myid`, `zoo.cfg`, `zoo.cfg.dynamic` 파일을 생성합니다. +8. 사용한 버전과 토폴로지 원본을 운영 장비의 `home`에 저장합니다. + +### 아카이브 준비 + +Apache ZooKeeper 아카이브는 다음 위치에 내려받거나 기존 파일을 재사용합니다. + +```text +/images/zookeeper/apache-zookeeper--bin.tar.gz +``` + +### 원격 장비의 설치 경로 + +ZooKeeper 바이너리는 원격 장비의 `/`에 설치됩니다. 앙상블별 설정과 기본 데이터는 `` 아래에 별도로 생성됩니다. + +```text +/ +├── / +│ ├── bin/ +│ │ └── zkServer.sh +│ ├── conf/ +│ ├── docs/ +│ ├── lib/ +│ ├── logs/ +│ └── zookeeper-.tar.gz +├── conf/ +│ └── / +│ └── zk/ +│ ├── zoo.cfg +│ └── zoo.cfg.dynamic +└── data/ + └── / + └── zk/ + └── myid +``` + +위의 `data` 구조는 `data_dir`을 생략한 경우입니다. `data_dir` 또는 `data_log_dir`을 지정하면 각각 다음 경로를 사용합니다. + +```text +/zk +/zk +``` + +`data_log_dir`을 생략하면 `data_dir`과 동일한 경로를 사용하므로 스냅샷과 트랜잭션 로그가 같은 `/zk` 디렉터리에 저장됩니다. + +같은 원격 장비의 동일한 `/`은 여러 앙상블이 공유할 수 있습니다. 해당 경로에 `zkServer.sh`가 이미 있으면 버전별 바이너리는 다시 설치하지 않고 앙상블별 설정과 데이터를 생성합니다. + +같은 원격 장비에 여러 ZooKeeper 서버가 있으면 버전별 바이너리는 한 번만 설치하고, 설정 파일과 데이터 디렉터리는 ZooKeeper 서버별로 생성합니다. + +다만 운영 환경에서는 원격 장비당 하나의 ZooKeeper 서버를 구성하는 것이 일반적이며, **같은 원격 장비에서 여러 ZooKeeper 서버를 구동하는 방식은 권장하지 않습니다.** + +> [!WARNING] +> 배포 중 오류가 발생해도 완료된 작업은 자동으로 롤백되지 않습니다. +> 일부 원격 장비에 파일이나 설정이 남을 수 있으므로 오류 메시지에 표시된 원격 장비를 확인하고 직접 정리해야 합니다. + +## `zk start` + +ZooKeeper 서버를 시작합니다. + +### 명령 형식 + +전체 앙상블을 시작합니다. + +```sh +arcusctl zk start +``` + +특정 ZooKeeper 서버만 시작하려면 `myid`를 지정합니다. + +```sh +arcusctl zk start --node +``` + +### 실행 예시 + +전체 앙상블을 시작합니다. + +```sh +arcusctl zk start my-ensemble +``` + +`myid`가 `2`인 ZooKeeper 서버만 시작합니다. + +```sh +arcusctl zk start my-ensemble --node 2 +``` + +전체 앙상블을 시작하면 토폴로지에 선언된 순서대로 각 ZooKeeper 서버를 시작합니다. + +한 ZooKeeper 서버에서 오류가 발생하면 명령은 해당 지점에서 중단됩니다. 앞선 ZooKeeper 서버는 이미 실행 중일 수 있으므로 `status`로 전체 상태를 확인하세요. + +## `zk status` + +ZooKeeper 앙상블의 상태를 확인합니다. + +### 명령 형식 + +```sh +arcusctl zk status +``` + +### 실행 예시 + +```sh +arcusctl zk status my-ensemble +``` + +저장된 토폴로지의 모든 ZooKeeper 서버에 대해 `zkServer.sh status`를 실행하고 다음 정보를 출력합니다. + +- 원격 장비 주소와 `myid` +- ZooKeeper 서버 상태 +- leader 또는 follower 역할 + +특정 ZooKeeper 서버에 연결할 수 없거나 상태 확인에 실패하면 해당 ZooKeeper 서버의 오류를 출력하고 다음 ZooKeeper 서버를 계속 확인합니다. + +> [!NOTE] +> 앙상블의 quorum이 정상인지 판단하려면 모든 ZooKeeper 서버의 결과와 leader/follower 구성을 함께 확인하세요. + +## `zk list` + +현재 `home`에서 관리하는 ZooKeeper 앙상블 목록을 출력합니다. + +### 명령 및 실행 예시 + +```sh +arcusctl zk list +``` + +다음 정보를 표시합니다. + +- 앙상블 이름 +- ZooKeeper 버전 +- 배포 시간 + +`list`는 실행 중인 ZooKeeper 서버를 자동으로 탐색하지 않습니다. 현재 `home`에 저장된 메타데이터를 기준으로 목록을 출력합니다. + +## `zk stop` + +ZooKeeper 서버를 중지합니다. + +### 명령 형식 + +전체 앙상블을 중지합니다. + +```sh +arcusctl zk stop +``` + +특정 ZooKeeper 서버만 중지하려면 `myid`를 지정합니다. + +```sh +arcusctl zk stop --node +``` + +### 실행 예시 + +전체 앙상블을 중지합니다. + +```sh +arcusctl zk stop my-ensemble +``` + +`myid`가 `2`인 ZooKeeper 서버만 중지합니다. + +```sh +arcusctl zk stop my-ensemble --node 2 +``` + +전체 앙상블을 중지하면 토폴로지에 선언된 순서대로 각 ZooKeeper 서버를 중지합니다. + +한 ZooKeeper 서버에서 오류가 발생하면 명령은 해당 지점에서 중단됩니다. 앞선 ZooKeeper 서버는 이미 중지되었을 수 있으므로 `status`로 전체 상태를 확인하세요. + +## `zk delete` + +ZooKeeper 앙상블을 삭제합니다. + +기본 `delete`는 앙상블의 설정과 데이터를 삭제하지만 버전별 설치 파일은 보존합니다. `--purge` 옵션을 지정하면 다른 앙상블이 공유하지 않는 버전별 설치 파일도 삭제합니다. + +### 명령 형식 + +앙상블의 설정, 데이터 및 운영 장비의 메타데이터를 삭제합니다. + +```sh +arcusctl zk delete +``` + +원격 장비의 버전별 설치 디렉터리까지 삭제하려면 `--purge`를 지정합니다. + +```sh +arcusctl zk delete --purge +``` + +### 실행 예시 + +```sh +arcusctl zk delete my-ensemble +arcusctl zk delete my-ensemble --purge +``` + +`delete`는 다음 순서로 동작합니다. + +1. 운영 장비의 `home`에 저장된 메타데이터와 토폴로지를 읽습니다. +2. 각 원격 장비에 `/conf//zk` 설정 디렉터리가 존재하는지 확인합니다. +3. 모든 ZooKeeper 서버가 중지되어 있는지 확인합니다. +4. 삭제 경고를 출력하고 사용자에게 진행 여부를 확인합니다. +5. 앙상블별 설정 디렉터리와 ZooKeeper 서버별 데이터 및 로그 디렉터리를 제거합니다. +6. `--purge`를 지정한 경우 다른 앙상블과 공유하지 않는 `/`을 제거합니다. +7. 운영 장비의 `home`에서 앙상블 메타데이터와 토폴로지를 제거합니다. + +기본 `delete`로 원격 장비에서 제거되는 경로는 다음과 같습니다. + +```text +/conf//zk +/zk +/zk +``` + +`--purge`를 지정하면 현재 `home`에 등록된 다른 앙상블이 같은 원격 장비에서 동일한 `/`을 사용하는지 확인합니다. 해당 설치를 공유하는 다른 앙상블이 없는 원격 장비에서만 다음 디렉터리를 추가로 제거합니다. + +```text +/ +``` + +운영 장비에서는 다음 디렉터리를 제거합니다. + +```text +/clusters/zookeeper/ +``` + +기본 `delete`와 `delete --purge` 모두 운영 장비의 다음 아카이브는 삭제하지 않습니다. + +```text +/images/zookeeper/apache-zookeeper--bin.tar.gz +``` + +> [!CAUTION] +> 기본 `zk delete`도 앙상블의 설정과 ZooKeeper 데이터를 영구적으로 삭제합니다. `--purge` 옵션의 차이는 원격 장비의 버전별 설치 경로인 `/`까지 삭제하는 것입니다. +> +> 명시적으로 지정한 `data_dir` 또는 `data_log_dir`을 다른 앙상블과 공유하면 의도하지 않은 데이터가 함께 삭제될 수 있으므로 전용 경로를 사용하세요. +> +> 운영 환경에서는 앙상블을 완전히 삭제하는 경우에만 삭제 대상과 데이터 보존 여부를 충분히 확인한 후 실행하는 것을 권장합니다. diff --git a/zk-sample-topology.yml b/zk-sample-topology.yml index 49c220a..d40a61a 100644 --- a/zk-sample-topology.yml +++ b/zk-sample-topology.yml @@ -1,20 +1,21 @@ # For more configuration options, see: # https://zookeeper.apache.org/doc/r3.5.9/zookeeperAdmin.html#sc_configuration +# 192.0.2.0/24 is reserved for documentation. Replace it with addresses from your environment. name: my-ensemble # required path: /home/arcus/zookeeper # required servers: - myid: 1 # required - address: zk1:2181:2888:3888 # required (host:clientPort:quorumPort:electionPort) + address: 192.0.2.11:2181:2888:3888 # required (host:clientPort:quorumPort:electionPort) config: # optional - per-node override - data_log_dir: /data/zk1-txlog + data_log_dir: /data/zookeeper/txlog-1 - myid: 2 - address: zk2:2181:2888:3888 + address: 192.0.2.12:2181:2888:3888 - myid: 3 - address: zk3:2181:2888:3888 + address: 192.0.2.13:2181:2888:3888 global_config: # optional (default: 2000) @@ -36,4 +37,4 @@ global_config: properties: maxClientCnxns: "60" autopurge.snapRetainCount: "10" - autopurge.purgeInterval: "24" \ No newline at end of file + autopurge.purgeInterval: "24"