DOCS: Add `cluster upgrade` interface draft by oliviarla · Pull Request #63 · jam2in/arcusctl

oliviarla · 2026-10-20T08:51:37Z

🔗 Related Issue

버전 업그레이드 인터페이스 설계 공유를 위한 PR 입니다.
리뷰해주신 후 본 PR 은 close하고 구현 진행하면 될 것 같습니다.

⌨️ What I did

claude · 2026-10-20T08:54:33Z

리뷰 완료 — Blocker 0건, Major 2건, Minor 0건, Question 0건

claude · 2026-10-20T09:06:17Z

지적 사항 없음

f1v3-dev · 2026-10-23T00:16:30Z

+### 기존 명령과의 연계
+
+`upgrade`를 지원하면서 클러스터 안에 여러 버전이 함께 존재할 수 있습니다. 이에 맞춰 기존 명령의 버전 처리도 다음과 같이 바뀝니다.
+
+| 명령        | 변경 내용                                                                                  |
+|-------------|--------------------------------------------------------------------------------------------|
+| `deploy`    | 배포 버전을 명령 인자 대신 토폴로지의 `globalConfig.version`으로 지정합니다. 아래 [배포 버전 지정 방식 변경 (예정)](#배포-버전-지정-방식-변경-예정)을 참고하세요. |
+| `start`     | 캐시 서버별로 기록된 버전으로 시작합니다.                                                  |
+| `stop`      | 캐시 서버별로 기록된 버전의 pid 파일(`<path>/<version>/memcached-<port>.pid`)로 중지합니다. |
+| `delete`    | 실행 여부 확인과 `--purge` 대상 경로를 캐시 서버별 버전 기준으로 판단합니다.               |
+| `list`      | 버전 혼용 여부와 버전별 캐시 서버 수를 표시합니다.                                         |
+| `status`    | 기존 출력에 캐시 서버별 실행 버전과 업그레이드 진행·실패 단계를 추가합니다.                |


수정해야하는 작업 기록용으로 코멘트 남깁니다.

start에 버전 인자를 추가하고, stop+start 하는 것과
upgrade 명령의 동작에는 어떤 차이가 있나요?

~~내부 토폴로지의 버전은 언제 사용(변경)되나요?~~

start는 binary 파일이 위치에 없는 경우 수행되지 못합니다.
upgrade는 community의 경우 새로운 버전의 바이너리 파일 준비 -> 재구동 이 합쳐진 것이고, enterprise의 경우 새로운 버전의 바이너리 파일 준비 -> 그룹 단위의 재구동 이 합쳐진 형태입니다.

claude · 2026-10-26T11:22:54Z

지적 사항 없음

oliviarla · 2026-10-27T06:18:37Z

@jhpark816 업그레이드 인터페이스 확인해주시면 됩니다.

jhpark816 · 2026-10-27T12:48:05Z

@namsic
업그레이드 기능에 대한 interface 설계인데, 한번 리뷰해 주세요.

namsic · 2026-10-27T13:15:23Z

+|-------------|--------------------------------------------------------------------------------------------|
+| `deploy`    | 배포 버전을 명령 인자 대신 토폴로지의 `globalConfig.version`으로 지정합니다. 아래 [배포 버전 지정 방식 변경 (예정)](#배포-버전-지정-방식-변경-예정)을 참고하세요. |
+| `start`     | 캐시 서버별로 기록된 버전으로 시작합니다.                                                  |
+| `stop`      | 캐시 서버별로 기록된 버전의 pid 파일(`<path>/<version>/memcached-<port>.pid`)로 중지합니다. |


pid는 <path>/memcached-port.pid 처럼 한 개 경로 공유해도 될 것 같습니다.

원래 구조에서 <path>/<version>/memcached-<port>.pid로 저장하고 있는데, 이부분은 향후 수정하면 될 것 같습니다.

jhpark816

리뷰 완료

jhpark816 · 2026-10-27T12:50:48Z

+```
+
+- `--group`으로 업그레이드할 replication group을 지정합니다. 여러 group을 지정하면 나열한 순서대로 업그레이드합니다.
+- `--node`는 사용할 수 없습니다.


@namsic
enterprise에서 --node 제공하지 않아도 되는지 검토 바랍니다.

현재 인터페이스를 기준으로 할 때,
복제에서 upgrade --node는 어색해 보입니다.

slave는 그대로 두고 master node만 재시작하는 것은 권장하는 운영 방식이 아니고,

slave node만 업그레이드 하는 동작은 가능하겠으나 이를 위해 --node를 별도 제공할 이유는 크지 않습니다.

standalone master의 경우에도 --node 제공하지 않고 --group으로 업그레이드하도록 할 수 있을 것입니다.

slave만 업그레이드한 후에 며칠 상황을 지켜보는 경우가 있을까요?

slave만 업그레이드한 후에 며칠 상황을 지켜보는 경우가 있을까요?

old master → new slave 상태를 유지하는 것인데,
테스트 목적이 아닌 실 서비스 환경에서 이 상태로 지켜볼 이유는 없어 보입니다.

버전 업그레이드 방식에 고정된 가이드라인을 둘 것이면 그 한 가지에 맞춰서 동작하도록 하면 됩니다.
그 외 변주가 필요한 때는 arcusctl 없이 사용자가 직접 조작하는 것으로 합니다.

그렇지 않고 arcusctl로 여러가지 업그레이드 시나리오에 모두 대응할 수 있도록 해야 한다면
upgrade 하나에서 인자로 처리하는 것에는 한계가 있을 것으로 보이고,
개별 노드 단위로 운영자가 아래 작업을 매뉴얼하게 수행할 수 있도록 구분해야 할 것 같습니다.

장비에 신규 버전 설치

기존 노드 개별 중지 및 재구동

재구동 대상 노드 운영자가 직접 선택
(일부 노드 선택 및 업그레이드 간격 운영자가 직접 결정)

재구동 시 사용할 버전 운영자가 직접 선택
(문제 생겨 롤백하는 상황 등 고려하면, 신/구 버전을 선택 구동할 수 있어야 함)

oliviarla · 2026-10-28T08:08:17Z

deploy 명령을 바꿀 필요는 없을 것 같아 기존대로 두었습니다.
list 에서 보이던 version 은 더 이상 표시하지 않고(버전 혼용 시 처리의 복잡함이 존재), status에서만 노드의 버전이 보이도록 수정했습니다.

claude · 2026-10-28T08:10:36Z

리뷰 완료 — Blocker 0건, Major 2건, Minor 0건, Question 1건

[Question] cluster upgrade의 --node/--group는 쉼표로 여러 값을 받도록 설계되어 있는데(438행), 기존 cluster start/cluster stop의 동일한 이름 플래그는 단일 값만 받습니다(cmd/cluster/stop.go, cmd/cluster/start.go). 같은 플래그 이름이 명령마다 다른 값 형식(단일 값 vs 쉼표 목록)을 갖게 되는 것이 의도된 설계인지, 아니면 기존 명령과 동일하게 단일 값으로 맞출 계획인지 확인이 필요합니다.

claude · 2026-10-28T09:17:33Z

리뷰 완료 — Blocker 0건, Major 1건, Minor 1건, Question 0건

[Minor] 문서 상단 "운영 흐름"(11행)과 "명령 요약" 표(21~28행)에 이번에 추가한 cluster upgrade가 반영되지 않았습니다. 사용자가 전체 명령 목록을 한곳에서 파악할 수 있도록 함께 갱신해 주세요.

Draft of the rolling upgrade interface for review before implementation. Existing command docs still describe current behavior; planned changes live only in the `cluster upgrade` section. - Targets must be given explicitly with `--node`, `--group` or `--all` to prevent accidental cluster-wide upgrades. `--all` skips targets already running the target version. - Show a plan table with per-target current/target version and action. - Install target binaries on all hosts before stopping any server. - Plan to move the deploy version into `globalConfig.version`. - Plan to show per-server versions in `cluster status`. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

oliviarla · 2026-10-29T08:19:11Z

@jhpark816 최종 수정했습니다. 다시 리뷰 부탁드립니다.

claude · 2026-10-29T08:24:08Z

리뷰 완료 — Blocker 0건, Major 0건, Minor 1건, Question 1건

jhpark816 · 2026-11-02T02:00:37Z

@oliviarla
리뷰 끝나면, merge하면 되나요?

oliviarla · 2026-11-02T02:25:07Z

합의가 끝나면 close하고 이 커밋 기준으로 @f1v3-dev 님이 구현해주시면 됩니다.

oliviarla requested review from f1v3-dev and jhpark816 October 20, 2026 08:51

claude Bot reviewed Oct 20, 2026

View reviewed changes

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

claude Bot reviewed Oct 20, 2026

View reviewed changes

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

oliviarla force-pushed the mkkim/upgrade branch from cd19bea to ad57e65 Compare October 20, 2026 09:02

f1v3-dev reviewed Oct 23, 2026

View reviewed changes

oliviarla force-pushed the mkkim/upgrade branch from ad57e65 to 0a4ce54 Compare October 26, 2026 11:20

f1v3-dev approved these changes Oct 26, 2026

View reviewed changes

jhpark816 requested a review from namsic October 27, 2026 12:47

namsic reviewed Oct 27, 2026

View reviewed changes

jhpark816 reviewed Oct 28, 2026

View reviewed changes

oliviarla force-pushed the mkkim/upgrade branch from 0a4ce54 to 794005c Compare October 28, 2026 08:07

claude Bot reviewed Oct 28, 2026

View reviewed changes

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

claude Bot reviewed Oct 28, 2026

View reviewed changes

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

oliviarla force-pushed the mkkim/upgrade branch from 794005c to d6da01d Compare October 28, 2026 09:12

claude Bot reviewed Oct 28, 2026

View reviewed changes

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

oliviarla force-pushed the mkkim/upgrade branch from d6da01d to 7b25565 Compare October 29, 2026 08:18

claude Bot reviewed Oct 29, 2026

View reviewed changes

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

claude Bot reviewed Oct 29, 2026

View reviewed changes

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

jhpark816 requested a review from namsic October 29, 2026 09:22

namsic approved these changes Nov 1, 2026

View reviewed changes

Conversation

oliviarla commented Oct 20, 2026

🔗 Related Issue

⌨️ What I did

Uh oh!

Uh oh!

Uh oh!

claude Bot commented Oct 20, 2026

Uh oh!

claude Bot commented Oct 20, 2026

Uh oh!

f1v3-dev Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

namsic Oct 27, 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!

oliviarla Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

claude Bot commented Oct 26, 2026

Uh oh!

oliviarla commented Oct 27, 2026

Uh oh!

jhpark816 commented Oct 27, 2026

Uh oh!

Uh oh!

namsic Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

oliviarla Oct 28, 2026

Choose a reason for hiding this comment

Uh oh!

jhpark816 left a comment

Choose a reason for hiding this comment

Uh oh!

jhpark816 Oct 27, 2026

Choose a reason for hiding this comment

Uh oh!

namsic Oct 28, 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!

jhpark816 Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

namsic Oct 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

oliviarla commented Oct 28, 2026

Uh oh!

Uh oh!

Uh oh!

claude Bot commented Oct 28, 2026

Uh oh!

Uh oh!

claude Bot commented Oct 28, 2026

Uh oh!

oliviarla commented Oct 29, 2026

Uh oh!

Uh oh!

Uh oh!

claude Bot commented Oct 29, 2026

Uh oh!

jhpark816 commented Nov 2, 2026

Uh oh!

oliviarla commented Nov 2, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

namsic Oct 27, 2026 •

edited

Loading

namsic Oct 28, 2026 •

edited

Loading