IP 풀

원문 보기 위키 갱신 2026.10.11

IP 풀 (IP pool)

IP 풀 리소스(IPPool)는 Calico가 엔드포인트 IP를 할당할 것으로 기대하는 IP 주소 컬렉션을 나타내요. 이 문서에서는 IPPool 리소스의 구조와 각 필드의 의미, 그리고 CIDR 중복 검증 같은 동작을 하나씩 살펴봐요.

출처: 문서

본문

IP 풀 리소스(IPPool)는 Calico가 엔드포인트 IP를 할당할 것으로 기대하는 IP 주소 컬렉션을 나타내요.

샘플 YAML

apiVersion: projectcalico.org/v3
kind: IPPool
metadata:
  name: my.ippool-1
spec:
  cidr: 10.1.0.0/16
  ipipMode: CrossSubnet
  natOutgoing: true
  disabled: false
  nodeSelector: all()
  allowedUses:
    - Workload
    - Tunnel
  assignmentMode: Automatic

IP 풀 정의

메타데이터 (Metadata)

필드	설명	허용 값	스키마
name	이 IPPool 리소스의 이름이에요. 반드시 지정해야 해요.	`.`, `_`, `-`를 선택적으로 포함하는 영숫자 문자열	string

스펙 (Spec)

필드	설명	허용 값	스키마	기본값
cidr	이 풀에서 사용할 IP 범위예요. 중복 동작에 대한 자세한 내용은 CIDR 중복 검증을 보세요.	유효한 IPv4 또는 IPv6 CIDR. 서브넷 길이는 최소한 블록 하나를 담을 만큼 커야 해요 (기본적으로 IPv4는 `/26`, IPv6는 `/122`). Link Local 범위인 `169.254.0.0/16` 또는 `fe80::/10`과 겹치면 안 돼요.	string
blockSize	이 풀이 사용하는 할당 블록의 CIDR 크기예요. 블록은 필요할 때 호스트에 할당되고 라우트를 애그리게이션하는 데 쓰여요. 이 값은 풀을 생성할 때만 설정할 수 있어요.	IPv4는 20~~32(포함), IPv6는 116~~128(포함)	int	IPv4 풀은 `26`, IPv6 풀은 `122`.
ipipMode	IPIP를 언제 사용할지 정의하는 모드예요. `vxlanMode`와 동시에 설정할 수 없어요.	Always, CrossSubnet, Never	string	`Never`
vxlanMode	VXLAN을 언제 사용할지 정의하는 모드예요. `ipipMode`와 동시에 설정할 수 없어요.	Always, CrossSubnet, Never	string	`Never`
natOutgoing	활성화하면 이 풀의 Calico 네트워킹 컨테이너에서 Calico IP 풀 바깥 목적지로 보내는 패킷이 마스커레이드돼요.	true, false	boolean	`false`
disabled	true로 설정하면 Calico IPAM이 이 풀에서 주소를 할당하지 않아요.	true, false	boolean	`false`
disableBGPExport (since v3.21.0)	이 IP 풀의 CIDR에서 BGP로 라우트를 내보내는 것을 비활성화해요.	true, false	boolean	`false`
nodeSelector	Calico IPAM이 이 풀에서 주소를 할당할 노드를 골라요.		selector	all()
allowedUses (since v3.21.0)	풀이 특정 타입의 자동 할당에 사용될지 제어해요. 자세한 내용은 아래를 보세요.	Workload, Tunnel, LoadBalancer	list of strings	`["Workload", "Tunnel"]`
assignmentMode	풀이 자동 할당에 사용될지, 아니면 사용자가 직접 요청할 때만 사용될지 제어해요	Automatic, Manual	strings	`Automatic`

SECONDARY: 모든 Calico 컴포넌트가 커스텀 blockSize를 지원하는 버전(최소 v3.3.0)으로 업데이트되기 전에는 커스텀 blockSize를 사용하지 마세요. 구버전 컴포넌트는 이 필드를 이해하지 못해서 잘못된 크기의 블록을 만들어 IP 풀을 망가뜨릴 수 있어요.

허용 용도 (Allowed uses)

워크로드에 자동으로 IP 주소를 할당할 때는 allowedUses 필드에 "Workload"가 있는 풀만 참조돼요. 마찬가지로 터널 디바이스에 IP를 할당할 때는 "Tunnel" 풀만 후보가 돼요.

allowedUses 필드의 조합 옵션은 제한적이에요. 다음 옵션과 옵션 조합만 지정할 수 있어요:

allowedUses: ["Tunnel","Workload"] (기본값)
allowedUses: ["Tunnel"]
allowedUses: ["Workload"]
allowedUses: ["LoadBalancer"]

