Calico 컴포넌트 메트릭 모니터링

원문 보기 위키 갱신 2026.10.11

Calico 컴포넌트 메트릭 모니터링 (Monitor Calico component metrics)

이 튜토리얼은 오픈소스 Prometheus로 Calico의 Felix, Typha, kube-controllers 메트릭을 수집하는 방법을 다뤄요. 시계열 데이터를 기반으로 알림 규칙까지 구성할 수 있어요. 단계별로 따라 하면 Prometheus 대시보드에서 그래프를 그리는 것까지 완료할 수 있어요.

출처: 문서

본문

큰 그림 (Big picture)

Calico 컴포넌트에 맞게 구성된 Prometheus를 사용하면 Calico 상태에 대한 유용한 메트릭을 얻을 수 있어요.

가치 (Value)

오픈소스 Prometheus 모니터링·알림 툴킷을 사용하면 Calico 컴포넌트의 시계열 메트릭을 Prometheus나 Grafana 인터페이스에서 볼 수 있어요.

개념 (Concepts)

Prometheus 알아보기

Prometheus 모니터링 툴은 계측(instrumented)된 잡(job)에서 메트릭을 스크레이프해서 시각화 도구(예: Grafana)에 시계열 데이터로 보여줘요. Calico의 경우 Prometheus가 메트릭을 수집할 수 있는 "잡"은 Felix와 Typha 컴포넌트예요.

Calico Felix, Typha, kube-controllers 컴포넌트 알아보기

Felix는 네트워크 정책을 구현하는 모든 머신에서 실행되는 데몬이에요. Felix는 Calico의 두뇌 역할을 해요. Typha는 Calico 노드와 데이터스토어 사이 트래픽을 확장(scaling)할 수 있게 Felix를 확장하는 선택적인 파드 셋이에요. kube-controllers 파드는 리소스 가비지 컬렉션, 쿠버네티스 API와의 동기화 같은 다양한 컨트롤 플레인 기능을 담당하는 컨트롤러 셋을 실행해요.

Felix, Typha, kube-controllers를 설정해서 Prometheus에 메트릭을 제공하게 할 수 있어요.

시작하기 전에...

이 튜토리얼에서는 다른 입문 튜토리얼을 모두 마쳤고 Calico가 설치된 쿠버네티스 클러스터가 동작하고 있다고 가정해요. 다음 단계는 kubectl 또는 calicoctl 중 하나로 수행할 수 있어요. 사용할 도구에 따라 아래와 같은 사전 준비가 되어 있는지 확인하세요.

탭: kubectl

kubectl 바이너리로 Calico 구성을 수정하려면 클러스터에 Calico API 서버가 있어야 해요. API 서버를 사용하면 projectcalico.org/v3 API 그룹 안의 리소스를 관리할 수 있어요.

SECONDARY: Operator 기반 설치에는 API 서버가 기본으로 포함되어 있어요.

API 서버에 대한 자세한 내용은 이 링크를 사용하세요.

탭: calicoctl

Calico 데이터스토어에 네트워크로 접근할 수 있는 아무 호스트에서 calicoctl을 바이너리 또는 컨테이너로 실행해 projectcalico.org/v3 API 그룹의 Calico API를 관리할 수 있어요.

calicoctl에 대한 자세한 내용은 이 링크를 사용하세요.

방법 (How to)

이 튜토리얼은 Prometheus로 Calico 기본 모니터링을 구현하는 데 필요한 단계를 다뤄요.

메트릭 보고를 활성화하도록 Calico를 구성해요.
Prometheus가 필요로 하는 네임스페이스와 서비스 어카운트를 만들어요.
Prometheus를 배포하고 구성해요.
Prometheus 대시보드에서 메트릭을 보고 간단한 그래프를 만들어요.

1. 메트릭 보고를 활성화하도록 Calico 구성하기

Felix 구성

Felix의 Prometheus 메트릭은 기본적으로 비활성이에요.

SECONDARY: 구성 값 전체 목록은 이 링크에서 볼 수 있어요.

다음 명령으로 Felix 메트릭을 활성화해요.

탭: kubectl

kubectl patch felixconfiguration default --type merge --patch '{"spec":{"prometheusMetricsEnabled": true}}'

아래와 같은 출력이 보여야 해요:

felixconfiguration.projectcalico.org/default patched

탭: calicoctl

calicoctl patch felixconfiguration default  --patch '{"spec":{"prometheusMetricsEnabled": true}}'

아래와 같은 출력이 보여야 해요:

Successfully patched 1 'FelixConfiguration' resource

Felix 메트릭을 노출하는 서비스 만들기

Prometheus는 쿠버네티스 서비스를 사용해 엔드포인트를 동적으로 탐색해요. 여기서는 Prometheus가 모든 Felix 메트릭 엔드포인트를 탐색하는 데 사용할 felix-metrics-svc라는 서비스를 만들어요.

