Skip to content

DOCS: add zk, cluster guide - #49

Open
f1v3-dev wants to merge 1 commit into
developfrom
f1v3/docs
Open

DOCS: add zk, cluster guide#49
f1v3-dev wants to merge 1 commit into
developfrom
f1v3/docs

Conversation

@f1v3-dev

Copy link
Copy Markdown
Collaborator

🔗 Related Issue

⌨️ What I did

문서 링크: https://github.com/jam2in/arcusctl/tree/f1v3/docs/docs/cluster

  • arcusctl의 실행 환경과 로컬 상태 관리 방식을 설명하는 시작 가이드를 추가합니다.
    • ZooKeeper 토폴로지 작성 방법 및 명령어 설명 가이드 추가
    • Arcus Cluster 토폴로지 작성 및 명령어 설명 가이드 추가
  • getting-startedzk-guidecluster-guide 순으로 읽는 구조로 구성하였습니다.

@f1v3-dev
f1v3-dev requested review from namsic and oliviarla August 10, 2026 01:47
@f1v3-dev f1v3-dev self-assigned this Aug 10, 2026
@linear-code

linear-code Bot commented Aug 10, 2026

Copy link
Copy Markdown

APL-15

@f1v3-dev

f1v3-dev commented Aug 10, 2026

Copy link
Copy Markdown
Collaborator Author

수정사항에 따라 문서 내용 변경사항이 존재합니다.

