DOCS: update arcusctl guides by f1v3-dev · Pull Request #54 · jam2in/arcusctl

f1v3-dev · 2026-09-01T11:30:23Z

🔗 Related Issue

⌨️ What I did

문서 구조 비교

AS-IS: https://github.com/jam2in/arcusctl/tree/develop/docs

TO-BE: https://github.com/jam2in/arcusctl/tree/f1v3/docs-2/docs

arcusctl의 전체 문서 구조와 내용을 정리했습니다.

현재 구현을 기준으로 명령 형식, 동작 설명 및 출력 예시를 보완했습니다.
기존 ACL 명령 및 설정 문서를 하나의 ACL 운영 가이드로 통합했습니다.
설정 및 토폴로지 예시를 examples 디렉터리로 분리하고 Community와 Enterprise 예시를 각각 제공하도록 변경했습니다.
README에 문서와 예시 파일의 진입 경로를 추가했습니다.

f1v3-dev · 2026-09-01T11:33:05Z

@namsic
기존 ACL 명령 및 설정 문서를 통합한 3-arcus-acl-guide.md의 구성과 내용 검토 부탁드립니다.

@jhpark816
이전에 대표님과 논의했던 내용을 전반적으로 반영했습니다. 전체 문서 구조와 각 문서의 구성 및 흐름을 검토해 주시면 감사하겠습니다.

jhpark816

리뷰 완료

jhpark816 · 2026-09-01T13:53:19Z


 ```text
-~/.arcusctl/
+<home>/


아래 2개 디렉토리를 구분하여 설명해야 하지 않는 지?

arcusctl repo 자체를 다운로드하여 설치하는 디렉토리

.arcusctl 디렉토리

arcusctl 설치 디렉터리는 사용자가 운영 과정에서 직접 관리하거나 참조하는 대상이 아니므로 별도로 설명하지 않았습니다.

또한 실행 파일의 위치와 디렉터리 구조는 바이너리, go install, Docker 등 설치 방식에 따라 달라지며, Docker로 실행하는 경우에는 호스트에 별도의 설치 디렉터리가 생성되지 않습니다. 따라서 공통 가이드에서 설명할 대상은 아니라고 판단했습니다.

@oliviarla
위의 내용 검토 바랍니다.

바이너리를 설치하는 위치랑은 무관한 내부 파일이다라는 설명만 추가하면 되지 않을까요?

arcusctl 레포를 다운로드/설치하는 위치는 사용자가 알아서 정하면 됩니다.
(고객사의 경우 저희가 권장하는 위치에 설치하겠지만 그 부분은 고객사 가이드에 작성해두면 됩니다.)

운영 장비의 상태 및 아카이브

home은 arcusctl 실행 파일의 설치 디렉터리와는 별개로, 운영 장비에 아카이브와 배포 상태를 저장하기 위해 내부적으로 사용하는 기준 디렉터리입니다.

home의 기본값은 ~/.arcusctl이며, 설정 파일의 home 또는 ARCUSCTL_HOME 환경 변수로 다른 경로를 지정할 수 있습니다.

위와 같이 표현하는 형태로 수정하면 괜찮을 것 같은데 어떤가요?

jhpark816 · 2026-09-02T01:08:37Z

  init_limit: 10
  sync_limit: 5
  data_dir: /var/lib/zk/data
  data_log_dir: /var/lib/zk/datalog


data_log_dir => log_dir 로 표현하면 될 것 같은데요.
ZooKeeper 공식 문서에서는 어떻게 표현하는 지 궁금합니다.

공식문서에서도 dataLogDir 이라는 표현을 사용하고 있습니다.

아래와 같은 공식 용어를 사용해야 할 것 같은 데, 어떤가요?

tickTime initLimit syncLimit dataDir dataLogDir

현재 ZooKeeper 및 Arcus 클러스터 토폴로지에서 global_config, data_log_dir과 같이 스네이크 케이스(snake_case)를 기준으로 구현되어 있습니다.

ZooKeeper 토폴로지에서 tickTime, dataLogDir과 같은 공식 설정명을 사용하면 zoo.cfg와의 대응 관계가 더 명확해지는 장점은 있습니다. 다만 이를 적용한다면 클러스터 토폴로지를 포함한 전체 토폴로지의 필드명을 하나의 명명 규칙으로 통일하는 것이 좋을 것 같습니다.

기존 토폴로지 파일과의 호환성 및 코드 변경이 필요한 사항이므로, 명명 규칙이 결정되면 별도 PR에서 진행하겠습니다.

저는 지금대로도 두어도 사용자가 이해하기에 어려움 없을 것 같습니다.

jhpark816

리뷰 완료

jhpark816 · 2026-09-03T07:50:20Z

  init_limit: 10
  sync_limit: 5
  data_dir: /var/lib/zk/data
  data_log_dir: /var/lib/zk/datalog


아래와 같은 공식 용어를 사용해야 할 것 같은 데, 어떤가요?

tickTime initLimit syncLimit dataDir dataLogDir

jhpark816 · 2026-09-03T07:52:30Z


 ```text
-~/.arcusctl/
+<home>/


@oliviarla
위의 내용 검토 바랍니다.

jhpark816

기능에 대해 리뷰 의견이 있습니다.

@f1v3-dev @oliviarla @namsic
같이 검토 바랍니다.

jhpark816 · 2026-09-03T10:22:29Z

+캐시 서버별 프로세스 실행 상태와 ZooKeeper 등록 여부를 다음과 같이 출력합니다.
+
+```text
+Arcus cluster "my-cluster" (edition: community, version: 1.16.1)


캐시 서버별 버전 정보이어야 할 것 같은 데, 검토 바랍니다.

arcusctl으로 관리한다면 클러스터 배포 시, 그리고 추후 추가될 upgrade 시에 버전을 명시하게 됩니다.
일부 서버만 다른 버전을 사용하는 경우는 rolling upgrade 작업 도중 외에는 없기 때문에 클러스터 별 버전 정보 명시로도 충분할 것 같습니다.

arcusctl로 관리할 시에 노드 단위로 다른 버전을 가지게 되는 경우가 많습니다.
Naver 사례 참고 바랍니다.

jhpark816 · 2026-09-03T10:24:08Z

+ADDRESS           PROCESS_STATUS  ZK_REGISTERED
+192.0.2.21:11211  running         yes
+192.0.2.22:11211  running         yes
+192.0.2.23:11211  running         yes


ZK_REGISTERED는 항상 yes일 것 같습니다.
어떤 경우에 no가 되나요?

혹시나 cache server mapping에서 해당 주소가 담긴 znode가 사라지는 경우 no가 됩니다.
사용자가 정의한 클러스터 토폴로지(.arcusctl 내 저장) - Znode - 실제 프로세스 구동 정보를 모두 보여주기 위해 이렇게 구성되어 있습니다.

jhpark816 · 2026-09-03T10:26:52Z

 ```

 - Community 클러스터는 `--node <host>:<port>`로 특정 캐시 서버를 지정할 수 있습니다.
 - Enterprise 클러스터는 `--group <group-name>`으로 특정 replication group을 지정할 수 있습니다.


Enterprise 클러스터도 --node 옵션만 제공하는 것이 맞습니다.

--group 옵션이 real or dev 용도 모두에 유용하지 않습니다.

--node 옵션이 하나만 중지할 수도 있고, group 시작/중지도 가능합니다.

--node 명령을 제공하면 사용자는 어떤 상황에 어떤 목적으로 사용하게 되나요?

arcusctl의 제공 목적이 선언형인만큼, 직접 명령을 통해 클러스터의 특정 상태를 변경/제어하는 작업은 지양하고자 하여 이렇게 구성하였습니다.

--node 옵션을 주는 것이 노드 단위로 start/stop하기 위함입니다.
복제 운영에서 업그레이드 시에도 노드 단위의 start/stop이 필요하고, group 단위로 start/stop 하여서는 안 됩니다.

추가 의견을 남깁니다.

start/stop은 --node 옵션이 적합

deploy/delete는 전체 외에 일부 작업이 가능하면 좋겠음

CE버전은 node 단위의 deploy 또는 delete 옵션이 있으면 좋겠음

EE버전은 group 단위의 deploy/delete 옵션이 적당해 보임.

토폴로지 파일에 master/slave 지정을 강제화하는 것이 맞지 않을 것 같음
복제 그룹에 들어갈 노드 목록만 있으면 되고,
노드 목록의 순서대로 구동하면 좋겠음. (그러면, 첫째 노드가 master 노드가 됨)

jhpark816 · 2026-09-03T10:28:05Z

+```text
+SERVICECODE      VERSION   EDITION     NODES  DEPLOYED_AT
+my-cluster       1.16.1    community   3      2026-08-01 12:30:02
+my-repl-cluster  0.12.1-E  enterprise  4      2026-09-01 01:00:13


repl이면 복제 그룹의 수가 중요하지 않는 지 ?

이 정보는 추가하면 될 것 같습니다.

jhpark816

본 PR 자체에 대한 리뷰만 진행합니다.

앞서 리뷰는 PR 자체에 대한 리뷰 보다는 arcusctl 기능에 대한 리뷰이기도 합니다.
따라서, 이전 리뷰는 별도로 처리하도록 하고,
본 PR에 대해서는 문서의 수정 내용에 대해서만 리뷰하고 merge하도록 하시죠.

f1v3-dev self-assigned this Sep 1, 2026

f1v3-dev requested review from jhpark816 and namsic September 1, 2026 11:32

jhpark816 reviewed Sep 2, 2026

View reviewed changes

namsic reviewed Sep 2, 2026

View reviewed changes

Comment thread docs/3-arcus-acl-guide.md

f1v3-dev force-pushed the f1v3/docs-2 branch from 5e3bf59 to 139ab57 Compare September 3, 2026 01:50

f1v3-dev requested review from jhpark816 and namsic September 3, 2026 01:59

namsic approved these changes Sep 3, 2026

View reviewed changes

jhpark816 reviewed Sep 3, 2026

View reviewed changes

f1v3-dev force-pushed the f1v3/docs-2 branch from 139ab57 to 02768f2 Compare September 3, 2026 08:42

jhpark816 reviewed Sep 3, 2026

View reviewed changes

Comment thread docs/1-zk-guide.md

Comment thread docs/1-zk-guide.md Outdated

Comment thread docs/2-cluster-guide.md Outdated

Comment thread docs/2-cluster-guide.md Outdated

f1v3-dev force-pushed the f1v3/docs-2 branch from 02768f2 to a502d7d Compare September 4, 2026 01:12

DOCS: update arcusctl guides

d841309

f1v3-dev force-pushed the f1v3/docs-2 branch from a502d7d to d841309 Compare September 4, 2026 01:33

jhpark816 approved these changes Sep 4, 2026

View reviewed changes

jhpark816 merged commit f38c786 into develop Sep 4, 2026
1 check passed

Uh oh!

Conversation

f1v3-dev commented Sep 1, 2026

🔗 Related Issue

⌨️ What I did

Uh oh!

f1v3-dev commented Sep 1, 2026

Uh oh!

jhpark816 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

운영 장비의 상태 및 아카이브

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jhpark816 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhpark816 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhpark816 Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jhpark816 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

jhpark816 Sep 4, 2026 •

edited

Loading