SECONDARY: Felix는 기본적으로 TCP 9091 포트로 메트릭을 공개해요.

탭: Operator

kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  name: felix-metrics-svc
  namespace: calico-system
spec:
  clusterIP: None
  selector:
    k8s-app: calico-node
  ports:
  - port: 9091
    targetPort: 9091
EOF

Calico for Windows를 실행 중이라면 Windows 노드용 서비스도 만드세요:

kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  name: felix-windows-metrics-svc
  namespace: calico-system
spec:
  clusterIP: None
  selector:
    k8s-app: calico-node-windows
  ports:
  - port: 9091
    targetPort: 9091
EOF

기본적으로 Windows 방화벽은 포트 리스닝을 차단해요. Calico가 Prometheus 메트릭 포트의 Windows 방화벽 규칙을 관리하게 하려면 FelixConfiguration에서 windowsManageFirewallRules 설정을 활성화하세요:

kubectl patch felixConfiguration default --type merge --patch '{"spec":{"windowsManageFirewallRules": "Enabled"}}'

자세한 내용은 FelixConfiguration 참조를 보세요. Calico가 관리하게 두는 대신 Prometheus 메트릭 포트의 리스닝을 허용하는 Windows 방화벽 규칙을 직접 추가할 수도 있어요.

탭: Manifest

kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  name: felix-metrics-svc
  namespace: kube-system
spec:
  clusterIP: None
  selector:
    k8s-app: calico-node
  ports:
  - port: 9091
    targetPort: 9091
EOF

Typha 구성

탭: Operator

Operator로 설치한 Calico는 클러스터 규모에 따라 Typha 인스턴스를 한 개 이상 자동 배포해요. 기본적으로 이 인스턴스들의 메트릭은 비활성화되어 있어요.

다음 명령으로 tigera-operator에게 Typha 메트릭을 활성화하라고 지시하세요.

kubectl patch installation default --type=merge -p '{"spec": {"typhaMetricsPort":9093}}'

아래와 비슷한 결과가 보여야 해요:

installation.operator.tigera.io/default patched

탭: Manifest

SECONDARY: Typha 구현은 선택 사항이에요. 클러스터에 Typha가 없다면 Typha 구성 섹션은 건너뛰어도 돼요.

클러스터에 Typha가 있는지 확실하지 않다면 다음 코드를 실행하세요:

kubectl get pods -A | grep typha

결과가 아래에 보이는 것과 비슷하다면 클러스터에서 Typha를 사용 중이에요.

SECONDARY: 아래에 보이는 파드 이름 접미사는 동적으로 생성된 거예요. 여러분의 typha 인스턴스는 다른 접미사를 가질 수 있어요.

kube-system     calico-typha-56fccfcdc4-z27xj                         1/1     Running   0          28h
kube-system     calico-typha-horizontal-autoscaler-74f77cd87c-6hx27   1/1     Running   0          28h

두 가지 방법으로 Typha 메트릭을 Prometheus가 소비하도록 활성화할 수 있어요.

Typha 메트릭을 노출하는 서비스 만들기

SECONDARY: Typha는 기본적으로 TCP 9091 포트로 메트릭을 공개해요. 다만 Amazon yaml 파일로 Calico를 설치했다면 TYPHA_PROMETHEUSMETRICSPORT 환경 변수로 수동 설정되어 있어 이 포트는 9093이 돼요.

탭: Operator

typhaMetricsPort를 설정하면 operator가 이 메트릭을 노출하는 서비스를 자동으로 만들어 줘요. 직접 만들 필요가 없어요.

다음 명령으로 확인할 수 있어요.

kubectl get svc -n calico-system calico-typha-metrics

아래와 비슷한 결과가 보여야 해요:

NAME                   TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)    AGE
calico-typha-metrics   ClusterIP   10.43.164.10   <none>        9093/TCP   39d

탭: Manifest

kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  name: typha-metrics-svc
  namespace: kube-system
spec:
  clusterIP: None
  selector:
    k8s-app: calico-typha
  ports:
  - port: 9093
    targetPort: 9093
EOF

kube-controllers 구성

calico-kube-controllers의 Prometheus 메트릭은 TCP 포트 9094에서 기본으로 활성화되어 있어요.

탭: Operator

operator가 이 메트릭을 노출하는 서비스를 자동으로 만들어 줘요.

다음 명령으로 확인할 수 있어요.

kubectl get svc -n calico-system

아래와 비슷한 결과가 보여야 해요:

calico-kube-controllers-metrics   ClusterIP   10.43.77.57     <none>        9094/TCP   39d

탭: Manifest

kube-controllers 메트릭을 노출하는 서비스 만들기

