calicoctl 설치하기

원문 보기 위키 갱신 2026.10.11

Calico 리소스를 관리하고 관리자 기능을 수행할 수 있게 해주는 calicoctl 명령줄 도구를 설치하는 방법을 다뤄요. 바이너리 또는 컨테이너 형태로 어느 워크스테이션에서든 설치할 수 있어요. Calico 정책과 설정 관리, 클러스터 상태 조회 등 많은 기능에 이 도구가 필요해요.

출처: 문서

본문

큰 그림

이 가이드는 Calico 리소스를 관리하고 관리 기능을 수행할 수 있도록 calicoctl 명령줄 도구를 설치하도록 도와줘요.

활용 가치

calicoctl 명령줄 도구는 Calico의 많은 기능을 사용하는 데 필요해요. Calico 정책과 설정을 관리하고, 상세한 클러스터 상태를 조회하는 데 사용돼요.

개념

API 그룹

모든 Kubernetes 리소스는 하나의 API 그룹에 속해요. API 그룹은 리소스의 apiVersion으로 표시돼요. 예를 들어 Calico는 설정을 위해 projectcalico.org/v3 API 그룹의 리소스를 사용하고, 오퍼레이터는 operator.tigera.io/v1 API 그룹의 리소스를 사용해요.

API 그룹에 대한 자세한 내용은 Kubernetes 문서에서 읽을 수 있어요.

calicoctl과 kubectl

projectcalico.org/v3 API 그룹의 Calico API를 관리하려면 calicoctl을 사용하는 것이 좋아요. calicoctl은 이런 리소스에 대해 kubectl에서는 제공되지 않는 중요한 검증(validation)과 기본값 채우기(defaulting)를 제공하기 때문이에요. 하지만 다른 Kubernetes 리소스는 여전히 kubectl로 관리해야 해요.

SECONDARY: kubectl로 projectcalico.org/v3 API 리소스를 관리하고 싶다면 Calico API 서버를 사용할 수 있어요. 또는 네이티브 v3 CRD를 사용하는 경우, kubectl이 API 서버나 calicoctl 없이도 projectcalico.org/v3 리소스를 네이티브 CRD로 직접 관리할 수 있어요.

WARNING: crd.projectcalico.org API 그룹의 리소스는 절대 직접 수정하지 마세요. 이것들은 내부 데이터 표현이며, 직접 수정하면 예상치 못한 동작이 발생할 수 있어요. 리소스 관리 외에도 calicoctl은 IP 풀 사용률 조회, BGP 상태 조회 같은 다른 Calico 관리 작업도 가능하게 해줘요.

데이터스토어

Calico 객체는 두 데이터스토어 중 하나에 저장돼요. etcd 또는 Kubernetes예요. 데이터스토어 선택은 Calico 설치 시점에 결정돼요. 보통 Kubernetes 설치에서는 Kubernetes 데이터스토어가 기본이에요.

calicoctl은 Calico 데이터스토어에 네트워크로 접근할 수 있는 어떤 호스트에서든 바이너리 또는 컨테이너로 실행할 수 있어요. 단계별 안내는 원하는 배포 방식에 해당하는 섹션을 참고하세요.

방법

SECONDARY: 클러스터에서 실행 중인 Calico 버전과 일치하는 calicoctl 버전을 항상 설치하세요.

단일 호스트에 바이너리로 calicoctl 설치하기
단일 호스트에 컨테이너로 calicoctl 설치하기

단일 호스트에 바이너리로 calicoctl 설치하기

탭: Linux

호스트에 로그인하고 터미널 프롬프트를 연 뒤, 바이너리를 설치하려는 위치로 이동하세요.

SUCCESS: PATH에 있는 위치로 이동하는 것을 고려하세요. 예를 들어 /usr/local/bin/이요.

다음 명령어를 사용해 calicoctl 바이너리를 다운로드하세요.

AMD64:

curl -L https://github.com/projectcalico/calico/releases/download/v3.33.0/calicoctl-linux-amd64 -o calicoctl

ARM64:

curl -L https://github.com/projectcalico/calico/releases/download/v3.33.0/calicoctl-linux-arm64 -o calicoctl

PPC64le:

curl -L https://github.com/projectcalico/calico/releases/download/v3.33.0/calicoctl-linux-ppc64le -o calicoctl

파일을 실행 가능하게 설정하세요.
```
chmod +x ./calicoctl
```
SECONDARY: calicoctl의 위치가 PATH에 없다면, 파일을 PATH에 있는 위치로 옮기거나 그 위치를 PATH에 추가하세요. 그러면 위치를 접두사로 붙이지 않고도 실행할 수 있어요.

탭: macOS

호스트에 로그인하고 터미널 프롬프트를 연 뒤, 바이너리를 설치하려는 위치로 이동하세요.

SUCCESS: PATH에 있는 위치로 이동하는 것을 고려하세요. 예를 들어 /usr/local/bin/이요.

다음 명령어를 사용해 calicoctl 바이너리를 다운로드하세요.

ARM64 (Apple Silicon):

curl -L https://github.com/projectcalico/calico/releases/download/v3.33.0/calicoctl-darwin-arm64 -o calicoctl

AMD64 (Intel):

curl -L https://github.com/projectcalico/calico/releases/download/v3.33.0/calicoctl-darwin-amd64 -o calicoctl

파일을 실행 가능하게 설정하세요.
```
chmod +x calicoctl
```
SECONDARY: calicoctl을 처음 사용할 때 cannot be opened because the developer cannot be verified 오류가 나타나면, Applications > System Preferences > Security & Privacy로 이동해 General 탭 하단에서 Allow anyway를 클릭하세요.

SECONDARY: calicoctl의 위치가 PATH에 없다면, 파일을 PATH에 있는 위치로 옮기거나 그 위치를 PATH에 추가하세요. 그러면 위치를 접두사로 붙이지 않고도 실행할 수 있어요.

탭: Windows

다음 PowerShell 명령어를 사용해 calicoctl 바이너리를 다운로드하세요.

SUCCESS: 관리자 권한으로 PowerShell을 실행하고 PATH에 있는 위치로 이동하는 것을 고려하세요. 예를 들어 C:\Windows요.

Invoke-WebRequest -Uri "https://github.com/projectcalico/calico/releases/download/v3.33.0/calicoctl-windows-amd64.exe" -OutFile "calicoctl.exe"

단일 호스트에 컨테이너로 calicoctl 설치하기

calicoctl은 통합 calico/calico 이미지의 일부로 제공돼요. 단일 호스트에 컨테이너로 설치하려면 대상 호스트에 로그인하고 다음 명령어를 실행하세요.

docker pull calico/calico:v3.33.0

컨테이너 안의 바이너리를 실행해 calicoctl을 사용하세요. 예를 들면:

docker run --rm calico/calico:v3.33.0 calicoctl get nodes

다음 단계:

데이터스토어에 연결하도록 calicoctl 설정하기.

더 알아보기 (Learn more)

calicoctl은 클러스터의 Calico 버전과 동일한 버전으로 설치하는 것이 중요해요. projectcalico.org/v3 API 리소스 관리에는 calicoctl이, 일반 Kubernetes 리소스에는 kubectl을 쓴다는 구분도 기억하세요. 설치 후에는 데이터스토어 연결 설정이 다음 단계예요.