round9 확인 리뷰가 CI 파일의 설명이 실제와 다른 곳을 짚었다. - verify.sh 머리 표: PR 단계 job 이름이 `gradle`이다. 실제는 `done`. - build.gradle: JMH가 「세 leaf」에 있다고 하지만 지금은 플러그인을 쓰는 leaf가 정한다. verifyFeatureScaffold는 「leaf 다섯 중첩 빌드」라고 하지만 그 안의 architectureCheck가 모든 leaf의 architecture lane을 부른다. - release.yml: `release` job 주석은 「ci를 다시 돌리지 않는다」인데 뒤의 job들은 ci가 이미 돈 시험 일부를 다시 돈다. 그 이유(문서가 job id로 부르는 릴리스 증거이고, 이미지 job이 모두를 needs로 받아 같은 run·같은 커밋에서 통과한 뒤 publish한다)를 적었다. job은 그대로다. - gates.md 2절: redis-topology 줄을 desktop에서 그대로 돌리라고 하지만 스크립트 안 ./gradlew는 daemon을 남긴다. desktop에서는 GRADLE_OPTS=-Dorg.gradle.daemon=false를 붙이라고 적었다. 스크립트에 --no-daemon을 넣지 않은 이유: CI는 한 job의 step 11개가 daemon을 다시 쓴다. - redis-sdk compose README: cache-redis 칸에 필수 클래스가 둘뿐이다. build.gradle의 standalone·cluster 목록 다섯으로 맞췄다. - template-vs-consumer.md: object-storage-aws를 nightly job으로 적었다. 실제는 손으로 실행하고 입력 run_protected_aws를 켤 때만 돈다. 최상위 항목을 더하면 「AGENTS.md 지도를 함께 고친다」고 했지만 지도는 루트 목록을 두지 않고 check-repo-layout.py를 가리킨다. src/ 최상위 폴더일 때만 지도의 src/ 줄을 고친다고 적었다. 동작 변경 없음: workflow는 주석만, 스크립트는 머리 주석만 바꿨다. 검증: scripts/verify.sh docs(노트북) rc=0. Refs: round9 확인 리뷰(r9-be wave1-r4 「넘길 것」)
11 KiB
Redis SDK topology lane
이 lane들은 결정적인 메모리 gateway가 답하지 못하는 질문에 답하려고 있다: Sentinel 승격 중에 Lettuce가 실제로 어떻게 움직이는지, Cluster resharding이 진행 중인 명령에 무엇을 하는지, ACL 계정이 SDK가 내는 명령을 정확히 허락하는지.
넷 모두 Redis 7.4에서 돌았고 증거는 docs/redis/support-matrix.md에 적혀 있다.
.gitea/workflows/main.yml의 nightly redis-topology job이 매일 밤(그리고 손으로 실행할 때) 지원 버전 × topology 표
전체를 job 하나 안에서 행마다 step 하나(scripts/ci/redis-topology.sh <topology> <version>)로 돌린다. 같은 줄을 Docker가 있는 머신에서
손으로 돌릴 수 있다. pull request마다 돌던 standalone lane은 2026-11-08에 nightly로 옮겼다(어댑터 컨테이너 lane은
main 단계, 소유자 결정 2026-11-07).
TLS는 손으로 배선할 것이 아니라 그 표의 lane 하나다. 배포 모드가 아니라 tls다: 모양은 standalone이고 검증하는
것은 전송이다. 그래서 redisTopologyTest는 시험에서 lane 이름을 standalone으로 대응시키고, tag 필터와 필요한
신뢰 자료는 lane에 둔다.
TLS lane
tls/compose.yml은 전송만 바꾼 standalone 모양이다. 평문 port는 완전히 끈다(--port 0). 이것만이 무언가를
증명하는 설정이다: 둘 다 받는 lane이면 TLS 협상에 실패한 client가 소리 없이 물러서고도 통과할 수 있다.
인증서는 저장소에 넣지 않고 기동 때 named volume 안에 만든다 — 파일 이름을 어떻게 붙이든 저장소 안의 개인 키는 저장소 안의 개인 키다 — 그리고 하루 동안만 유효해서, 낡은 lane은 조용히 어긋나지 않고 눈에 띄게 실패한다.
REDIS_VERSION=7.4 docker compose -f src/adapter/outbound/redis-sdk/compose/tls/compose.yml up -d --wait
# The client needs the generated CA; copy it out of the volume first.
docker compose -f src/adapter/outbound/redis-sdk/compose/tls/compose.yml cp redis:/tls/ca.crt /tmp/redis-lane-ca.pem
./gradlew :adapter:outbound:redis-runtime:redisTopologyTest \
-Predis.topology.host=127.0.0.1 -Predis.topology.port=6390 \
-Predis.topology.mode=tls -Predis.topology.trust-material=/tmp/redis-lane-ca.pem
lane은 redis.topology.trust-material 없이는 돌기를 거절한다. 아무것이나 믿는 TLS lane은 아무것도 검증하지
않으니, 「CA를 설정하지 않음」은 검증을 끈 client가 아니라 오류다.
ACL fixture
compose/redis/acl/lane-fixture-accounts.acl이 모든 lane이 쓰는 계정을 만든다(각 lane의 compose.yml이 저장소
루트의 그 폴더를 mount한다). 중요한 점이 둘인데, 둘 다 그 파일 안에 쓸 수 없다 — aclfile에 주석 줄이 있으면
Redis가 시작을 거절한다. 그래서 파일 전체가 지시문이고 설명은 여기 있다.
첫 줄 user default off는 일부러 둔 것이다. Redis는 default를 켜고 비밀번호 없이 내놓는다. 그것이 켜져 있는
동안에는 인증하지 않기만 해도 나머지 계정의 모든 제한을 우회할 수 있어서 fixture가 장식이 된다. 그것을 꺼야
client가 — 그리고 compose healthcheck가 — 이름 있는 계정을 고르게 된다.
이름 있는 모든 계정에는 진짜 비밀번호가 있다 — >fixture-application, >fixture-advanced 같은 것이다. 예전에는
nopass였고, 그것이 더 위험한 쪽의 잘못이었다: 아무 비밀번호나 받는 계정에서는 인증에 대한 모든 단언이 오타가
있어도 통과할 이유로 통과했다. 그래서 lane이 AUTH, 교체, 비밀 값 배선을 덮는 것과 덮지 않는 것을 구별할 수
없었다. LiveRedisCompositionTest는 이제 일부러 틀린 비밀번호를 내고 WRONGPASS를 요구한다. 계정이 비밀번호를
강제하기 때문에 뜻이 있는 단언이다.
이 비밀번호는 버리는 container 안의 fixture 값이고 배포 template이 아니다: 실제 배포는 계정마다 credential을
secret://로 해석하고 설정에 쓰지 않는다.
계정은 role로도 나뉜다. SDK가 그렇게 쓰기 때문이다. ca-skeleton-application은 보통 데이터 명령을 돌리고
script를 실행할 수 없다. ca-skeleton-application-advanced는 SCRIPT LOAD와 EVALSHA를 가지고, 다른 계정은 그것이
필요 없다. 이 분리는 장식이 아니라 실제다: LiveRedisSemanticPortsTest는 advanced 계정 없이 rate limiter를 돌리고
그것이 Unavailable로 돌아오기를 요구한다.
하나 돌리기
lane마다 자기 endpoint가 있다. client에게 주는 주소가 topology마다 같은 종류가 아니기 때문이다. standalone은 데이터 노드를 선언한다. Sentinel은 sentinel을 선언하고, 거기서 primary를 찾으며 승격되면 다시 찾는다. Cluster는 아무 노드나 선언하고, 거기서 나머지 topology를 찾는다.
# Standalone
REDIS_VERSION=7.4 docker compose -f src/adapter/outbound/redis-sdk/compose/standalone/compose.yml up -d --wait
./gradlew :adapter:outbound:redis-runtime:redisTopologyTest :adapter:outbound:redis-sdk:redisTopologyTest :adapter:outbound:cache-redis:redisTopologyTest \
-Predis.topology.host=localhost -Predis.topology.port=6379 -Predis.topology.mode=standalone
# Sentinel — the port is a sentinel, and the monitored primary has to be named
REDIS_VERSION=7.4 docker compose -f src/adapter/outbound/redis-sdk/compose/sentinel/compose.yml up -d --wait
./gradlew :adapter:outbound:redis-runtime:redisTopologyTest :adapter:outbound:redis-sdk:redisTopologyTest \
-Predis.topology.host=localhost -Predis.topology.port=27010 \
-Predis.topology.mode=sentinel -Predis.topology.master=skeleton
# Cluster — `up --wait` waits for the `ready` gate, not just for six servers that answer PING.
# Slot assignment finishes after the nodes are healthy, and a client that connects in between sees
# CLUSTERDOWN for reasons that have nothing to do with the SDK.
REDIS_VERSION=7.4 docker compose -f src/adapter/outbound/redis-sdk/compose/cluster/compose.yml up -d --wait
./gradlew :adapter:outbound:redis-runtime:redisTopologyTest :adapter:outbound:redis-sdk:redisTopologyTest :adapter:outbound:cache-redis:redisTopologyTest \
-Predis.topology.host=localhost -Predis.topology.port=7100 -Predis.topology.mode=cluster
leaf마다 자기 시험이 검증하는 lane을 가지고, lane마다 돌아야 하는 클래스를 build.gradle에 적는다
(redisTopologyLane { requiredClasses ... }). leaf가 선언하지 않은 모드를 고르면 아무것도 돌리지 않는 대신
실패한다. 그러니 lane에 적힌 leaf만 돌린다:
| lane | redis-runtime |
redis-sdk |
cache-redis |
|---|---|---|---|
| standalone | LiveRedisCompositionTest |
RedisTopologyContractTest, LiveRedisGuardrailTest |
LiveRedisSemanticPortsTest, LiveRedisSemanticScriptAclProbeTest, LiveRedisDistributedLeaseContractTest, LiveRedisCacheRegionContractTest, LiveRedisIdempotencyStoreContractTest |
| sentinel | LiveRedisCompositionTest |
RedisTopologyContractTest, LiveRedisSentinelPromotionTest |
— |
| cluster | LiveRedisCompositionTest |
LiveRedisClusterTest, LiveRedisClusterTransactionTest |
LiveRedisSemanticPortsTest, LiveRedisSemanticScriptAclProbeTest, LiveRedisDistributedLeaseContractTest, LiveRedisCacheRegionContractTest, LiveRedisIdempotencyStoreContractTest |
| tls | LiveRedisTlsTest |
— | — |
lane은 docker compose -f src/adapter/outbound/redis-sdk/compose/<lane>/compose.yml down -v로 내린다.
| lane | port | 메모 |
|---|---|---|
| standalone | 6379 | bridge network, 내놓은 port |
| sentinel | primary 7010, replica 7011, sentinel 27010–27012 | host network |
| cluster | 노드 7100–7105, bus 17100–17105 | host network. ready가 cluster_state:ok를 기다린다 |
| tls | 6390 | 내놓은 port, 평문 port는 아예 없음. 실행마다 CA를 만든다 |
Sentinel과 Cluster lane이 host network를 쓰는 이유
두 topology 모두 proxy를 하지 않는다. Sentinel은 SENTINEL get-master-addr-by-name에 자기가 감시하는 주소로 답하고
client가 그 주소로 직접 연결한다. cluster client는 CLUSTER SHARDS를 읽고 거기 적힌 모든 노드에 연결한다. bridge
network에서는 그것이 container 안쪽 주소라서, host의 client는 닿을 수 없는 topology를 찾게 되고 — 승격 뒤에는
역시 닿을 수 없는 다른 topology를 찾는다. host network namespace를 같이 쓰면 topology가 알리는 주소가 client가
쓸 수 있는 주소가 된다. 그것이 SDK를 시험하는 것과 Docker network를 시험하는 것의 차이다.
같은 이유로 그 port들은 매개변수로 두지 않고 고정한다: 주소는 만들 때 Sentinel과 cluster 자신의 설정에 쓰이고, 두 절반이 서로 어긋날 수 있는 lane은 SDK와 관계없는 이유로 실패한다.
고르기는 손이 아니라 lane으로 한다
redisTopologyTest는 선언한 모드에서 JUnit tag 식을 끌어낸다: redis-topology & lane-<mode>. 승격 시험은
sentinel 없이는 뜻이 없고 cross-slot 시험은 cluster 없이는 뜻이 없다. 하지만 그것을 런타임 가정으로 나타내면
「lane이 시작되지 않았다」가 초록 건너뛰기가 된다. tag로 고르면 실패하면 닫힌 상태가 된다 — 모드가 증명할 수
없는 것은 고르지 않고, 고른 것은 통과해야 한다.
lane은 endpoint에 대해서도 실패하면 닫힌다: host, port, mode(Sentinel lane이면 redis.topology.master도) 없이
redisTopologyTest를 고르면 건너뛰기가 아니라 오류다. 연결하지 않아서 소리 없이 통과하는 topology 시험은
topology 시험이 없는 것보다 나쁘다.
Sentinel lane의 min-replicas-to-write
Sentinel lane은 min-replicas-to-write 1과 min-replicas-max-lag 1을 정한다. 우연히 둔 설정이 아니다. 그것
없이 잰 승격에서는 밀려난 primary가 대체된 뒤에도 11초 동안 +OK로 답했다: 호출자에게 확인해 준 쓰기
2,086개가 버려졌고, 실패한 명령은 정확히 하나였다. 그것을 두고 같은 승격을 재면 쓰기 하나를 잃고 2,020개를
NOREPLICAS로 거절했다. SDK는 그것을 호출자가 대응할 수 있는, 모호하지 않은 확정 실패로 알린다.
확인 응답에 뜻이 있어야 하는 배포는 모두 이것을 정해야 한다. 전체 기록은 docs/redis/support-matrix.md를 본다.
ACL 계정
compose/redis/acl/에는 CommandAccess 수준마다 파일이 하나씩 있다. 일부러 SDK 자신의 규칙보다 좁게 둔다. 그래서
SDK의 실수도 서버가 거절한다 — 계정이 마지막 경계이고, 허가는 그것을 넓히지 않는다.
모든 lane은 모든 데이터 노드에 같은 파일을 읽어 들인다. 계정은 노드마다 강제되므로 「한 노드에 있다」는 topology가 그것을 강제한다는 증거가 아니다.