calico-kube-controllers 메트릭을 Prometheus에 노출할 서비스를 만드세요.

kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  name: kube-controllers-metrics-svc
  namespace: kube-system
spec:
  clusterIP: None
  selector:
    k8s-app: calico-kube-controllers
  ports:
  - port: 9094
    targetPort: 9094
EOF

원한다면 KubeControllersConfiguration 리소스를 수정해서 포트를 바꿀 수도 있어요.

SECONDARY: 이 값을 0으로 설정하면 kube-controllers 파드에서 메트릭이 비활성화돼요.

탭: kubectl

kubectl patch kubecontrollersconfiguration default --type=merge  --patch '{"spec":{"prometheusMetricsPort": 9095}}'

탭: calicoctl

calicoctl patch kubecontrollersconfiguration default  --patch '{"spec":{"prometheusMetricsPort": 9095}}'

2. 클러스터 준비하기

네임스페이스 생성

Namespace는 클러스터 안의 리소스를 격리해요. 여기서는 모니터링 리소스를 담을 calico-monitoring이라는 네임스페이스를 만들어요.

SECONDARY: 쿠버네티스 네임스페이스 가이드는 이 링크에서 볼 수 있어요.

kubectl create -f -<<EOF
apiVersion: v1
kind: Namespace
metadata:
  name: calico-monitoring
  labels:
    app:  ns-calico-monitoring
    role: monitoring
EOF

서비스 어카운트 생성

Prometheus가 Calico에서 정보를 수집하는 데 필요한 권한을 가진 serviceAccount를 제공해야 해요.

SECONDARY: 사용자 역할과 인증에 대한 종합 가이드는 이 링크에서 볼 수 있어요.

kubectl apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: calico-prometheus-user
rules:
- apiGroups: [""]
  resources:
  - endpoints
  - services
  - pods
  verbs: ["get", "list", "watch"]
- nonResourceURLs: ["/metrics"]
  verbs: ["get"]
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: calico-prometheus-user
  namespace: calico-monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: calico-prometheus-user
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: calico-prometheus-user
subjects:
- kind: ServiceAccount
  name: calico-prometheus-user
  namespace: calico-monitoring
EOF

3. Prometheus 설치하기

Prometheus 구성 파일 만들기

ConfigMap을 사용해 Prometheus를 구성하면 원하는 설정을 영구적으로 저장할 수 있어요.

SECONDARY: 구성 파일에 대한 종합 가이드는 이 링크에서 볼 수 있어요.

탭: Operator

kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: prometheus-config
  namespace: calico-monitoring
data:
  prometheus.yml: |-
    global:
      scrape_interval:   15s
      external_labels:
        monitor: 'tutorial-monitor'
    scrape_configs:
    - job_name: 'prometheus'
      scrape_interval: 5s
      static_configs:
      - targets: ['localhost:9090']
    - job_name: 'felix_metrics'
      scrape_interval: 5s
      scheme: http
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - source_labels: [__meta_kubernetes_service_name]
        regex: felix-metrics-svc
        replacement: $1
        action: keep
    - job_name: 'felix_windows_metrics'
      scrape_interval: 5s
      scheme: http
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - source_labels: [__meta_kubernetes_service_name]
        regex: felix-windows-metrics-svc
        replacement: $1
        action: keep
    - job_name: 'typha_metrics'
      scrape_interval: 5s
      scheme: http
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - source_labels: [__meta_kubernetes_service_name]
        regex: calico-typha-metrics
        replacement: $1
        action: keep
    - job_name: 'kube_controllers_metrics'
      scrape_interval: 5s
      scheme: http
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - source_labels: [__meta_kubernetes_service_name]
        regex: calico-kube-controllers-metrics
        replacement: $1
        action: keep
EOF

탭: manifest

kubectl apply -f - <<EOF
apiVersion: v1
kind: ConfigMap
metadata:
  name: prometheus-config
  namespace: calico-monitoring
data:
  prometheus.yml: |-
    global:
      scrape_interval:   15s
      external_labels:
        monitor: 'tutorial-monitor'
    scrape_configs:
    - job_name: 'prometheus'
      scrape_interval: 5s
      static_configs:
      - targets: ['localhost:9090']
    - job_name: 'felix_metrics'
      scrape_interval: 5s
      scheme: http
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - source_labels: [__meta_kubernetes_service_name]
        regex: felix-metrics-svc
        replacement: $1
        action: keep
    - job_name: 'felix_windows_metrics'
      scrape_interval: 5s
      scheme: http
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - source_labels: [__meta_kubernetes_service_name]
        regex: felix-windows-metrics-svc
        replacement: $1
        action: keep
    - job_name: 'typha_metrics'
      scrape_interval: 5s
      scheme: http
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - source_labels: [__meta_kubernetes_service_name]
        regex: typha-metrics-svc
        replacement: $1
        action: keep
    - job_name: 'kube_controllers_metrics'
      scrape_interval: 5s
      scheme: http
      kubernetes_sd_configs:
      - role: endpoints
      relabel_configs:
      - source_labels: [__meta_kubernetes_service_name]
        regex: kube-controllers-metrics-svc
        replacement: $1
        action: keep
