Neutron과 etcd 사이 재동기화(Resync)

Calico OpenStack 배포에서 Neutron 데이터베이스와 Calico etcd 데이터스토어가 어떻게 일치하는지 다뤄요. 시작 시 자동 실행되는 resync와, 필요할 때 관리자가 직접 실행하는 calico-resync 명령 두 가지 경로를 배워요. 리소스 범위를 좁혀 빠르게 재동기화하는 방법도 소개해요.

출처: 문서

본문

전체 그림

Calico OpenStack 배포에서는 Neutron 데이터베이스가 네트워킹 상태의 원천(source of truth)이고, Calico 드라이버는 Calico에 필요한 부분 — 포트, 서브넷, 보안 그룹 — 을 Calico etcd 데이터스토어에 WorkloadEndpoint, Subnet, NetworkPolicy 리소스로 (인스턴스가 마이그레이션 중인 동안은 LiveMigration 항목까지) 미러링해요.

평상시에는 드라이버가 etcd를 점진적으로 최신 상태로 유지하며, 포트와 보안 그룹이 바뀔 때 Neutron post-commit 훅에서 etcd에 기록해요. resync는 현재 Neutron 상태와 현재 etcd 상태를 읽고 차이를 바로잡는 조정(reconciliation) 작업이에요 — etcd에 빠진 것은 만들고, 어긋난 것은 업데이트하고, Neutron에 더 이상 대응되지 않는 etcd 항목은 삭제하죠. 그 목적은 Neutron 서버가 요청 처리 도중 죽었거나, 업데이트가 일어난 순간 etcd가 잠깐 도달 불능이었던 경우처럼, 점진적 경로로 etcd가 뒤처질 수 있는 드문 상황을 복구하는 거예요.

resync가 실행되는 시점

resync가 일어나는 방법은 두 가지예요:

• 시작 resync(startup resync): Neutron 서버가 시작하거나 재시작할 때 자동으로 실행되는 일회성 resync. 정상적인, 손 댈 필요 없는 메커니즘이고 기본값으로 활성화돼 있어요.

• 온디맨드 resync — 관리자가 calico-resync 명령으로 명시적으로 실행하며, 특정 네트워크·서브넷·포트·보안 그룹으로 범위를 좁힐 수도 있어요.

참고: v3.32까지 릴리스에서는 드라이버가 주기적 resync도 돌렸어요. 대략 30초마다 반복되었고 resync_interval_secs와 resync_max_interval_secs 옵션으로 제어됐죠. 그 주기적 resync는 올바른 메인라인 동작에 결코 필요하지 않았고, 필요한 것처럼 남겨두는 게 오해를 낳았기 때문에 제거됐어요. 관련 설정 옵션은 이제 no-op이며, 기존 neutron.conf가 깨지지 않도록 남겨두기만 했어요. 아래 기존 배포를 위한 업그레이드 노트를 참고하세요.

시작 resync

Neutron 서버가 시작하거나 재시작하면 Calico 드라이버는 전체 리소스 resync를 한 번 수행해요. 시작 때 한 번만 돌리면 충분한 이유는, 이후로는 점진적 post-commit 경로가 etcd를 계속 최신 상태로 유지하기 때문이에요.

시작 resync는 /etc/neutron/neutron.conf의 [calico] 섹션에 있는 startup_resync 옵션으로 제어해요:

거의 모든 배포에서는 startup_resync = always로 두는 게 좋아요. never는 resync 실행 시점을 완전히 직접 통제하고 싶은 경우를 위한 거예요. 예를 들면:

• 원하는 시점에 calico-resync로 수동 조정을 트리거하고 싶은 배포

• Neutron 서버가 여러 개인 배포에서, 그중 하나만 시작 resync를 수행하도록 정하고 싶은 경우. 이때는 선택한 컨트롤 노드에는 always, 나머지에는 never로 설정해요.

참고: 드라이버의 다른 백그라운드 작업(etcd compaction, agent-status 감시, endpoint-status 감시)은 etcd 키를 통해 단일 활성 워커를 동적으로 선출해서 작업이 깔끔하게 페일오버되는 반면, 시작 resync는 이 정적 startup_resync 설정 스위치로 통제돼요. 한 번 실행되고 끝나는 동작이라 자동 페일오버보다 "어디서, 실행할지"에 대한 관리자 수준의 통제가 더 유용해요.

calico-resync 명령

calico-resync는 시작 resync와 같은 resync 로직을 대역 밖(out-of-band)으로, 필요할 때 구동하는 콘솔 스크립트예요. /etc/neutron/neutron.conf와 Neutron 데이터베이스에 접근할 수 있는 Neutron 컨트롤 노드에서 실행하세요.

패키지로 Calico를 설치했다면 calico-resync 명령은 같은 이름의 전용 패키지 calico-resync로 제공돼요. calico-control 패키지를 설치하는 것과 같은 방식으로 각 컨트롤 노드에 설치하세요.

범위 플래그가 없으면 모든 리소스를 전체 resync해요:

calico-resync

기본적으로 /etc/neutron/neutron.conf를 읽어요. 다른 파일을 가리키려면 --config-file을 쓰세요(반복 가능, 계층화된 설정용).

resync 범위 지정

resync를 특정 리소스로 제한할 수 있어요. 전체 resync보다 훨씬 빠르고, 어떤 오브젝트가 주의가 필요한지 알고 있을 때 유용해요:

예를 들어 포트 하나와 그 포트가 참조하는 보안 그룹을 조정하려면:

calico-resync --port <port ID> --include-sgs-for-ports

출력

calico-resync는 stdout으로 JSON ResyncResult를 출력해요. resync된 범위, 전체 ok 플래그, 시작·종료 타임스탬프와 총 소요 시간, 그리고 단계(phase)별 분석이 담겨 있어요. 각 단계는 자체 타이밍과, 리소스 종류별로 이미 올바르던 개수와 etcd에서 만들기·업데이트·삭제가 필요했던 개수의 카운터를 보고해요. endpoints 단계는 WorkloadEndpoint와 LiveMigration 리소스를 합쳐서 다뤄요.

-o PATH / --output PATH 옵션으로 JSON을 파일에 쓸 수도 있어요. 로깅 구성에 따라 oslo.log가 stdout에 다른 줄을 출력해 JSON 파싱을 어렵게 만들 수 있어서, 도구 연동에는 이 방식이 편해요.

예를 들어 포트 3,000개 정도인 배포에서 etcd가 이미 거의 최신 상태였던(워크로드 엔드포인트 하나는 만들고, 하나는 업데이트해야 했던) 전체 resync의 출력은 다음과 같을 수 있어요:

{
  "scope": {
    "all": true,
    "networks": [],
    "subnets": [],
    "ports": [],
    "security_groups": [],
    "include_sgs_for_ports": false
  },
  "phases": {
    "subnets": {
      "total_ms": 11,
      "etcd_read_ms": 3,
      "neutron_read_ms": 7,
      "compare_ms": 1,
      "create_ms": 0,
      "etcd_items": 6,
      "neutron_items": 6,
      "correct": 6,
      "updated": 0,
      "deleted": 0,
      "created": 0
    },
    "policy": {
      "total_ms": 52,
      "etcd_read_ms": 9,
      "neutron_read_ms": 38,
      "compare_ms": 5,
      "create_ms": 0,
      "etcd_items": 40,
      "neutron_items": 40,
      "correct": 40,
      "updated": 0,
      "deleted": 0,
      "created": 0
    },
    "endpoints": {
      "total_ms": 684,
      "etcd_read_ms": 121,
      "neutron_read_ms": 402,
      "compare_ms": 18,
      "create_ms": 143,
      "etcd_items": 2999,
      "neutron_items": 3000,
      "correct": 2998,
      "updated": 1,
      "deleted": 0,
      "created": 1
    }
  },
  "started_at": "2026-06-25T09:14:03.512100+00:00",
  "finished_at": "2026-06-25T09:14:04.271100+00:00",
  "total_ms": 759,
  "ok": true,
  "error": null
}

어떤 단계가 실패하면 ok가 false가 되고, error 필드에 메시지가 담기며, 나머지 단계는 건너뛰어져요.

관측 가능성(Observability)

resync 동안 — 시작이든 온디맨드든 — 드라이버는 조정해야 하는 각 리소스에 대해 INFO 수준 로그를 남겨요. 무엇이 어긋났는지, resync가 왜 개입했는지 정확히 볼 수 있어요:

Resync creating <kind> <name> in etcd
Resync updating <kind> <name> in etcd: old=<existing>, new=<replacement>
Resync deleting <kind> <name> from etcd

etcd 데이터가 이미 Neutron과 일치하는 리소스는 INFO 수준에서는 나열되지 않아요(DEBUG에서만 기록돼요). 그래도 종류별 요약 총계에는 포함돼요. etcd에 쓰기·삭제가 실패하는 경우는 WARNING으로 남아요. 이는 일상적인 조정이 아니라 실제 레이스 상황일 수 있기 때문이에요.

성능과 동시성

resync 코드는 포트별·보안 그룹별 질의를 반복하는 대신 Neutron 상태를 벌크로 읽어요. 덕분에 대규모 resync가 이전 릴리스보다 훨씬 빨라졌어요(수천 개 포트 규모 배포에서 수십 배 빠른 수준). 드라이버는 현대적인 Neutron/SQLAlchemy 데이터베이스 접근 패턴을 사용해서, 예전에 대규모 resync에서 발생할 수 있었던 커넥션 풀과 이벤트 루프 문제 일부를 피해요.

resync는 API 요청과 post-commit 업데이트를 처리하는 Neutron 서버 프로세스와 별개인 자기 프로세스에서 실행돼요. 오래 걸리는 resync가 포트 생성 같은 동적 작업을 실질적으로 막지 않아요. 바쁜 배포에서도 정상적인 Neutron 활동을 멈추지 않고 calico-resync를 실행할 수 있어요.

기존 배포를 위한 업그레이드 노트

v3.32 이하에서 업그레이드하는 경우:

• 설정 변경이 필요 없어요. 드라이버는 이제 기본으로 Neutron 서버 시작 시 resync를 실행하고, 주기적 resync는 더 이상 실행하지 않아요.

• resync_interval_secs와 resync_max_interval_secs는 이제 효과가 없어요. neutron.conf에 그대로 둬도(에러는 나지 않아요) 제거해도 돼요. 이전에 드리프트 복구용으로 주기적 resync에 의존했다면, 시작 resync(기본값)를 쓰고 즉시 조정이 필요할 때 calico-resync를 온디맨드로 실행하세요.

더 알아보기 (Learn more)

OpenStack 연동 전체 그림이 궁금하면 Calico OpenStack 설치 문서를 함께 참고해 보세요. 대규모 배포에서는 범위 지정 옵션으로 필요한 부분만 재동기화하는 습관이 운영 부담을 크게 줄여줘요.