allowedUses 필드를 지정하지 않으면 구버전 Calico와의 호환성을 위해 ["Workload", "Tunnel"]이 기본값이 돼요. 허용 용도가 전혀 없는 풀을 지정하는 것은 불가능해요.

allowedUses 필드는 새 할당에만 참조돼요. 필드를 바꿔도 이전에 할당된 주소에는 영향이 없어요.

Calico는 특정 IP 주소의 사용을 강제하는 어노테이션을 지원해요. 이 어노테이션은 allowedUses 필드보다 우선해요.

CIDR 중복 검증

기본(API 서버 모드)에서는 기존 풀과 겹치는 CIDR로 IPPool을 만들면 생성 시점에 동기적으로 거부돼요.

네이티브 v3 CRD를 사용할 때는 CIDR 중복 검증이 비동기예요. CIDR가 겹치는 풀은 성공적으로 생성되지만 Disabled 상태 조건을 받아요. IPAM은 비활성화된 풀에서 주소를 할당하지 않아요. CIDR 중복 때문에 비활성화된 풀이 있는지 IPPool 상태를 확인하세요.

IPIP

목적지 IP 주소가 IPIP가 활성화된 IP 풀에 있으면 IP-in-IP를 사용한 패킷 라우팅이 사용돼요. 추가로 ipipMode가 CrossSubnet이면, Calico는 목적지 노드의 IP 주소가 다른 서브넷에 있을 때만 IP-in-IP로 라우팅해요. 각 노드의 서브넷은 노드 리소스에 설정되어 있어요 (calico/node 서비스를 실행할 때 자동으로 판단될 수도 있어요).

배포에서 IP-in-IP를 구성하는 방법에 대한 자세한 내용은 IP-in-IP 구성을 참고하세요.

SECONDARY: ipip가 활성화된 IP 풀에는 natOutgoing을 설정하는 것을 권장해요. ipip를 natOutgoing 없이 활성화하면 Calico를 실행하는 워크로드와 호스트 사이 라우팅이 비대칭이 되고, RPF 검사 실패로 트래픽이 필터링될 수 있어요.

VXLAN

목적지 IP 주소가 VXLAN이 활성화된 IP 풀에 있으면 VXLAN을 사용한 패킷 라우팅이 사용돼요. 추가로 vxlanMode가 CrossSubnet이면, Calico는 목적지 노드의 IP 주소가 다른 서브넷에 있을 때만 VXLAN으로 라우팅해요. 각 노드의 서브넷은 노드 리소스에 설정되어 있어요 (calico/node 서비스를 실행할 때 자동으로 판단될 수도 있어요).

SECONDARY: vxlan이 활성화된 IP 풀에는 natOutgoing을 설정하는 것을 권장해요. vxlan을 natOutgoing 없이 활성화하면 Calico를 실행하는 워크로드와 호스트 사이 라우팅이 비대칭이 되고, RPF 검사 실패로 트래픽이 필터링될 수 있어요.

블록 크기

기본 블록 크기인 IPv4 26, IPv6 122는 64개 주소를 담은 블록을 제공해요. 이렇게 하면 같은 호스트에서 실행되는 워크로드에 주소를 그룹으로 할당할 수 있어요. 주소를 그룹으로 묶으면 호스트 사이, 그리고 다른 BGP 피어와 교환해야 하는 라우트 수가 줄어들어요. 호스트가 블록 안의 모든 주소를 할당하면 추가 블록을 하나 더 할당받아요. 더 이상 사용 가능한 블록이 없으면 호스트는 다른 호스트에 할당된 블록에서 주소를 가져갈 수 있어요. 빌려온 주소에는 특정 라우트가 추가되는데, 이는 라우트 테이블 크기에 영향을 줘요.

블록 크기를 기본에서 늘리면(예: IPv4에서 24를 사용해 블록당 256개 주소) 호스트당 블록 수가 줄고 라우트도 잠재적으로 줄어들어요. 다만 풀 안의 블록 수가 호스트 수와 같거나 더 많도록 유지하도록 노력하세요.

블록 크기를 기본에서 줄이면(예: IPv4에서 28을 사용해 블록당 16개 주소) 호스트당 블록 수가 늘고 그래서 라우트도 잠재적으로 늘어나요. 블록을 호스트들 사이에 더 공평하게 분배할 수 있게 해 준다면 이득이 될 수 있어요.

할당 모드 (Assignment Mode)