EOF

Prometheus 파드 만들기

메트릭을 수집할 권한이 있는 serviceaccount와 Prometheus용 유효한 구성 파일이 준비됐으니, 이제 Prometheus 파드를 만들 차례예요.

kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: prometheus-pod
  namespace: calico-monitoring
  labels:
    app: prometheus-pod
    role: monitoring
spec:
  nodeSelector:
    kubernetes.io/os: linux
  serviceAccountName: calico-prometheus-user
  containers:
  - name: prometheus-pod
    image: prom/prometheus
    resources:
      limits:
        memory: "128Mi"
        cpu: "500m"
    volumeMounts:
    - name: config-volume
      mountPath: /etc/prometheus/prometheus.yml
      subPath: prometheus.yml
    ports:
    - containerPort: 9090
  volumes:
  - name: config-volume
    configMap:
      name: prometheus-config
EOF

클러스터 파드를 확인해서 파드 생성이 성공했고 prometheus 파드가 Running 상태인지 확인하세요.

kubectl get pods prometheus-pod -n calico-monitoring

아래와 비슷한 결과가 나와야 해요.

NAME             READY   STATUS    RESTARTS   AGE
prometheus-pod   1/1     Running   0          16s

4. 메트릭 보기

포트 포워딩 기능으로 prometheus 대시보드에 접근할 수 있어요.

kubectl port-forward pod/prometheus-pod 9090:9090 -n calico-monitoring

http://localhost:9090으로 접속하면 prometheus 대시보드가 보여요. Expression 입력 상자에 felix_active_local_endpoints를 입력하고 execute 버튼을 누르세요. 콘솔 테이블에 모든 노드와 각 노드의 엔드포인트 수가 채워질 거예요.

SECONDARY: Felix 메트릭 목록은 이 링크에서 볼 수 있어요. kube-controllers와 Typha에도 비슷한 목록이 있어요.

Add Graph 버튼을 누르면 그래프에 메트릭이 그려지는 것을 볼 수 있어요.

정리 (Cleanup)

이 섹션은 이 튜토리얼을 따라 하면서 만든 리소스를 제거하는 데 도움을 줘요. 컴포넌트 메트릭 시각화를 위해 Grafana를 배포할 생각이라면 이 단계는 건너뛰세요. 먼저 다음 명령으로 서비스를 제거해요:

탭: Operator

kubectl delete service felix-metrics-svc -n calico-system

Calico for Windows를 실행 중이라면 Windows 노드 서비스도 정리하세요:

kubectl delete service felix-windows-metrics-svc -n calico-system

탭: Manifest

kubectl delete service felix-metrics-svc -n kube-system
kubectl delete service typha-metrics-svc -n kube-system
kubectl delete service kube-controllers-metrics-svc -n kube-system

Calico 구성을 기본 상태로 되돌려요.

탭: kubectl

kubectl patch felixConfiguration default --type merge --patch '{"spec":{"prometheusMetricsEnabled": false}}'
kubectl patch installation default --type=json -p '[{"op": "remove", "path":"/spec/typhaMetricsPort"}]'

탭: calicoctl

calicoctl patch felixConfiguration default  --patch '{"spec":{"prometheusMetricsEnabled": false}}'

마지막으로 네임스페이스와 RBAC 권한을 제거해요.

kubectl delete namespace calico-monitoring
kubectl delete ClusterRole calico-prometheus-user
kubectl delete clusterrolebinding calico-prometheus-user

모범 사례 (Best practices)

Calico 메트릭을 Prometheus로 보내기로 했다면, 네트워크 정책으로 Calico 메트릭 엔드포인트 접근을 제한하는 것이 모범 사례예요. 자세한 내용은 Calico Prometheus 엔드포인트 보안을 보세요.

Prometheus 메트릭을 사용하지 않는다면 보안을 위해 Prometheus 포트를 완전히 비활성화하는 것을 권장해요.

다음 단계 (Next Steps)

Grafana로 메트릭 시각화하기.

더 알아보기 (Learn more)

Felix 메트릭의 전체 목록은 Felix Prometheus 참조에서 확인할 수 있어요.
메트릭 엔드포인트를 네트워크 정책으로 보호하는 방법은 Calico Prometheus 엔드포인트 보안 문서를 참고하세요.
메트릭을 그래프로 시각화하려면 다음 단계인 Grafana 시각화 튜토리얼로 이어가 보세요.