SSH 연결 방식 변경 (PR #50)

  • 원격 명령 실행과 파일 전송에 시스템 OpenSSH의 ssh, scp 사용으로 설명을 수정합니다.
  • ~/.ssh/config 설정이 적용됨을 안내합니다.
  • 현재 운영체제의 사용자명과 ~/.ssh/id_rsa 를 고정으로 사용한다는 기존 설명을 제거합니다.

ZooKeeper 디렉터리 관리 변경 (PR #51)

  • zk deploy: 노드별 <data_log_dir>/zk<myid> 디렉터리 생성
  • zk delete: 노드별 <data_dir>/zk<myid><data_log_dir>/zk<myid 디렉터리 삭제

@oliviarla oliviarla left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

리뷰 완료입니다.

- `arcusctl cluster delete <servicecode> --purge`

- 기본 `cluster delete` 작업을 수행합니다.
- 다른 로컬 관리 클러스터가 같은 호스트, 설치 경로 및 버전을 사용하지 않는 경우 원격 설치 디렉터리도 제거합니다.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

로컬 관리 클러스터가 어떤 의미인가요..?

Comment thread docs/cluster/zk-guide.md
| `tick_time` | ZooKeeper의 기본 `tick` 시간 | `2000` |
| `init_limit` | follower가 leader에 연결하고 동기화할 수 있는 `tick` 수 | `10` |
| `sync_limit` | follower와 leader 사이의 요청 및 응답에 허용되는 `tick` 수 | `5` |
| `data_dir` | 스냅샷과 `myid`를 저장할 기본 디렉터리 | 없음, 필수 |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

기본값이 있으면 편리할 것 같은데 @namsic 님은 어떻게 생각하시나요? 고객사에서 일반적으로 쓰는 경로가 있나요??

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

고객사에서 일반적으로 쓰는 경로가 있나요??

일반적으로 고객사에서는 arcus 설치될 최상위 루트 경로 하나만 결정하고
그 하위 구조는 설치한 사람 마음대로 구성하게 되는데,
익숙해서 그런지 개발 환경에서 구성하듯이 ZK 설치 경로 아래에 data 두는 경우가 많은 듯 합니다.

버전 업그레이드를 고려하여 ZK 설치 경로 바깥에 conf와 data를 두는 경우(jam2in/arcus-tool#3)도 있습니다.

Comment thread docs/cluster/zk-guide.md
### 실행 예시

```sh
arcusctl zk deploy 3.8.4 zk-topology.yml

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

버전은 기본적으로 3.5.9로 표현하는게 좋을 것 같습니다.

Comment thread docs/cluster/zk-guide.md
```

> [!CAUTION]
> `delete`는 원격 호스트에서 `<path>` 전체를 제거합니다. 다른 앙상블이나 프로그램과 공유하지 않는 전용 경로를 사용하세요. No newline at end of file

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

purge옵션을 제공하지 않고 delete 시에 항상 디렉터리 자체를 제거하도록 인터페이스를 만든 것은 한 장비에는 하나의 zk만 구동하는 것이 현재까지의 일반적인 운영 패턴이었기 때문입니다. 그런데 현재 문서에서는 이 점이 잘 드러나지 않아서 전체적으로 잘 표현되면 좋겠습니다. (ex. line 149의 "같은 호스트에 여러 노드가 있으면" 부분에서 이러한 상황은 권장되지 않는다고 명시하는 정도면 괜찮을 것 같습니다.)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

참고로, 실습/테스트 목적이 아닌 이상 실 운영 환경에서 delete 기능 사용할 일이 없을 것입니다.
(위험하기도 하고, 설치된 파일을 제거해야 할 필요성 자체도 낮음)
기존 도구들 중에도 uninstall 기능을 제공하는 도구가 없습니다.

zookeeper: zk1:2181,zk2:2181,zk3:2181

servers:
- address: cache1:11211

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

현재 address에 hostname을 넣어도 클러스터가 정상 동작하나요?

@f1v3-dev

Copy link
Copy Markdown
Collaborator Author

@namsic @oliviarla

문서 전반에서 로컬 호스트, 원격 호스트, 원격 서버, ZooKeeper 노드, ZooKeeper 서버 등 표현이 혼용되고 있어 용어를 통일하고자 합니다.

현재는 아래와 같이 정리하는 방향을 생각하고 있습니다.

  • 운영 장비: arcusctl을 실행하고 메타데이터 및 아카이브를 저장하는 장비
  • 원격 장비: arcusctl이 SSH/SCP로 관리하는 장비
  • ZooKeeper 서버: myid로 구분되는 ZooKeeper 프로세스
  • 캐시 서버: <host>:<port>로 구분되는 Arcus memcached 프로세스

즉, 장비는 OS 또는 VM 단위의 실행 환경을 의미하고, 서버는 해당 호스트에서 실행되는 ZooKeeper 혹은 Memcached 프로세스를 의미하도록 구분하려 합니다.

이러한 용어 구분이 적절할지, 또는 실행 호스트와 대상 호스트보다 더 자연스러운 표현이 있을지 의견 부탁드립니다.

@namsic namsic left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

즉, 장비는 OS 또는 VM 단위의 실행 환경을 의미하고, 서버는 해당 호스트에서 실행되는 ZooKeeper 혹은 Memcached 프로세스를 의미하도록 구분하려 합니다.
이러한 용어 구분이 적절할지, 또는 실행 호스트와 대상 호스트보다 더 자연스러운 표현이 있을지 의견 부탁드립니다.

저는 장비/호스트(==VM), 서버/노드(==process) 표현이면 크게 어색하지 않습니다.

Comment thread docs/cluster/zk-guide.md
| `tick_time` | ZooKeeper의 기본 `tick` 시간 | `2000` |
| `init_limit` | follower가 leader에 연결하고 동기화할 수 있는 `tick` 수 | `10` |
| `sync_limit` | follower와 leader 사이의 요청 및 응답에 허용되는 `tick` 수 | `5` |
| `data_dir` | 스냅샷과 `myid`를 저장할 기본 디렉터리 | 없음, 필수 |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

고객사에서 일반적으로 쓰는 경로가 있나요??

일반적으로 고객사에서는 arcus 설치될 최상위 루트 경로 하나만 결정하고
그 하위 구조는 설치한 사람 마음대로 구성하게 되는데,
익숙해서 그런지 개발 환경에서 구성하듯이 ZK 설치 경로 아래에 data 두는 경우가 많은 듯 합니다.

버전 업그레이드를 고려하여 ZK 설치 경로 바깥에 conf와 data를 두는 경우(jam2in/arcus-tool#3)도 있습니다.

Comment thread docs/cluster/zk-guide.md
```

> [!CAUTION]
> `delete`는 원격 호스트에서 `<path>` 전체를 제거합니다. 다른 앙상블이나 프로그램과 공유하지 않는 전용 경로를 사용하세요. No newline at end of file

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

참고로, 실습/테스트 목적이 아닌 이상 실 운영 환경에서 delete 기능 사용할 일이 없을 것입니다.
(위험하기도 하고, 설치된 파일을 제거해야 할 필요성 자체도 낮음)
기존 도구들 중에도 uninstall 기능을 제공하는 도구가 없습니다.

Copy link
Copy Markdown
Member

저도 동의합니다.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants