DOCS: add zk, cluster guide

[f1v3-dev]

🔗 Related Issue

⌨️ What I did

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

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

[linear-code]

APL-15

[f1v3-dev]

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

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]

리뷰 완료입니다.

[f1v3-dev]

@namsic @oliviarla

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

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

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

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

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

[namsic]

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

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

[oliviarla]

저도 동의합니다.

[f1v3-dev]

@oliviarla @namsic

• 원격 장비의 ZooKeeper 설치 디렉터리 구조
• zk delete에 --purge 옵션 추가
• 리뷰 내용 반영
• 코멘트 기반 용어 통일

위의 수정사항들을 문서에 다시 반영한 상태입니다.
확인해주시면 감사하겠습니다.

[oliviarla]

일부 리뷰입니다.
getting started 부분은 괜찮은데, zk/cluster guide 부분의 문서 방향 협의가 필요할 것 같습니다.
최대한 간결하고 추상화하여 표현 vs 최대한 자세하게 내부 동작까지 표현 중 저는 간결하고 추상화해 표현하는게 낫다는 입장입니다.

[f1v3-dev]

getting started 부분은 괜찮은데, zk/cluster guide 부분의 문서 방향 협의가 필요할 것 같습니다.
최대한 간결하고 추상화하여 표현 vs 최대한 자세하게 내부 동작까지 표현 중 저는 간결하고 추상화해 표현하는게 낫다는 입장입니다.

zk-guide, cluster-guide 에 동작을 상세하게 작성한 이유는 arcusctl이 여러 원격 장비에서 작업을 수행하고, 중간에 실패하더라도 완료된 작업을 자동으로 롤백하지 않기 때문입니다.

따라서 장애 발생 시 사용자가 직접 완료된 범위와 원격 장비에 남아 있는 파일 등을 확인할 수 있도록 주요 처리 순서와 생성 및 삭제 경로를 포함했습니다.

제 생각에는 getting-started는 간결한 입문 문서로 유지하고, zk-guide와 cluster-guide는 장애 대응에 필요한 상세 내용을 포함하는 운영 가이드로 구성하는게 좋을 것 같습니다.

[oliviarla]

네 그러면 zk/cluster guide는 지금 상태로 두어도 될 것 같습니다.