OpenShift HCP 클러스터에 Calico 설치

원문 보기 위키 갱신 2026.10.11

OpenShift Hosted Control Planes(HCP) 클러스터는 컨트롤 플레인이 관리형으로 제공되고, 데이터 플레인은 사용자가 소유한 노드에서 실행되는 구조예요. 이 문서는 HyperShift 미들웨어를 사용하는 HCP 클러스터에 Calico 오픈 소스를 설치하는 절차를 안내해요. HyperShift 공식 문서의 단계를 기본으로 삼되, Calico 설치에 필요한 부분을 보강해서 설명해요.

출처: 문서

본문

큰 그림

OpenShift Hosted Control Planes(HCP) 클러스터에 Calico를 설치해요.

가치

HyperShift 미들웨어를 사용하는 OpenShift Hosted Control Planes(HCP) 클러스터에 Calico를 설치하는 절차를 제공해요. 필요한 곳에는 HyperShift 문서의 단계를 보강해서 설명해요.

방법

시작하기 전에

환경이 Calico 시스템 요구 사항을 충족하는지 확인해요.
Red Hat 계정이 있는지 확인해요. OpenShift 클러스터를 프로비저닝하는 데 필요한 pull secret을 받으려면 Red Hat 계정이 필요해요. 참고로 OpenShift 설치 프로그램은 AWS 리전 중 일부만 지원해요.
AWS에 설치한다면 다음을 준비했는지 확인해요.
- OpenShift 4에 적합하게 구성된 AWS 계정
- AWS 자격 증명 설정
- 로컬 SSH 개인 키를 생성하고 ssh-agent에 추가
HyperShift CLI를 설치하고 HyperShift 문서의 나머지 사전 요구 사항을 모두 충족해요.

호스팅 클러스터 생성

Calico와 함께 OpenShift 클러스터를 배포해요. 이 클러스터가 호스팅 클러스터가 되고, 아래 단계로 배포하는 모든 호스티드 클러스터의 컨트롤 플레인 노드를 여기서 담당해요. 호스팅 클러스터의 kubeconfig 파일 경로로 KUBECONFIG 환경 변수를 설정해요.

export KUBECONFIG=/path/to/kubeconfig

호스팅 클러스터에 HyperShift 오퍼레이터 설치

HyperShift 문서의 HyperShift 오퍼레이터 설치 단계를 따라 해요.

호스티드 클러스터 생성

다음 단계를 따라 Calico를 사용하는 호스티드 클러스터를 만들어요(HyperShift 문서를 살짝 수정한 절차예요).

HostedCluster를 만들고 HostedCluster.spec.networking.networkType을 Other로 설정해요.

SECONDARY: 아래 명령의 변수들을 클러스터, 자격 증명, 환경에 맞는 올바른 값으로 조정했는지 꼭 확인해요.

HOSTED_CLUSTER_NAME=my-os-hosted-cluster
REGION=us-west-2
BASE_DOMAIN=www.example.com
AWS_CREDS="$HOME/.aws/credentials"
PULL_SECRET="$HOME/.secrets/redhat-pull-secret.txt"

hypershift create cluster aws \
  --name $HOSTED_CLUSTER_NAME \
  --node-pool-replicas=3 \
  --base-domain $BASE_DOMAIN \
  --pull-secret $PULL_SECRET \
  --aws-creds $AWS_CREDS \
  --region $REGION \
  --generate-ssh \
  --network-type Other