IP 풀을 Calico IPAM의 자동 IP 할당에 사용할지 결정해요. Automatic assignmentMode에서는 Calico IPAM이 이 풀에서 자동으로 IP 주소를 할당해요. assignmentMode를 Manual로 설정하면 사용자가 이 풀을 지정하지 않는 한 Calico IPAM이 이 풀에서 IP 주소를 할당하지 않아요.

노드 셀렉터 (Node Selector)

IP 풀 노드 셀렉터를 구성하는 방법에 대한 자세한 내용은 토폴로지 기반 IP 주소 할당 가이드를 읽어보세요.

셀렉터 참조

레이블 셀렉터는 리소스의 레이블을 기준으로 매칭 여부를 판단하는 표현식이에요.

Calico 레이블 셀렉터는 여러 연산자를 지원하고, 불리언 연산자와 괄호를 사용해 더 큰 표현식으로 조합할 수 있어요.

표현식	의미
논리 연산자
`( <expression> )`	`<expression>`이 매칭될 때, 그리고 그때만 매칭돼요. (괄호는 표현식을 묶는 용도로 사용해요.)
`! <expression>`	`<expression>`이 매칭되지 않을 때, 그리고 그때만 매칭돼요. 팁: `!`는 YAML 문자열의 시작 위치에서는 특수 문자예요. YAML 문자열 시작에 `!`를 써야 한다면 문자열을 따옴표로 감싸세요.
`<expression 1> && <expression 2>`	"And": `<expression 1>`과 `<expression 2>` 둘 다 매칭될 때, 그리고 그때만 매칭돼요
`<expression 1> \|\| <expression 2>`	"Or": `<expression 1>` 또는 `<expression 2>`가 매칭될 때, 그리고 그때만 매칭돼요.
매치 연산자
`all()`	스코프 안의 모든 리소스와 매칭해요. 아무 리소스도 매칭하지 않으려면 `!`와 조합해 `!all()`을 만드세요.
`global()`	네임스페이스에 속하지 않는 모든 리소스와 매칭해요. 글로벌 네트워크 셋 같은 글로벌 리소스를 고르는 `namespaceSelector`에서 유용해요.
`k == 'v'`	레이블 'k'와 값 'v'를 가진 리소스와 매칭해요.
`k != 'v'`	레이블 'k'가 없거나, 레이블 'k'의 값이 `v`와 같지 않은 리소스와 매칭해요
`has(k)`	값과 상관없이 레이블 'k'를 가진 리소스와 매칭해요. 레이블 `k`가 없는 파드를 매칭하려면 `!`와 조합해 `!has(k)`를 만드세요
`k in { 'v1', 'v2' }`	레이블 'k'를 가지고 값이 주어진 집합에 속하는 리소스와 매칭해요
`k not in { 'v1', 'v2' }`	레이블 'k'가 없거나, 레이블 'k'의 값이 주어진 집합에 속하지 않는 리소스와 매칭해요
`k contains 's'`	레이블 'k'를 가지고 값이 부분 문자열 's'를 포함하는 리소스와 매칭해요
`k starts with 's'`	레이블 'k'를 가지고 값이 부분 문자열 's'로 시작하는 리소스와 매칭해요
`k ends with 's'`	레이블 'k'를 가지고 값이 부분 문자열 's'로 끝나는 리소스와 매칭해요

연산자 우선순위는 다음과 같아요:

가장 높음: 모든 매치 연산자
괄호 ( ... )
!를 사용한 부정
&&를 사용한 논리곱(conjunction)
가장 낮음: ||를 사용한 논리합(disjunction)

예를 들어 다음 표현식은

! has(my-label) || my-label starts with 'prod' && role in {'frontend','business'}

이렇게 "괄호로 묶여" 있어요:

((!(has(my-label)) || ((my-label starts with 'prod') && (role in {'frontend','business'}))

이 표현식은 다음에 매칭돼요:

"my-label" 레이블이 없는 모든 리소스.
다음 두 조건을 모두 만족하는 모든 리소스:
- my-label 값이 "prod"로 시작하고,
- role 레이블의 값이 "frontend" 또는 "business" 중 하나인 경우.

함께 보기 (See also)

IPReservation 리소스를 사용하면 IP 풀의 일부 구간을 예약해서 자동 IPAM 할당에 사용되지 않게 할 수 있어요.

더 알아보기 (Learn more)

IP 풀의 일부 주소를 예약해 두고 싶다면 IPReservation 리소스 문서를 참고하세요.
IPIP나 VXLAN 모드 구성 방법은 IP-in-IP 구성 가이드에 자세히 나와 있어요.
노드 토폴로지에 따라 IP를 나눠 주고 싶다면 토폴로지 기반 IP 주소 할당 가이드를 보세요.