SECONDARY: 호스티드 클러스터가 Red Hat pull secret으로 인가 문제를 겪는다면(HyperShift 오퍼레이터 파드 로그에 unauthorized: authentication required가 보인다면) OpenShift Container Platform(OCP)의 안정 릴리스 이미지를 사용하고 있는지 확인해요. 이런 이미지는 [https://amd64.ocp.releases.ci.openshift.org]에서 찾을 수 있어요. 예를 들어 --release-image quay.io/openshift-release-dev/ocp-release:4.16.4-x86_64처럼 지정해요.

SECONDARY: OVNSbDb 서비스가 없어서 호스티드 클러스터 설치가 진행되지 않는 HyperShift 미들웨어 이슈를 만난다면, 호스티드 클러스터 리소스를 패치해서 서비스를 추가해요.
HOSTED_CLUSTER_NAME=my-os-hosted-cluster
CLUSTER_NS="clusters"
oc patch -n ${CLUSTER_NS} hostedcluster ${HOSTED_CLUSTER_NAME} --type='json' -p '[{"op": "add", "path": "/spec/services/-", "value": {"service":"OVNSbDb","servicePublishingStrategy": {"type": "Route"}}}]'

호스티드 클러스터가 뜨면 hypershift CLI 도구로 kubeconfig 파일을 생성해요. 호스티드 클러스터용 디렉터리를 따로 만드는 걸 강력히 권장해요. 호스팅 클러스터와 호스티드 클러스터의 설정과 매니페스트가 섞이지 않도록 하는 것이 아주 중요해요.

mkdir my_hosted_cluster && cd my_hosted_cluster
hypershift create kubeconfig > hosted_kubeconfig && export KUBECONFIG=$(pwd)/hosted_kubeconfig

그다음, 호스팅 클러스터의 aws-creds 시크릿을 호스티드 클러스터로 복사해요. 호스팅 클러스터 kubeconfig를 사용해 시크릿을 yaml 파일로 추출해요.

oc get secrets --kubeconfig /path/to/hosting/kubeconfig -n kube-system aws-creds -o yaml > aws-creds.yaml

이어서 호스티드 클러스터에 임포트해요.

oc apply --kubeconfig /path/to/hosted/kubeconfig -f aws-creds.yaml

SECONDARY: 호스티드 클러스터의 kubeconfig 파일이 셸의 KUBECONFIG 환경 변수로 설정되어 있다면 --kubeconfig CLI 인자를 지정할 필요가 없어요.

Calico 설치 매니페스트 다운로드

OpenShift용 Calico 매니페스트를 내려받아요.

mkdir calico
wget -qO- https://github.com/projectcalico/calico/releases/download/v3.33.0/ocp.tgz | \
tar xvz --strip-components=1 -C calico

데이터 플레인 선택 및 구성

OpenShift용 Calico 매니페스트는 eBPF 데이터 플레인을 구성·설치할 준비가 되어 있어요. 아래 eBPF(권장) 탭의 단계가 과정을 안내해요. 다른 데이터 플레인을 구성하고 싶다면 다른 탭을 골라 그 단계를 따라가도 돼요.

Tab: eBPF (권장)

eBPF 데이터 플레인을 구성하려면 다음을 해요.

calico/01-configmap-kubernetes-services-endpoint.yaml 파일에서 KUBERNETES_SERVICE_HOST 값을 설정해요. oc config view 명령으로 클러스터의 server 값을 확인할 수 있어요. 다음 명령은 oc config view 출력에서 URL을 추출해 설정해요.
```
API_SERVER_URL=$(oc config view | sed -n 's/.*server: https:\/\/$[^:]*$.*/\1/p') && \
sed -i "s|^$[^:]*KUBERNETES_SERVICE_HOST: $.*\$|\1\"$API_SERVER_URL\"|" calico/01-configmap-kubernetes-services-endpoint.yaml
```
apiserver DNS를 resolving하기 위해 calico/02-tigera-operator.yaml 파일에 다음 spec.template.spec.dnsConfig.nameservers 블록을 포함해요. AWS 클러스터의 DNS 서버 주소는 169.254.169.253이에요.
```
spec:
  template:
    spec:
      (...)
      dnsConfig:
        nameservers:
        - 169.254.169.253 # AWS DNS server
```

OpenShift Cluster Network Operator에서 kube-proxy를 비활성화해요.

oc patch network.operator.openshift.io cluster --type merge --patch '{"spec":{"deployKubeProxy":false}}'

Tab: Iptables

iptables로 Calico를 설치하려면 다음을 해요.

calico/03-cr-installation.yaml 파일에서 linuxDataplane을 Iptables로 설정해요.
calico/cluster-network-operator.yaml 파일과 calico/01-configmap-kubernetes-services-endpoint.yaml 파일을 제거해요.

다음 명령으로 한 번에 처리할 수 있어요.

sed -i 's/^\(\s*linuxDataplane:\s*\)BPF/\1Iptables/' calico/03-cr-installation.yaml && \
rm -f calico/cluster-network-operator.yaml && \
rm -f calico/01-configmap-kubernetes-services-endpoint.yaml

추가 구성 제공(선택 사항)

설치 시점에 Calico에 추가 구성을 넘겨주고 싶을 수 있어요. 예를 들어 BGP 구성이나 피어 설정 같은 것이요. 설치의 일부로 원하는 Calico 리소스를 담은 Kubernetes ConfigMap을 사용해 구성을 지정할 수 있어요. 추가 구성이 필요 없다면 이 섹션은 건너뛰어도 돼요.

설치 중 Calico 리소스를 포함하려면 calico/02-configmap-calico-resources.yaml 파일을 편집해 자신만의 구성을 추가해요.

SECONDARY: Calico 리소스가 담긴 디렉터리가 있다면 다음 명령으로 파일을 만들 수 있어요.
oc create configmap -n tigera-operator calico-resources \
--from-file=<resource-directory> --dry-run -o yaml \
calico/02-configmap-calico-resources.yaml
최신 버전의 oc에서는 kubeconfig가 설정되어 있거나 실제로 사용하지 않더라도 --server='127.0.0.1:443'을 추가해야 해요.

SECONDARY: calico-resources configmap을 제공했는데 tigera-operator 파드가 Init:CrashLoopBackOff 상태로 뜨지 않는다면, oc logs -n tigera-operator -l k8s-app=tigera-operator -c create-initial-resources로 init 컨테이너의 출력을 확인해요.

Calico 설치 매니페스트 적용

필요한 순서를 지켜가며 설치 매니페스트를 적용해요. 먼저 Tigera Operator를 설치하는 데 필요한 매니페스트를 모두 적용해요.

cd calico/
ls 00* | xargs -n1 oc apply -f
ls 01* | xargs -n1 oc apply -f
ls 02* | xargs -n1 oc apply -f

그다음, 클러스터에 Calico를 설치하는 CustomResource를 적용하기 전에 Tigera Operator가 필요한 CustomResourceDefinitions(CRD)를 만들 때까지 기다려요.

timeout --foreground 600 bash -c "while ! kubectl get crd installations.operator.tigera.io; do sleep 5; done" # wait until CRDs are created by the operator
ls 03* | xargs -n1 oc apply -f

SECONDARY: 해당 접두사의 yaml 파일이 없다면 ls: cannot access '0X*': No such file or directory 오류는 안전하게 무시해도 돼요.

위 명령이 끝나면, 다음 명령으로 구성 요소가 모두 준비됐는지 확인해서 Calico가 설치됐는지 검증할 수 있어요.

oc get tigerastatus

SECONDARY: 더 자세한 정보를 보려면 위 명령에 -o yaml을 추가해요.

다음 단계

추천 - 네트워킹

기본 BGP 네트워킹(캡슐화 없는 풀 메시 노드 간 피어링)을 사용 중이라면, BGP 피어링 구성 문서로 이동해 파드 간 트래픽이 흐르도록 만들어요.
네트워킹 옵션이 확실하지 않거나 캡슐화(오버레이 네트워킹)를 도입하고 싶다면 최적 네트워킹 옵션 결정을 참고해요.

추천 - 보안

Calico 구성 요소 간 통신 보안
호스트에 Calico를 설치해 호스트 보안 확보
Calico 네트워크 정책으로 파드 보안 확보
Calico를 Istio 서비스 메시와 함께 사용한다면 여기서 시작해요: 애플리케이션 계층 정책 활성화

더 알아보기 (Learn more)

HyperShift 기반 HCP 클러스터는 컨트롤 플레인과 데이터 플레인이 분리되어 있어서, 호스팅 클러스터와 호스티드 클러스터의 kubeconfig와 매니페스트를 분리 관리하는 것이 설치 성공의 핵심이에요. networkType을 Other로 지정해 OpenShift 기본 CNI를 건너뛴 뒤 Calico 매니페스트로 데이터 플레인을 완성하는 흐름을 기억해 두면 좋아요.