Posts on Riveroverflow

AWS ALB기반의 Gateway API 구축

Mon, 11 May 2026 13:39:24 +0900

AWS Load Balancer Controller는 쿠버네티스 환경에서 Elastic Load Balancer를 관리할 수 있게 해준다.
Ingress, LoadBalancer등의 타입을 지원하며, AWS 상에서는 Application Load Balancer, Network Load Balancer, Classic Load Balancer 등이 프로비저닝된다.

⚙️ 동작방식

Ingress의 경우

동작 순서

1개의 ingress 리소스에 대해, 다음과 같이 동작한다:

Controller가 API Server로부터 ingress 이벤트를 확인한다.
조건 만족 시, AWS 리소스의 생성을 시작한다.
ALB가 새로운 Ingress 리스로 생성된다.
인터넷에 노출되거나(internet-facing), 내부(internal)일 수 있다.
AWS에서 ingress 리소스에 따른 타겟 그룹이 생긴다.
정해진 포트에 따라 리스너가 생성된다. 기본적으로 80 또는 443이 사용된다.
annotation으로 인증서를 붙일 수도 있다.
ingress 리소스에 따라서 rule이 생긴다.
알맞은 Kubernetes Service에 트래픽이 도달하게 된다.

또한, Load Balancer Controller는 다음의 작업도 한다:

k8s에서 ingress가 지워진 경우, 관련 AWS 자원 제거
k8s에서 ingress가 변경 시, AWS 자원 수정
controller가 재시작된 경우, 복구되도록 ingress와 관련된 AWS 자원들을 조합

트래픽 처리

Load Balancer Controller는 두 가지의 트래픽 모드를 지원한다:

Instance mode(기본): ALB에서 Kubernetes Node로 보내서 Service의 NodePort로 보낸다.
IP mode: ALB에서 직접적으로 Kubernetes Pods로 트래픽을 흘린다. CNI가 POD ip에 직접 접근하는 것을 지원해줘야 한다.
- hop 감소로 더 나은 성능을 보인다.
- alb.ingress.kubernetes.io/target-type: ip annotation으로 설정한다.

Gateway API의 경우

다음과 같은 통합 루프가 일어난다:

API Monitoring: Controller가 API Server를 통해 지속적으로 Gateway API 리소스를 모니터링
Queueing: 확인된 리소스들이 내부 큐에 추가된다.
Processing: 각 큐의 요소들에 대해서,
- 연결된 GatewayClass가 관리하는 controllerName인지 확인한다. 즉, GatewayClass리소스의 spec.controllerName이 gateway.k8s.aws/alb이거나, gateway.k8s.aws/nlb인지 확인한다.
- Gateway API 정의는 AWS 리소스의 NLB/ALB Listener, Rule, Target Group, Addon등으로 매핑된다.
- 매핑된 리소스들은 AWS의 실제 상태와 비교된다.
  desired 상태와 다르면, controller는 AWS API를 호출하여 상태를 동기화한다.
Status Updates: 상태를 맞춘 후, Gateway 리소스의 status필드에 상태를 업데이트한다.
이는 로드밸런서 DNS 이름, ARN등 프로비저닝된 AWS 리소스에 대한 실시간 피드백과 Gateway가 승인되고 programmed된 상태인지 알려준다.

NOTE: Gateway API인데, NLB도 왜 지원하나요?
Gateway API는 실제로 L7라우터로만이 아닌, L4라우터를 대신할 수도 있습니다.
즉, type: LoadBalancer의 대체를 할 수도 있습니다.
Gateway별로 서로 다른 레벨의 Route 규칙을 붙일 수 없습니다.
예를 들어, HTTPRoute와 TCPRoute는 같은 Gateway에서 사용될 수 없습니다.

L7 Gateway: HTTPRoute, GRPCRoute

L4 Gateway: TCPRoute, UDPRoute, TLSRoute

Gateway API도 똑같이 Instance mode와 IP mode를 지원한다.

🚀 Load Balancer Controller 설치하기

Helm을 통한 설치

아래 명령으로 repository를 추가한다.

1

helm repo add eks https://aws.github.io/eks-charts

1
2
3
4
5
6
7
8
9


helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
 -n kube-system \
 --version 3.33.0 \
 --set clusterName = <cluster_name> \
 --set region = <aws_region> \
 --set vpcId = <vpc_id> \
 --set serviceAccount.create = true \
 --set serviceAccount.name = aws-load-balancer-controller \
 --set controllerConfig.featureGates.ALBGatewayAPI = true # 중요: ALB Gateway API에 필수

또는, values.yaml에 helm values를 넣고 설치하면 된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# values.yaml
clusterName: <clutser_name>
region: <aws_region>
vpcId: <vpc_id>

serviceAccount:
 create: true
 name: aws-load-balancer-controller

controllerConfig:
 featureGates:
 ALBGatewayAPI: true

1
2
3
4


helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
 -n kube-system \
 --version 3.33.0 \
 -f values.yaml

이외의 values들

위의 helm value들과 별개로, 다음의 값들을 고려할 수 있다.

autoscaling: controller에게 hpa를 제공한다. 변경이 잦다면, 필요할 수도 있다.
enableWafv2: WAF v2와 연동할 수 있게 된다.
enableCertManager: admission webhook에 쓰이는 TLS인증서를 cert-manager로 관리하게 된다.

자세한 건 여기를 참조.

📝 Hands-on Example

ALB Gateway API를 만들어서, L7규칙기반 라우팅을 제공할 것이다.
ACM을 붙여 TLS Termination을 적용하고, WAF ACL 규칙도 적용시키고, S3 access log도 붙여볼 것이다.
또한, 외부에서는 /metrics경로를 접근하지 못하도록 정책도 만들어볼 것이다.

필수 요소

EKS 클러스터
AWS Load Balancer Controller(설치는 위 참조)
- AWS API에 접근하기 위한 IAM Policy를 가진 Role을 IRSA / Pod Identity로 Load Balancer Controller가 Assume해야 함
Gateway API CRD에서 설치 manifest를 받는다. \

추가 요소

Route53 Hosted Zone & ACM Certificate & External-DNS

추가 요소로 분류되어있긴 하지만, 사실상 필수이다.
실제 운영에서는 ALB만으로는 쓰지 않고, 커스텀 도메인을 붙인다.

아래는 Route53 hosted zone 구성 + ACM 인증서를 발급하는 Terraform 코드 예시이다.
AWS 콘솔에서 도메인을 구매했다면, Hosted Zone이 자동으로 생기는데, 그 때에는 import로 가져와야 한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


resource "aws_route53_zone" "main" {
 name = var.root_domain_name
}

resource "aws_acm_certificate" "alb" {
 domain_name = var.root_domain_name
 subject_alternative_names = var.certificate_subject_alternative_names
 validation_method = "DNS"

 lifecycle {
 create_before_destroy = true
 }
}

resource "aws_route53_record" "alb_acm_validation" {
 for_each = {
 for dvo in aws_acm_certificate.alb.domain_validation_options :
 dvo.domain_name => {
 name = dvo.resource_record_name
 record = dvo.resource_record_value
 type = dvo.resource_record_type
 }
 }

 allow_overwrite = true
 zone_id = aws_route53_zone.main.zone_id
 name = each.value.name
 type = each.value.type
 ttl = 60
 records = [each.value.record]
}

resource "aws_acm_certificate_validation" "alb" {
 certificate_arn = aws_acm_certificate.alb.arn
 validation_record_fqdns = [for record in aws_route53_record.alb_acm_validation : record.fqdn]
}

## Variables
variable "root_domain_name" {
 description = "Primary public DNS zone managed in Route 53."
 type = string
 default = "example.com"
}

variable "certificate_subject_alternative_names" {
 description = "Additional DNS names to include in the shared ACM certificate."
 type = list(string)
 default = ["*.example.com"]

 validation {
 condition = length(var.certificate_subject_alternative_names) > 0
 error_message = "At least one subject alternative name must be provided."
 }
}

External-DNS는 여기에서 받을 수 있다.

아래는 Helm values 예시이다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


provider:
 name: aws

serviceAccount:
 create: true
 name: external-dns

# Source 종류는 다음을 참고:
# https://kubernetes-sigs.github.io/external-dns/latest/docs/sources/about/
sources:
 - gateway-httproute

env:
 - name: AWS_DEFAULT_REGION
 value: ap-northeast-2

domainFilters:
 - example.com

policy: upsert-only

registry: txt
txtOwnerId: my-web

필요한 IAM Policy는 아래와 같다.
이 Policy를 IRSA / Pod identity로 적용해주면 된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


{
 "Version": "2012-10-17",
 "Statement": [
 {
 "Effect": "Allow",
 "Action": [
 "route53:ChangeResourceRecordSets",
 "route53:ListResourceRecordSets",
 "route53:ListTagsForResources"
 ],
 "Resource": [
 "arn:aws:route53:::hostedzone/*"
 ]
 },
 {
 "Effect": "Allow",
 "Action": [
 "route53:ListHostedZones"
 ],
 "Resource": [
 "*"
 ]
 }
 ]
}

External DNS는 다음 로직으로 동작한다:

ExernalDNS가 DNS이름 후보를 HTTPRoute등에서 추출
- spec.hostname
- external-dns.alpha.kubernetes.io/hostname
HTTPRoute의 status의 parents로 Gateway 식별
Gateway에서 Route를 Accept했는지 확인
Gateway의 listener와 Route의 정보들 매칭
Gateway.status.addresses[].value들을 확인해서 로드밸런서 주소 확인
DNS레코드 생성

WAFv2 regional ACL

Reginal 스코프의 WAFv2 ACL을 만들어서 ALB에 추가할 수 있다.
여기서는 ACL만 만들고, Association은 만들지 않는다.
만들어진 ACL에 Load Balancer Controller가 association을 만드는 형식이다.

S3 for access logging

ALB의 액세스 로그는 S3에 직접 저장되게 할 수 있다. (Cloudwatch 로그그룹 아님)
다음의 옵션들이 권장된다:

Lifecycle Policy
Block Public Access
KMS암호화(필요 시)

여기서, ALB가 S3에 로그를 쓰기 위해선, 다음의 정책이 S3 버킷에 적용되어야 한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


{
 "Version":"2012-10-17",
 "Statement": [
 {
 "Effect": "Allow",
 "Principal": {
 "Service": "logdelivery.elasticloadbalancing.amazonaws.com"
 },
 "Action": "s3:PutObject",
 "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/prefix/AWSLogs/123456789012/*"
 }
 ]
}

GatewayClass

spec.controllerName에서 gateway.k8s.aws/alb를 선택해야 한다.

1
2
3
4
5
6
7


# GatewayClass.yaml
apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
 name: aws-alb-gateway-class
spec:
 controllerName: gateway.k8s.aws/alb

LoadBalancerConfiguration

LoadBalancerConfiguration은 AWS Load Balancer Controller를 설치하면 이용할 수 있는 CRD로, AWS ELB의 추가 설정을 세팅할 수 있다.
Gateway 리소스에서는 Gateway API 스펙에 맞는 옵션들을 붙이지만, 여기서는 실제 AWS-specific한 내용들이 들어간다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


apiVersion: gateway.k8s.aws/v1beta1
kind: LoadBalancerConfiguration
metadata:
 name: alb-config
 namespace: kube-system
spec:
 # 외부 퍼블릭 IP를 가질지, 내부 IP를 가질지
 scheme: internet-facing
 ipAddressType: ipv4
 # 인증서 정보 추가
 listenerConfigurations:
 - protocolPort: HTTPS:443
 defaultCertificate: <ARN of ACM Certificate>
 # sslPolicy에 대해서는 다음을 참고: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/describe-ssl-policies.html
 sslPolicy: ELBSecurityPolicy-TLS13-1-2-2021-06
 # WAF 추가 (regional WAFv2 ACL의 arn을 추가)
 wafV2:
 webACL: <ARN of wafv2 regional web acl)
 # 로드밸런서가 S3 에 access 로깅을 하도록 설정
 loadBalancerAttributes:
 - key: access_logs.s3.enabled
 value: "true"
 - key: access_logs.s3.bucket
 value: <s3 bucket name>
 - key: access_logs.s3.prefix
 value: ""
 # 어느 subnet에 붙을지에 대해 사용
 loadBalancerSubnets:
 - identifier: <subent-id>

loadBalancerSubnets가 비어있다면, AWS Subnet은 Tag로 다음의 값을 가져야 한다:

Public Load Balancer인 경우(internet-facing): “kubernetes.io/role/elb” = “1”
Private Load Balancer인 경우(internal) “kubernetes.io/role/internal-elb” = “1”

Gateway

Gateway에서는 GatewayClass의 이름을 참조해야 한다.
또한, LoadBalancerConfiguration의 이름을 참조하여 해당 로드 밸런서의 추가 옵션을 이용할 수 있다.
Gateway 리소스가 생기면, 실제 AWS ELB가 프로비저닝되며, Listener에 매핑된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
 name: aws-alb-gateway
 namespace: kube-system
spec:
 # GatewayClass의 이름을 참조해야 함
 gatewayClassName: aws-alb-gateway-class
 # ALB의 추가 옵션을 참조하여 이용 가능
 infrastructure:
 parametersRef:
 kind: LoadBalancerConfiguration
 name: alb-config
 group: gateway.k8s.aws
 listeners:
 - name: http
 protocol: HTTP
 port: 80
 hostname: www.example.com
 allowedRoutes:
 namespaces:
 from: Selector
 selector:
 matchLabels:
 # namespace의 이름이 my-web이여야 함
 kubernetes.io/metadata.name: my-web
 - name: https
 protocol: HTTPS
 port: 443
 hostname: www.example.com
 allowedRoutes:
 namespaces:
 from: Selector
 selector:
 matchLabels:
 kubernetes.io/metadata.name: my-web

HTTPRoute

HTTPRoute는 실제 Rule과 Target Group으로 매핑된다.
여기서는 두 개의 Rule이 있는데, 하나는, /metrics요청이 외부에서 오면, 차단시키는 것이다.
이는 아래에서 더 자세히 다룰 것이다.
두 번째의 Rule은 루트 경로 (/)에 대해 웹 서버로 포워딩한다.
여러 prefix에 매칭되는 경우, PathPrefix는 더 상세한 (more specific) 경로가 우선 선호된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
 name: my-web
 namespace: my-web
 labels:
 app: my-web
 app.kubernetes.io/name: my-web
spec:
 # Gatway의 리스너와 매핑
 parentRefs:
 - name: my-alb-gateway # Gateway 이름
 namespace: kube-system
 sectionName: http # Listener 이름
 - name: my-alb-gateway
 namespace: kube-system
 sectionName: https
 # 받고자 하는 hostname. 여기서의 hostname으로 External-DNS가 레코드를 생성함.
 hostnames:
 - www.example.com
 rules:
 - matches:
 - path:
 type: PathPrefix
 value: /metrics
 filters:
 - type: ExtensionRef
 extensionRef:
 group: gateway.k8s.aws
 kind: ListenerRuleConfiguration
 name: deny-metrics
 - matches:
 - path:
 type: PathPrefix
 value: /
 # 라우팅할 service 이름
 backendRefs:
 - name: my-web
 port: 80

ListenerRuleConfiguration

아래는 /metrics가 연결하는 Rule로, 고정된 403에러를 응답하도록 한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: gateway.k8s.aws/v1beta1
kind: ListenerRuleConfiguration
metadata:
 name: deny-metrics
 namespace: my-web
spec:
 actions:
 - type: "fixed-response"
 fixedResponseConfig:
 statusCode: 403
 contentType: "text/plain"
 messageBody: "Forbidden for public access"

TargetGroupConfiguration

타겟 그룹에 대해 ELB는 헬스 체크가 필요하다.
헬스 체크 엔드포인트를 넣는다.
또한, Ingress에서 annotation으로 IP인지, Instance인지를 정했듯이, targetType으로 대상을 정한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


apiVersion: gateway.k8s.aws/v1beta1
kind: TargetGroupConfiguration
metadata:
 name: my-web
 namespace: my-web
spec:
 targetReference:
 group: ""
 kind: Service
 name: my-web
 defaultConfiguration:
 # Pod IP에 직접 라우팅
 targetType: ip
 healthCheckConfig:
 healthCheckPath: /helathz/
 healthCheckProtocol: http
 matcher:
 httpCode: 200-399

🌐 결과 예시

아래는 설정들을 적용한 뒤의 Load Balancer Controller가 생성한 리소스 맵의 예시이다.

타겟 그룹에서 healthy한 파드가 없는 이유는 스크린샷 당시에 워커 노드를 모두 제거해서 그런데,
healthy한 타겟이 있는 경우, Pod IP들이 각 타겟 그룹에서 보인다.
프로젝트 당시 편의를 위해 Grafana, ArgoCD등도 퍼블릭으로 노출했었다.

Route53에서도 레코드가 추가된 것을 볼 수 있다.

버킷의 S3 acceess log도 잘 쌓이는 것을 볼 수 있다.

Referenes

Karpenter: Kubernetes의 효율적인 Node Autoscaler

Fri, 01 May 2026 16:34:04 +0900

❓ Karpenter 란?

Karpenter는 cloud-based의 쿠버네티스 환경에서 노드를 자동 확장해주는 오픈 소스 도구이다.
주로 Amazon EKS에서 쓰이며, 가장 권장되는 방식이다.
AWS상에서 EKS를 쓰지 않는 쿠버네티스에서도 동작하지만, 권장되지는 않는다.
Karpenter는 AKS나 Alibaba Cloud등, 다양한 다른 클라우드에서도 사용될 수 있다.

Karpenter는 다양한 이점이 있다:

Automatic node scaling: 스케줄되지 못한 pod가 있으면, Karpenter는 새로운 노드를 프로비저닝하여 pod가 스케줄링될 수 있도록 한다.
또한 더 이상 쓰이지 않는 노드 등을 정리하기도 한다.
Cost efficiency: Karpenter는 pod의 자원 요구량과 노드의 자원들을 종합하여 가장 비용 효율적인 노드 사용으로 맞춘다. (bin-packing)
Speed: Karpenter는 전통적인 EKS에서의 오토스케일 방식인 Cluster Autoscaler보다 빠르다.

EKS에서 Auto Mode를 사용하면, AWS가 Karpenter를 자동으로 관리해준다.
그러나, EKS Auto Mode자체로 추가 비용이 든다는 것을 알아야 한다.

🚀 동작 방식

Provisioning

Karpenter는 Kubernetes가 부적절한 클러스터 스펙으로 pod를 스케줄하지 못할 때, 새 노드를 프로비저닝 한다.

프로비저닝의 단계는 다음과 같다:

Karpenter는 지속적으로 스케줄링 되지 못하거나 대기 중인 pod들을 조회한다.
Karpenter는 어떻게 노드를 생성할지에 대한 EC2NodeClass와 같은 NodeClass를 참조하는 NodePool을 적절히 선택한다.
Karpenter는 NodeClaim을 만들어 새로운 EC2 인스턴스를 생성하도록 AWS에 요청한다.
새로운 EC2 인스턴스는 워커 노드로써의 초기화 작업을 진행한다.
워커 노드가 새로 합류하며, pod는 스케줄될 수 있다.

Disruption

또한, 노드 제거에 관한 작업도 진행한다. 자동으로 제거할 노드를 찾아서, 필요시에는 대체 노드를 생성하기도 한다.
여러 이유로 제거가 일어날 수 있다:

Drift
- NodePool또는 NodeClass의 설정 변경
Consolidation
- 노드가 비어있음
- 노드가 거의 사용되지 않음
- 더 저렴한 노드에서 실행될 수 있음
Expiration
- NodePool에서 정해진 expireAfter와 같은 유효기간이 지난 경우
Interruption
- AWS가 인터럽트 이벤트를 보낸 경우

이중에서 drift로 인한 노드 제거는 클러스터의 일관된 상태를 유지하기 위해 가장 우선시된다.
제거 플로우는 다음의 다이어그램처럼 된다:

Disruption Controller

Pod들이 종료될 수 있는지 확인
Disruption budget을 확인(NodePool의 spec에 있는데, 너무 자주 제거되지 않기 위한 제한이다.)
스케줄링 시뮬레이션으로 pod들이 재배치될 수 있는지 예측
karpenter.sh/disrupted:NoSchedule taint 를 추가하여 새로운 스케줄링이 되는것을 차단
대체 노드 필요시, NodeClaim을 만들어서 추가
노드 제거. Termination Controller가 이후 흐름을 제어

Termination Controller

DeletionTimestamp가 노드에 설정되고, Finalizer도 설정되어 노드 제거가 블록됨
karpenter.sh/disrupted:NoSchedule taint 추가
Pod들이 Kubernetes Eviction API를 통해 PDB를 준수하면서 제거됨
모든 VolumeAttachemtns가 제거되었는지 확인
노드의 NodeClaim과 EC2 인스턴스 제거
Finalizer제거
노드 제거 완료

왜 Disruption이 두 단계로 나뉘는가
Karpenter-managed노드가 여러 방법으로 제거될 수 있는데(ex. kubectl delete node <node-name>),
그러한 방식들의 제거들 모두 제거 과정에서 Graceful Shutdown이 필요하여 Termination 단계는 다른 곳에서도 재사용되어야 한다.
그리고 이것이 karpenter.sh/disrupted:NoSchedule taint를 붙이는 과정이 둘 다 있는 이유이다.

Interruption

Interruption은 AWS 이벤트에 의한 노드 종료이다.
이벤트가 나면, Karpenter는 영향을 받는 노드의 제거작업을 실시한다.

다음의 이벤트들이 잡힐 수 있다:

Spot 인스턴스 회수
유지보수 이벤트 등의 주기적인 이벤트
인스턴스 종료 / 중지 / 헬스 체크 실패

다음의 과정을 따른다:

EventBridge rule이 AWS 이벤트를 수신한다.
이벤트 메시지가 SQS queue로 보내진다.
Karpenter는 주기적으로 SQS queue에 폴링한다.
이벤트가 감지되면, 해당 노드를 제거하는 프로세스를 진행한다.

Spot 인스턴스의 경우, 2분 내로 노드가 회수된다. Karpenter는 동시에 대안이 되는 노드를 프로비저닝 진행한다.
AWS는 Spot 재조정 추천 이벤트를 제안하지만, 그에 대한 기존 노드 정리 등의 작업이 자동으로 일어나지 않는다.
이 기능을 켜기 위해선, 아래 flag로 Karpenter가 구동되어야 한다:

1

--interruption-queue=<queue-name>

🍪 Karpenter를 위해 필요한 것들

Karpenter를 설치하기 전에, AWS 리소스에 대한 권한 설정이 필요하다:

IAM role for Karpenter
- Karpenter가 AWS API에 클라우드 자원에 대해 요청할 수 있어야 한다.
IAM role for Karpenter-provisioned nodes
- Karpenter 워커 노드들이 받는 IAM Role
Subnets for Karpenter-provisioned nodes
- 각 서브넷은 karpenter.sh/discovery 태그가 필요하다.
Security groups for Karpenter-provisioned nodes
- 각 보안그룹은 karpenter.sh/discovery 태그가 필요하다.
EKS access entry for Karpenter-provisioned nodes
- Access entry 타입이 EC2_LINUX or EC2_WINDOWS여야 한다.
Optional: SQS queue
- Interruption handling이 필요하다면, 생성되어야 한다.
Optional: EventBridge rule and target
- 이벤트들을 수신받기 위해 필요하다.

아래의 IaC참고자료들을 보면, IAM Policy를 어떻게 설정하는지 알기 좋을 것이다.

📊 Helm으로 설치

Karpenter는 공식 Helm chart를 통해 쉽게 설치될 수 있다.

1
2
3
4
5
6
7
8


helm upgrade --install karpenter oci://public.ecr.aws/karpenter/karpenter \
 --version <KARPENTER_VERSION> \
 --namespace <KARPENTER_NAMESPACE> \
 --create-namespace \
 --set "settings.clusterName=<CLUSTER_NAME>" \
 --set "settings.interruptionQueue=<INTERRUPTION_QUEUE_NAME>" \
 --set "settings.enableZonalShift=<ENABLE_ZONAL_SHIFT>" \
 --wait

주요 파라미터는 아래와 같다:

settings.clusterName: EKS cluster의 이름
settings.interruptionQueue: 인터럽션 핸들링을 위한 SQS queue.
settings.enableZonalShift: Zonal shift를 활성화

⚙️ 구성 예시

NodePool

아래는 간단한 NodePool예시이다.
Karpenter를 사용하면 NodePool과 그에 대응되는 EC2NodeClass와 같은 NodeClass들을 참조해야 한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
 name: default
spec:
 # Priority of this NodePool.
 # A higher weight gives the NodePool higher scheduling priority.
 weight: 10

 template:
 spec:
 # Node requirements
 requirements:
 - key: kubernetes.io/arch
 operator: In
 values: ["amd64"]

 - key: kubernetes.io/os
 operator: In
 values: ["linux"]

 - key: karpenter.sh/capacity-type
 operator: In
 values: ["spot", "on-demand", "reserved"]

 - key: karpenter.k8s.aws/instance-category
 operator: In
 values: ["c", "m", "r"]

 - key: karpenter.k8s.aws/instance-generation
 operator: Gt
 values: ["2"]

 # Reference to the EC2NodeClass
 nodeClassRef:
 group: karpenter.k8s.aws
 kind: EC2NodeClass
 name: default

 # Node expiration time
 expireAfter: "720h"

 limits:
 # Maximum CPU capacity that this NodePool can provision
 cpu: 64

 disruption:
 # If set to WhenEmptyOrUnderutilized, Karpenter may remove or replace
 # empty or underutilized nodes to reduce cost.
 #
 # If set to WhenEmpty, Karpenter only consolidates nodes that do not
 # have any workload pods.
 consolidationPolicy: WhenEmptyOrUnderutilized

 # The amount of time Karpenter waits before consolidating a node
 # after a pod has been added or removed.
 consolidateAfter: 1m

NodeClass

아래는 EC2NodeClass 예시이다.

EC2NodeClass는 IAM role, AMI selection, Subnet, Security Group, ec2 tag등의 설정들이 담겨있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


apiVersion: karpenter.k8s.aws/v1
kind: EC2NodeClass
metadata:
 name: default
spec:
 # You must specify either `role` or `instanceProfile`.
 role: <NODE_ROLE_NAME>

 # AMI selection
 amiSelectorTerms:
 - alias: al2023@latest

 # Subnet discovery
 subnetSelectorTerms:
 - tags:
 karpenter.sh/discovery: <CLUSTER_NAME>

 # Security group discovery
 securityGroupSelectorTerms:
 - tags:
 karpenter.sh/discovery: <CLUSTER_NAME>

 # Tags added to EC2 instances created by Karpenter
 tags:
 ManagedBy: "Karpenter"

🧑‍🔬 노드 확장 테스트

Karpenter를 테스트하기 위해, 워크로드들을 스케줄시켜보자.
아래명령어는 cpu “500m"을 요구하는 nginx deployment의 replica를 10개 띄우는 명령이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


cat <<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
 name: nginx
 labels:
 app: nginx
spec:
 replicas: 10
 selector:
 matchLabels:
 app: nginx
 template:
 metadata:
 labels:
 app: nginx
 spec:
 containers:
 - name: nginx
 image: nginx:latest
 resources:
 requests:
 cpu: "500m"
EOF

다음의 명령으로 확장되는 상태를 간단히 볼 수 있다

1
2


kubectl get pods -w
kubectl get nodes -w

새로운 EC2 인스턴스에서 tag가 EC2NodeClass에 쓰인 것과 같은 tag를 가진 것을 볼 수 있다.

1

ManagedBy: Karpenter

📚 References

Karpenter - documentations

CKA(Certified Kubernetes Administrator) 후기 (2026)

Sun, 19 Apr 2026 09:30:00 +0900

작년 말에 프로그래머스에서 얼리버드 할인으로 약 27~8만원에 바우처를 구매했는데, 올해 내로 모두 응시할 계획이고, 우선 CKA를 먼저 준비했다.

ℹ️ 시험 정보

CKA(Certified Kubernetes Administrator)

주관: Linux Foundation
시험 내용 및 범위: Kubernetes 를 다루며 문제를 해결하는 Performance-based 시험
- Storage: 10%
- Troubleshooting: 30%
- Workloads & Scheduling: 15%
- Cluster Architecture, Installation & Configuration: 25%
- Services & Networking: 20%
시험 시간: 120분
Kubernetes 버전: v1.35 (2026. 04. 18기준, 보통 마이너 버전이 출시되고 1~2개월 이후에 시험버전이 업데이트)
비용: $445
- 구매 시, 1년 이내로 시험을 신청할 수 있음
- 1번의 재기회 제공
- 정가에 구매하지 말고, 쿠폰을 통한 할인을 노리는 것 권장
시험 환경: 온라인, PSI Secure browser 사용, Xfce 기반 Linux 호스트에서 문제별 SSH접속
- 공간 및 카메라:
  - 방 안에서 혼자 응시해야 함
  - 아이, 어른, 동물을 포함한 아무도 출입할 수 없음
  - 조용하고 정숙한 환경이어야 함
  - 시험 중 입을 가릴 수 없음
  - 벽에는 인쇄물이 붙어있지 않아야 함
    - 그림 등의 액자는 허용
    - 화이트보드가 벽에 붙어있는 경우, 아무 내용이 없어야 함
  - 책상 밑에는 아무 것도 없어야 함
  - 시험에 필요한 컴퓨터를 제외하고 다른 물건들은 치워야 하며, 시험 중 손에 닿을 수 없어야 함
  - 이어폰 착용 불가
  - 손목에도 아무 것도 찰 수 없음
  - 라벨이 없는 투명한 물병에 담긴 물은 반입가능
- 시험 장비
  - 지원 운영체제: 최신 Windows 10 또는 11 / MacOS / Linux(Ubuntu only)
  - PSI 브라우저 이외에 다른 프로세스 실행 불가(웹 브라우저, 노트앱 등)
  - 마이크, 웹캠을 사용할 수 있어야 함
  - 안정적인 네트워크 환경 권장
  - 회사 장비가 아닌 개인 PC 및 노트북 권장
  - 방화벽 등에 대한 제약이 없는 네트워크 권장
  - 15인치 이상의 모니터 권장
  - 추가 모니터를 사용할 수 없음
- 이외 추가적인 제약들이 있을 수 있음(자세한건 Linux Foundtation 에서 직접 확인)
신분증:
- 신분증에 사진이 있어야 함
- 영문 이름과 시험 등록 이름이 같아야 함
- 여권, 국제 운전면허증 등..

📖 시험 준비

총 준비 기간은 3주이다. 하루 평균 1~2시간 정도 투자한 것 같다.
강의는 Udemy - Certified Kubernetes Administrator (CKA) with Practice Tests를 봤고, 강의에서 같이 제공되는 KodeKloud의 기출문제들도 섹션마다 강의를 보고 바로 풀었다.
강의는 전반적으로 만족스럽다. 설명도 친절하게 잘 해주며, 환경을 재현하기 힘들더라도 문제 상황을 바로 제공해주니 학습하기 편했다.
또한, CKA 시험에만 중요한 게 아닌, 다른 배경 지식들도 한 번씩 설명해줘서 알던 내용들은 복습이 되고, 모르는 내용들도 쉽게 배울 수 있었다.

시험 이틀 전에는 강의와 연계된 KodeKloud에서 제공되는 Lightning Labs와 Mock Exam을 풀었고,
시험 전날에는 시험 등록 시에 제공되는 Killer.sh의 2개의 모의고사들을 풀었다.

시험 당일에는 아침에 걸어가면서 정리한 오답노트들을 다시 읽었다.

✏️ 시험 응시

조건이 빡빡하기에, 집에서 응시하기에는 현실적으로 힘들 것 같았다.
그래서 인터넷의 다른 후기들처럼 스터디카페에서 스터디룸을 미리 예약해서 시험을 봤다.
스터디룸 예약을 09:00 ~ 12:00으로 잡고, 시험 예약을 09:30 ~ 11:30으로 해놓으니 딱 적절했다.

시험 환경에는 30분 전부터 입장가능해서 미리 들어가 있으면 일찍 주변 환경 점검을 할 수 있고, 바로 시험을 볼 수 있다.
환경 점검이 시작되고, 신분증 확인 먼저 했다. 다른 후기에서는 시험 등록에서 미리 사진으로 등록되면 신분증 확인은 건너뛴다고 하던데, 나의 경우에는 한번 더 확인하였다.
이후 주변 환경을 보여주는데, 책상 아래까지 꼼꼼히 노트북 웹캠으로 보여줬다.
스마트폰으로도 QR을 연결하면 시험 환경을 보여주는 데 잠깐 활용할 수 있다고 한다.
마지막으로, 스마트폰을 치우는 모습을 보여주고, 손목과 귀를 돌리면서 보여준 뒤, 시험을 시작했다.
노트북 거치대와 무선마우스 사용가능 여부를 묻자, 사용 가능하다고 하였다.

이후, 문제를 풀었다.
문제 난이도는 KodeKloud보다는 조금 어렵고, Killer.sh보다는 쉬웠다.
보통 Killer.sh에서 통과할 정도라면, 시험에는 안정권이라고 한다.
커뮤니티를 봐서는 Killer.sh에서 불합격임에도 시험을 통과하는 경우가 꽤 있는 듯 하다.

문제는 자유롭게 돌아다닐 수 있으며, flag를 세우면 리스트에서 마킹되어 다시 검토하기 편하게 되어있다.
문제의 맨 위에는 관련 문서 링크를 제안해주고, 접속해야 할 SSH 정보도 바로 복사-붙여넣기 가능하다.
본문은 시나리오를 설명하는 context와 해야하는 일인 task로 나뉜다.
일부 문제는 맞게 풀었는지 검증하는 테스트 명령이 있다. 그러나, 이게 정상 동작한다고 해서 정답인건 아니다. 예를 들면 namespace불일치로 인해 테스트는 성공하나, 오답처리될 수 있다.

vscodium이 사용가능하며, 플러그인은 설치할 수 없다.
나는 그냥 터미널 + vim을 이용했는데, vsc기반의 환경을 선호한다면 사용하는 것도 좋아보인다.

🚀 시험 결과

24시간 뒤, 결과가 나온다!
시험에서 namespace를 잘못한게 기억이 나서 크게 실점받을걸 예상했지만 합격 자체에 대해서는 Killer.sh에서 이미 합격점이었기에, 걱정은 없었다.
점수는 76%를 받았는데, 솔직히 스스로의 기대치에는 미치지 못했다.
어쨌든 합격을 한게 중요하므로 아쉬움은 뒤로하기로 했다. (그리고 2년뒤에 어차피 또 봐야한다 ㅎㅎ..)

자격증은 PDF로 다운받을 수 있다.
또한 Credly에서 Open Badge를 발급받을 수 있다.

🍕 최신 정보 (2026. 04) 및 시험에 대한 팁

다른 과거의 후기들을 보면, alias 및 자동완성 설정을 쉘에서 해놓으라고 하는데, 이제는 할 필요가 없다.
base host에서 ssh를 통해 문제마다 다른 환경에 옮겨다녀야 하며, alias k="kubectl", 자동완성이 이미 세팅되어있다.
과한 alias설정은 문제마다 환경이 옮겨지므로 거의 의미가 없다(ex. kgpoy = kubectl get pod -o yaml).
그냥 기본 세팅대로 하면 된다.

아래는 신유형이라 문제로 나올 가능성이 크다:

Kustomize
Helm
Gateway API
CustomResourceDefinition(CRD)

이외 시험에 대한 팁은 여러 가지 있다:

명령형으로 작업하고 --dry-run=client -o yaml를 적극 활용하는게 좋다.
KodeKloud환경 연습을 할 때도, 강의 자료 및 노트, 개인 메모를 참고하지 말고 시험처럼 공식 문서를 활용하자.
Kubernetes에 필요한 지식을 보는 시험이기에, 이외의 것들은 친절히 알려준다.
- ex. nginx 설정을 어떻게 수정해야 하는지, sidecar 컨테이너에서 어떤 명령어를 써야 하는지
하지만, 명령어를 잘 알수록 좋다. 예를 들면:
- k get no <nodename> -o yaml | grep -A10 "taints": 노드의 taints 아래 10줄까지 출력
- journalctl -u kubelet: kubelet 로그확인
- openssl x509 -noout -text -in <cert-file>: 인증서 정보 보기
- kubeadm token create --print-join-command: join 토큰생성 + 워커노드 join 명령어까지 생성
또한, crictl, yq 및 kubectl의 jsonpath, custom header를 익혀두는 것 또한 도움이 될 수 있다.
문제를 잘 읽고, namespace혼동이 없게 하자. 사소한 표현 하나하나가 서브태스크이거나 조건일 수 있다.
복사-붙여넣기를 적극 활용하자. 리소스 이름과 같은 것들을 복붙하여 오타를 줄일 수 있다.
- 브라우저는 Ctrl + <C/V>, 터미널은 Ctrl + Shift + <C/V>.

🛏️ 시험 후기 및 마무리

CKA를 취득했지만, Kubernetes에 대해 마스터가 된 것은 아니라는 것을 알아야 한다.
여전히 부족하며, 앞으로 배워야 할 것들이 많다.
그저 훈련장에서 공을 리프팅하고 드리블하는 걸 익혔을 뿐, 실제 경기에서 활약하는 것이 중요하다.

그래도 시험을 준비하며 Kubernetes에 대해 더 많은 것을 배웠고, 클러스터 조작에 대한 기초체력이 크게 향상된 것은 사실이다.
아직 CKAD, CKS 의 바우처를 가지고 있어서, 이것들도 올해 볼 생각이다.

커스텀 Terraform module로 EKS 클러스터 구축

Tue, 14 Apr 2026 23:43:24 +0900

🌯 Introduction

작년 여름에 K-DT에서 Amazon EKS를 쓴 경험이 있는데, 내가 클러스터를 구축하고 관리하지는 않았었다.
이번 프로젝트에서는 AWS에 대한 전권을 내가 쥐고 있어서, 내가 EKS 클러스터를 구축해야 한다.

처음에는, terraform-aws-modules/eks/aws 모듈을 쓰려고 했다.
그러나, 너무 추상화가 되어있고, 입력 매개변수들이 너무 많아서 이게 어떤 구조인지 이해하기 어려웠다.
그래서 추상화가 이미 된 모듈을 사용하는 대신, 내가 직접 모듈들을 만들어서 EKS 클러스터를 만들어보기로 했다.
직접 모듈을 만들면서 각 컴포넌트의 역할을 더 잘 이해할 수 있었다.

여러 모듈로 구성되어있는데, 의존 관계는 다음과 같다:

❓ Amazon EKS?

Amazon EKS(Elastic Kubernetes Service) 는 AWS의 관리형 Kubernetes 서비스이다.
AWS에서 Kubernetes를 운영하면서, Control Plane을 운영하는 것에 대한 복잡도를 줄여준다.

퍼블릭 클라우드에서 Kubernetes를 운영한다면, 이러한 관리형 서비스를 쓰는 것이 직접 클라우드 VM위에서 띄우는 것보다 좋은 선택이다.
운영 복잡도를 줄이고, 클라우드 플랫폼에서의 통합 기능을 강력하게 이용할 수 있다.

주된 이점들은 다음과 같다:

Control Plane운영 자동화
Worker Node의 확장 및 관리
VPC, 보안그룹, LB, CNI등의 네트워크 설정
IAM, CloudWatch, EBS등 통합

EKS Standard vs Auto Mode

Amazon EKS 는 두 가지의 주요 옵션이 있다:

EKS Standard
- AWS 는 Control Plane만 관리
- 직접 클러스터 컴포넌트에 대한 운영 필요
  - node groups, addons 등
EKS Auto Mode
- AWS가 여러 운영 기능들을 자동 지원
- 추가 비용이 발생할 수 있음

여기서는 EKS Standard를 쓰는데, 추가 비용이 내기 싫은 것도 있고, 직접 관리하기를 원하기 때문이다.
프로젝트에는 학습 목적도 있기에, Auto Mode등의 기능은 쓰지 않는 것이 더 도움될 듯 하기도 하다.

🧀 EKS Cluster

이 모듈은 코어 EKS control plane을 생성한다.
클러스터 자체와 control plane에 필요한 IAM role, 그리고 Kubernetes API에 대한 접근제어 등을 정의한다.
Public API 노출과 Private API노출을 토글가능하게 만들었으며, 이외에도 로깅 설정이나 Auto Mode비활성화 등의 설정이 들어있다.

`main.tf`

메인 리소스는 aws_eks_cluster 인데, EKS control plane을 생성한다.

Private mode를 설정가능하게 만들어서, Public Access 또는 Private Access를 전환할 수 있으며, Private인경우 bastion host가 접속할 수 있도록 VPC cidr로부터 보안그룹을 허용해주고 있다.

access_config에서는, authentication_mode = "API"를 써서, aws-auth ConfigMap를 이용한 구형 인증방식 대신 새로운 인증방식을 사용하도록 했다.

이 모듈은 또한 Control Plane에 필요한 IAM role도 생성하여, 클러스터 작업을 할 수 있도록 해준다.

기본적으로, EKS cluster는 ETCD암호화를 제공한다.
컴플라이언스 등으로 인해서CMK(Customer Managed Key) 를 원한다면, encryption_config 블록을 이용할 수 있다.
여기 에서 세부 정보를 확인가능하다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78


resource "aws_security_group" "eks_control_plane_access" {
 count = var.private_mode ? 1 : 0

 name = "${var.cluster_name}-eks-control-plane-access"
 description = "Allow bastion to reach EKS private API"
 vpc_id = var.vpc_id
}

resource "aws_vpc_security_group_ingress_rule" "eks_api_from_vpc" {
 count = var.private_mode ? 1 : 0

 security_group_id = aws_security_group.eks_control_plane_access[0].id
 cidr_ipv4 = var.vpc_cidr
 ip_protocol = "tcp"
 from_port = 443
 to_port = 443
}
resource "aws_eks_cluster" "eks" {
 name = var.cluster_name

 access_config {
 authentication_mode = "API"
 }

 role_arn = aws_iam_role.eks.arn
 version = var.kubernetes_version
 bootstrap_self_managed_addons = var.bootstrap_self_managed_addons
 enabled_cluster_log_types = var.enabled_cluster_log_types

 vpc_config {
 subnet_ids = var.subnet_ids
 endpoint_public_access = !var.private_mode
 endpoint_private_access = var.private_mode

 security_group_ids = aws_security_group.eks_control_plane_access[*].id
 }

 # Disable Auto-Mode
 compute_config {
 enabled = false
 }

 control_plane_scaling_config {
 tier = var.cp_scaling_tier
 }

 upgrade_policy {
 support_type = "STANDARD"
 }

 depends_on = [aws_iam_role_policy_attachment.cluster_AmazonEKSClusterPolicy]

}

# IAM Role for Contorl Plane
resource "aws_iam_role" "eks" {
 name = "${var.cluster_name}-role"
 assume_role_policy = jsonencode({
 Version = "2012-10-17"
 Statement = [
 {
 Action = [
 "sts:AssumeRole",
 "sts:TagSession"
 ]
 Effect = "Allow"
 Principal = {
 Service = "eks.amazonaws.com"
 }
 },
 ]
 })
}

resource "aws_iam_role_policy_attachment" "cluster_AmazonEKSClusterPolicy" {
 policy_arn = "arn:aws:iam::aws:policy/AmazonEKSClusterPolicy"
 role = aws_iam_role.eks.name
}

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


variable "cluster_name" {
 description = "EKS cluster name"
 type = string
}

variable "kubernetes_version" {
 description = "EKS version"
 type = string
}

variable "bootstrap_self_managed_addons" {
 description = "Wheter to Enable VPC CNI and kube-proxy"
 type = bool
 default = true
}

variable "vpc_id" {
 description = "VPC ID"
 type = string
}

variable "vpc_cidr" {
 description = "VPC CIDR Block"
 type = string
}

variable "subnet_ids" {
 description = "Subnet IDs"
 type = list(string)
}

variable "private_mode" {
 description = "Enable EKS private access"
 type = string
}

variable "cp_scaling_tier" {
 description = "Scaling tier for Control Plane"
 type = string
 default = "standard"
}

variable "enabled_cluster_log_types" {
 type = set(string)
 default = []
 validation {
 condition = alltrue([
 for t in var.enabled_cluster_log_types :
 contains(["api", "audit", "authenticator", "controllerManager", "scheduler"], t)
 ])
 error_message = "enabled_cluster_log_types must contain only valid EKS control plane log types."
 }
}

`outputs.tf`

기본적으로, 클러스터의 보안그룹이 생성된다.
vpc_config블록 안에서 cluster_security_group_id라는 attribute를 가진다. 더 자세한 내용은 여기에서 볼 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


output "cluster_name" {
 value = aws_eks_cluster.eks.name
}

output "endpoint" {
 value = aws_eks_cluster.eks.endpoint
}

output "ca_certificate" {
 value = aws_eks_cluster.eks.certificate_authority[0].data
}

output "arn" {
 value = aws_eks_cluster.eks.arn
}

output "cluster_security_group_id" {
 value = aws_eks_cluster.eks.vpc_config[0].cluster_security_group_id
}

🔑 Access Entries

클러스터가 authentication_mode = "API"를 쓰기에, 클러스터의 액세스는 aws-auth ConfigMap 대신 access entries를 이용한다.

둘의 큰 차이는 어디에서 액세스가 관리되느냐이다.
aws-auth는 IAM-Kubernetes의 매핑이 클러스터 내부 ConfigMap에 저장되어있다.
Access entries는 AWS의 영역에서 관리된다.
새로운 모델이 더 선호되는데, IaC친화적이며, 관리 모델이 더 단순하고 깔끔하기 때문이다.

IAM user를 이용하는 것보다, IAM role을 assume하여 클러스터에 접근하는 것이 더 권장되는 패턴이다.
즉, 엔지니어가 role을 assume하여 클러스터에 해당 role로써 접근하는 것이다.
IAM role은 임시 자격증명을 이용한 방식이기에, IAM user보다 더 안전한 패턴이다.
또한, 운영의 관점에서도, role을 기반으로 인증하는 것이 더 자연스러운 접근이다.
IAM user가 IAM role을 assume하기 위해서는, "sts:AssumeRole" action을 해당 role에 대해 할 수 있어야 하며, 그 role은 trust policy로 해당 IAM user가 assume하는것을 허용해야 한다.

하나 짚고 가야하는건, EKS access entries가 Kubernetes RBAC를 대체하는 것은 아니라는 것이다.
Access Entries는 IAM principal이 클러스터에 접근할 수 있는지에 대한 것만 판단하고, Kubernetes RBAC는 해당 API작업을 할 수 있는지를 더 세부적으로 정한다.
즉, 두 개의 계층이 함께 동작한다.
이 모듈에서는 kubernetes_group라는 옵셔널한 필드가 있는데, 여기에 access entry가 kubernetes내부에서 어떤 그룹에 속하는지를 정할 수 있다.
더 많은 정보는 여기에서 볼 수 있다.

이 모듈은 두 개의 리소스로 구성된다:

aws_eks_access_entry, IAM principal을 EKS에 entry로 등록한다.
aws_eks_access_policy_association, 액세스 정책을 entry에 붙일 수 있다.
- 여기서의 액세스 정책은 RBAC와는 다른 EKS수준에서의 접근제어이다. 대략적인 접근제어가 가능하지만, RBAC만큼 정교하지는 못하다.

`main.tf`

aws_eks_access_entry 리소스는 하나의 IAM principal을 eks에 entry로 등록한다.
이후, aws_eks_access_policy_association 리소스는 map형태로 입력받아서, 여러 개의 policy를 추가할 수 있도록 설정하였다.

각 policy association 은 또한 access scope도 존재하는데, 클러스터 레벨 또는 namespace에 대해 접근 권한을 할당받을 수 있도록 되어있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


resource "aws_eks_access_entry" "access" {
 cluster_name = var.cluster_name
 principal_arn = var.principal_arn
 kubernetes_groups = var.kubernetes_groups
}

resource "aws_eks_access_policy_association" "access" {
 for_each = var.eks_access_policy_association

 cluster_name = var.cluster_name
 principal_arn = var.principal_arn
 policy_arn = each.value.policy_arn

 access_scope {
 type = each.value.access_scope_type
 namespaces = each.value.namespaces
 }
}

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


variable "cluster_name" {
 description = "EKS cluster name"
 type = string
}

variable "principal_arn" {
 description = "IAM role ARN registering access policy"
 type = string
}

variable "kubernetes_groups" {
 description = "List of Kubernetes groups to assign to the principal"
 type = list(string)
 default = []
}

variable "eks_access_policy_association" {
 type = map(object({
 policy_arn = string
 access_scope_type = string
 namespaces = optional(list(string))
 }))
 default = {}
 validation {
 condition = alltrue([
 for t in var.eks_access_policy_association :
 contains(["namespace", "cluster"], t.access_scope_type)
 ])
 error_message = "eks_access_policy_association must contain only 'namespace' or 'cluster'"
 }
}

👪 Node Groups

EKS managed 노드 그룹은 워커 노드들의 프로비저닝과 생명 주기 관리를 자동화한다.

이 모듈은 여러 입력 변수들이 존재하는데, 인스턴스 타입이나 스케일링 제한, label, taint 등의 다양한 구성이 가능하도록 해야 하기 때문이다.

워커 노드들은 role과 AWS권한들이 일부 요구된다.
최소한으로, AmazonEKSWorkerNodePolicy, AmazonEC2ContainerRegistryPullOnly 가 있어야 EKS Control Plane에 연결될 수 있으며, ECR에서 이미지를 불러온다.

`main.tf`

코어 리소스는 aws_eks_node_group이다.

labels과 taints를 변수화하여 스케줄링 옵션에서 사용할 수 있도록 하였다.
예를 들어, 다른 애플리케이션들은 SPOT노드그룹에 올리더라도, 다른 운영 도구들은 ONDEMAND 인스턴스인 노드그룹에 올릴 수 있다.

desired_size는 상태 비교에서 무시되는데, 만약 추가 scale이 된경우에는 무시하여 설정 드리프트로 인식하지 않게 하기 위함이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56


resource "aws_eks_node_group" "ng" {
 cluster_name = var.cluster_name
 node_group_name = var.node_group_name
 node_role_arn = aws_iam_role.ng.arn

 ami_type = var.ami_type
 instance_types = var.instance_types
 subnet_ids = var.subnet_ids
 capacity_type = var.capacity_type
 disk_size = var.disk_size

 scaling_config {
 desired_size = var.scaling.desired_size
 min_size = var.scaling.min_size
 max_size = var.scaling.max_size
 }

 labels = var.labels

 dynamic "taint" {
 for_each = var.taints
 content {
 key = taint.value.key
 value = taint.value.value
 effect = taint.value.effect
 }
 }

 lifecycle {
 ignore_changes = [scaling_config[0].desired_size]
 }

 depends_on = [aws_iam_role_policy_attachment.ng_attachment]
}

resource "aws_iam_role" "ng" {
 name = "${var.node_group_name}-role"

 assume_role_policy = jsonencode({
 Version = "2012-10-17"
 Statement = [{
 Action = "sts:AssumeRole"
 Effect = "Allow"
 Principal = {
 Service = "ec2.amazonaws.com"
 }
 }]
 })
}

resource "aws_iam_role_policy_attachment" "ng_attachment" {
 for_each = var.role_policy_attachment

 policy_arn = each.value
 role = aws_iam_role.ng.name
}

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91


variable "cluster_name" {
 description = "Name of EKS Cluster"
 type = string
}

variable "node_group_name" {
 description = "Name of node group"
 type = string
}

variable "subnet_ids" {
 description = "ID list of subnet"
 type = list(string)
}

variable "ami_type" {
 description = "Type of AMI"
 type = string
 validation {
 condition = contains([
 "AL2_x86_64", "AL2_x86_64_GPU", "AL2_ARM_64", "CUSTOM",
 "BOTTLEROCKET_ARM_64", "BOTTLEROCKET_x86_64",
 "BOTTLEROCKET_ARM_64_FIPS", "BOTTLEROCKET_x86_64_FIPS",
 "BOTTLEROCKET_ARM_64_NVIDIA", "BOTTLEROCKET_x86_64_NVIDIA",
 "BOTTLEROCKET_ARM_64_NVIDIA_FIPS", "BOTTLEROCKET_x86_64_NVIDIA_FIPS",
 "WINDOWS_CORE_2019_x86_64", "WINDOWS_FULL_2019_x86_64",
 "WINDOWS_CORE_2022_x86_64", "WINDOWS_FULL_2022_x86_64",
 "WINDOWS_CORE_2025_x86_64", "WINDOWS_FULL_2025_x86_64",
 "AL2023_x86_64_STANDARD", "AL2023_ARM_64_STANDARD",
 "AL2023_x86_64_NEURON", "AL2023_x86_64_NVIDIA", "AL2023_ARM_64_NVIDIA"
 ], var.ami_type)
 error_message = "amiType does not match. check: https://docs.aws.amazon.com/eks/latest/APIReference/API_Nodegroup.html#AmazonEKS-Type-Nodegroup-amiType"
 }
}

variable "instance_types" {
 description = "List of instance type"
 type = list(string)
}

variable "capacity_type" {
 description = "Node Capacity Type"
 type = string
 validation {
 condition = contains(["ON_DEMAND", "SPOT"], var.capacity_type)
 error_message = "Valid value: <ON_DEMAND | SPOT>"
 }
}

variable "disk_size" {
 description = "Disk size for each worker node"
 type = number
 default = 20
}

variable "scaling" {
 description = "Scaling Capacity"
 type = object({
 desired_size = number
 min_size = number
 max_size = number
 })
}

variable "labels" {
 description = "Node labels"
 type = map(string)
}

variable "taints" {
 description = "Taints for rule"
 type = map(object({
 key = string
 value = optional(string)
 effect = string
 }))

 validation {
 condition = alltrue([
 for _, v in var.taints :
 contains(["NO_SCHEDULE", "NO_EXECUTE", "PREFER_NO_SCHEDULE"], v.effect)
 ])
 error_message = "Valid effect: <NO_SCHEDULE | NO_EXECUTE | PREFER_NO_SCHEDULE>"
 }
}

variable "role_policy_attachment" {
 description = "Role policies to attach nodes"
 type = set(string)
 default = []
}

📲 Addons

EKS의 다른 부분들과는 다르게, 애드온들은 상대적으로 간단하다.
aws_eks_addon 리소스 하나로 되어서 굳이 모듈화할 필요는 없을 수 있지만, 일관된 형태를 위해 여기서는 모듈화하였다.

`main.tf`

1
2
3
4


resource "aws_eks_addon" "addon" {
 cluster_name = var.cluster_name
 addon_name = var.addon_name
}

`variables.tf`

1
2
3
4
5
6
7
8
9


variable "cluster_name" {
 description = "Name of EKS Cluster"
 type = string
}

variable "addon_name" {
 description = "Name of Addon"
 type = string
}

⛓️ Pod Identity Associations

EKS Pod Identity 는 Pod가 AWS 서비스를 IAM role을 할당받을 수 있도록 한다.
EC2 instance profile가 EC2 instance에게 자격증명을 부여하는 것과 비슷하게 동작하는데, 단위가 Kubernetes의 워크로드인 Pod인 것이다.

Worker Node와는 별도의 IAM role을 사용하여 실제 필요한 권한만 최소한으로 할당하도록 할 수 있다.

`main.tf`

우선, Pod에 할당한 IAM role을 만들어준다.
이후, AWS 서비스를 사용하기 위한 IAM Policy를 적절히 할당해준다.
마지막으로, pod identity association자원을 생성하여 IAM role이 namespace내부의 특정 serviceAccount에 할당되도록 한다.
Pod identity agent라는 daemonset이 클러스터 내부에서 동작하며, Pod에 임시 자격증명을 전달한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


resource "aws_iam_role" "pod" {
 name = var.role_name

 assume_role_policy = jsonencode({
 Version = "2012-10-17"
 Statement = [
 {
 Effect = "Allow"
 Principal = {
 Service = "pods.eks.amazonaws.com"
 }
 Action = [
 "sts:AssumeRole",
 "sts:TagSession"
 ]
 }
 ]
 })
}

resource "aws_iam_role_policy_attachment" "pod" {
 role = aws_iam_role.pod.name
 policy_arn = var.policy_arn
}

resource "aws_eks_pod_identity_association" "association" {
 cluster_name = var.cluster_name
 namespace = var.namespace
 service_account = var.service_account
 role_arn = aws_iam_role.pod.arn
}

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


variable "cluster_name" {
 description = "Name of EKS Cluster"
 type = string
}

variable "role_name" {
 description = "IAM role name to assign pod"
 type = string
}

variable "policy_arn" {
 description = "IAM policy arn"
 type = string
}

variable "namespace" {
 description = "Kubernetes namespace"
 type = string
}

variable "service_account" {
 description = "Name of serviceAccount"
 type = string
}

🚪 (Optional) Bastion Host

Private API로 EKS를 노출한다면, 퍼블릭 인터넷으로는 접근할 수 없다.
즉, 같은 VPC에서 관리를 할 수 있는 bastion host가 필요하다.

Bastion host만이 정답은 아니다. 다른 옵션들 역시 존재한다.
Client VPN이나 Site-to-Site VPN등의 옵션도 있지만, 비용의 측면에서도 부담스러우며, 및 소규모 팀에서 쓰기에는 부적절하다고 생각되었다.
그래서 EC2 bastion host를 만들어서 AWS SSM을 이용한 접근으로 클러스터를 관리할 수 있는 워크스테이션을 만드는 것을 선택했다.

`main.tf`

이 모듈은 작은 EC2인스턴스를 생성한다.

대신, ssh기반의 접속이 아닌, SSM으로 외부 인터넷 노출 포트 없이 더 안전하다.
또한, SSH키의 관리와 추가 보안그룹 규칙 관리 등의 부담도 없어진다.

eks:DescribeCluster 를 실행할 수 있도록 IAM policy를 할당해준다.
aws eks update-kubeconfig 를 통해서 kuberntes api에 접근할 수 있게 된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114


data "aws_ami" "ubuntu" {
 most_recent = true

 filter {
 name = "name"
 values = ["ubuntu/images/hvm-ssd-gp3/ubuntu-noble-24.04-arm64-server-*"]
 }

 filter {
 name = "virtualization-type"
 values = ["hvm"]
 }

 owners = ["099720109477"] # Canonical
}

resource "aws_security_group" "bastion" {
 name = "bastion_ssm"
 description = "Deny inbound traffic and allow outbound traffic"
 vpc_id = var.vpc_id
}

resource "aws_vpc_security_group_egress_rule" "bastion_internet" {
 security_group_id = aws_security_group.bastion.id

 cidr_ipv4 = "0.0.0.0/0"
 from_port = 443
 ip_protocol = "tcp"
 to_port = 443
}

resource "aws_iam_instance_profile" "ssm" {
 name = "${var.name}-profile"
 role = aws_iam_role.bastion.id
}

resource "aws_instance" "bastion" {
 ami = data.aws_ami.ubuntu.id
 instance_type = var.instance_type

 subnet_id = var.subnet_id
 vpc_security_group_ids = [aws_security_group.bastion.id]
 associate_public_ip_address = var.associate_public_ip_address

 iam_instance_profile = aws_iam_instance_profile.ssm.name

 metadata_options {
 http_tokens = "required"
 }

 root_block_device {
 encrypted = true
 volume_type = "gp3"
 }

 user_data = file("${path.module}/user_data.sh")
 user_data_replace_on_change = true

 tags = {
 Name = var.name
 }
}

resource "aws_iam_role" "bastion" {
 name = var.name
 path = "/"
 assume_role_policy = jsonencode({
 Version = "2012-10-17"
 Statement = [
 {
 Sid = "AllowEC2SSM"
 Effect = "Allow"
 Action = [
 "sts:AssumeRole"
 ]
 Principal = {
 Service = "ec2.amazonaws.com"
 }
 }
 ]
 })

 tags = {
 Purpose = "Bastion"
 }
}

resource "aws_iam_role_policy_attachment" "bastion_ssm" {
 role = aws_iam_role.bastion.name
 policy_arn = "arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore"
}

data "aws_iam_policy_document" "bastion_access_eks" {
 statement {
 sid = "AllowEKStoBastion"
 actions = [
 "eks:DescribeCluster"
 ]
 resources = [
 var.eks_arn
 ]
 }
}

resource "aws_iam_policy" "bastion_access_eks" {
 name = "${var.name}-access-eks"
 path = "/"
 policy = data.aws_iam_policy_document.bastion_access_eks.json
}

resource "aws_iam_role_policy_attachment" "bastion_access_eks" {
 role = aws_iam_role.bastion.name
 policy_arn = aws_iam_policy.bastion_access_eks.arn
}

`user_data.sh`

인프라 도구들을 미리 설치시키고, 쉘 설정들도 일부 넣어준다.
이 스크립트를 통해 bastion host가 VPC내부의 워크스테이션이 되게 해준다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66


#!/usr/bin/env bash
set -euo pipefail

export DEBIAN_FRONTEND=noninteractive

apt-get update
apt-get upgrade -y

apt-get install -y apt-transport-https ca-certificates curl gnupg unzip

# kubectl
mkdir -p /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.35/deb/Release.key |
 gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.35/deb/ /' \
 >/etc/apt/sources.list.d/kubernetes.list
apt-get update
apt-get install -y kubectl

# OpenTofu
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://get.opentofu.org/opentofu.gpg | tee /etc/apt/keyrings/opentofu.gpg >/dev/null
curl -fsSL https://packages.opentofu.org/opentofu/tofu/gpgkey | gpg --dearmor -o /etc/apt/keyrings/opentofu-repo.gpg
chmod a+r /etc/apt/keyrings/opentofu.gpg /etc/apt/keyrings/opentofu-repo.gpg

cat >/etc/apt/sources.list.d/opentofu.list <<'EOF'
deb [signed-by=/etc/apt/keyrings/opentofu.gpg,/etc/apt/keyrings/opentofu-repo.gpg] https://packages.opentofu.org/opentofu/tofu/any/ any main
deb-src [signed-by=/etc/apt/keyrings/opentofu.gpg,/etc/apt/keyrings/opentofu-repo.gpg] https://packages.opentofu.org/opentofu/tofu/any/ any main
EOF

apt-get update
apt-get install -y tofu

ARCH="$(uname -m)"

case "$ARCH" in
x86_64)
 AWSCLI_URL="https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip"
 ;;
aarch64 | arm64)
 AWSCLI_URL="https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip"
 ;;
*)
 echo "Unsupported architecture: $ARCH"
 exit 1
 ;;
esac

curl -fsSL "$AWSCLI_URL" -o "awscliv2.zip"
unzip -o awscliv2.zip
./aws/install

# SSM Agent
snap install amazon-ssm-agent --classic || true
systemctl enable snap.amazon-ssm-agent.amazon-ssm-agent.service || true
systemctl restart snap.amazon-ssm-agent.amazon-ssm-agent.service || true

# Shell
curl -fsSL https://starship.rs/install.sh | sh -s -- -y

cat <<'EOF' >>/home/ubuntu/.bashrc
eval "$(starship init bash)"
alias k='kubectl'
EOF

chown ubuntu:ubuntu /home/ubuntu/.bashrc

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


variable "name" {
 description = "Name of the instance"
 type = string
}

variable "vpc_id" {
 description = "VPC ID"
 type = string
}

variable "subnet_id" {
 description = "Subnet ID"
 type = string
}

variable "instance_type" {
 description = "EC2 Instance Type"
 type = string
 default = "t4g.nano"
}

variable "eks_arn" {
 description = "EKS Arn"
 type = string
}

variable "associate_public_ip_address" {
 description = "Associate public IP address"
 type = bool
}

`outputs.tf`

1
2
3
4
5
6
7


output "bastion_id" {
 value = aws_instance.bastion.id
}

output "bastion_role_arn" {
 value = aws_iam_role.bastion.arn
}

🚀 Modules 사용하기

아래는 모듈의 사용 예시이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167


##########
# locals #
##########
locals {
 vpc_cidr = "10.0.0.0/16"

 # Enable/disable EKS private access
 eks_private_mode = true

 # EKS Addon list
 eks_addons = toset([
 "coredns",
 "kube-proxy",
 "vpc-cni",
 "aws-ebs-csi-driver",
 "eks-pod-identity-agent",
 ])

 # Pod identity associations
 pod_identity_associations = {
 vpc_cni = {
 role_name = "${var.cluster_name}-vpc-cni"
 policy_arn = "arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy"
 namespace = "kube-system"
 service_account = "aws-node"
 }
 ebs_csi = {
 role_name = "${var.cluster_name}-ebs-csi"
 policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy"
 namespace = "kube-system"
 service_account = "ebs-csi-controller-sa"
 }
 }
}

########################################################
# EKS - Cluster #
# #
# NOTE: #
# By default, EKS secrets are protected with enveloped #
# encryption in EKS version 1.28 or higher #
########################################################
module "eks_cluster" {
 source = "../../../modules/eks-cluster"

 cluster_name = var.cluster_name
 kubernetes_version = "1.35"
 vpc_id = module.vpc.vpc_id
 vpc_cidr = local.vpc_cidr
 subnet_ids = module.vpc.private_subnet_ids
 private_mode = local.eks_private_mode

 enabled_cluster_log_types = []
 cp_scaling_tier = "standard"
}

######################
# EKS - Access Entry #
######################
module "eks_access_entry_private" {
 count = local.eks_private_mode ? 1 : 0
 source = "../../../modules/eks-access-entry"

 # Use module output instead of var.cluter_name because of the dependency implication.
 cluster_name = module.eks_cluster.cluster_name
 principal_arn = module.bastion[0].bastion_role_arn

 eks_access_policy_association = {
 clusteradmin = {
 policy_arn = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
 access_scope_type = "cluster"
 }
 }
}

module "eks_access_entry_public" {
 count = local.eks_private_mode ? 0 : 1
 source = "../../../modules/eks-access-entry"

 cluster_name = module.eks_cluster.cluster_name
 principal_arn = data.terraform_remote_state.shared.outputs.eks_fullaccess_role_arn

 eks_access_policy_association = {
 clusteradmin = {
 policy_arn = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
 access_scope_type = "cluster"
 }
 }
}

#####################################
# EKS - Node Group #
# Desired Node group size is ignored #
# when comparing the state #
#####################################
module "eks_node_group" {
 source = "../../../modules/eks-node-group"

 cluster_name = module.eks_cluster.cluster_name
 node_group_name = "${var.cluster_name}-ng"

 ami_type = "AL2023_ARM_64_STANDARD"
 subnet_ids = module.vpc.private_subnet_ids
 instance_types = ["t4g.large"]

 capacity_type = "ON_DEMAND"
 disk_size = 20

 scaling = {
 desired_size = 2
 min_size = 2
 max_size = 4
 }

 labels = {
 NodeGroupName = "default"
 }

 taints = {}

 # Role policy Attachment
 role_policy_attachment = [
 "arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy",
 "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly"
 ]
}

################
# EKS - Addons #
################
module "eks-addons" {
 source = "../../../modules/eks-addons"
 for_each = local.eks_addons

 cluster_name = module.eks_cluster.cluster_name
 addon_name = each.value
}


###################################
# EKS - Pod identity associations #
###################################
module "pod_identity_association" {
 source = "../../../modules/eks-pod-identity-association"
 for_each = local.pod_identity_associations

 cluster_name = module.eks_cluster.cluster_name
 role_name = each.value.role_name
 policy_arn = each.value.policy_arn
 namespace = each.value.namespace
 service_account = each.value.service_account
}

################
# Bastion Host #
################
module "bastion" {
 count = local.eks_private_mode ? 1 : 0
 source = "../../../modules/ec2-ssm-bastion"

 name = "bastion-prod"
 vpc_id = module.vpc.vpc_id
 subnet_id = module.vpc.private_subnet_ids[0]
 instance_type = "t4g.nano"
 eks_arn = module.eks_cluster.arn
 associate_public_ip_address = false
}

🪪 EKS Cluster에 접속

EKS가 퍼블릭 API를 노출한다면, kubeconfig를 업데이트하여 로컬 환경에서 바로 접근할 수 있다.

1
2


# Add --role-arn <role-arn> if you need to assume a role
aws eks update-kubeconfig --region <region> --name <cluster-name>

클러스터가 private mode에서 돌아간다면, ssm으로 bastion host에 들어가는 것이 먼저이다.

1

aws ssm start-session --target <instance-id>

이후, 안에서 kubeconfig를 업데이트해주면 된다.

➡️ 더 해야 할 일들

EKS 클러스터를 프로비저닝 하는 것은 이제 시작일 뿐이다.
클러스터 내부에 운영을 위해 더 설치를 고려해야 하는 것들이 더 많다:

예를 들면, 아래와 같다:

ArgoCD 를 통한 GitOps
cert-manager 를 통한 TLS연결
AWS Load Balancer Controller 를 통한 Load Balancer연동
Karpenter 를 통한 노드 오토스케일링
Gateway API CRD
관찰성(Observability) 스택
이외 더 많은 운영 도구들

AWS EKS Capabilities를 고려할 수도 있다.

📚 References

Obsidian Sync를 셀프호스트로 대체하기

Sat, 11 Apr 2026 02:26:13 +0900

🧋 개요

나의 노트앱 여정

나는 Notion 대신에 Obsidian을 주로 쓰는데, 이유는 다음과 같다:

노션은 너무 무거움
불필요한 기능들이 많음
로딩이 김

Obsidian은 더 가볍고 단순해서 계속 사용하게된다.
(그리고 더 이쁘다)

Obsidian의 동기화 옵션들

여러 옵션들이 있어 많은 고민들 끝에 동기화 방식을 정하게 되었다.

공식
- Obsidian Sync
  - 좋긴 할 것 같지만, 유료 구독제라 탈락
- iCloud
  - 완전 애플생태계만 쓴다면 괜찮은 선택
  - 그러나, 나는 NixOS랩탑을 쓰는 등, 다른 환경도 사용하기에 부적절하다.
비공식
- Git & GitHub
  - 내가 Obsidian을 쓰기 처음의 옵션이였지만, 레포지토리가 커지면서 모바일에서의 경험이 좋지 못했다.
  - iPhone에서 Working Copy앱이 Pull 및 Push 오류가 꽤 잦았다.
- Syncthing
  - Peer-to-peer방식이 매력적이고, Tailscale과 연동하면 특히 강력해보인다.
  - 좋아보이긴 하지만, iPhone에서 공식 지원이 없어서 탈락..
- ⭐ Self-hosted livesync(with CouchDB)
  - 이걸로 정했다.

Self-Hosted LiveSync를 고른 이유

결국, CouchDB기반의 self-hosted LiveSync 를 골랐는데, 이유는 다음과 같다:

이미 Proxmox 홈서버가 있음
LiveSync 플러그인은 10k stars이상이며, 꽤 강력한 커뮤니티를 가지고있음
재밌을거같아서

이 포스트에서는, CouchDB + Caddy를 Proxmox LXC 컨테이너에서 운영하고, Tailscale로 기기들을 연결하여 Obsidian Sync 시스템을 만들 것이다.

🏗️ LXC Container 프로비저닝하기

우선, LXC Container 를 Proxmox Cluster에서 만들어줄 것이다.

선언적 환경 구성을 위해, Terraform 으로 설치할 것이며, provider는 bgp/proxmox를 이용한다.

Debian 13 LXC Image 다운로드

Terraform을 쓰긴 하지만, proxmox_download_file리소스가 현재 LXC이미지를 받을 때, 체크섬 확인에서 오류가 나서 매번 재설치를 진행한다.
대신, 이미지는 수동 설치를 하는 것이 좋을 듯 하다.

우선. SSH로 Proxmox 클러스터에 접속한다:

1

ssh <your-proxmox-cluster>

이후, 공식 지원 LXC 이미지를 검색한다:

1

pveam available

Debian13 이미지를 설치한다:

1

pveam download local debian-13-standard_13.1-2_amd64.tar.zst

Terraform 모듈

코드의 재사용성을 위해, 모듈을 만들어준다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111


# ./modules/lxc_container/main.tf
terraform {
 required_providers {
 proxmox = {
 source = "bpg/proxmox"
 version = "0.101.0"
 }
 }
}

resource "proxmox_virtual_environment_container" "container" {
 description = var.description

 node_name = var.node_name
 vm_id = var.vm_id

 unprivileged = true
 # If true, it cannot be destoryed.
 protection = var.protection

 features {
 nesting = true
 }

 # Required to turn on tailscaled on LXC container.
 device_passthrough {
 path = "/dev/net/tun"
 }

 # If you want you can make resource quotas to variables.
 cpu {
 cores = 2
 limit = 2
 units = 1024
 }

 memory {
 dedicated = 2048
 swap = 512
 }

 initialization {
 hostname = var.hostname

 ip_config {
 ipv4 {
 address = "dhcp"
 }
 }

 user_account {
 keys = var.ssh_keys
 password = random_password.container.result
 }
 }

 wait_for_ip {
 ipv4 = true
 }

 network_interface {
 name = var.network_interface
 }

 disk {
 datastore_id = var.datastore_id
 size = var.disk_size
 }

 operating_system {
 template_file_id = var.template_file_id
 type = var.os_type
 }

 startup {
 order = "3"
 up_delay = "60"
 down_delay = "60"
 }

 dynamic "mount_point" {
 for_each = var.mount_points

 content {
 path = mount_point.value.path
 volume = mount_point.value.volume

 size = try(mount_point.value.size, null)
 read_only = try(mount_point.value.read_only, null)
 backup = try(mount_point.value.backup, null)
 replicate = try(mount_point.value.replicate, null)
 shared = try(mount_point.value.shared, null)
 quota = try(mount_point.value.quota, null)
 acl = try(mount_point.value.acl, null)
 mount_options = try(mount_point.value.mount_options, null)
 }
 }

 tags = var.tags
}

resource "random_password" "container" {
 length = 16
 override_special = "_%@"
 special = true
}

output "container_password" {
 value = random_password.container.result
 sensitive = true
}

아래는 모듈의 variables.tf이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91


# ./module/lxc_container/variables.tf

variable "description" {
 type = string
 description = "LXC description"
}

variable "node_name" {
 type = string
 description = "Proxmox node name"
}

variable "vm_id" {
 type = number
 description = "LXC VM ID"
}

variable "protection" {
 type = bool
 description = "Whether to prevent data"
}

variable "hostname" {
 type = string
 description = "Container hostname"
}

variable "ssh_keys" {
 type = list(string)
 description = "SSH public keys for root account"
 default = []
}

variable "network_interface" {
 type = string
 description = "Container network interface name"
}

variable "datastore_id" {
 type = string
 description = "Datastore ID for root disk"
}

variable "disk_size" {
 type = number
 description = "Root disk size in GB"
}

variable "template_file_id" {
 type = string
 description = "OS template file ID"
}

variable "os_type" {
 type = string
 description = "Container OS type"

 validation {
 condition = contains([
 "alpine",
 "centos",
 "debian",
 "fedora",
 "ubuntu",
 "unmanaged"
 ], var.os_type)
 error_message = "os_type must be one of the supported Proxmox LXC OS types."
 }
}

variable "mount_points" {
 description = "Additional mount points for the container"
 type = list(object({
 path = string
 volume = string
 size = optional(string)
 read_only = optional(bool)
 backup = optional(bool)
 replicate = optional(bool)
 shared = optional(bool)
 quota = optional(bool)
 acl = optional(bool)
 mount_options = optional(list(string))
 }))
 default = []
}

variable "tags" {
 description = "Tags"
 type = list(string)
}

IPv4 주소를 output으로 꺼내주면, LXC 컨테이너에 접속하기 쉬워진다:

1
2
3
4


# ./modules/lxc_container/outputs.tf
output "ipv4" {
 value = proxmox_virtual_environment_container.container.ipv4
}

`provider.tf`

디바이스 패스스루를 하려면, Proxmox에 관리자 계정 (root@pam)을 비밀번호 기반으로 접근해야 한다.
토큰 기반으로는 안된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


terraform {
 required_providers {
 proxmox = {
 source = "bpg/proxmox"
 version = "0.101.0"
 }
 }
}

provider "proxmox" {
 endpoint = <your_endpoint>
 username = var.proxmox_username
 password = var.proxmox_password
 insecure = true

 ssh {
 agent = true
 username = "root"
 }
}

`main.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


# main.tf
locals {
 # Import your SSH public keys here
 ssh_keys = [
 ]
}

module "couchdb" {
 source = "./modules/lxc_container"
 node_name = <your-node-name>
 description = "CouchDB LXC"
 datastore_id = <your-datastore-id>
 protection = true # Recommended

 vm_id = 500 # You can change if you want
 network_interface = <your-network-interface>
 disk_size = 32 # You can change if you want
 hostname = "couchdb" # You can change if you want

 # File ID format: `datasotre_id:type/<image>`
 template_file_id = "local:vztmpl/debian-13-standard_13.1-2_amd64.tar.zst"
 os_type = "debian"
 ssh_keys = local.ssh_keys

 # Example tags
 tags = ["debian", "couchdb", "obsidian"]
}

output "couchdb_ipv4" {
 value = module.couchdb.ipv4
}

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# varialbes.tf
# `terraform.tfvars` should be ignored by Git.
# or, you can use environment variable: `export TF_VAR_<variable_name>`
variable "proxmox_username" {
 type = string
 default = "root@pam"
}

variable "proxmox_password" {
 type = string
 sensitive = true
}

적용 & 접속하기

이제, LXC 컨테이너를 만들 수 있다!

1
2
3
4
5


terraform init

terraform plan

terraform apply -auto-approve

이후, 컨테이너에 접속할 수 있다:

1

ssh root@<your-container-ip>

🪏 CouchDB + LiveSync 서버 세팅

CouchDB 설치

우선, 패키지 매니저를 업데이트하고, 패키지를 업그레이드해준다.
이후, 설치 매뉴얼에서 필요한 의존성들을 받아준다:

1
2
3


apt update
apt upgrade -y
apt install -y gpg curl sudo

이후, 공식 CouchDB 문서를 통해 CouchDB를 다운받는다.

설치하는동안, TUI 인터랙션이 시작된다.
아래의 설정대로 따라가면 된다:

type: standalone
bind address: 127.0.0.1
Erlang magic cookie: <your-random-long-string>
admin password: <your-admin-password>

Magic cookie, admin password는 안전한 곳에 넣자.

CouchDB가 실행되는지 확인해보자:

1

systemctl status couchdb

Obsidian LiveSync 설치

아래 스크립트에 정보를 넣고 실행하자:

1

curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | hostname=http://<YOUR SERVER IP>:5984 username=<INSERT USERNAME HERE> password=<INSERT PASSWORD HERE> bash

원본 설치 매뉴얼도 같이 참고하는걸 추천한다:

결과가 아래처럼 나오면, 성공이다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


-- Configuring CouchDB by REST APIs... -->
{"ok":true}
""
""
""
""
""
""
""
""
""
<-- Configuring CouchDB by REST APIs Done!

🔒 Tailscale 설치

Tailscale 은 WireGuard 기반의 Peer-to-peer의 VPN이다.
이를 통해 안전하게 장치들 간의 연결을 할 수 있다.

디바이스들에 Tailscale설치

Tailscale에 로그인하고 대시보드에 들어간다.

대시보드에서 설치 메뉴얼을 친절하게 제공하므로, 따르면 된다.
Obsidian을 쓰려는 모든 기기마다 설치해주면 된다.

Tailscale이 설치되면, 새로운 네트워크 인터페이스가 추가된다.
아래는 LXC 컨테이너에서의 설치 이후 모습이다:

MagicDNS 세팅

Tailscale은 또한 내부 DNS와 Let’s Encrypt에서 제공하는 HTTPS 인증서 연동을 지원한다. \

Dashboard -> DNS에서, MagicDNS 와 HTTPS Certificates를 enable해준다.

👮 Caddy 설치

Caddy 는 리버스 프록시로도 활용될 수 있는 간단한 웹 서버이다.
Tailscale과 연계가 특히 좋은데, CouchDB는 REST API를 지원하여, Caddy는 CouchDB의 앞단에서 동작할 것이다.

여기에서 Caddy를 설치할 수 있다.

/etc/caddy/Caddyfile에서, 리버스 프록시 설정을 해준다.

1
2
3
4
5
6
7
8
9


# /etc/caddy/Caddyfile
# Match your tailnet MagicDNS FQDN
https://<hostname>.<your-tailnet>.ts.net {
 reverse_proxy 127.0.0.1:5984 {
 header_up Host {host}
 header_up X-Forwarded-For {remote_host}
 header_up X-Forwarded-Proto {scheme}
 }
}

/opt/couchdb/etc/local.ini에서, CORS설정을 해준다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


[chttpd]
bind_address = 127.0.0.1
port = 5984
enable_cors = true

[cors]
credentials = true
origins = app://obsidian.md, capacitor://localhost, http://localhost
headers = accept, authorization, content-type, origin, referer
methods = GET, PUT, POST, HEAD, DELETE, OPTIONS
max_age = 3600

/etc/default/tailscaled에서, caddy유저가 Tailscale을 통해 인증서를 관리하도록 한다.

1

TS_PERMIT_CERT_UID=caddy

이후, 서비스들을 재시작한다.

1
2
3


systemctl restart tailscaled
systemctl restart caddy
systemctl restart couchdb

🍰 클라이언트 사용법

이제 남은건, 저장소 마이그레이션과 클라이언트 연동 뿐이다.

Setup URI 생성

아래 명령어로 생성한다.
LXC말고, 편한 곳에서 실행하면 된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


export hostname=<your-hostname>
export database=obsidiannotes # Change this if you want
export passphrase=<random-passphrase>
export username=<username>
export password=<password>

deno run -A https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/flyio/generate_setupuri.ts

# Generated Passphrase & Link:
Your passphrase of Setup-URI is: <passphrase>
This passphrase is never shown again, so please note it in a safe place.
obsidian://setuplivesync?settings=....

기존 Obsidian Vault로부터 마이그레이션(첫 클라이언트 등록 시)

아래 단계를 따른다:

Obsidian에서 Self-hosted LiveSync 플러그인을 설치한다.
플러그인을 활성화한다.
Device Setup Method 에서,Use a Setup URI 를 고른다.
- passphrase와 URI(obsidian://setuplivesync?settings=...)를 입력한다.
“I am setting up a new server for the first time / I want to reset my existing server.” 를 선택한다.
나머지 단계를 적절하게 진행한다.
Without saving으로 앱을 재실행한다.

추가 클라이언트 등록

두 번째 기기 부터는 새로운 vault를 만들어서 진행했다. 아래 단계를 따른다:

Obsidian에서 Self-hosted LiveSync 플러그인을 설치한다.
플러그인을 활성화한다.
Device Setup Method 에서, Use a Setup URI 를 고른다.(모바일에서 QR이 안되던데, 가능하면 QR을 써도 될거같다.)
- passphrase와 URI(obsidian://setuplivesync?settings=...)를 입력한다.
“My remote server is already set up. I want to join this device” 를 고른다.
“This Vault is empty, or contains only new files that are not on the server” 를 고른다.
나머지 단계를 적절하게 진행한다.
Without saving으로 앱을 재실행한다.

설정

LiveSync 프리셋을 이용해서, 실시간 동기화 기능을 켜고 사용 중이다.
대부분의 상황에서 1초 이내로 동기화된다.

☁️ Off-Site 백업

현재 DB가 단일 장애점의 위험 이 있기에, 정전 및 디스크 장애에 대해 대비할 수 있어야 한다.
대비하면 이후에 장애 상황에서도 백업을 할 수 있다.

Git & GitHub

이전에 Git을 쓰다가 갈아타는 거라면서, 계속 Git을 쓴다니, 좀 이상할 수 있다.
그러나, 보조 백업수단으로는 꽤 괜찮은데, Git플러그인에서 주기적 푸시를 지원하며, 이는 꽤 가볍기 때문이다.
즉, 가벼운 백업을 짧은 주기로 계속 emit하는거라 꽤 괜찮다.
또한, 모든 디바이스에서 설치할 이유 없이, 메인 디바이스(컴퓨터, 노트북)에서만 추가로 Git 플러그인을 설치해서 푸시하면 된다.
.git폴더는 LiveSync에서 자동으로 동기화 무시되므로, CouchDB에도 부담이 덜하고, 동기화 문제도 걱정 할 필요 없다.

Cloud Object Storage

Cloudflare R2 나 AWS S3 와 같은 오브젝트 스토리지는 매우 높은 가용성과 데이터 내구성을 자랑한다.
또한, 비용도 저렴한 편이다.
주기적으로 오브젝트 스토리지에 백업해주는 것도 좋다.
예를 들어, cron과 AWS CLI를 이용하면 자동 백업이 가능하다.

📚 References

Terraform - 개발환경에서 NAT Gateway 비용절감

Fri, 10 Apr 2026 16:17:05 +0900

💰 서론

학교 캡스톤디자인에서, AWS 인프라를 풀로 가동할 예산에 무리가 있다.
그러나, 실제 운영환경이 아닌, 개발 환경이며, 24/7로 가동할 이유가 없다.
NAT Gateway는 프로비저닝되어있는 동안, 그 자체로 비용이 꽤 나가기에, 야간 등 팀이 작업하지 않을 때에는 닫아놓아도 된다.
작업하지 않을 때 꺼두기만 해도 큰 지출을 줄일 수 있을 것이다.

💡 전략

NAT Gateway를 natgw_azs라는 변수를 통해 토글하면 된다.
natgw_azs는 list(string)의 타입으로, Regional NAT Gateway의 EIP를 할당하는 az를 정하게 하는데, 만약 비어있다면, NAT Gateway와 관련 라우팅 테이블 엔트리를 생성하지 않으면 된다.
만약 생성된 상태여도, 비우고 새로 apply하게 되면, 사라질 것이다.
이러한 구조로 모듈을 설계하면, NAT Gateway와 라우팅 테이블 엔트리를 조건부터 생성할 수 있게 되고, 자동화 도구와 추후 연계하여 비용을 절감할 수 있을 것이다.

🖥️ Terraform 코드

Module

이 모듈은 natgw_azs가 한 개 이상의 요소를 가질 때 Regional NAT Gateway를 생성한다.
natgw_azs가 비어있다면, NAT Gateway는 apply시에 없는 상태여야 한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166


# main.tf
locals {
 nat_enabled = length(var.natgw_azs) > 0
}

#########
## VPC ##
#########
resource "aws_vpc" "vpc" {
 cidr_block = var.cidr_block
 enable_dns_support = true
 enable_dns_hostnames = true

 tags = {
 Name = "${var.cluster_name}-vpc"
 }
}

#############
## Subnets ##
#############
resource "aws_subnet" "public" {
 for_each = var.public_subnets

 vpc_id = aws_vpc.vpc.id
 cidr_block = each.value.cidr
 availability_zone = var.azs[each.value.az]
 map_public_ip_on_launch = false

 tags = {
 Name = "${var.cluster_name}-public-subnet-${each.key}"
 "kubernetes.io/role/elb" = "1"
 }
}

resource "aws_subnet" "private" {
 for_each = var.private_subnets

 vpc_id = aws_vpc.vpc.id
 cidr_block = each.value.cidr
 availability_zone = var.azs[each.value.az]
 map_public_ip_on_launch = false

 tags = {
 Name = "${var.cluster_name}-private-subnet-${each.key}"
 "kubernetes.io/role/internal-elb" = "1"
 }
}

resource "aws_subnet" "db" {
 for_each = var.db_subnets

 vpc_id = aws_vpc.vpc.id
 cidr_block = each.value.cidr
 availability_zone = var.azs[each.value.az]
 map_public_ip_on_launch = false

 tags = {
 Name = "${var.cluster_name}-db-subnet-${each.key}"
 }
}

#################
## IGW & NATGW ##
#################
resource "aws_internet_gateway" "igw" {
 vpc_id = aws_vpc.vpc.id

 tags = {
 Name = "${var.cluster_name}-igw"
 }
}

# Create EIPs for each azs
resource "aws_eip" "regional_nat" {
 for_each = local.nat_enabled ? toset([
 for az in var.natgw_azs : var.azs[az]
 ]) : []

 domain = "vpc"

 tags = {
 Name = "${var.cluster_name}-regional-nat-${each.key}"
 }
}

# NAT Gateway: created when len(natgw_azs) > 0
resource "aws_nat_gateway" "regional_natgw" {
 count = local.nat_enabled ? 1 : 0

 vpc_id = aws_vpc.vpc.id
 availability_mode = "regional"

 # Associate EIP alloc & NATGW
 dynamic "availability_zone_address" {
 for_each = aws_eip.regional_nat

 content {
 availability_zone = availability_zone_address.key
 allocation_ids = [availability_zone_address.value.id]
 }
 }

 tags = {
 Name = "${var.cluster_name}-regional-natgw"
 }
}

###############################
## Route Table & Association ##
###############################
resource "aws_route_table" "public_rtb" {
 vpc_id = aws_vpc.vpc.id
 route {
 cidr_block = "0.0.0.0/0"
 gateway_id = aws_internet_gateway.igw.id
 }
 tags = {
 Name = "${var.cluster_name}-public-rtb"
 }
}

resource "aws_route_table" "private_rtb" {
 vpc_id = aws_vpc.vpc.id

 # Create route entry for NATGW if presents
 # aws_nat_gateway.regional_nat returns array, because of `count`
 dynamic "route" {
 for_each = local.nat_enabled ? [1] : []

 content {
 cidr_block = "0.0.0.0/0"
 nat_gateway_id = aws_nat_gateway.regional_natgw[0].id
 }
 }

 tags = {
 Name = "${var.cluster_name}-private-rtb"
 }
}

resource "aws_route_table" "db_rtb" {
 vpc_id = aws_vpc.vpc.id

 tags = {
 Name = "${var.cluster_name}-db-rtb"
 }
}

resource "aws_route_table_association" "public_rtb" {
 for_each = aws_subnet.public
 subnet_id = each.value.id
 route_table_id = aws_route_table.public_rtb.id
}

resource "aws_route_table_association" "private_rtb" {
 for_each = aws_subnet.private
 subnet_id = each.value.id
 route_table_id = aws_route_table.private_rtb.id
}

resource "aws_route_table_association" "db_rtb" {
 for_each = aws_subnet.db
 subnet_id = each.value.id
 route_table_id = aws_route_table.db_rtb.id
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44


# variables.tf
variable "cluster_name" {
 description = "Kubernetes cluster name for prefix"
 type = string
}

variable "azs" {
 description = "Availability zone aliases"
 type = map(string)
}

variable "cidr_block" {
 description = "CIDR block for vpc."
 type = string
}

variable "public_subnets" {
 description = "Public subnets"
 type = map(object({
 cidr = string
 az = string
 }))
}

variable "private_subnets" {
 description = "Private subnets"
 type = map(object({
 cidr = string
 az = string
 }))
}

variable "db_subnets" {
 description = "DB subnets"
 type = map(object({
 cidr = string
 az = string
 }))
}

variable "natgw_azs" {
 description = "EIP alloc az for NATGW"
 type = list(string)
}

Usage

아래는 모듈을 사용하는 예시이다. natgw_azs를 조절하여 NAT Gateway를 토글할 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


# main.tf

#######
# VPC #
#######
module "vpc" {
 source = "../../../modules/vpc"
 cluster_name = var.cluster_name
 cidr_block = local.vpc_cidr
 azs = {
 a = "ap-northeast-2a"
 c = "ap-northeast-2c"
 }
 public_subnets = {
 a = {
 cidr = "10.1.0.0/24"
 az = "a"
 }
 c = {
 cidr = "10.1.1.0/24"
 az = "c"
 }
 }
 private_subnets = {
 a = {
 cidr = "10.1.100.0/24"
 az = "a"
 }
 c = {
 cidr = "10.1.101.0/24"
 az = "c"
 }
 }
 db_subnets = {
 a = {
 cidr = "10.1.200.0/24"
 az = "a"
 }
 c = {
 cidr = "10.1.201.0/24"
 az = "c"
 }
 }
 # When reducing the number of NAT gateway AZs,
 # it is safer to first set `natgw_azs` to an empty list and apply,
 # then recreate the NAT gateway with the desired AZs.
 natgw_azs = ["a", "c"]
}

📚 References

AWS STS: AssumeRole - 단기 자격증명으로 AWS Service에 접근하는법

Fri, 10 Apr 2026 13:49:23 +0900

🔑 AWS Security Token Service (STS)란?

AWS Security Token Service (STS)는 IAM user 또는 role에 단기자격증명을 부여하는 AWS 서비스이다.
이러한 자격증명은 액세스 키와 같은 장기자격증명의 사용을 줄이고, 최소권한부여를 사용하도록 유도하게 된다.

❓ AWS STS를 쓰는 이유

AssumeRole을 이용하면, 액세스 키와 같은 장기자격증명을 배포하는 것을 막을 수 있다.
임시자격증명은 자동으로 만료되고 롤링되기에, 더 안전하다.
STS는 다중계정간 자격증명을 교환하는 데에 사용된다.
최소권한원칙을 따르기 쉬운 구조이다.
SSO, OAuth등과 같은 페더레이션을 지원한다.

⚙️ AssumeRole의 동작방식

사용자, 애플리케이션, 또는 AWS 서비스가 IAM Role을 맡도록 요청을 보낸다.
AWS는 Role의 신뢰 정책(trust policy) 으로 해당 요청자가 그 Role을 받는 것이 허용되었는지 검사한다.
만약 허용된다면, STS는 다음의 임시 자격증명 정보를 제공한다:
- Access key ID
- Secret access key
- Session token
요청자는 임시자격증명으로 AWS 자원에 접근할 수 있게 된다.
해당 자격증명은 세션 유지기간이후 만료된다.

🚀 유스 케이스

다중계정간 액세스
CI/CD 파이프라인
AWS 워크로드에 자격증명 부여
임시로 권한상승을 받는경우 등

💻 Terraform 예시

아래 예시는 EC2 인스턴스에 IAM Role로 S3에 접근할 수 있게 되는 예시를 보여준다.
EC2인스턴스에 Access Key ID나 Secrey Access Key를 주지 않고 S3에 접근할 수 있게 된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142


provider "aws" {
 region = "ap-northeast-2"
}

# --------------------------------------------------
# S3 bucket
# --------------------------------------------------
resource "aws_s3_bucket" "app_bucket" {
 # bucket name must be unique
 bucket = "my-sts-demo-bucket-1234567890"
}

resource "aws_s3_bucket_public_access_block" "app_bucket" {
 bucket = aws_s3_bucket.app_bucket.id

 block_public_acls = true
 block_public_policy = true
 ignore_public_acls = true
 restrict_public_buckets = true
}

# --------------------------------------------------
# IAM role for EC2
# EC2 can assume this role
# --------------------------------------------------
data "aws_iam_policy_document" "ec2_assume_role" {
 statement {
 effect = "Allow"

 actions = ["sts:AssumeRole"]

 principals {
 type = "Service"
 identifiers = ["ec2.amazonaws.com"]
 }
 }
}

resource "aws_iam_role" "ec2_s3_role" {
 name = "ec2-s3-access-role"
 # Trust Policy
 assume_role_policy = data.aws_iam_policy_document.ec2_assume_role.json
}

# --------------------------------------------------
# Policy: allow EC2 role to read objects from S3
# --------------------------------------------------
data "aws_iam_policy_document" "s3_read_policy" {
 statement {
 effect = "Allow"

 actions = [
 "s3:ListBucket"
 ]

 resources = [
 aws_s3_bucket.app_bucket.arn
 ]
 }

 statement {
 effect = "Allow"

 actions = [
 "s3:GetObject"
 ]

 resources = [
 "${aws_s3_bucket.app_bucket.arn}/*"
 ]
 }
}

resource "aws_iam_policy" "s3_read_policy" {
 name = "ec2-s3-read-policy"
 policy = data.aws_iam_policy_document.s3_read_policy.json
}

resource "aws_iam_role_policy_attachment" "attach_s3_read" {
 role = aws_iam_role.ec2_s3_role.name
 policy_arn = aws_iam_policy.s3_read_policy.arn
}

# --------------------------------------------------
# Instance profile for EC2
# --------------------------------------------------
resource "aws_iam_instance_profile" "ec2_profile" {
 name = "ec2-s3-instance-profile"
 role = aws_iam_role.ec2_s3_role.name
}

# --------------------------------------------------
# Networking (simple example)
# Replace with your existing VPC/subnet/security group if needed
# --------------------------------------------------
data "aws_vpc" "default" {
 default = true
}

data "aws_subnets" "default" {
 filter {
 name = "vpc-id"
 values = [data.aws_vpc.default.id]
 }
}

resource "aws_security_group" "ec2_sg" {
 name = "ec2-s3-demo-sg"
 description = "Security group for EC2 S3 demo"
 vpc_id = data.aws_vpc.default.id

 ingress {
 description = "SSH"
 from_port = 22
 to_port = 22
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }

 egress {
 from_port = 0
 to_port = 0
 protocol = "-1"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

# --------------------------------------------------
# EC2 instance
# Replace ami with one valid in your region
# --------------------------------------------------
resource "aws_instance" "app" {
 ami = var.ami
 instance_type = "t3.micro"
 subnet_id = data.aws_subnets.default.ids[0]
 vpc_security_group_ids = [aws_security_group.ec2_sg.id]
 iam_instance_profile = aws_iam_instance_profile.ec2_profile.name

 tags = {
 Name = "sts-demo-ec2"
 }
}

👍 Best Practices

장기 액세스 키 대신 임시자격증명을 이용
Role의 권한에 최소권한원칙을 적용
넓은 principal에게 assume되지 않도록, trust policy를 명확히
적절한 세션 길이를 유지
외부 계정과 연동 시, external ID를 사용
CloudTrail로 role사용을 모니터링

📚 References

AWS ECR - Pull Through Cache + VPC Endpoint로 컨테이너 비용절감

Fri, 20 Mar 2026 14:41:13 +0900

캡스톤디자인 프로젝트를 하는데, 예산 문제로 EKS 클러스터를 매일 올리고 내려야 하는 상황에 도달했다.
EKS의 Control Plane 비용만 해도, 서울 리전 기준 $0.10 / hr이기 때문이다.
그래서 작업할 때에만 클러스터를 올리고, 내려야 하며, NAT Gateway도 야간에는 내리는 방식의 운영을 하려고 한다.
RDS는 suspend를, elasticache는 서버리스를 쓸 것 같다.

그러나, 한 가지 함정이 있었다.
매일 새로운 클러스터가 똑같은 이미지들을 풀링하는 것이다.
각종 운영도구들 말이다.
Cilium, GitOps, Observability 등의 동일한 컨테이너 이미지들을 매일 받아야 한다.
Docker Hub, Quay, ghcr.io, k8s.io, Public ECR 등, 여러 이미지들을 Pull 해와야 하는데, 이들을 모두 NAT Gateway를 통해서 노드가 받아온다.
즉, NAT Gateway에서 추가 트래픽 비용이 발생한다.
이를 방지하기 위해, ECR에 캐시 레지스트리르 만들고, VPC Endpoint로 비용을 줄여보고자 한다.

📏 ECR Pull Through Cache Rule

Pull Through Cache Rule은 직접 레지스트리를 만들지 않는다.
이후, 첫 pull 요청이 오면, 이용하는 인스턴스(EC2, ECS, EKS 등)는 실제 Private Registry를 만들고, 원본 이미지를 받아오도록 요청한다.
이후 다른 이미지들도 그렇게 누적되면서, 그 Private Registry에 다른 캐시들도 쌓인다.

룰 사용을 위해 필요한 것들

AWS ECR은 업스트림으로부터 컨테이너의 캐시 레지스트리를 만드는 것을 지원한다.
해당 레지스트리를 이용하는 주체(ECS, EKS 등)는 다음의 권한을 가져야 있는 것이 좋다:

ecr:BatchImportUpstreamImage: 외부 이미지를 받고 프라이빗 레지스트리에 저장시키는 것을 요청
ecr:CreateRepository: 프라이빗 레지스트리를 만들기 위한 권한, 레지스트리 자체가 없는 경우 필요

또한, ECR로부터 이미지를 받기 위해서는 다음의 권한도 가져야 한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
 "Version":"2012-10-17",
 "Statement": [
 {
 "Effect": "Allow",
 "Action": [
 "ecr:BatchCheckLayerAvailability",
 "ecr:BatchGetImage",
 "ecr:GetDownloadUrlForLayer",
 "ecr:GetAuthorizationToken"
 ],
 "Resource": "*"
 }
 ]
}

Pull Through Cache Rule을 만드는 주체는 ecr:CreatePullThroughCacheRule이 있어야 한다. \

업스트림 레지스트리에서 자격 증명을 요구한다면, secrets manager를 이용해서 값을 넣어야 한다. \

Secret의 이름은 ecr-pullthroughcache/로 시작해야 한다.
해당 시크릿과 Pull Through Cache Rule의 리전이 일치해야 한다.

업스트림 레지스트리

업스트림 레지스트리들은 다음과 같다:

public.ecr.aws: ECR Public
{registryId}.dkr.ecr.{region}.amazonaws.com: ECR Private
registry.k8s.io: Kubernetes
quay.io: Quay
cgr.dev: ChainGuard
ghcr.io: GitHub Container Registry
{custom}.azurecr.io: Azure Container Registry
registry.gitlab.com: GitLab Container Registry

Repository Prefix

Pull Through Cache 레포지토리는 캐시 저장소 경로와 upstream 저장소 경로 사이의 prefix 변환 규칙을 설정할 수 있다. \

ECR repository prefix: ECR 측에서 사용자가 pull 할 때 보는 캐시 레지스트리의 prefix이다.
Upstream repository prefix: 원본 upstream registry측의 저장소 이름 prefix이다.

ROOT라는 특별한 키워드가 있는데, 이는 별도 prefix가 없음을 말한다.
예시로, 다음의 변환들을 볼 수 있다:

Cache(ECR repository) namespace	Upstream namespace	Mapping
ecr-public	ROOT(default)	`ecr-public/my-app/image1` -> `ecr-public/my-app/image1`
ROOT	ROOT	`my-app/image1` -> `my-app/image1`
team-a	team-a	`ecr-public/my-app/image1` -> `ecr-public/my-app/image2`
my-app	upstream-app	`my-app/image1` -> `upstream-app/image1`

NOTE Prefix의 끝에는 자동으로 /가 적용된다.
즉, ecr-public이라고 적으면, ECR은 ecr-public/이라고 인식한다.

🍱 ECR Repository Creation Template

ECR Repository Creation Template은 최초 푸시 시 생성, Pull through Cache, 복제 등의 작업에서 여러 구성 설정을 적용시키기 위한 미리 정의해두는 탬플릿이다.
Prefix로 매칭된다.

이미지 태그의 mutable설정, 암호화 설정, 레포지토리 정책, 태그, lifecycle policy, IAM Role할당 등을 할 수 있다.

⏳ Lifecycle Policy

Amazon ECR에서는 컨테이너 이미지의 생명 주기 관리를 하여 비용 절감이 가능하다.
lifecycle policy가 레포지토리에 적용되면,

사용자가 lifecycle policy 규칙을 생성
rule을 저장하고 미리 preview로 확인한다.
확인 후 policy를 적용한다.
적용 후에는 조건을 만족한 이미지가 24시간 이내에 처리된다.

Rule들은 priority가 있으며, 낮은 순서가 우선순위이다.
그러나, ECR의 evaluator는 모든 이미지들에 모든 규칙들을 적용하여 검사하고, 이후 우선순위에 따라 적용한다. \

생명주기는 이미지를 제거하는 방법만 있지 않고, 다른 방법도 존재한다.

expire: 완전히 삭제
archive: 보관 상태로 전환

Rule은 json으로 작성되며, 아래의 포맷을 가진다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


{
 "rules": [
 {
 "rulePriority": integer,
 "description": "string",
 "selection": {
 "tagStatus": "tagged"|"untagged"|"any",
 "tagPatternList": list<string>,
 "tagPrefixList": list<string>,
 "storageClass": "standard"|"archive",
 "countType": "imageCountMoreThan"|"sinceImagePushed"|"sinceImagePulled"|"sinceImageTransitioned",
 "countUnit": "string",
 "countNumber": integer
 },
 "action": {
 "type": "expire"|"transition",
 "targetStorageClass": "archive"
 }
 }
 ]
}

여러 예제들은 여기에서 확인가능하다.

여러 주의할 점들이 있다:

tagPatternList 또는 tagPrefixList는 tagged에서 반드시 사용되어야 한다.
tagPatternList와 tagPrefixList는 같이 사용할 수 없다
tagPatternList와 tagPrefixList의 값들은 AND조건으로 맞아야 한다.
예를 들어, tagPrefixList = ["prod", "stable"]이면, 해당 이미지는 prod로 시작하는 태그와 stable로 시작하는 태그 모두 있어야 한다.
untagged 이미지들에 대한 정책은 하나의 storageClass만을 선택해야 한다.
시간 기준은 항상 최신 이미지들이 남는다
any의 경우, 정책 리스트에서 맨 아래에 있어야 한다.
sinceImagePulled는 바로 expire될 수 없다.
대신, transition으로 archive stroageClass로 전이시킨 뒤, 이후 expire시키는 패턴을 사용할 수 있다.

✨ VPC Endpoint

기본적으로 필요한 VPC Endpoint들

VPC Endpoint로 ECR에 비용 효율적으로 컨테이너를 받아올 수 있다.

com.amazonaws.{region}.ecr.dkr: Docker client 명령(pull, push)등에 대한 API를 위해 사용
com.amazonaws.{region}.ecr.api: ECR API에 대해 연결(DescribeImages나 CreateRepository와 같은 API)

이 두 가지 Endpoint들에 대해서, Private DNS Name 옵션을 켜줘야 한다.
또한, Endpoint의 ENI들에 적용할 보안그룹에서는 Ingress로 tcp 443, 즉 https를 허용해야 한다.

그러나, 이들만으로는 부족한데, ECR은 Amazon S3에 이미지 레이어들을 저장하기에, S3 gateway endpoint까지 필요하다.
엔드포인트명은 com.amazonaws.{region}.s3이다.

EKS에서 필요한 VPC Endpoint들

이외에도, EKS를 사용한다면, 아래 표에서 더 많은 VPC Endpoint들을 고려해볼 수 있다:

Service	Endpoint
Amazon EC2	`com.amazonaws.{region}.ec2`
Amazon ECR	`com.amazonaws.{region}.ecr.api`, `com.amazonaws.{region}.ecr.dkr`, `com.amazonaws.{region}.s3`
Amazon ALB	`com.amazonaws.{region}.elasticloadbalancing`
(Optional) AWS X-ray	`com.amazonaws.{region}.xray`
(Optional) AWS SSM	`com.amazonaws.{region}.ssm`
Amazon CloudWatch Logs	`com.amazonaws.{region}.logs`
Amazon STS(Security Token Service)	`com.amazonaws.{region}.sts`
Amazon EKS Auth(required when using Pod Identity associations)	`com.amazonaws.{region}.eks-auth`
Amazon EKS	`com.amazonaws.{region}.eks`

🫟 Terraform 코드 예시

Pull Through Cache 생성

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151


locals {
 # 자격증명들
 cache_creds = {
 docker-hub = {
 username = var.dockerhub_username
 accessToken = var.dockerhub_access_token
 }
 ghcr = {
 username = var.ghcr_username
 accessToken = var.ghcr_access_token
 }
 }

 # Pull through cache rule들 정보를 map형태로
 pull_through_cache_rules = {
 k8s = {
 upstream_registry_url = "registry.k8s.io"
 needs_auth = false
 }
 ecr-public = {
 upstream_registry_url = "public.ecr.aws"
 needs_auth = false
 }
 quay = {
 upstream_registry_url = "quay.io"
 needs_auth = false
 }
 ghcr = {
 upstream_registry_url = "ghcr.io"
 needs_auth = true
 }
 docker-hub = {
 upstream_registry_url = "registry-1.docker.io"
 needs_auth = true
 }
 }
}

## ECR Caches for external registries

# 시크릿
# 기본 KMS(AWS Managed Key) 사용중
# 필요시 CMK(Customer Managed Key) 사용가능
resource "aws_secretsmanager_secret" "cache_cred" {
 for_each = local.cache_creds
 name = "ecr-pullthroughcache/${each.key}"
 description = "Credentials for ECP pull through cache: ${each.key}"
}

# 시크릿 정보 저장
# 주의: secret_version을 이용한 이러한 방법은 tfstate에 시크릿 정보가 저장될 수 있음
# 그래서 시크릿 데이터 자체는 IaC를 이용하지 않는 경우도 있음
resource "aws_secretsmanager_secret_version" "cache_cred" {
 for_each = local.cache_creds
 secret_id = aws_secretsmanager_secret.cache_cred[each.key].id
 secret_string = jsonencode({
 username = each.value.username
 accessToken = each.value.accessToken
 })
}

# Pull through cache rule
# locals에있는 레지스트리정보들마다 생성
# Template의 prefix와 맞춤
resource "aws_ecr_pull_through_cache_rule" "cache" {
 for_each = local.pull_through_cache_rules

 ecr_repository_prefix = each.key
 upstream_registry_url = each.value.upstream_registry_url

 credential_arn = each.value.needs_auth ? aws_secretsmanager_secret.cache_cred[each.key].arn : null

 # 실제 version이 생긴 이후에 생성되어야 하므로 depends_on을 넣음
 depends_on = [
 aws_secretsmanager_secret_version.cache_cred
 ]

}

# Template
# Pull through cache에서 생성됨
# 태그는 IMMUTABLE
# prefix는 pull_through_cache_rule의 prefix와 맞춤
resource "aws_ecr_repository_creation_template" "cache_template" {
 for_each = local.pull_through_cache_rules

 prefix = each.key

 description = "Template for cache registries"
 image_tag_mutability = "IMMUTABLE"

 applied_for = [
 "PULL_THROUGH_CACHE",
 ]

 # 기본암호화. 필요하다면 KMS + CMK암호화로 컴플라이언스 준수 가능.
 encryption_configuration {
 encryption_type = "AES256"
 }

 # 생명주기 정책
 # 1. Untagged 이미지: push된지 5일 지나면 정리(expire)
 # 2. tagged 이미지: 마지막으로 pull된지 30일이 지나면 archive, 180이후 정리
 lifecycle_policy = jsonencode({
 rules = [
 {
 rulePriority = 1
 description = "Expire untagged images older than 5 days"
 selection = {
 tagStatus = "untagged"
 countType = "sinceImagePushed"
 countUnit = "days"
 countNumber = 5
 }
 action = {
 type = "expire"
 }
 },
 {
 rulePriority = 2
 description = "Archive images not pulled for 30 days"
 selection = {
 tagStatus = "tagged"
 tagPatternList = ["*"]
 countType = "sinceImagePulled"
 countUnit = "days"
 countNumber = 30
 }
 action = {
 type = "transition"
 targetStorageClass = "archive"
 }
 },
 {
 rulePriority = 3
 description = "Expire archived images after 180 days in archive"
 selection = {
 tagStatus = "tagged"
 tagPatternList = ["*"]
 storageClass = "archive"
 countType = "sinceImageTransitioned"
 countUnit = "days"
 countNumber = 180
 }
 action = {
 type = "expire"
 }
 }
 ]
 })
}

VPC Endpoint 정의

VPC Endpoint 모듈 정의

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# 엔드포인트 타입에 따라 필요한 인자가 달라질 수 있음
resource "aws_vpc_endpoint" "this" {
 for_each = var.endpoints

 vpc_id = var.vpc_id
 service_name = each.value.service_name
 vpc_endpoint_type = each.value.endpoint_type

 private_dns_enabled = each.value.endpoint_type == "Interface" ? try(each.value.private_dns_enabled, true) : null
 subnet_ids = each.value.endpoint_type == "Interface" ? try(each.value.subnet_ids, null) : null
 security_group_ids = each.value.endpoint_type == "Interface" ? try(each.value.security_group_ids, null) : null
 route_table_ids = each.value.endpoint_type == "Gateway" ? try(each.value.route_table_ids, null) : null

 policy = try(each.value.policy, null)
 ip_address_type = try(each.value.ip_address_type, null)

 tags = merge(
 var.tags,
 try(each.value.tags, {}),
 {
 Name = each.key
 }
 )
}

입력 변수

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


variable "vpc_id" {
 description = "VPC ID"
 type = string
}

variable "tags" {
 description = "Global Tags for endpoints"
 type = map(string)
 default = {}
}

variable "endpoints" {
 description = "Endpoint Informations"
 type = map(object({
 service_name = string
 endpoint_type = string
 private_dns_enabled = optional(bool)
 subnet_ids = optional(list(string), [])
 security_group_ids = optional(list(string), [])
 route_table_ids = optional(list(string), [])
 policy = optional(string)
 ip_address_type = optional(string)
 tags = optional(map(string), {})
 }))
}

모듈 사용

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79


# VPC Endpoints

# 보안그룹 생성
resource "aws_security_group" "vpce" {
 vpc_id = module.vpc.vpc_id
 name = "allow-private-subnets"
 description = "Allow traffic from private subnets"
}

# ingress 룰 생성
resource "aws_vpc_security_group_ingress_rule" "allow_vpc" {
 security_group_id = aws_security_group.vpce.id

 cidr_ipv4 = var.vpc_cidr
 ip_protocol = "tcp"
 from_port = 443
 to_port = 443
}

module "vpc-endpoints" {
 source = "../../modules/vpc-endpoint" # 모듈 파일 참조 주의
 vpc_id = module.vpc.vpc_id
 endpoints = {
 ec2 = {
 service_name = "com.amazonaws.ap-northeast-2.ec2"
 endpoint_type = "Interface"
 private_dns_enabled = true
 subnet_ids = module.vpc.private_subnet_ids
 security_group_ids = [aws_security_group.vpce.id]
 }
 ecr_api = {
 service_name = "com.amazonaws.ap-northeast-2.ecr.api"
 endpoint_type = "Interface"
 private_dns_enabled = true
 subnet_ids = module.vpc.private_subnet_ids
 security_group_ids = [aws_security_group.vpce.id]
 }
 ecr_dkr = {
 service_name = "com.amazonaws.ap-northeast-2.ecr.dkr"
 endpoint_type = "Interface"
 private_dns_enabled = true
 subnet_ids = module.vpc.private_subnet_ids
 security_group_ids = [aws_security_group.vpce.id]
 }
 s3 = {
 service_name = "com.amazonaws.ap-northeast-2.s3"
 endpoint_type = "Gateway"
 route_table_ids = [module.vpc.private_route_table_id]
 }
 cloudwatch_logs = {
 service_name = "com.amazonaws.ap-northeast-2.logs"
 endpoint_type = "Interface"
 private_dns_enabled = true
 subnet_ids = module.vpc.private_subnet_ids
 security_group_ids = [aws_security_group.vpce.id]
 }
 sts = {
 service_name = "com.amazonaws.ap-northeast-2.sts"
 endpoint_type = "Interface"
 private_dns_enabled = true
 subnet_ids = module.vpc.private_subnet_ids
 security_group_ids = [aws_security_group.vpce.id]
 }
 eks_auth = {
 service_name = "com.amazonaws.ap-northeast-2.eks-auth"
 endpoint_type = "Interface"
 private_dns_enabled = true
 subnet_ids = module.vpc.private_subnet_ids
 security_group_ids = [aws_security_group.vpce.id]
 }
 eks = {
 service_name = "com.amazonaws.ap-northeast-2.eks"
 endpoint_type = "Interface"
 private_dns_enabled = true
 subnet_ids = module.vpc.private_subnet_ids
 security_group_ids = [aws_security_group.vpce.id]
 }
 }
}

References

Cilium - Gateway API

Wed, 18 Mar 2026 10:32:11 +0900

🛣️ Cilium Gateway API

Cilium Gateway API는 두 가지 모드를 지원한다:

Standalone DaemonSet mode: 각 노드마다 별도의 Envoy를 실행
Embedded mode: Cilium Agent에 Envoy를 내장

기본적으로 신규 설치에서는 Standalone DaemonSet mode를 사용한다.
helm values에서 envoy.enabled를 false로 설정하면 Embedded mode로 변경할 수 있다.

1
2
3
4
5
6
7
8


envoy:
 # @schema
 # type: [null, boolean]
 # @schema
 # -- Enable Envoy Proxy in standalone DaemonSet.
 # This field is enabled by default for new installation.
 # @default -- `true` for new installation
 enabled: ~

다른 Controller들과의 차이점

구현이 CNI와 결합이 얼마나 되었는가의 차이가 가장 크다.
Cilium에게는 Ingress와 Gateway API는 네트워킹 스택의 일부이고, 다른 컨트롤러들과는 다르게 동작한다.
다른 Ingress 또는 Gateway API 컨트롤러는 Deployment 또는 Daemonset으로 설치되어서 LoadBalancer 등으로 노출된다(Cilium도 가능하다)
Cilium의 Ingress와 Gateway API의 설정은 Loadbalancer 또는 NodePort로 노출되어 있거나, Host network로 노출될 수 있다.
트래픽이 도착하면, eBPF 코드는 트래픽을 가로채서 투명하게 Envoy로 전달한다.
CiliumNetworkPolicy와의 연동도 가능하다.

Cilium의 Ingress Config와 CiliumNetworkPolicy

Ingress와 Gateway API의 트래픽은 노드마다 있는 Envoy 프록시를 통해서 벡엔드 서비스에 도달한다.
노드의 Envoy 프록시는 eBPF 정책 엔진과 상호작용하는 특수 코드가 있어서, 정책을 조회할 수 있다.
수평 트래픽의 네트워크 정책을 조정할 수 있다.

그러나, ingress 설정에서는 추가 과정이 필요하다.
Envoy에 도착한 트래픽은 Cilium Policy Engine에서 특별한 ingress 신원을 가진다.
외부에서 오는 트래픽은 world라는 신원을 가진다.
네트워크 정책을 클러스터에 적용할 때, world → ingress → 목적지 pod의 신원 설정이 중요하다.

NOTE
Cilium을 통해 클러스터 내부에서 ingress controller를 사용하던, gateway api controller를 사용하던, envoy의 신원은 ingress이다.

Source IP 가시성

벡엔드가 어느 IP에서 요청왔는지 이해하는 것에 대해서는 대부분의 애플리케이션에서 중요한 일이다.
기본적으로, Cilium의 Envoy 인스턴스는 X-Forwarded-For 헤더를 붙여서 서버에 전달한다.
그리고, 신뢰할 수 있는 hop 수를 조정해서, 어떤 IP를 실제 클라이언트로 볼지 결정한다.

X-Forwarded-For에는 값이 여러 개 추가될 수가 있다.

1
2


# 순서대로 2, 1, 0번
X-Forwarded-For: 203.0.113.42, 10.0.0.5, 10.0.0.10

이 중에서 n번째 홉을 고르도록 해서, 맨 오른쪽 부터 0번이다.
기본 값은 0으로, Envoy의 바로 앞단의 IP를 본다는 뜻이다.
X-Envoy-External-Address에 실제 클라이언트 주소만 따로 떼어서 준다.

예를 들면, 앞단에 클라우드 로드 밸런서가 붙어있다면, trusted hops=1이어야 한다.
이외 네트워크 구성에 따라 신뢰할 수 있는 앞단의 홉 수를 조정할 수 있다.

홉의 수는 helm values에서 gatewayAPI.xffNumTrustedHops로 설정할 수 있다.

externalTrafficPolicy

Cilium의 Ingress(Ingress, Gateway API 모두)는 LoadBalancer 또는 NodePort서비스를 사용한다.

Service 오브젝트는 Client IP를 가시성에 관련된 필드가 하나 있다: externalTrafficPolicy이다.

기존의 Kubernetes에서의 externalTrafficPolicy는 다음과 같다:

Local: 로컬 노드의 Pod들에만 트래픽을 라우트한다.
- 이 때문에, kube-proxy를 쓰는 기존 다른 CNI의 클러스터는 source IP 가시성을 보장하는 유일한 방법이다.
- 이 경우, 노드들이 healthCheckNodePort를 열고, http://<nodeIP>:<healthCheckNodePort>/healthz로 요청을 보내면 로컬 Pod가 200을 응답할 것이고, 없으면 200이 아닌 응답을 보낼 것이다.
- 때문에 실제 Pod로 라우트가능한 노드만 로드밸런서가 보낼 수 있다.
Cluster: 노드는 클러스터 전역의 어디에도 트래픽을 보낼 수 있다.
- 업스트림 로드밸런서들은 트래픽을 아무 노드에나 보낼 수 있다는 것을 알고, source IP를 변환할지도 모른다.
- 즉, 대부분의 상황에서는 externalTrafficPolicy: Cluster는 벡엔드 Pod가 소스 IP를 안봐도 된다는 이야기이도 하다.

그러나, Cilium Ingress에서는 트래픽이 어느 노드로 와도 그 노드의 로컬 Envoy가 TPROXY로 원본 source IP를 유지한 채 받기 때문에, Cluster여도 client IP visibility를 확보할 수 있다.
또한 Envoy를 노출하는 Cilium Service에서는 Local이어도 모든 노드가 health check를 통과하도록 처리한다.

즉, 아래와 같다:

로컬 노드에 애플리케이션 backend Pod가 없어도
로컬 Envoy는 존재하고 health check도 통과
요청은 일단 그 로컬 Envoy가 받고
이후 클러스터의 다른 노드에 있는 backend endpoint로 전달 가능

TLS Passthrough 및 Source IP 가시성

Ingress와 Gateway API는 TLS Passthrough를 지원한다.
TLS Passthrough에서는 Envoy가 TLS를 종료하지 않고 TCP 프록시로 동작하므로, HTTP 헤더인 X-Forwarded-For를 추가할 수 없다.

Envoy는 TLS handshake의 ClientHello에 포함된 SNI(Server Name Indication) 를 보고 어떤 backend로 보낼지 결정한다.
이후 backend와 새로운 TCP 연결을 만들어 TLS 스트림을 그대로 전달하기 때문에, backend 입장에서는 source IP가 원래 클라이언트가 아니라 Envoy IP로 보이게 된다.

Host 네트워크 모드

Host 네트워크에 직접 연결하도록 노출할 수 있다.
LoadBalancer가 불가능한 상황에서 외부에 노출할 때 유용하다.

helm values에 아래와 같이 설정하면 된다:

1
2
3
4


gatewayAPI:
 enabled: true
 hostNetwork:
 enabled: true

한번 활성화되면, Gateway를 위한 호스트 네트워크 포트가 spec.listeners.port에 명시될 수 있다.
포트는 1023 이상이어야 한다.

Privileged Port로의 바인딩

기본적으로 Cilium L7 Envoy는 well-known포트를 쓸 권한이 없다.
만약 1023이하의 포트를 고르려면, Helm 값에서 envoy.securityContext.capabilities.keepCapNetBindService=true가 설정되었고, NET_BIND_SERVICE를 설정해야 한다.

Standalone DaemonSet mode 예시:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


gatewayAPI:
 enabled: true
 hostNetwork:
 enabled: true
envoy:
 enabled: true
 securityContext:
 capabilities:
 keepCapNetBindService: true
 envoy:
 # Add NET_BIND_SERVICE to the list (keep the others!)
 - NET_BIND_SERVICE

Embedded mode 예시:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


gatewayAPI:
 enabled: true
 hostNetwork:
 enabled: true
envoy:
 securityContext:
 capabilities:
 keepCapNetBindService: true
securityContext:
 capabilities:
 ciliumAgent:
 # Add NET_BIND_SERVICE to the list (keep the others!)
 - NET_BIND_SERVICE

Gatewat API리스너를 노드의 서브셋으로 배포

Cilium Gateway API Envoy 리스터는 노드의 부분집합으로 노출될 수 있다.
host 네트워크 모드에서만 가능하고, node labelselector가 동작한다.

예시 values:

1
2
3
4
5
6
7
8


gatewayAPI:
 enabled: true
 hostNetwork:
 enabled: true
 nodes:
 matchLabels:
 role: infra
 component: gateway-api

Gateway API 주소 지원

Cilium Gateway는 Gateway API 스텍에 제공된 주소가 있다.
spec.addresses는 Gateway의 IP주소로 쓰인다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: my-gateway
spec:
 addresses:
 - type: IPAddress
 value: 172.18.0.140
 gatewayClassName: cilium
 listeners:
 - allowedRoutes:
 namespaces:
 from: Same
 name: web-gw
 port: 80
 protocol: HTTP

출력은 다음과 같이 예상된다:

1
2
3


$ kubectl get gateway my-gateway
NAME CLASS ADDRESS PROGRAMMED AGE
my-gateway cilium 172.18.0.140 True 2d7h

io.cilium/lb-ipam-ips를 spec.infrastructure.annotations를 IP설정에 썼다면, spec.addresses는 무시 될 것이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: my-gateway
spec:
 infrastructure:
 annotations:
 io.cilium/lb-ipam-ips: "172.18.0.141"
 addresses: # This will be ignored
 - type: IPAddress
 value: 172.18.0.140
 gatewayClassName: cilium
 listeners:
 - allowedRoutes:
 namespaces:
 from: Same
 name: web-gw
 port: 80
 protocol: HTTP

출력은 다음과 같다:

1
2
3


$ kubectl get gateway my-gateway
NAME CLASS ADDRESS PROGRAMMED AGE
my-gateway cilium 172.18.0.141 True 2d7h

🏃 Hands-On

CRD설치 및 helm values 설정

Gateway API CRD를 설치해야 한다.

1
2
3
4
5


kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_gatewayclasses.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_gateways.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_referencegrants.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/standard/gateway.networking.k8s.io_grpcroutes.yaml

TLSRoute(experimental)도 설치하고 싶다면, 아래와 같이 설치한다.

1

kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/gateway-api/v1.4.1/config/crd/experimental/gateway.networking.k8s.io_tlsroutes.yaml

gateway API가 활성화되어야 한다.

1
2


gatewayAPI:
 enabled: true # ingress.enabled = false로 되어야 한다.

데모 애플리케이션 생성

1
2
3
4
5
6
7
8


git clone https://github.com/fudoge/cilium-playground.git
cd cilium-playground

# gRPC 애플리케이션
kubectl apply -f grpc/grpc-app

# HTTP 애플리케이션
kubectl apply -f http/http-app

GatewayClass 생성

helm values에서 gatewayAPI.gatewayClass.create: auto로 설정하면 GatewayClass가 자동으로 생성된다. \

또는, 아래처럼 직접 만들 수있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
 name: example-gateway-class
spec:
 controllerName: io.cilium/gateway-controller # Cilium gateway의 controller name임
 description: The default Cilium GatewayClass
 parametersRef:
 group: cilium.io
 kind: CiliumGatewayClassConfig
 name: example-gateway-config
 namespace: default
---
apiVersion: cilium.io/v2alpha1
kind: CiliumGatewayClassConfig
metadata:
 name: example-gateway-config
 namespace: default
spec:
 service:
 type: LoadBalancer
---

NOTE
로드밸런서 또는 외부 노출은 L2 announcement또는 BGP Peering으로 광고하거나, 다른 방법이 없다면 NodePort를 사용해야 한다.

Gateway 생성

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: example-gateway
spec:
 gatewayClassName: example-gateway-class
 listeners:
 - protocol: HTTP
 port: 8080
 name: web-gw
 # 같은 네임스페이스의 route만 허용. 만약 다른 namespace의 route를 허용하고 싶다면 `All`로 설정한다.
 # 또는 matchLabels등을 사용할 수 있다.
 allowedRoutes:
 namespaces:
 from: Same
 - protocol: HTTP
 port: 50051
 name: grpc-gw
 allowedRoutes:
 namespaces:
 from: Same

grpc-gw도 HTTP 프로토콜임을 볼 수 있는데, gRPC도 http에서 동작하기 떄문이다.

Route 생성

HTTPRoute

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: http-test-app
spec:
 parentRefs:
 - name: example-gateway
 namespace: default
 sectionName: http-gw # listener의 name과 일치해야 한다.
 hostnames:
 - http-test.mynetwork.local
 rules:
 - matches:
 - path:
 type: PathPrefix
 value: /
 backendRefs:
 - name: http-test
 port: 8080

GRPCRoute

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
 name: grpc-test-app
spec:
 parentRefs:
 - name: example-gateway
 namespace: default
 sectionName: grpc-gw
 hostnames:
 - grpc-test.mynetwork.local
 rules:
 - matches:
 - method:
 service: test.v1.TestService
 method: Ping
 backendRefs:
 - name: grpc-test
 port: 50051

service와 method의 매칭은 아래 protobuf를 보면 이해 될 것이다.
서비스명은 패키지 포함 풀 네임이어야 하며, 메서드 이름도 정확히 맞춰야 한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


# proto/test/v1/test.proto
syntax = "proto3";

package test.v1;

option go_package = "test/v1;testv1";

service TestService {
 rpc Ping(PingRequest) returns (PingResponse);
}

message PingRequest {
 string message = 1;
}

message PingResponse {
 string message = 1;
 int64 server_time_ms = 2;
}

조회 및 요청 테스트

우선, service를 조회해보자.

1
2
3
4
5
6


$ kubectl get svc
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
cilium-gateway-example-gateway LoadBalancer 10.101.100.12 172.20.0.2 8080:31832/TCP,50051:31376/TCP 5m27s
grpc-test ClusterIP 10.105.48.100 <none> 50051/TCP 27m
http-test ClusterIP 10.96.66.40 <none> 8080/TCP 5d12h
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 17d

나는 /etc/hosts에서 EXTERNAL-IP를 추가해줬다.

1
2


# /etc/hosts
172.20.0.2 http-test.mynetwork.local grpc-test.mynetwork.local

이제, 요청을 보내보자.

1
2
3
4
5
6
7
8
9


# HTTP 요청
$ curl http-test.mynetwork.local:8080
hello from http server
method=GET path=/ time=2026-03-18T03:38:35Z

# gRPC 요청
# 데모 gRPC 서버에 대한 Client App: https://github.com/fudoge/cilium-playground/blob/main/grpc/grpc-app/cmd/client/main.go
$ go run main.go -addr grpc-test.mynetwork.local:50051
2026/03/18 12:38:33 response message="hello" server_time_ms=1773805113280

📚 Reference

Cilium - Gateway API
Cilium - Gateway API examples - 더 많은 예시들은 여기에서 볼 수있다.
Hands-On GitHub Source Code

Kubernetes - Gateway API

Wed, 18 Mar 2026 10:01:06 +0900

Gateway API는 동적인 인프라 프로비저닝과 강화된 트래픽 라우트를 지원하는 API이다.
쉽게 생각하면 Ingress를 현대적인 모델로 개선한 버전이라고 보면 된다.

⚠️ 기존 Ingress의 문제점

Ingress Controller를 사용하여 Ingress를 구현하는 방식은 여러가지 문제가 있었다:

한 리소스가 너무 많은 책임을 가진다
- 외부 노출
- 도메인
- TLS
- path별 라우팅
- 벡엔드 연결
리소스의 소유권이 모호하다
- 앱 팀이 수정하면 운영 정책도 같이 건드려지고, 운영팀이 관리하면 앱 팀의 배포 속도가 느려진다
Controller별로 다르게 구현되어 있어 일관성이 없다
너무 많은 것들이 annotation으로 구현되어 있어 유지보수가 어렵다

🧠 Gateway API의 설계 철학

Gateway API의 설계 철학은 다음과 같다:

Role-oriented Kubernetes service networking을 관리하는데 드는 보통의 조직의 역할모델을 그대로 가져왔다.
- Infrastructure Provider: 전체 시스템 플랫폼의 제공자. GatewayClass를 관리
- Cluster Operator: 실제 클러스터를 운영하는 사람. 클러스터 내부에서 운영 정책을 통제. Gateway를 관리
- Application Developer: 클러스터 내부에서 실행되는 애플리케이션을 관리. 어떤 host 및 path로 받을지, 어떤 service로 트래픽을 통하게할지 실제 흐름에 관심 HTTPRoute, GRPCRoute와 같은 CRD관리
Portable Custorm resources로 이루어져 있고, 다양한 구현체로 지원된다.
Expressive 기존 Ingress에서는 커스텀 annotation으로만 제공되던 특이기능들(e.g. 헤더기반 매칭, 트래픽 가중치)을 기본적으로 제공한다.
Extensible 기능 확장을 위해 별도 커스텀 리소스를 붙일 수 있는데, GatewayClass/Gateway/Route와 같은 적절한 계층에 연결하여 책임 범위에 맞는 세밀한 커스터마이징이 가능하다.

📦 리소스 모델

Gateway API는 4개의 안정적인 API가 있다:

GatewayClass: Gateway들의 Type을 정의한다. Gateway의 설계도/상품 카탈로그에 가깝다. (ex. cilium, aws-alb, istio, nginx 등)
Gateway: 실제 트래픽을 받는 구체적인 입구 인스턴스이다.
HTTPRoute: HTTP트래픽을 어떤 규칙으로 어떤 서비스에 보낼지 결정한다.
- host
- path
- header
- query parameter
- weight기반 분산
GRPCRoute: gRPC트래픽을 어디에 보낼지 정의한다.
- service/method기반 라우팅
이외에도 TCPRoute, UDPRoute, TLSRoute 등, 다양한 Route를 정의할 수 있다.

Gateway는 하나의 GatewayClass와 연관된다.
GatewayClass는 gateway controller를 정의한다.

여러 개의 Route들은 parentRefs로 Gateway에 붙는다.
Gateway는 listeners로 route들을 필터링할 수 있다.
이렇게 양방향의 신뢰 관계가 만들어진다.

🛣️ Gateway API CRD들

GatewayClass

Gateway는 여러 다양한 Controller들에 의해 구현될 수 있고, 설정이 다를 수 있다.
Gateway는 반드시 controller의 이름을 포함하는 GatewayClass를 참조해야 한다.

최소한은 GatewayClass는 다음과 같다:

1
2
3
4
5
6


apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
 name: example-class
spec:
 controllerName: example.com/gateway-controller

Gateway API는 스펙만 있고, 실제 동작은 구현체(Controller)가 한다.
GatewayClass는 어떤 컨트롤러가 이 클래스를 처리할지 선언하는 것이다.

Gateway

Gateway는 트래픽 핸들링 인프라의 인스턴스를 묘사한다.
필터링, 밸런싱, 스플릿 등의 정책을 정의할 수 있다.

아래는 일반적인 Gateway의 예시이다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: example-gateway
 namespace: example-namespace
spec:
 gatewayClassName: example-class
 listeners:
 - name: http
 protocol: HTTP
 port: 80
 hostname: "www.example.com"
 allowedRoutes:
 namespaces:
 from: Same

이 Gateway는 앞서 만든 example-class를 사용한다.

listeners로 어떤 트래픽을 어떻게 받을지 정의한다.
http라는 이름의 리스너 규칙이 있는데, 이는 www.example.com:80으로 들어오는 HTTP요청을 받을 준비가 된 논리적 수신 지점을 하나 가짐을 말한다.

allowedRoutes에서의 의미는, Gateway와 같은 namespace에 있는 Route만 붙을 수 있다는 의미이다.

spec.addresses가 설정되지 않았는데, 이는 구현체별 방식으로 적절한 주소를 할당할 수 있다는 의미이다.
실제 바인딩 주소는 status.addresses에 반영된다.
이 말은, 클라우드 구현체면, 외부 LB 주소나 DNS이름이 붙을 수 있고, 다른 구현체면 내부 프록시의 엔드포인트가 붙을 수 있다는 의미이다.

클라이언트는 Gateway에 할당된 주소로 요청을 보내고, 그 다음 Route가 그 요청을 Service로 연결한다는 뜻이다.

HTTPRoute

HTTPRoute는 라우팅 동작을 정의한다.
즉, 실제로 어느 서비스에 넘길지를 정의한다.

HTTPRoute가 새로 생기거나 변경되면, 클러스터 내부 proxy server 또는 cloud load balancer에 구성이 변경될 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: example-httproute
spec:
 parentRefs:
 - name: example-gateway
 hostnames:
 - "www.example.com"
 rules:
 - matches:
 - path:
 type: PathPrefix
 value: /login
 backendRefs:
 - name: example-svc
 port: 8080

이 HTTPRoute는 example-gateway에 붙고싶다는 의미이다.
이 예시에서는, example-gateway로부터 온 HTTP 트래픽에서, www.example.com Host 헤더를 달아 오고, /login path로 왔다면, example-svc의 8080으로 이동한다는 뜻이다.

GRPCRoute

gRPC요청을 어떤 벡엔드로 보낼지 정의하는 리소스이다.
gRPC는 HTTP/2를 전제로 하기에, GRPCRoute를 지원하는 Gateway는 반드시 HTTP/2를 처리할 수 있어야 한다.

단순한 예제는 아래와 같다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
 name: example-grpcroute
spec:
 parentRefs:
 - name: example-gateway
 hostnames:
 - "svc.example.com"
 rules:
 - backendRefs:
 - name: example-svc
 port: 50051

example-gateway로 들어온 svc.example.com대상 gRPC요청은 전부 example-svc:50051로 보낸다.

서비스/메서드를 매칭해보자:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


apiVersion: gateway.networking.k8s.io/v1
kind: GRPCRoute
metadata:
 name: example-grpcroute
spec:
 parentRefs:
 - name: example-gateway
 hostnames:
 - "svc.example.com"
 rules:
 - matches:
 - method:
 service: com.example
 method: Login
 backendRefs:
 - name: foo-svc
 port: 50051

여기서, spec.rules[0].matches[0].method.service는 K8s service가 아니라, gRPC service name을 말한다.
spec.rules[0].backendRefs[0].name의 foo-svc는 K8s Service를 말한다.

➡️ 요청 흐름

요청 흐름은 아래와 같다:

클라이언트가 http://www.example.com으로 HTTP요청 보냄
Client의 DNS리졸버는 Gateway에 대한 IP주소를 받음
Client는 Gateway에 요청. Gateway는 HTTPRoute를 기반으로 적절한 통신규약을 생성
(Optional) 헤더 및 경로기반으로 룰 매칭
(Optional) 헤더 제거 및 기타 필터링 작업 수행
backend에 통신 전달

🛸 구현체 예시

Cilium

📚 Reference

Cilium - BGP Peering

Thu, 12 Mar 2026 23:21:49 +0900

🧱 BGP Control Plane Resources

Cilium의 BGP Control Plane은 BGP Peer, Policy, advertisement 구성을 제공하는 유연한 커스텀 리소스들로부터 제공된다.

BGP Control Plane을 관리하기 위해, 다음의 자원들이 사용된다:

CiliumBGPClusterConfig: BGP 인스턴스와 피어링 구성을 정의한다. 여러 노드들에 적용된다.
CiliumBGPPeerConfig: BGP Peering의 일반적인 설정 셋으로, 여러 peer들간에 사용될 수 있다.
CiliumBGPAdvertisement: BGP Routing table에 주입되는 prefix들을 정의한다.
CiliumBGPNodeConfigOverride: node-specific한 BGP구성을 정의하여 더 나은 제어를 제공한다.

아래의 다이어그램으로 보여질 수 있다:

📜 BGP 클러스터 구성

CiliumBGPClusterConfig는 nodeSelector필드에 있는 1개 이상의 노드에 대한 BGP설정을 하는 곳이다.
각각의 CiliumBGPClusterConfig은 1개 이상의 BGP 인스턴스를 정의하며, 그들의 name필드에 대해 식별된다.

BGP 인스턴스는 1개 이상의 Peer를 가질 수 있다.
각 Peer는 name필드에 의해 식별된다.
Peer AS는 peerASN과 peerAddress필드에 의해 정의된다.

Peer의 구성 설정은 peerConfigRef필드로 참조할 수 있다.
peerConfigRef의 Group과 kind는 옵셔널하며, 기본적으로 cilium.io와 CiliumBGPPeerConfig이다.

기본적으로, BGP 컨트롤 플레인은 리스닝 포트 없이 동작한다.
설정된 Peering만 가능하다는 의미이며, 들어오는 Peering을 받을 수 없다는 뜻이다.

이게 기본인데, 그 이유는 같은 노드에서 BGP라우터가 동작할 수 있음을 고려했기 때문이다.
들어오는 커넥션을 받으려면, localPort필드로 리스닝 포트를 정할 수 있다.

NOTE
기본 BGP Port(179)를 쓸 때에는, CAP_NET_BIND_SERVICE가 필요하다.
만약 기본 포트를 쓰고싶다면, securityContext.capabilities.ciliumAgent에서 CAP_NET_BIND_SERVICE를 helm value로 넣어줘야 한다.

아래는 CiliumBGPClusterConfig의 예시이며, instance-65000이 두 개의 peer와 피어링한 것이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


apiVersion: cilium.io/v2
kind: CiliumBGPClusterConfig
metadata:
 name: cilium-bgp
spec:
 nodeSelector:
 matchLabels:
 rack: rack0
 bgpInstances:
 - name: "instance-65000"
 localASN: 65000
 localPort: 179
 peers:
 - name: "peer-65000-tor1"
 peerASN: 65000
 peerAddress: fd00:10:0:0::1
 peerConfigRef:
 name: "cilium-peer"
 - name: "peer-65000-tor2"
 peerASN: 65000
 peerAddress: fd00:11:0:0::1
 peerConfigRef:
 name: "cilium-peer"

Auto-Discovery

Cilium BGP Control Plane은 BGP Peer에 대한 자동 디스커버리 역시 지원한다.
mode에서 특정 특정 IP주소를 정할 수 있다.

DefaultGateway모드도 있다.
기본 게이트웨이를 이용하면, 자동으로 기본 게이트웨이와 BGP를 맺으려 한다.

아래와 같이 할 수 있다:

1
2
3
4
5
6
7
8
9


peers:
- name: "tor-switch"
 peerASN: 65000
 autoDiscovery:
 mode: "DefaultGateway"
 defaultGateway:
 addressFamily: ipv6 # ipv4, ipv4중에 가능
 peerConfigRef:
 name: "cilium-peer"

ToR switch의 BGP 구성에는 다음 설정을 해줘야 한다:

1
2
3
4


router bgp 65100
 neighbor CILIUM peer-group
 neighbor CILIUM local-as 65000 no-prepend replace-as
 bgp listen range fd00:10:0:1::/64 peer-group CILIUM

설정이 적용되면, Cilium은 특정 Address Family의 기본게이트웨이를 식별하여 자동으로 BGP 세션을 맺는다.
peerConfigRef 세션 파라미터를 참조하여 피어링을 맺는다.

default gateway설정 + multi-homing(두 개 이상의 BGP와 연결)일때는 같은 address family에 대해서 동시에 여러 BGP세션을 맺을 수 없다.
대신, 우선순위가 더 높은 (metric이 더 낮은)경로를 하나 선택하여 BGP 세션을 맺는다.

Cilium은 BGP 세션을 address family당 하나만 맺을 수 있다.
대신, failover로 연결가능한데, 처음에 아래와 같은 상황이라고 가정했을 때,

1
2


default via ToR A, metric 100
default via ToR B, metric 200

ToR A가 장애가 난다면, ToR B와 새로 BGP 세션을 맺는다.

아래 예시에서는, IP를 직접 명시하지 않았지만 기본 게이트웨이에서 가장 우선순위가 높은 하나를 고른다고 보면 된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


bgpInstances:
- name: "65001"
 localASN: 65001
 peers:
 - name: "instance-65001"
 peerASN: 65000
 autoDiscovery:
 mode: "DefaultGateway"
 defaultGateway:
 addressFamily: ipv6
 peerConfigRef:
 name: "cilium-peer"

대신, 같은 address family에서 여러 peer와 세션을 맺고 싶다면, 직접 두 peer를 명시해야 한다.

🛠️ BGP Peer Configuration

CiliumBGPPeerConfig 자원은 BGP Peer 연결설정을 정의할 때 사용한다.
여러 Peer와의 연결에서 같은 Configuration을 공유해서 사용할 수 있다.

여러 옵션을 가질 수 있다:

MD5 Password
Timers
EBGP Multihop
Graceful Restart
Transport
Address Families

아래는 예시이다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


apiVersion: cilium.io/v2
kind: CiliumBGPPeerConfig
metadata:
 name: cilium-peer
spec:
 timers:
 holdTimeSeconds: 9
 keepAliveTimeSeconds: 3
 authSecretRef: bgp-auth-secret
 ebgpMultihop: 4
 gracefulRestart:
 enabled: true
 restartTimeSeconds: 15
 families:
 - afi: ipv4
 safi: unicast
 advertisements:
 matchLabels:
 advertise: "bgp"

MD5 Password

AuthSecretRef는 RFC-2385의 TCP MD5 Password를 BGP Peering에 쓸 수 있다.

아래는 예시이다.

1
2
3
4
5
6


apiVersion: cilium.io/v2
kind: CiliumBGPPeerConfig
metadata:
 name: cilium-peer
spec:
 authSecretRef: bgp-auth-secret

AuthSecretRef는 BGP secrets namespace에 써야 한다.
(helm-chart 기본값은 kube-system)
password라는 키를 가져야 한다.
BGP 시크릿은 각 Cilium Agent 인스턴스가 최소로 쓸 수 있는 권한으로 제한되어있다.

만약 namespace를 바꾸고싶다면, helm chart의 bgpControlPlane.secretNamespace.name의 값을 바꾸면 된다.
생성도 자동으로 하고싶으면, bgpControlPlane.secretNamespace.create를 true로 해주면 된다.

패스워드가 틀리다면, dial: i/o timeout으로만 뜬다.
만약 authSecretRef의 시크릿을 찾을 수 없으면, BGP시션은 빈 패스워드를 쓰고, 아래와 같은 오류를 낸다:

1

level=error msg="Failed to fetch secret \"secretname\": not found (will continue with empty password)" component=manager.fetchPeerPassword subsys=bgp-control-plane

Timers

BGP Control Plane은 BGP timer 파라미터를 수정하는 것을 지원한다.

Name	Field	Default
ConnectRetryTimer	`connectRetryTimeSeconds`	120
HoldTimer	`holdTimeSeconds`	90
KeepaliveTimer	`keepAliveTimeSeconds`	30

장애 감지를 더 빠르게 하기 위해서는, HoldTimer와 KeepaliceTimer를 더 짧은 주기로 설정하는것을 권장한다.
최소수치인 holdTmeSeconds=9와 keepAliveTimeSeconds=3과 같은 식으로 할 수 있다.

Peer와 연결이 끊기고 빠르게 회복하려면, connectRetryTimeSeconds를 줄이면 된다.
내부적으로 랜덤 jitter가 적용되는데, [ConnectRetryTimeSeconds, 2 * CoonnectRetryTimeSeconds)이다.

1
2
3
4
5
6
7
8
9


apiVersion: cilium.io/v2
kind: CiliumBGPPeerConfig
metadata:
 name: cilium-peer
spec:
 timers:
 connectRetryTimeSeconds: 5
 holdTimeSeconds: 9
 keepAliveTimeSeconds: 3

EBGP Multihop

기본적으로 BGP 패킷의 IP TTL은 1인데, Multihop 설정을 위해서는, spec.ebgpMultihop을 1보다 크게 해주면 된다.

Graceful Restart

Graceful Restart 를 켜면, Cilium Agent가 재시작하는것과 같이 BGP 프로세스가 잠깐 내려가도, 실제 커널은 살아있어서 패킷 포워딩은 가능한 경우가 있다.

이때 route를 지우면 트래픽 중단이 불필요하게 생기니, 금방 다시 올라올 수 있다고 알려주는 capacity가 graceful restart이다.

Cilium이 BGP OPEN 메시지에서 graceful restart capacity를 광고
Peer는 재시작중에도 경로유지를 할 것을 약속
Cilium Agent가 재시작되는 동안, BGP 세션이 끊기는데,
Peer는 route를 RestartTime동안 유지
Cilium은 다시 BGP를 복구하면, 트래픽 중단없이 계속 이어짐
시간이 초과되면, 실제로 죽었다고 판단하고 route삭제

상대 라우터는 TCP FIN플래그 메시지를 받고, RestartTime 타이머를 시작한다.

1
2
3
4
5
6
7
8


apiVersion: cilium.io/v2
kind: CiliumBGPPeerConfig
metadata:
 name: cilium-peer
spec:
 gracefulRestart:
 enabled: true
 restartTimeSeconds: 15

RestartTime의 기본값은 120초이다.

Transport

transport는 TCP연결의 세부사항을 만진다. 기본 설정과 다르게 TCP연결을 설정할 때 사용한다.

1
2
3
4


spec:
 transport:
 peerPort: 179
 sourceInterface: lo

Address Families

families필드에는 AFI(Address Family Identifier) , SAFI(Subsequent Address Family Identifier) 의 리스트가 있다.

기본적으로, address family가 없다면, BGP Control Plane은 IPv4 Unicast와 IPv6 Unicast를 멀티프로토콜 확장 capability로 광고한다.

각 Address family에서는, advertisements label selector를 통해 라우트 광고를 제어할 수 있다.
CiliumBGPAdvertisement를 골라야 한다.

NOTE 매칭이 없으면, 아무 prefix도 광고될 수 없다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


apiVersion: cilium.io/v2
kind: CiliumBGPPeerConfig
metadata:
 name: cilium-peer
spec:
 families:
 - afi: ipv4
 safi: unicast
 advertisements:
 matchLabels:
 advertise: "bgp"
 - afi: ipv6
 safi: unicast
 advertisements:
 matchLabels:
 advertise: "bgp"

📢 BGP Advertisements

CiliumBGPAdvertisement자원은 다양한 광고 타입을 정할 수 있다.
advertisements label의 매칭은 Peer Configuration의 familes와 연관있다.

BGP Attributes

BGP path attributes를 advertisements[*]에 정의할 수 있다.

두 가지의 속성이 있는데, Communities와 LocalPreference이다.

Communities: BGP의 라우트 태그같은 개념이라고 보면 된다.
- standard는 :으로 32비트 숫자를 나누며, 16비트:16비트숫자를 쓰는 형식이다.
- wellknown은 standard와 같은 형식을 가지지만, well-known값에 대한 alias를 가진다.
  - ex. internet은 0:0, no-advertise는 “65535:65282”
- large는 3개의 4바이트정수가 콜론으로 나뉘어진다.
  - ex. 64512:100:50
Local Preference: iBGP에서의 내부 우선순위 값이며, eBGP peer에게는 무시될것이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: cilium.io/v2
kind: CiliumBGPAdvertisement
metadata:
 name: bgp-advertisements
 labels:
 advertise: bgp
spec:
 advertisements:
 - advertisementType: "PodCIDR"
 attributes:
 communities:
 standard: [ "65000:99" ] # Route에 65000:99 태그를 붙임
 localPreference: 99 # iBGP내부 선호값(값이 클수록 더 선호)

Advertisement Types

Cilium은 세 가지의 광고를 제공한다:

Pod CIDR range
Service VIPs
Interface IPs

Pod CIDR Ranges

노드의 Pod CIDR prefix를 광고할 수 있다.
BGP Peer가 로드밸런서 또는 NAT없이 접속할 수 있다.

IPAM모드 세팅별로 두 가지 방법이 있다.

Kubernetes나 ClusterPool IPAM인 경우, advertisement의 type을 PodCIDR로 하면 된다.

1
2
3
4
5
6
7
8
9


apiVersion: cilium.io/v2
kind: CiliumBGPAdvertisement
metadata:
 name: bgp-advertisements
 labels:
 advertise: bgp
spec:
 advertisements:
 - advertisementType: "PodCIDR"

이 구성으로, BGP 인스턴스는 로컬 노드의 Pod CIDR prefix를 광고할 수 있다.

MultiPool IPAM에서는 advertisementType을 CiliumIPPool로 해야 한다.
selector필드의 .matchLabels 또는 matchExpressions로 매칭할 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


apiVersion: cilium.io/v2
kind: CiliumPodIPPool
metadata:
 name: default
 labels:
 pool: blue
---
apiVersion: cilium.io/v2
kind: CiliumBGPAdvertisement
metadata:
 name: pod-ip-pool-advert
 labels:
 advertise: bgp
spec:
 advertisements:
 - advertisementType: "CiliumPodIPPool"
 selector:
 matchLabels:
 pool: "blue"

이 설정에서는 선택된 Cilium Pod IP Pool에 할당된 PodCIDR prefix가 광고된다.
이 예시에서, CiliumNode 리소스에 CIDR이 반드시 할당되어야 한다.

모든 CiliumPodIPPool CIDR를 클러스터 안에 광고하고 싶다면, NotIn으로 dummy key-value를 이용하여 쓸 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: cilium.io/v2
kind: CiliumBGPAdvertisement
metadata:
 name: pod-ip-pool-advert
 labels:
 advertise: bgp
spec:
 advertisements:
 - advertisementType: "CiliumPodIPPool"
 selector:
 matchExpressions:
 - {key: somekey, operator: NotIn, values: ['never-used-value']}

name이나 namespace를 기반으로 고르고 싶은 때가 있는데, 특별한 키를 제공한다.

io.cilium.podippool.name -> meta.name
io.cilium.podippool.namespace -> meta.namespace

1
2
3
4
5
6


selector:
 matchExpressions:
 - key: io.cilium.podippool.namespace
 operator: In
 values:
 - kube-system

다른 IPAM Type은 BGP prefix 광고가 지원하지 않는다.

Service Virtual IPs

Service는 여러 virtual IP를 가질 수 있다.
Service의 virtual IP를 BGP Peer로 광고할 수 있다.

NOTE Cilium의 BGP Control Plane은 VIP를 /32또는 /128 prefix로 광고한다.

service의 virtual IP를 광고하기 위해, advertisementType의 필드를 Service로 하고,
service.addresses 필드에 LoadBalancerIP, ClusterIP, 또는 ExternalIP로 해준다.

.selector에서 .matchLabels또는 matchExpressions로 가능하다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


apiVersion: cilium.io/v2
kind: CiliumBGPAdvertisement
metadata:
 name: bgp-advertisements
 labels:
 advertise: bgp
spec:
 advertisements:
 - advertisementType: "Service"
 service:
 addresses:
 - ClusterIP # ClusterIP
 - ExternalIP # ExternalIP
 - LoadBalancerIP # LoadBalancerIP
 selector:
 matchExpressions:
 - { key: bgp, operator: In, values: [ blue ] }

업스트림 라우터가 **ECMP(Equal Cost Multi Path)**를 지원한다면, 같은 VIP에 대해서 실제로 로드밸런싱이 일어날 것이다.

NOTE 많은 라우터들이 라우팅 테이블에 저장하는 ECMP 경로에 대해 한계를 가지는데, 많은 노드들로부터 Service VIP가 광고된다면, 한계를 넘을 수 있다. 이 기능을 쓰려면, 네트워크 관리자로부터 한계를 알아내는 것이 좋을 것이다.

각 주소 타입별로 특징이 있다:

ClusterIP
- 클러스터 내부 전용.
- kubeProxyReplacement와 함께 쓰려면, 여기를 참고
ExternalIP
- 관리자가 직접 지정하는 외부 노출용 IP
- kubeProxyReplacement와 함께 쓰려면, ExternalIP 지원이 켜져야 한다.
LoadBalancerIP
- Kubernetes에서는 이 IP를 자동할당하지 않는다.
- 그래서, 별도 할당 주체가 필요하다.
- Cilium은 LoadBalancer IPAM을 이용할 수 있다. 특별한 metadata들 역시 제공된다:
io.kubernetes.service.namespace -> .meta.namespace
io.kubernetes.service.name -> .meta.name

service가 LoadBalancer 타입일때, loadBalancerClass=io.cilium/bgp-control-plane이거나 비어있다면, Cilium이 광고할 수 있다.
또는, 미설정인 경우 광고할 수 있다.

대신, 다른 class를 지정하면, Cilium은 광고할 수 없다.

NOTE externalTrafficPolicy가 Cluster인경우, 조건 없이 광고하지만, Local인 경우, 해당 endpoint가 없으면 광고하지 않는다.

하나의 Service가 여러 advertisement selector에 동시에 걸릴 수 있는데, 이 경우 community는 합쳐지며(union), local-pref는 가장 큰 값 하나(max)를 쓴다.

기본적으로 service는 단일 IP(/32, /128)을 광고하지만, aggregation이 지원되기도 한다.
아래와 같이 더 큰 대역단위로 광고할 수 있다.

1
2
3


service:
 aggregationLengthIPv4: 24
 aggregationLengthIPv6: 120

이렇게 하면, 라우팅 테이블을 적게 차지하며, 광고 수를 줄일 수 있다.

그러나, 실제 service에 없는 트래픽도 클러스터로 들어올 수 있음을 유의해야 하며,
또한 externalTrafficPolicy=Local인 경우, aggregation될 수 없다.

Interface IP

Service가 아니라, 노드 인터페이스에 붙은 IP자체를 광고할 수도 있다.
멀티호밍에 유용하게 쓰일 수 있다.
정확한 주소(/32, /128)로 광고되며, 다음의 주소는 광고되지 않는다:

loopback
multicast
IPv6 link-local
IPv4-mapped IPv6

인터페이스는 up이나 unknown상태여야 한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


apiVersion: cilium.io/v2
kind: CiliumBGPAdvertisement
metadata:
 name: bgp-advertisements
 labels:
 advertise: bgp
spec:
 advertisements:
 - advertisementType: "Interface"
 interface:
 name: lo

(여기서의 lo는 논리적 인터페이스로, 127.0.0.1이 아닌 다른 주소를 붙인 것이다.)

📝 BGP Configurations Override

현재는 이 글에서 다루지 않음, 대신 여기서 확인

🏋️ Hands-On

helm values에 다음과 같이 추가한 뒤, 업데이트한다:

1
2
3


# bgpControlPlane
bgpControlPlane:
 enabled: true

LoadBalancer IP 광고

다음의 네트워크 토폴로지를 가정한다:

쿠버네티스 노드들의 기본 게이트웨이가 FRRouter로 설정되어있다.
FRRouter의 설정(/etc/frr/frr.conf)은 다음과 같다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


frr version 10.5.1
frr defaults traditional
hostname frr-router
log syslog informational
service integrated-vtysh-config
!
# 라우트맵 정의: 모든 경로 허용
route-map ALLOW-ALL permit 10
exit
!
# BGP 라우터 설정 (ASN 65000)
router bgp 65000
 # BGP 라우터 ID 설정
 bgp router-id 192.168.10.1
 # K8S-NODES라는 peer-group 생성
 neighbor K8S-NODES peer-group
 # K8S-NODES peer-group의 remote ASN을 65001로 설정
 neighbor K8S-NODES remote-as 65001
 # capability를 동적으로 협상 가능하게 하도록 설정(새로운 세션 없이)
 neighbor K8S-NODES capability dynamic
 # 192.168.10.0/24 대역의 노드들이 동적으로 BGP피어링이 가능하도록 설정
 bgp listen range 192.168.10.0/24 peer-group K8S-NODES
 !
 # IPv4 유니캐스트 Address family 설정
 address-family ipv4 unicast
 # K8S-NODES그룹에게 Next-hop을 자신으로 변경
 neighbor K8S-NODES next-hop-self
 # K8s-NODES그룹에서 받는 경로에 ALLOW_ALL 라우트맵 적용
 neighbor K8S-NODES route-map ALLOW-ALL in
 # K8s-NODES그룹으로 보내는 경로에 ALLOW_ALL 라우트맵 적용
 neighbor K8S-NODES route-map ALLOW-ALL out
 # ECMP(Equal-Cost Multi-Path) 설정 - 최대 경로 수를 64개 설정
 maximum-paths 64
 exit-address-family
exit
!

CiliumBGPClusterConfig

우선, CiliumBGPClusterConfig를 설정한다.
이 설정은 모든 노드에 적용된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


apiVersion: cilium.io/v2
kind: CiliumBGPClusterConfig
metadata:
 name: cilium-bgp
spec:
 nodeSelector:
 matchLabels:
 kubernetes.io/os: linux
 bgpInstances:
 - name: "K8S-NODES"
 localASN: 65001
 localPort: 179
 peers:
 - name: "FRRouter" # frr 라우터
 peerASN: 65000 # frr AS
 peerAddress: 192.168.10.1 # frr IP
 peerConfigRef:
 name: "cilium-peer" # cilium-peer라는 CiliumBGPPeerConfig를 참조

localPort를 BGP의 기본 포트인 179번 well-known포트로 받기 위해서는, helm values에서 다음과 같이 설정되어야 한다:

1
2
3
4
5
6


# Listening on the default BGP Port
securityContext:
 privileged: true
 capabilities:
 ciliumAgent:
 - CAP_NET_BIND_SERVICE

CiliumBGPPeerConfig

cilium-peer라는 CiliumBGPPeerConfig를 설정한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


apiVersion: cilium.io/v2
kind: CiliumBGPPeerConfig
metadata:
 name: cilium-peer
spec:
 timers:
 holdTimeSeconds: 90
 keepAliveTimeSeconds: 30
 gracefulRestart:
 enabled: true
 restartTimeSeconds: 120
 families:
 - afi: ipv4
 safi: unicast
 advertisements:
 matchLabels:
 advertise: "bgp" #CiliumBGPPeerConfig의 advertisements의 matchLabels와 일치 

CiliumBGPAdvertisement

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


apiVersion: cilium.io/v2
kind: CiliumBGPAdvertisement
metadata:
 name: advertise-gateway-lb
 labels:
 advertise: bgp #CiliumBGPPeerConfig의 advertisements의 matchLabels와 일치
 bgp-advertisement: "true"
spec:
 advertisements:
 - advertisementType: Service # Service 광고
 selector:
 matchLabels:
 app: http-test # app: http-test 라벨을 가진 Service 광고
 service:
 addresses:
 - LoadBalancerIP # LoadBalancer IP 광고

간단한 HTTP 앱 노출

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


# http-test.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: http-test
 labels:
 app: http-test 
spec:
 replicas: 1
 selector:
 matchLabels:
 app: http-test
 template:
 metadata:
 labels:
 app: http-test
 spec:
 containers:
 - name: http-server
 image: riveroverflow/cilium-test-http:latest
 ports:
 - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
 name: http-test
 labels:
 app: http-test # CiliumBGPAdvertisement의 selector와 일치
spec:
 selector:
 app: http-test
 ports:
 - protocol: TCP
 port: 80
 targetPort: 8080
 type: LoadBalancer

이제, kubectl apply -f http-test.yaml로 적용하면 된다.

단, CiliumLoadBalancerIPPool이 설정되어있어야 한다. 아래와 같이 설정할 수 있다:

1
2
3
4
5
6
7
8


apiVersion: cilium.io/v2
kind: CiliumLoadBalancerIPPool
metadata:
 name: public-pool
spec:
 blocks:
 - cidr: 172.20.0.0/24
 disabled: false

생성된 service를 확인해보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


cilium-playground on  main on ☁️ (ap-northeast-2) on ☁️ fudoge67@gmail.com
23:49:07 ❯ k get svc
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
...
http-test LoadBalancer 10.105.166.135 172.20.0.1 80:30525/TCP 5d8h
...

이제, `curl http://172.20.0.1:80`로 테스트해보면 된다.

```bash
cilium-playground on  main on ☁️ (ap-northeast-2) on ☁️ fudoge67@gmail.com
23:54:52 ❯ curl http://172.20.0.1
hello from http server
method=GET path=/ time=2026-03-12T14:54:54Z

BGP Peering 상태도 확인할 수 있다:

1
2
3
4
5
6


cilium-playground on  main on ☁️ (ap-northeast-2) on ☁️ fudoge67@gmail.com
23:54:45 ❯ cilium bgp peers
Node Local AS Peer AS Peer Address Session State Uptime Family Received Advertised
cp-1 65001 65000 192.168.10.1 established 76h5m19s ipv4/unicast 1 1
worker-1 65001 65000 192.168.10.1 established 76h5m19s ipv4/unicast 1 1
worker-2 65001 65000 192.168.10.1 established 76h4m51s ipv4/unicast 1 1

📚 결론

Cilium BGP Control Plane을 이용하여 BGP Peering을 맺은 라우터에 클러스터 내에서 쓰이는 IP들 및 LoadBalancer IP들을 광고할 수 있다.
L2광고대신 실드가 LoadBalancer IP를 광고하는 “진짜 로드밸런싱"이 가능하다.
Pod IP에 직접 접근할 수도 있으며, 서로 다른 네트워크에서 중간에 BGP라우터가 중개하는 경우, Pod간 통신에서 이 기능이 활용될 수 있다.

📚 References

Network - BGP(Border Gateway Protocol)

Sun, 08 Mar 2026 18:17:58 +0900

🌐 BGP란

BGP(Border-Gateway Protocol, 경계 게이트웨이 프로토콜) 는 자율 시스템들간의 라우팅 프로토콜이다.
서로 다른 AS간에 라우팅 정보를 교환하는 데 쓰이도록 디자인되었다.

자율 시스템

AS(Autonomous System, 자율 시스템) 는 하나의 관리 주체가 운영하는 IP 네트워크들의 그룹이다.
예를 들어, 통신사, 대형 기업, 클라우드 사업자 등이 하나의 AS를 가지고 운영한다.

보통 AS내부의 라우팅은 IGP(Interior Gateway Protocol)라고 하며, 보통 OSPF/IS-IS가 있다.
AS간의 라우팅은 EGP(Exterior Gateway Protocol)라고 하며, BGP가 있다.

AS는 ASN(AS number) 이라는 고유의 식별번호를 가진다.
AS의 식별자로써 쓰이며, EGP의 라우팅 정보 교환에도 쓰인다.
ASN은 고유의 32비트 정수이다.
처음에는 16비트로, “2-byte ASN"또는 “2-octet ASN"이라고 불렸다
이제는 32비트로, 4byte 또는 4octet의 ASN을 가진다.

ASN은 퍼블릭과 프라이빗이 존재한다.
아래 범위는 내부 ASN으로만 사용되어야 한다:

2-byte ASN: 64,512 ~ 65,534
4-byte ASN: 4,200,000,000 ~ 2^32 -2
나머지들은 모두 퍼블릭이다.
끝번호들은 사용되지 않는다(0, 2^16-1, 2^32-1)

BGP의 구성요소

BGP Speaker: BGP 프로토콜을 실행하는 장비.
BGP Peer: 서로 BGP Peering을 맺은 상대방의 BGP Speaker를 말한다.
BGP Session: 두 BGP Speaker간에 맺어진 논리적 통신 관계.
보통 TCP 179포트를 이용해서 세션을 맺는다.

경로-벡터 알고리즘

Prefix들은 ASN의 리스트로 광고되며, “AS Path"라고 불린다.
즉, “그 목적지까지 가는동안 어떤 AS들을 거치는지"라는 경로 정보 자체를 들고다닌다.

1
2


172.18.0.0/24
AS_PATH: 65001 65000

이 말은, 172.18.0.0대역으로 가려면, 65001 -> 65000의 AS경로를 거쳐야 한다는 의미이다.
BGP는 몇 홉 떨어져있나보다, 어떤 경로를 지나가는가를 보고 판단한다.

이 방식 덕분에, 루프 방지가 가능하고, 정책 기반 라우팅이 가능하다.
그래서 BGP가 인터넷처럼 큰 규모의 AS간 라우팅에 적합한 것이다.

위 그림에서는, AS 65000에게 172.18.0.0의 경로 광고가 65002 -> 65000으로 이루어지지 않는다.
AS 65000가 65002로부터 172.18.0.0의 광고를 받게 된다면, AS_PATH: 65002 65001 65000으로 받게 되는데, 자기 자신의 ASN이 있는 것을 보고, 기각될 것이다.

대신, 192.168.12.0/24는 65000이 받을 수 있다.
받으면, 다음과 같을 것이다:

1
2


192.168.12.0/24
AS_PATH: 65002 65001

BGP-4와 MP-BGP

BGP는 1989년에 설명되어, 1994년부터 인터넷에 사용되었다.

version 1: RFC1105
version 2: RFC1163
version 3: RFC1267
version 4: RFC1654 -> RFC4271(Jan 2006)

BGP는 처음에 IPv4만 지원되었다가, Multiprotocol BGP(MP-BGP) 부터는 여러 종류의 주소들을 지원한다.
그래서, Address Family라는 단위를 사용하는데, 교환하는 라우팅 정보가 어떤 주소 종류를 쓰는지를 구분하는데 쓰인다.

AFI(Address Family Identifier)
SAFI(Subsequent Address Family Identifier)
라는 식별자들의 조합으로 구분된다.

주요 AF는 다음과 같다:

IPv4 Unicast
- AFI = 1
- SAFI = 1
IPv6 Unicast
- AFI = 2
- SAFI = 1
VPNv4 Unicast
- AFI = 1
- SAFI = 128
VPNv6 Unicast
- AFI = 2
- SAFI = 128
이외에도 다양한 AF들이 존재한다.
AFI와 SAFI들의 리스트는 IANA(인터넷 할당 번호 관리 기관)에서 관리된다.

eBGP와 iBGP

eBGP: 서로 다른 AS간의 BGP. 다른 ASN을 가진다.
iBGP: AS내부의 BGP. 같은 ASN을 가진다.

그러나 ,eBGP가 위 그림같지만은 않을 수 있다.

대신, multihop 설정이 된다면, 아래 그림처럼도 가능하다:

전체적으로, 다음과 같이 동작한다:

경계 라우터가 eBGP로 외부 AS에게서 경로를 받음
iBGP로 내부 라우터들에게 전파
내부 라우터들도 외부로 트래픽을 보낼 수 있게 됨

그러나, AS_PATH를 다룰 때, 조금은 다르다.

eBGP는 광고 시, 자신의 ASN을 추가해서 Peer에게 prefix들을 전파하고,
iBGP는 같은 AS내부이므로, 자신의 ASN을 추가하지 않는다.
또한, iBGP로 경로를 전파받았다면, 다른 iBGP peer에게 다시 광고해서는 안된다.
루프가 생기거나 운영에 복잡도가 오르기 때문이다.
대신, 단순한 대안으로는 full mesh로, 모두 서로 연결되어 있기 때문에, eBGP를 광고받은 라우터가 내부 라우터들에게 직접 전달할 수가 있겠지만, 이러면 내부 세션 수가 너무 크게 늘어난다. $$S = \frac{n(n-1)}{2}$$

대신, Route Reflector / Confederation 등의 대안을 사용할 수 있다.

Route Reflector: 일부 라우터가 중앙 허브로 작동하며, 반사(Reflect)함.
Confederation: 내부에 Sub-AS를 둬서 여러 작은 AS로 나눠서 관리

Real-world에서의 BGP

인터넷에서는 ISP, 기업, 클라우드, 콘텐츠 사업자 등등이 eBGP를 통해서 외부 AS와 경로를 주고받는다.
오늘날의 인터넷은 수많은 AS들이 엉켜있다.
현실에서는 연결성 확보, 장애 대응, 비용 절감, 트래픽 제어 등, 운영, 비용, 품질, 사업적 측면에서 각종 정책을 활용하기 위해 BGP를 사용한다.

Transit vs Peering

Transit은 한 AS가 다른 AS에게 인터넷으로 가는 경로를 제공하는 서비스이다.
Transit Provider는 돈을 받고, 인터넷에 연결될 수 있도록 해준다.
Transit Customer는 인터넷 연결성을 확보할 수 있다.

Peering은 두 AS가 서로 연결되는 트래픽에 대해서는 직접 연결하여 저렴하게 트래픽을 교환한다.

회선 설계 개념

Single homed: 한 조직이 하나의 ISP에만 연결된다.
단순하고 비용이 낮으며, 운영이 쉽다.
대신, 장애 시 연결이 끊길 수 있으며, 경로 선택에 대한 유연성이 없다.
Dual-homed: 한 ISP에 대해 회선 연결을 이중화한다.
단일 링크 장애를 견딜 수 있지만, ISP 자체 장애에는 취약하며, 다양성은 부족할 수 있다.
Multi-homed: 둘 이상의 ISP에 연결된 상태를 말한다.
ISP 장애에 대응할 수 있으며, 트래픽 정책을 세부적으로 제어할 수 있다.
대신, 설계 및 정책 설정이 복잡해지며, 운영 난이도가 오른다.

라우트 종류

Full Route: 업스트림이 인터넷 전체의 BGP테이블을 제공하는 것을 말한다.
선택지가 많아지고 유연하지만, 라우터 성능에 대한 요구사항이 늘어나며, 운영 복잡도도 늘어난다.
Partial Route: 업스트림이 전체는 아니여도 일부 경로를 제공한다.
일부 정책을 설정할 수 있지만, 전체 정보는 알 수 없어서 최적화에 한계가 존재하긴 한다.
Default Route: 업스트림이 단순하게 0.0.0.0/0이다.
매우 단순하지만, 세밀한 제어는 불가능하다.

🤝 BGP의 동작

BGP 메시지

BGP 메시지는 BGP세션을 유지하며 라우팅 정보를 업데이트하는 정보를 가진다.
BGP 메시지의 크기는 65535 octects까지 가능하다. (RFC 8654)

BGP 메시지에는 4가지 종류가 존재한다:

OPEN
TCP연결이 맺어진 뒤, 바로 교환하는 메시지로, 메시지 헤더와 메시지 데이터로 이루어진다.
데이터에는 다음의 정보를 가진다:
- BGP Version
- ASN
- Hold Time
- BGP Router ID
- Capability code(Optional)
KEEPALIVE
메시지의 헤더만 전송하며, 메시지 데이터는 전송하지 않는다.
HoldTimer가 만료되지 않게 하기위해 전송된다.
RFC 4271에서는 Keepalice시간을 30초, Hold Time을 90초로 제안한다.
즉, 매 30초마다 KEEPALIVE메시지를 보내며, 90초이상 메시지를 받지 못한 피어는 상대방과 세션이 종료된 것으로 판단한다.
이 시간들은 조정가능하며, 벤더마다 구성이 다를 수 있다.
UPDATE
경로 정보를 광고하거나 철회할 때 사용한다.
어떤 네트워크에 도달가능한지와, 더 이상 불가능한 경로에 대해서도 전달한다.
NOTIFICATION
오류가 발생했을때, 에러코드와 에서 서브코드를 전송한다.
에러코드는 1~6까지의 번호를 가진다.

BGP의 유한 상태 머신(FSM)

BGP는 다음 여섯 개의 상태를 가진다:

IDLE
CONNECT
ACTIVE
OPENSENT
OPENCONFIRM
ESTABLISHED

우선, 처음에는 IDLE 상태이다.
- BGP자원을 초기화하고, ConnectRetryTimer를 초기값으로 시작한다.
- Peer와 TCP연결을하기 위해 시도할 준비가 되면, CONNECT상태로 전이한다.
- 다른 오류가 있다면, IDLE에 계속 있는다.
CONNECT 상태가 된다.
- Peer와 TCP 연결을 시도하고, OPEN 메시지를 보낸다.
  - 성공하면, OpenSent로 이동한다.
  - 실패하면, Active로 이동한다.
- ConnectRetryTimer가 만료되면, 계속 CONNECT 상태에서 있으며, ConnectRetryTimer를 초기화하고, 새로운 TCP연결을 시도한다.
- 다른 문제가 생기면, 다시 IDLE로 돌아간다.
ACTIVE 상태는 현재 라우터가 TCP세션을 맺을 수 없다는 뜻이다.
- Peer와 다시 TCP연결을 시도한다. 이후 OPEN메시지를 보낸다.
  - 성공하면, OpenSent로 이동한다.
  - 실패하면, IDLE로 돌아간다.
- ConnectRetryTimer가 만료되면, CONNECT상태로 돌아가며, ConnectRetryTimer가 다시 초기화된다.
OPENSENT 는 OPEN 메시지가 Peer에게 전송되었으며, Peer로부터 OPEN메시지를 응답받기를 기다린다.
- OPEN 메시지를 응답받으면, KEEPALIVE메시지를 보내면서, 상태를 OPENCONFIRM으로 둔다.
- OPEN을 응답받고, 미스매치로 인한 에러가 발생하면, NOTIFICATION 메시지를 peer에게 전송하고, 상태를 IDLE상태로 돌린다.
- TCP 연결이 실패하면, 다시 ACTIVE상태로 돌아간다.
OPENCONFIRM 상태에서는 라우터가 KEEPALICE 또는 NOTIFICATION 메시지를 Peer로부터 기다린다.
- Peer의 KEEPALIVE를 받으면, ESTABLISHED로 상태를 바꾼다.
- HoldTimer가 만료되거나, NOTIFICATION을 받으면, IDLE상태로 이동한다.
ESTABLISHED 는 BGP Peer 연결이 성공적임을 나타낸다.
- UPDATE, NOTIFICATION, KEEPALIVE를 주고받을 수 있다.
- NOTIFICATION을 받으면 IDLE로 돌아간다.

BGP 세션 맺기

각 라우터는 32비트의 고유한 숫자로, 점-십진법 표기로 작성된다.

두 라우터가 함께 있는 망은 172.20.0.0/30이라고 가정한다.
R1(AS65000)

10.0.0.0/8
172.20.0.1
Router ID는 10.0.0.1

R2(AS65001)

172.16.0.0/13
172.20.0.2
Router ID는 172.16.0.1
로 가정한다.

아래와 같은 흐름을 따른다: OPEN 메시지를 교환하다가, 스펙 등이 호환되지 않는 경우, NOTIFICATION 메시지를 보낸 뒤, 재협상하기도 한다.

아래 명령어들은 CISCO IOS기준이다.

각각의 라우터에게 ASN을 할당하고, router-id를 넣어주자.
R1

1
2


router bgp 65000
bgp router-id 10.0.0.1

1
2


router bgp 65001
bgp router-id 172.16.0.1

이후, Peering 설정을 해준다.

1
2
3
4


no bgp default ipv4-unicast # cisco ios의 기본설정을 제거
neighbor 172.20.0.2 remote-as 65001
address-family ipv4 unicast
neighbor 172.20.0.2 activate

1
2
3
4


no bgp default ipv4-unicast
neighbor 172.20.0.1 remote-as 65000
address-family ipv4 unicast
neighbor 172.20.0.1 activate

BGP 네트워크 광고

BGP 네트워크란, BGP 라우터에 의해 관리되는 네트워크 prefix를 말한다.
Prefix들은 개별 호스트 라우트라기보단, 서브넷 또는 집계된 라우트이다.
너무 긴 Prefix(longer than /24 in IPv4, /48 in IPv6)은 불가능하다.

CISCO IOS에서 다음과 같이 하면 된다:
R1

1
2
3
4
5
6
7
8
9


ip route 10.0.0.0 255.0.0.0 Null0 # 소유한 네트워크임을 명시

router bgp 65000
 bgp router-id 10.0.0.0
 no bgp default ipv4-unicast
 neighbor 172.20.0.2 remote-as 65001
 address-family ipv4 unicast
 neighbor 172.20.0.2 activate
 network 10.0.0.0 mask 255.0.0.0 # 이 Prefix는 광고대상이다

1
2
3
4
5
6
7
8
9


ip route 172.16.0.0 255.248.0.0 Null0 # 소유한 네트워크임을 명시

router bgp 65001
 bgp router-id 172.16.0.1
 no bgp default ipv4-unicast
 neighbor 172.20.0.1 remote-as 65000
 address-family ipv4 unicast
 neighbor 172.20.0.1 activate
 network 172.16.0.0 mask 255.248.0.0 # 이 Prefix는 광고대상이다

BGP Best Path는 라우팅 정보 기반(RIB, Routing Information Base)에서 BGP가 선택하는 경로이다.
BGP는 최고의 경로를 찾기 위해 path attrubute들을 이용한다.

항상 최단경로가 최선이 아닐 수 있다. 정책에 기반한 최선의 경로가 생성될 뿐이다.

기본적으로 BGP는 각 목적지별로 최고의 경로를 설치한다.
BGP는 peer에게 최고의 경로만 광고한다.

만약 최고의 경로가 여러 개가 있다면, BGP Multipath를 이용해서 여러 best path를 가질 수 있다.
이를 통해 여러 nexthop에 부하를 분산시킬 수도 있다.

BGP Session이 ESTABLISHED되면, 두 Peer는 서로 전체 정보를 교환하며, 이후 변경사항을 공유한다.
그러나, 때로는 완전 새로고침을 또 받기를 원하는 경우가 있는데(정책변경, prefix-list 변경, 라우트맵 변경 등), Route Refresh는 BGP Session이 유지된 채로 많은양의 정보를 다시 받을 수 있게 해준다.

📚 References

Linux - 작업 스케줄러(CFS, EEVDF)

Sun, 22 Feb 2026 21:51:28 +0900

⚖️ CFS 스케줄러

개요

CFS(Completely Fair Scheduler) 는 Linux 2.6.23이후의 작업 스케줄러이다.

이상적인 CPU라면 여러 프로그램이 동시에 돌아갈 때, 각 작업에게 CPU시간을 아주 공정하고 정확하게 나눠줘야 하는데, 그 이상적인 모습을 현실에서 최대한 흉내내려는 스케줄러가 CFS스케줄러이다.

실제 하드웨어에서는, 하나의 작업만 실행할 수 있는데, “이상적인 동시 실행"을 위해서는 각 Task가 공정하게 얼마나 CPU를 받았느냐는 기준이 필요하다.
이를 위해 “virtual runtime(vruntime)” 이라는 개념을 이용한다.

CFS에서 vruntime은 태스크별로 task_struct->se.vruntime값을 nanosec단위로 가진다.
이를 통해서 시간을 정확히 측정가능하며 예상된 CPU타임을 부여받을 수 있게 된다.

CFS의 Task picking로직은 이 task_struct->se.vruntime값에 기반한다.
항상 가장 작은 p->se.vruntime값을 가진 task를 실행하려고 시도한다.
CFS는 항상 CPU타임을 쪼개서 runnable한 tasks들 사이에서 이상적인 멀티태스킹 하드웨어를 모방하기 위해 노력한다.

RBTree

기존에는 active/expired 두 개의 배열을 번갈아서 스위치하는 방식이었다.
task가 다 사용되면 expired, active가 비면 둘을 스왑시켰다.
이러한 방식때문에 이 경계에서 이상한 현상이 생겼고, 순서가 바뀌거나 지연이 튀는 현상이 발생하였다.

대신, CFS에서는 RBTree(레드블랙트리) 자료구조를 이용해서, 정렬 키를 p->se.vruntime으로 하였다.
즉, vruntme이 가장 작으면 CPU를 덜 받은 task이다.

RBTree안에서 가장 왼쪽 끝
= 가장 작은 키
= CPU를 덜 받은 태스크
= 다음에 할 작업
인 것이다.
실행되다보면 vruntime이 증가하므로, 오른쪽으로 밀려나게 된다.
그래서 언젠가는 다른 노드가 왼쪽 끝이 되어 CPU를 받게 된다.
즉, 공정성이 해결되며 기아를 방지하게 된다.

CFS는 또한 rq->cfs.min_vruntime값을 이용하는데, runqueue내에서 가장 작은 vruntime을 추적한다.
시스템 내부의 모든 작업은 이 시간만큼 보장받았음을 의미하는데, 새로 활성화된 태스크(ex. block대기 끝나거나 sleep끝나고 깨어남)를 보정하는데 쓰인다.
이 값은 이 CPU가 지금까지 공정하게 처리한 작업량의 기준점이 된다.

주요 자료구조

struct sched_entity: 스케줄가능한 엔티티는 모두 sched_entity라는 객체를 통해 추적된다. 스케줄가능한 엔티티는 하나의 task일수도 있고, task들의 그룹일 수 있다.
- sched_entity::load: 이 entity의 가중치 정보이다.
- sched_entity::vruntime: 이 엔티티의 vruntime값. 핵심 key가 된다
- sched_entity::run_node: RB트리에 연결되는 노드(트리에 넣기 위한 link)
- sum_exec_runtime: 지금까지 CPU에서 실행된 실제 시간.
- prev_sum_exec_runtime: 이전까지 CPU에서 실행된 실제 시간. -> 둘의 차이로 얼마 돌았는지 계산된다.
struct load_weight: sched_entity가 얼마나 CPU를 받을 수 있는지에 대한 숫자 가중치이다.
- 즉,sched_entity::load는 struct load_weight
- 기본적으로 nice값(-20 ~ +19)의 영향을 받는다.
- 그룹 스케줄링(cgroup)에서는 cpu.weight/cpu.shares를 기반으로 결정된다.
struct task_struct: Task에 필요한 모든 정보는 이 구조체에 들어가있다.
- 스케줄링에 관한 정보인 task_struct::se필드의 타입은 struct sched_entity이다.
struct rq: 이 CPU에서의 모든 runnable한 task들에 대한 정보를 가진다.
- per-CPU의 자원이며, 필드에는 CFS스케줄러를 위한 runqueue 이외에도, 다른 스케줄링 클래스(rt, dl등)들의 runqueue들도 필드로 가진다.
- CFS의 runqueue필드는 rq::cfs이다.
struct cfs_rq: CFS 전용 runqueue.
- 내부에는 vruntime으로 정렬된 RB Tree를 가진다.
- cfs_rq::tasks_timeline: RB Tree의 루트 노드
- cfs_rq::nr_running: CPU위에 있는 runnable한 CFS task들의 수
- cfs_rq::load runqueue내부의 se::load들의 합
- cfs_rq::min_vruntime: CFS runqueue내부의 가장 작은 sched_entity::vruntime값.
  - 오랫동안 sleep하다온 task가 runqueue에 복귀했을 때 RB Tree의 맨 왼쪽에 계속 머무르지 않게 이 값을 이용해서 복귀 시 보정에 이 값의 근사한 값으로 넣어준다.

running중에서의 동작

Task가 CPU에서 실행되는 동안, 매 tick마다 update_curr()가 현재 task(curr)의 시간을 누적한다.
실제 실행시간은 다음의 과정으로 업데이트된다:

1
2
3


delta_exec = now - curr->exec_start;
curr->exec_start = now;
curr->sum_exec_runtime += delta_exec;

이후, vruntime은 다음과 같이 업데이트된다:

1

curr->vruntime += calc_delta_fair(delta_exec, curr);

반올림이나 오버플로우 체크 부분을 생략하면, calc_delta_fair()는 다음처럼 계산된다:

1
2


// NICE_0_LOAD = nice가 0인경우 매핑되는값 = 상수값 1024
delta_exec * (NICE_0_LOAD / se->load.weight)

weight가 클수록, 즉 우선순위가 높으면 분모가 커지므로, vruntime의 누적이 작아지고,
weight가 작아지면, 분모가 작아져서 vruntime의 누적이 커져서,
우선순위가 클수록 더 자주 rbtree 왼쪽에 머무르게 된다.
nice값이 0인경우, weight = NICE_0_LOAD여서, vruntime 증가량이 실제 cpu시간과 같아진다.

매 tick마다, 이 task가 이번 스케줄링 기간동안 받을 타임슬라이스(quota)를 정한다.

1
2


// sched_period는 모든 task들을 적어도 한 번 돌리기 위한 시간
sched_period * (se->load.weight / cfs_rq->load)

위의 두 보정(vruntime증가량, quota)를 계산하면, 결국 Task들이 자기 몫만큼 돌고나면, vruntime이 똑같이 증가한다.
아래의 예시를 보면 알 수 있다:

A의 weight = 2, B의 weight를 1로 두자
Sched Period는 P라고 두자.
- A slice = P * 2/3
- B slice = P * 1/3
slice만큼 돌면, vruntime 증가량이 둘다 같아진다(아래 수식 참고).

$$\triangle vruntime \approx \triangle exec \times \frac{c(=NICE\_0\_LOAD)}{weight}$$

$$\triangle vr_A \approx (P \cdot 2/3) \times \frac{c}{2} = P \cdot c / 3$$

$$\triangle vr_B \approx (P \cdot 1/3) \times \frac{c}{1} = P \cdot c / 3$$

현재 task가 자신의 quota보다 더 실행되면, TIF_NEED_RESCHED플래그가 세팅되어, 다음 스케줄 지점에서 reschedule된다.

Tick이란?
리눅스 시스템에서의 주기적 타이머 인터럽트 이다.
jiffies는 이 tick의 누적 카운트이며,
HZ는 1초에 tick이 몇 번 오냐에 대한 주파수 값이다.

최신 리눅스에서는 완전 주기적이지는 않다.
유휴 상태에서는 전력을 아끼기 위해 tick을 줄인다고 한다.

CFS는 RBTree에 들어오는 task에 대해 vruntime을 보정하기도 한다.
CFS는 sleep에서 wakeup된 task도 보정할 수 있는데, sleep되던 task는 vruntime이 한참 부족하다.
일어나게 되면, CFS는 새로운 vruntime으로 보정하는데, 다음의 방법을 따른다:

1
2
3
4
5
6


if scheduler supports GENTLE_FAIR_SLEEPERS feature:
 placed_vruntime = cfs_rq.min_vruntime - sysctl_shced_latency/2
else:
 placed_vruntime = cfs_rq.min_vruntime - sysctl_shced_latency

se->vruntime = max(se->vruntime, placed_vruntime)

즉, 기존 min_vruntime보다 약간 덜받은정도로 새로운 보정값을 우선 만든다.
GENTLE_FAIR_SLEEPERS를 키면, vruntime 보너스를 덜 주게 된다(latency를 덜 뺌)
이후, min_vruntime에 근접한 값으로 보정한 값과 기존 vruntime과 비교해서, 더 큰 값을 고른다.
-> 기존에도 충분히 보장받았음에도 또 보정을 받는 것을 방지한다.
-> 단, sleep이 너무 긴 경우, 오버플로우 문제와 같은 극단 케이스가 발생할 수도 있는데, 이럴 때에는 그냥 기존 vruntime을 쓴다.
그 뒤, runqueue에 sched_entity가 들어가진다.
깨운 task의 vruntime이 현재 실행 중인 task보다 충분히 작으면, 현재 task가 선점 대상이 될 수 있다.

fork()로 인해 자식 프로세스가 생길 수 있는데, 이 때는 sysctl_sched_child_runs_first가 중요하다.
이 값이 0(기본값)이면, 부모 프로세스의 vruntime이 더 작은 경우 부모 프로세스가 먼저 실행된다.
1이면 자식프로세스가 부모프로세스의 vruntime을 스왑하여 더 일찍 실행될 수 있는데, 보통 exec()가 fork()직후 일어나는 패턴이 많으므로, 불필요한 copy-on-write(cow) 비용을 줄일 수 있다.

Task가 블록되거나 종료되면, vruntime이 업데이트되고, sched_entitiy가 RBTree로부터 제거된다.

CFS 특징

기존 스케줄러와는 달리, jiffies/HZ와 같은 수치에만 의존하지 않는다.
CFS는 실제 나노초(ns)단위로 정확히 누적시킨다.

그래서 HS, jiffies에 상관없이 실행시간을 정밀하게 다룬다.

또한, 이전 O(1) 스케줄러가 가지던 방식의 timeslice라는 개념은 없다. runq와 부하와 weight에 따라 양이 달라진다.
기존에는 휴리스틱 기반의 고정된 시간조각을 돌려주는 설계였지만 이제는 그런 개념을 사용하지 않는다.
휴리스틱이 없으면, 규칙의 빈틈이 없어지고, 프로세스가 악용하는 경우를 없앤다.
그러한 예외적인 규칙들을 줄이고 수학적으로 실행 시간을 관리하여, 공격이나 악용이 잘 통하지 않게 된다.

대신, /sys/kernel/debug/sched/base_slice_ns가 튜닝될 수 있다.
이는 최소 CPU할당의 하한선인데,
값을 작게하면, low-latency가 되어 데스크톱에서 더 즉각적인 경험을 하게 되고,
값을 크게하면, batching이 증가하여 캐시 효율도 좋아지고 큰 작업을 묶어 처리하기에도 좋다.

그러나, CONFIG_HZ의 설정에 의해 tick의 간격이 크다면, base_slice_ns를 그보다 더 작게 설정해도 실제로는 tick보다 더 자주 변경되지는 어려워서 차이가 없을 수 있다.

CONFIG_HZ는 1초에 scheduler tick이 몇 번 발생하는지에 대한 설정이다. TIKC_NSEC은 tick의 주기를 말한다. 즉, base_slice_ns < TICK_NSEC 인 경우, 큰 효과가 없다는 의미이다.

CFS는 모든 runnable task들이 이 스케줄링 기간 안에는 한 번씩은 CPU를 받게 하려고 창을 잡는다.
shced_period = sysctl_sched_latency이다.
그러나, runnable task의 개수가 많아지면, 각 태스크에게 그러한 시간을 보장할 수도 없어지는데, runnable의 수가 sysctl_sched_nr_latency보다 많아지면, period를 늘린다.

그리고 task는 최대한 min_granularity_ns만큼 실행되도록 한다.

nice값 처리에도 좋은데, nice값이 높으면 vruntime이 더 크게 늘어나서 결과적으로 CPU를 덜 받게 된다.

SMP(멀티코어) 로드밸런싱에서도 단순해졌는데, 복잡한 runqueue-walking assumption이 사라지고, 스케줄링 모듈에서의 iterator를 이용하여 밸런싱 코드가 단순해지고 안전해졌다.

CFS정책

CFS는 다음의 세 가지 스케줄링 정책을 구현한다:

SCHED_NORMAL: 보통의 task들을 위한 스케줄링 정책
SCHED_BATCH: 보통의 task들만큼 자주 선점하지 않고, 한번에 많은 양을 처리하기 위한 스케줄링.
SCHED_IDLE: nice값 19보다도 약한 값이지만, true-idle 생태는 아니다.

실시간 스케줄링으로 SHCED_FIFO/_RR이 있는데, POSIX표준으로 sched/rt.c에 구현되어있다.

이들은 CFS정책은 아니다.

스케줄링 클래스

scheduler core는 정책을 직접 구현하지 않고, shced_class로 알고리즘을 분리해둔 뒤, core는 이벤트가 생길 시, 해당 class의 hook함수를 호출한다.

sched/fair.c: CFS class구현
sched/rt.c: RT(Real-Time) class 구현(FIFO/RR)
sched/deadline.c: DEADLINE class 구현 core에서는 Deadline -> RT -> CFS class순으로 우선순위를 가진다. 즉, 이렇게 검사한다:

1
2
3
4
5
6
7
8


if deadline task exists:
 run deadline
else if rt task exists:
 run rt
else if cfs task exists:
 run cfs
else:
 run idle

다음은 hook들의 예시이다:

enqueue_task()
dequeue_task()
yield_task()
check_preempt_curr()
pick_next_task()
set_curr_task()
task_tick()

🍕 CFS - 그룹 스케줄링

그룹 스케줄링 개요

만약 Alice가 1개의 task를 돌리려는데, Bob은 4개의 task를 돌린다고 하자.
CFS에 의해, task의 관점으로 각각 20%씩 할당해줬지만, 사용자의 입장에서는 20%, 80%씩 사용한것이다.

커널 옵션에서 CONFIG_CGROUP_SCHED와 CONFIG_FAIR_GROUP_SCHED를 이용하면, CPU cgroup controller를 이용한다.

그룹 스케줄링이 활성화되면, root_task_group이라는 루트 레벨의 task group이 생긴다.
태스크가 아무 그룹에도 없다면, root_task_group에 속하게 된다.
모든 다른 task group은 root_task_group의 자식이다.

Task group들이 생기고 CPU 사용량(cpu.shares/cpu.weight)가 정해질 수 있다.
이 수치는 CPU가 경쟁 상태일 때, 누구에게 더 많이 배분할지 정하는 가중치이다.

그룹 스케줄링의 동작

그룹 스케줄링에서는 task_group이라는 새로운 오브젝트가 등장한다.
task group에서는 여러 개의 runnable한 task들을 가질 수 있으며, 멀티코어 시스템에서는 이러한 task들이 서로 다른 CPU에 할당될 수 있다.
그룹 스케줄링의 결정을 할때, 스케줄러는 sched_entity만 믿고 결정할 수는 없다.
스케줄러는 task group의 task들이 태스크 그룹 내에서 quota를 받을 수 있도록 task_group레벨의 CFS runq가 필요하다.

task_group은 sched_entity의 배열을 가지고 있으며, task_group::se[i]는 CPU i에 대한 CPU runq위에서 이 그룹을 대표하는 sched_entity이다.
즉, i번째 CPU할당을 받기 위해 경쟁하는 그룹의 가상 sched_entity이다.
task_group::cfs_rq[i]는 CPU i에서의 그룹 전용 CFS runq이다.
CPU i에 있는 모든 runnable task중에서 이 그룹에 속한 task들은 task_group::cfs_rq[i]에 있다.

Task group에 있는 CFS runq, 즉 task_group::cfs_rq[i]는 tast_group::se[i]의 my_q를 통해 참조될 수 있다.
즉, task_group::se[i]::my_q == task_group::cfs_rq[i]이다.
task_group::shares는 유저 스페이스에서 설정하는 cpu.shares나 cpu.weight과 같은 task_group의 CPU 할당비율을 말한다.
task_group::load_avg는 그 그룹 내부에서의 평균 부하를 말한다.

root_task_group::cfs_rq[i] 는 per-CPU의 CFS rq랑 같다.
그래서 root_task_group::se[i] 는 null이다.

i번째 CPU에서, root_task_group::cfs_rq[i]에서 다음 sched_entity를 꺼낸다.
그 sched_entity는 실제 Task일수도 있고, task_group일수도 있다.
task라면 실행하면 되고, task_group이라면 my_q를 통해 해당 내부 rq에서 내부의 sched_entity를 꺼낸다.
이것이 반복된다.
즉, task와 task_group을 모두 함께 스케줄하고, 그룹이 뽑히면 내부 에서 다시 고르는 방식이 재귀적으로 이뤄지며 cgroup계층을 스케줄한다.

task_group::se[i]는 항상 큐에존재하는 것이 아닐 수도 있다.
해당 그룹 안에서 Runnable한 task가 하나도 없다면, 그 그룹은 Runnable하지 못하므로 상위 큐에 없을 수도 있다.

`load_avg`와 PELT

PELT(Per Entity Load Tracking) 은 여러 sched entitiy들(task 및 task group)에 대해 최근 얼마나 CPU를 필요로 했는지를 추적한다.
순간값이 아니라 평균값을 부드럽게 산출한다.
기본적으로 EWMA(Expoenetially Weighted Moving Average, 지수 가중 이동 평균) 으로 계산되는데, 각 주기(1024us)마다 감쇠되며, y^32 = 0.5가 되도록 잡혀 있다.
아래와 같이 가중 평균으로 계산된다:

1
2


ewma_sum(u) = u_0 + u_1*y + u_2*y^2 + ...
ewma(u) = ewma_sum(u) / ewma_sum(1) // ewma_sum(1) = 1 + y + y^2 + ...

즉, 32ms전 값은 절반까지 감쇠되고, 그보다 오래된 값은 점점 희미해진다.
그렇게 나누다 보면, 최종적으로 0~최대치 범위의 utilization에 근사한 값이 된다.
이 공식은 composable한데, 다음과 같은 연산이 가능하다:

1

ewma(A) + ewma(B) = ewma(A+B)

이 성질은 중요한데, task별 평균을 계산해두고, 그걸 runqueue평균으로도 합칠 수 있으며, task가 CPU를 옮겨다녀도 평균의 재조립이 쉽게 되어있다.
-> 스케줄러의 입장에서 매우 편리히다

PELT는 두 가지를 추적한다:

running: 실제로 CPU위에서 실행된 시간
runnable: runqueue에서 실행 가능한 상태였던 시간 여러 task들끼리 경쟁하다보면, running보다 runnable이 상대적으로 더 커지는데, runnable에는 실제 사용량과 경쟁 압력이 쌓인다.

또한, blocked task는 상위 그룹 등의 누적에 계속 반영되는데, 그들이 금방 복귀할 것이 기대되어 CPU를 다시 쓸 가능성이 높아지기 때문이다.

이외에도, PELT는 주파수와 CPU 성능차를 보정하며, UTIL_EST라는 sleep시의 보조 추정치와 utilization clamp 보정 작업들 역시 진행된다.

정리하면, 스케줄러는 task wakeup, migrate 등의 이벤트마다 PELT값을 갱신하여 schedutil governor에 알려서 CPU 주파수를 조절한다.
running값, util_est, RT/IRQ/Deadline부하, UCLAMP제한 등을 고려하여
현재 필요한 utilization와 원하는 주파수를 결정(DVFS)한다.

이러한 구조로 순간적인 스파이크에 덜 영향받으면서, 최근의 부하를 반영하며, ask migration에서 유영하며, 깨어나는 task에 대해 ramp up 지연을 줄일 수 있다.
대신 task migration동안 utilization gap이 생길 수 있으나, 평균 기반이라 완벽할 수 없으며, 시간이 지나며 결국 수렴하는 형태를 띤다.

멀티코어에서의 그룹 스케줄링

두 개의 CPU코어를 가진다고 해보자.
아래 그림과 같은 Task group계층을 가정한다.
빨간색 Task는 CPU0에서, 파란색은 CPU1에서 Runnable하다고 하고, 회색 Task는 Runnable하지 않다고 가정한다.
단, 저 Task들이 어디서 Runnable한지에 대해서는 특정 시점에 대해서만 유효하다.

CPU0의 runq 에서는 sched_entity(ies)로 t1과 tg2를 가진다.
tg1은 CPU0에서 runnable한 sched_entiy(ies)가 0개이므로, CPU0에서의 대표 sched_entity를 가지지 않는다.

CPU1의 runq에서는 shced_entity(ies)로 t2와 tg1을 가진다.
tg2는 CPU1에서 runnable한 sched_entity(ies)가 0개이므로, CPU1에서의 대표 sched_entity를 가지지 않는다.

CPU0에서는 t1과 tg2중 더 우선인 sched_entity(ies)를 고르고, 단일 Task라면 바로 실행하지만, Task group이라면 내부에서 또 우선순위를 비교한다.
CPU1에서도 같다.

가중치 분배

Task들은 이렇게 여러 CPU들에 분배될 수 있는데, 다 합친 Task Group의 사용량이 몫을 넘지 않도록 조절해야 한다.
그러나, task group 내의 task들은 항상 균등하게 분배되지 않는다.
예를 들어서, 4개의 task로 이루어진 task group이 있고, 4코어의 시스템에서 돌아간다면, 4개 다 runnable해서 4코어에 퍼질 수가 있고, 어떤 순간에는 runnable이 1~2개만 남아서 1~2코어에서만 동작할 수 있다.(lock, I/O, sleep 등으로 인해)
그래서 그룹 스케줄링은 매 순간마다 runnable의 분포에 맞춰서 그룹 몫을 CPU들에 재분배해야 한다.

이전에 설명했듯이, 그룹 스케줄링에서는 task group의 CPU할당은 cpu.shares 또는 cpu.weight으로 정해진다.
nice값처럼, cpu.shares 또는 cpu.weight은 그룹의 CPU 할당에 관여한다.
그룹의 CPU할당은 태스크와 내부 그룹의 태스크의 CPU 할당으로 분배된다.
기본적으로, cpu.shares는 1024이고, cpu.weight은 100이다.
커널 내부에서, 둘은 같은 스케일로 바뀌어 사용된다.
즉, cgroup v1인 cpu.shares=1024와 cgroup v2인 cpu.weight=100은 커널 내부에서 nice=0의 값인 NICE_0_LOAD로 바뀐다.
그래서 task_group을 만들 때, weight/shares는 내부 가중치로 환산되어 task_group::shares에 저장해두고, 그 값에 기반해 CFS가 그룹끼리 CPU시간을 나눈다.

예를 들어서, 3개의 CFS task가 nice=0, 2개의 CFS task group이 cpu.shares = 1024라면, 3개의 CFS task는 각각 20%의 CPU를 할당받고, 2개의 task group은 각각 20%의 CPU를 할당받아 내부에서 나눠쓴다.

한 번 cgroup이 만들어지고 나서는, cpu.shares/cpu.weight을 수정해서 할당시간을 조절시킬 수도 있다.

예시: 가중치 분배

systemd-run을 이용해서 실험해보자.
cgroup v2 + systemd환경이라면 따라해볼 수 있다.

하나의 group에서 하나의 Task

5개의 프로세스를 전부 같은 100의 weight로 하나의 CPU에서 실행한다.

1
2
3
4
5


sudo systemd-run --unit=w1 -p AllowedCPUs=0 -p CPUQuota=100% -p CPUWeight=100 bash -lc 'sha1sum /dev/zero >/dev/null'
sudo systemd-run --unit=w2 -p AllowedCPUs=0 -p CPUQuota=100% -p CPUWeight=100 bash -lc 'sha1sum /dev/zero >/dev/null'
sudo systemd-run --unit=w3 -p AllowedCPUs=0 -p CPUQuota=100% -p CPUWeight=100 bash -lc 'sha1sum /dev/zero >/dev/null'
sudo systemd-run --unit=w4 -p AllowedCPUs=0 -p CPUQuota=100% -p CPUWeight=100 bash -lc 'sha1sum /dev/zero >/dev/null'
sudo systemd-run --unit=w5 -p AllowedCPUs=0 -p CPUQuota=100% -p CPUWeight=100 bash -lc 'sha1sum /dev/zero >/dev/null'

이후, 프로세스를 확인해보자.
각자 한 CPU에서 경쟁함에도, 대략 20%씩은 보장받고있다.

이제, w5만 weight을 절반으로 낮춰보자.

1

sudo systemctl set-property w5 CPUWeight=50

상한은 없게 하였기에(CPUQuota=100%), 전체 CPU시간을 weight만으로 공평하게 할당해주고 있다.

아래 명령어로 정리하면 된다.

1
2


sudo systemctl stop demo1 demo2 demo3 demo4 demo5 w1 w2 w3 w4 w5 2>/dev/null
sudo systemctl reset-failed demo1 demo2 demo3 demo4 demo5 w1 w2 w3 w4 w5 2>/dev/null

Group 내에 여러 task

이번에는 5개의 cgroup인데, 하나의 그룹 안에서는 두 개의 task가 돌아가도록 해보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


sudo systemd-run --unit=g1 -p AllowedCPUs=0 -p CPUQuota=100% -p CPUWeight=100 \
 bash -lc 'sha1sum /dev/zero >/dev/null'

sudo systemd-run --unit=g2 -p AllowedCPUs=0 -p CPUQuota=100% -p CPUWeight=100 \
 bash -lc 'sha1sum /dev/zero >/dev/null'

sudo systemd-run --unit=g3 -p AllowedCPUs=0 -p CPUQuota=100% -p CPUWeight=100 \
 bash -lc 'sha1sum /dev/zero >/dev/null'

sudo systemd-run --unit=g4 -p AllowedCPUs=0 -p CPUQuota=100% -p CPUWeight=100 \
 bash -lc 'sha1sum /dev/zero >/dev/null'

# 두 개의 sha1sum을 실행
sudo systemd-run --unit=g5 -p AllowedCPUs=0 -p CPUQuota=100% -p CPUWeight=100 \
 bash -lc 'sha1sum /dev/zero >/dev/null & sha1sum /dev/zero >/dev/null & wait'

두 개의 sha1sum이 대략 10씩 나눠쓰는 모습을 볼 수 있다!

아래 명령어로 정리하자:

1
2


sudo systemctl stop g1 g2 g3 g4 g5 g5b 2>/dev/null
sudo systemctl reset-failed g1 g2 g3 g4 g5 g5b 2>/dev/null

가중치 할당

Task group에는 그룹 전체의 weight(task_group::shares)를 가진다.
서로 다른 CPU들에서의 부하에 대한 기여도가 각자 다를 수 있다.
어떤 순간에는 CPU0에 여러 개, 어떤 순간에는 CPU1에 runnable task가 없음 등의 상황이 생길 수 있다.
그래서 그룹의 몫을 CPU 수로 똑같이 나누는 것은 불가능하다.
그러면서도 그룹의 CPU share를 만족시켜야 한다.

Task group이 생성되고, per-cpu의 sched_entity(ies), 즉 task_group::se[i]가 NICE_0_LOAD의 weight로 나오는데, 처음 그룹을 만들 때에는 runnable task가 없기 때문에 기본값으로 줘도 된다.

Task group의 task들이 1개 이상의 CPU에서 동작하기 시작하면, task_group::se[i]가 해당 CPU에서의 부하 비율로 업데이트된다.
다음의 근사식을 통해 CPU i에서의 그룹 엔티티의 weight가 정해진다:

1

task_group.se[i].load.weight = task_group.weight * task_group.cfs_rq[i].avg.load_avg / task_group.load_avg

tg.weight: 그룹 전체 weight값(shares)
tg.cfs_rq[i].avg.load_avg: CPU i 에서 tg가 실제로 돌려고 하는 평균 load
tf.load_avg: tg의 전체 load(대략 모든 CPU의 load 합)

예를 들면, tg의 runnable load가

CPU0에 3개
CPU1에 1개 있다면, tg 전체 몫에서는
CPU0에 75%
CPU1에 25%
할당한다.

CFS 스케줄러는 완전 정밀하게 계산하지 않고, 근사값으로만 계산하는데, 매 순간 정확히 계산하는 데에는 오버헤드가 있기 때문이다.
그래서 load_avg같은 평균치기반으로 근사하게 나오는 것이다.

가중치 계산

이러한 weight 계산은 calc_group_shares()를 호출하는 update_cfs_group()을 통해서 일어난다.
calc_group_shares는 task_group::cfs_rq[i]를 본다.
즉, CPU i에서 이 그룹이 얼마나 바쁘게 돌고 있는지를 확인한다.
이후, 그 정도에 비례하여 task_group::shares를 CPU별로 나눈다.
그렇게 task_group::se[i]의 weight에 저장된다.

그러면 update_cfs_group은 언제 호출될까?
주기적으로 scheduler tick이 오면, 그 CPU에서 실행중인 task의 sched_entity에 대해 entity_tick이 호출되면서 호출된다.
그리고 그 태스크의 조상 그룹의 entity들까지 같이 호출된다.

또한, 이벤트 발생 시에도 호출되는데, 다음의 이벤트에서 호출된다:

enqueue_task_fair
dequeue_task_fair
enqueue_entity
dequeue_entity 이러한 함수들은 task가 rq에 들어오거나 나가는 순간들이다.

예를 들면, 다음과 같은 상황이 있다:

task가 깨어남
task가 sleep/block됨
task가 다른 cpu로 migrate됨(기존 CPU dequeue -> 현재 CPU enqueue)
task가 다른 cgroup으로 이동 (기존 그룹에서 dequeue, 새 그룹에 enqueue)

Load balancing으로 인해서 Task가 할당되는 CPU가 바뀌거나 cgroup을 바꾸면 task_group::cfs_rq[i]의 load기여와 task_group::se[i]의 weight도 바뀌어야 하므로 enqueue/dequeue에서도 update를 하는 것이다.

유저 공간에서의 cpu.shares 또는 cpu.weight를 변경하면 커널 벡엔드의 sched_group_set_shares()를 호출하여 task_group::shares를 업데이트하며 update_cfs_group이 호출된다.

task_group::load_avg은 이상적으로 다음과 같이 저장된다:

1

task_group.load_avg = sum of (task_group.cfs_rq[i].avg.load_avg)

Task group의 평균 부하는 update_tg_load_avg에서 업데이트되는데, 이는 per-cpu의 CFS runq들중 하나에서 호출된다.
우선 현재 runq의 부하와 이전 task_group의 load에 대한 contribution의 차이가 기록된다.
만약 그 차이가 충분히 크면(마지막 기여값의 1/64 보다 크면), 그 차이를 task_group::load_avg에 반영(변화량을 누적)하고, 그리고 task_group이 기억해두는 이 runq에서의 마지막 기여값을 현재 load로 갱신한다.
너무 자잘한 변화까지 매번 반영하면, 업데이트가 너무 잦아지면서 비용이 커지므로, 작은 오차는 그냥 무시해서 성능을 챙기는 전략 이다.

그래서 결과적으로 task group의 load_avg는 항상 sum(task_group.cfs_rq[i].load)와 완전히 같지는 않지만, 거의 비슷하며 그 차이가 가져오는 부작용은 거의 없다고 본다.

만약에 load가 줄어드는 경우, 즉 음수 delta인 경우에는
(현재 load - 마지막 기여값)이 음수가 될 수 있다.
그 음수 delta를 task_group::load_avg에 더한다는 것은, 그 runq가 이전에 기여했던 load를 빼는 효과로, 이 runq의 기여가 줄었으니 그룹 총 load에서도 그만큼 줄이게 된다는 의미이다.

스케줄링 다시 정리해보기

task group의 sched_entity는 CPU의 메인 CFS rq 또는 상위 task group에 존재하며, 그들의 quota는 각 scheduler period마다 그룹 se가 host runq에서 가진 weight와 load에 따라 실행 시간 몫이 결정된다.

Task가 CPU에서 실행중이면, 매 tick마다 실제 실행시간(physical runtime)와 가상 실행시간(vruntime)이 sched_entity에 업데이트된다.
그룹 스케줄링에서는 이 업데이트가 아래에서 위로 계층적으로 올라가며 반영 된다.
즉, task -> task group -> 상위 task group -> …
그리고, 각 레벨마다 그 레벨의 sched_entity의 weight가 쓰인다.

task level에서는 우선순위로 정해지는 load weight
task_group레벨에서는 calc_cfs_share()가 계산해주는 group weight가 쓰인다.
만약 quota를 다 사용함을 감지하면, 현재 task를 preempt(선점)대상으로 표시한다.

만약 task t1이 하나 있는데, 이 task 자체가 quota를 다 사용하거나, 상위 그룹이 quota를 다 사용하거나, 그 상위 그룹이 quota를 다 사용해버리거나 한다면, t1은 선점 대상이 된다.
즉, task가 잘 돌고 있어도, 상위 그룹이 quota가 다 차버리면 끊길 수도 있다.

다음에 누구를 실행할지 고를 때에도, “왼쪽 끝"을 계층적으로 내려간다.
스케줄러가 다음 실행 대상을 고를 때:

메인 CFS runq의 RB-Tree에서 가장 왼쪽의 sched_entity를 고른다
task가 아니라 task_group의 sched_entity라면
- 그 그룹의 task_group.cfs_rq[i] RB-Tree로 들어가서
- 그 안에서도 가장 왼쪽 entity를 고른다.
이를 반복하여 결국 실제 task의 sched_entity까지 내려간다.

🚀 EEVDF 스케줄러

CFS는 좋은 공정성을 가졌지만, 다음의 문제가 있었다:

interactive workload에서의 latency문제
sleeper fairness 문제

그래서, 이를 보완한 EEVDF 스케줄러가 등장했다.

EEVDF 개요

Earliest Eligible Virtual Deadline First(EEVDF) 스케줄러는 리눅스 커널 6.6버전부터 CFS 스케줄러를 대신한다.
기존의 자료구조와 fairness 철학을 유지하며, 기존 CFS 코드를 기반으로 수정되었지만, task의 선택 로직은 바뀌었으며, latency의 모델이 더 명확해졌다.
CFS 스케줄러와 유사하게, EEVDF는 runnable task들에 대해 CPU time을 공평하게 할당하는 것을 목표로 한다.
그러기 위해, task마다 가상의 runtime을 할당하는데, “lag"라는 값으로 CPU time을 공평하게 받았는지 판단한다.
양수값의 lag는 CPU time을 덜 받은, 음수값의 lag는 CPU time을 충분히 받아서 덜 할당받아도 됨을 의미한다.
EEVDF는 0 이상의 lag를 가진 task들 중에서, virtual deadline(VD)를 각각 계산하여, 가장 이른 VD를 가진 task를 골라 다음에 실행한다.
이러한 방법은 latency-sensitive한 task와 짧은 time slice를 우선시할 수 있어, 그들의 응답성에 도움이 된다.

lag 계산

lag값은 다음과 같이 계산된다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


/*
 * lag_i = S - s_i = w_i * (V - v_i)
 *
 * However, since V is approximated by the weighted average of all entities it
 * is possible -- by addition/removal/reweight to the tree -- to move V around
 * and end up with a larger lag than we started with.
 *
 * Limit this to either double the slice length with a minimum of TICK_NSEC
 * since that is the timing granularity.
 *
 * EEVDF gives the following limit for a steady state system:
 *
 * -r_max < lag < max(r_max, q)
 *
 * XXX could add max_slice to the augmented data to track this.
 */
static void update_entity_lag(struct cfs_rq *cfs_rq, struct sched_entity *se)
{
 s64 vlag, limit;

 WARN_ON_ONCE(!se->on_rq);

 vlag = avg_vruntime(cfs_rq) - se->vruntime;
 limit = calc_delta_fair(max_t(u64, 2*se->slice, TICK_NSEC), se);

 se->vlag = clamp(vlag, -limit, limit);
}

cfs_rq의 vruntime avg값은 근사된 평균 vruntime값이며, 이 값에 현재 sched_entity->vruntime을 뺀다.
그래서 이 값이 양수면, 평균보다 vruntime이 뒤쳐졌으므로 CPU를 덜 할당받은 task라는 의미 이다.
음수이면, 평균보다 vruntime을 더 앞섰다는 뜻으로 CPU를 이미 많이 할당 받았다는 의미이다.

clamp()하는 이유는, V는 근사값이기에 트리에서 연산이 일어날때 값이 급변할 수 있는데, 이러한 경우 vlag이 이상한 값이 되어 스케줄링이 잘못될 수 있으므로, 최대 2*slice(최소 tick단위)의 범위로 lag의 크기를 제한한 것이다.

VD 업데이트

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


static bool update_deadline(struct cfs_rq *cfs_rq, struct sched_entity *se)
{
 if (vruntime_cmp(se->vruntime, "<", se->deadline))
 return false;

 /*
 * For EEVDF the virtual time slope is determined by w_i (iow.
 * nice) while the request time r_i is determined by
 * sysctl_sched_base_slice.
 */
 if (!se->custom_slice)
 se->slice = sysctl_sched_base_slice;

 /*
 * EEVDF: vd_i = ve_i + r_i / w_i
 */
 se->deadline = se->vruntime + calc_delta_fair(se->slice, se);

 /*
 * The task has consumed its request, reschedule.
 */
 return true;
}

아직 vruntime이 deadline을 넘지 않았다면, 요청량을 다 못썼으므로 갱신이 불필요함을 의미한다.
크거나 같다면, 갱신이 필요하다.
slice 요청량을 보정하고, deadline을 새로 갱신해준다.
이후, true를 반환하여 재스케줄 트리거를 일으킬 수 있다.

선택 로직

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89


/*
 * Earliest Eligible Virtual Deadline First
 *
 * In order to provide latency guarantees for different request sizes
 * EEVDF selects the best runnable task from two criteria:
 *
 * 1) the task must be eligible (must be owed service)
 *
 * 2) from those tasks that meet 1), we select the one
 * with the earliest virtual deadline.
 *
 * We can do this in O(log n) time due to an augmented RB-tree. The
 * tree keeps the entries sorted on deadline, but also functions as a
 * heap based on the vruntime by keeping:
 *
 * se->min_vruntime = min(se->vruntime, se->{left,right}->min_vruntime)
 *
 * Which allows tree pruning through eligibility.
 */
static struct sched_entity *__pick_eevdf(struct cfs_rq *cfs_rq, bool protect)
{
 struct rb_node *node = cfs_rq->tasks_timeline.rb_root.rb_node;
 struct sched_entity *se = __pick_first_entity(cfs_rq);
 struct sched_entity *curr = cfs_rq->curr;
 struct sched_entity *best = NULL;

 /*
 * We can safely skip eligibility check if there is only one entity
 * in this cfs_rq, saving some cycles.
 */
 if (cfs_rq->nr_queued == 1)
 return curr && curr->on_rq ? curr : se;

 /*
 * Picking the ->next buddy will affect latency but not fairness.
 */
 if (sched_feat(PICK_BUDDY) &&
 cfs_rq->next && entity_eligible(cfs_rq, cfs_rq->next)) {
 /* ->next will never be delayed */
 WARN_ON_ONCE(cfs_rq->next->sched_delayed);
 return cfs_rq->next;
 }

 if (curr && (!curr->on_rq || !entity_eligible(cfs_rq, curr)))
 curr = NULL;

 if (curr && protect && protect_slice(curr))
 return curr;

 /* Pick the leftmost entity if it's eligible */
 if (se && entity_eligible(cfs_rq, se)) {
 best = se;
 goto found;
 }

 /* Heap search for the EEVD entity */
 while (node) {
 struct rb_node *left = node->rb_left;

 /*
 * Eligible entities in left subtree are always better
 * choices, since they have earlier deadlines.
 */
 if (left && vruntime_eligible(cfs_rq,
 __node_2_se(left)->min_vruntime)) {
 node = left;
 continue;
 }

 se = __node_2_se(node);

 /*
 * The left subtree either is empty or has no eligible
 * entity, so check the current node since it is the one
 * with earliest deadline that might be eligible.
 */
 if (entity_eligible(cfs_rq, se)) {
 best = se;
 break;
 }

 node = node->rb_right;
 }
found:
 if (!best || (curr && entity_before(curr, best)))
 best = curr;

 return best;
}

RBTree의 정렬 키는 deadline이다.
그래서 가장 earlier한 deadline을 가진 sched_entity를 __pick_first_entity()로 뽑아낼 수 있다.

그렇지 않다면, augmented RB-tree 를 검사하는데, 평소에 각 노드에는 se->min_vruntime = min(se->vruntime, left->min_vruntime, right->min_vruntime)을 유지시켜서, 서브트리 안에 eligible할 가능성이 있는 vruntime이 있을 수 있는지 빠르게 체크가능하다.
왼쪽 서브트리에 가능성이 있다면 왼쪽으로, 현재노드가 가능성이 있다면, 현재 노드로 확정, 그게 아니라면 오른쪽 서브트리로 이동하며 RBTree를 순회한다.

그렇게 best가 선정되면, curr와 비교한다. curr이 여전히 더 앞서면, curr을 유지한다.
주요 로직 이전에는 보호 및 최적화 로직이 있는데, buddy는 선점과 관련된 helper라고 보면 된다.
이외에도 nr_queue면 조기종료, slice보호 등의 처리가 있다.

sleeping task와 lag

lag를 어떻게 관리할지, 특히 sleeping task에 대한 lag관리는 어떻게 해야할지 등에 대한 논의는 여전히 지속되고 있다.
커널 6.19.0기준의 EEVDF는 VRT(virtrual runtime) 에 기반한 부패하는(decaying) 매커니즘을 이용한다.
이는 짧은 시간동안 sleep되어 negative lag이 초기화되는 악용을 막는다.
Task가 잠이 들면, runq에서 여전히 남지만, “deferred dequeue” 로 마킹되어 VRT를 기반으로 lag이 부패되도록 하는것이다.
그래서 장기간 sleep된 task는 최종적으로 lag reset에 도달할 수 있다.
최종적으로 task는 자신의 VD가 더 이른 시간이라면, 다른 task로부터 선점할 수 있으며, task들은 sched_setattr() 시스템 콜을 이용하여 새로운 특정한 time slice를 요청해서 latency-sensitive 애플리케이션에서의 유용하게 쓰일 수 있다.

📚 References

Nix를 이용한 개발환경 구축 (w/ Nix Shell, Devshell)

Sun, 08 Feb 2026 23:08:44 +0900

Nix Shell은 Nix 패키지 매니저를 기반으로 개발환경을 독립적이고 재현가능하게 구성해준다.
Devcontainer기반의 개발 환경보다도 더욱 가볍고, 에디터 중립적이며 패키지 변경이 훨씬 간단하다.

처음에는 단순한 임시 쉘을 열어볼 것이고, 이후, 레거시 방식인 shell.nix를 사용한 방법, 마지막으로 flake를 활용한 devShell을 만들어 볼 것이다.

🍿 임시로 Nix Shell 생성하기

nix-shell명령으로 Nix Shell을 생성할 수 있다.
기본적인 방법과 flake를 이용하는 방법이 있다.

아래 명령들은 각각 nodejs를 nixpkgs로부터 받아서 nix store에 설치하고, 해당 패키지와 함께 쉘을 실행한다.

1
2
3
4
5


# basic nix shell without flake
nix-shell -p nodejs

# basic nix shell with flake
nix shell -p nixpkgs#nodejs

그러나, 이 방법은 재현하기 불편하고, 선언적이지 못하다.

🚀 `shell.nix`를 통한 환경 구축

이번에는 선언적으로 관리해보자.
shell.nix파일을 통해서 레거시 방법으로 개발용 쉘을 만들 수 있다. (보통 Nix에서 devShell이라는 말은 flake기반 환경을 말한다.) shell.nix파일을 생성한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


{pkgs ? import <nixpkgs> {}}:
pkgs.mkShell {
 packages = with pkgs; [
 nodejs
 python3
 gnutar
 ];

 inputsFrom = [pkgs.bat];

 shellHook = ''
 echo "welcome to nix shell!"
 echo "current python version: $(python --version)"
 echo "current node version: $(node --version)"
 '';

 ENVVAR = "test";
}

pkgs.mkShell은 다음의 Attribute들을 가진다:

name: shell의 이름. 기본값은 nix-shell-env이다.
packages: nix-shell환경에서 직접 실행하기 위한 실행가능 패키지들을 선언
inputsFrom: 지정된 derivation들이 필요하다고 선언한 buildInputs/nativeBuildInputs를 nix-shell환경으로 재사용
- 즉, 직접 실행할 명령이면 packages에, 빌드에 필요하면 inputsFrom이다.
shellHook: nix-shell이 실행되고 나서의 쉘 스크립트. 쉘 초기화를 담당
이외 키=값쌍의 쉘 환경 변수들을 선언할 수 있다.
이외에도 mkDerivation의 특성들을 쓸 수는 있지만, 이 정도면 충분하다.

아래를 보면, mkShell이 내부적으로 mkDerivation을 사용함을 알 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


# pkgs.mkShell.nix
{ lib, stdenv, buildEnv }:

# A special kind of derivation that is only meant to be consumed by the
# nix-shell.
{ name ? "nix-shell"
, # a list of packages to add to the shell environment
 packages ? [ ]
, # propagate all the inputs from the given derivations
 inputsFrom ? [ ]
, buildInputs ? [ ]
, nativeBuildInputs ? [ ]
, propagatedBuildInputs ? [ ]
, propagatedNativeBuildInputs ? [ ]
, ...
}@attrs:
let
 mergeInputs = name:
 (attrs.${name} or [ ]) ++
 (lib.subtractLists inputsFrom (lib.flatten (lib.catAttrs name inputsFrom)));

 rest = builtins.removeAttrs attrs [
 "name"
 "packages"
 "inputsFrom"
 "buildInputs"
 "nativeBuildInputs"
 "propagatedBuildInputs"
 "propagatedNativeBuildInputs"
 "shellHook"
 ];
in

stdenv.mkDerivation ({
 inherit name;

 buildInputs = mergeInputs "buildInputs";
 nativeBuildInputs = packages ++ (mergeInputs "nativeBuildInputs");
 propagatedBuildInputs = mergeInputs "propagatedBuildInputs";
 propagatedNativeBuildInputs = mergeInputs "propagatedNativeBuildInputs";

 shellHook = lib.concatStringsSep "\n" (lib.catAttrs "shellHook"
 (lib.reverseList inputsFrom ++ [ attrs ]));

 phases = [ "buildPhase" ];

 # ......

 # when distributed building is enabled, prefer to build locally
 preferLocalBuild = true;
} // rest)

❄️ `flake.nix`를 통한 환경 구축

그러나, shell.nix만으로는 충분하지 않다.
nixpkgs만 입력받고, 버전이 고정되지 못한다.
우리는 flake기반의 현대적인 devShell을 만들 것이다.
flake를 이용해서 다양한 입력을 받고, 패키지도 더 안정적인 구조를 만들 수 있다.

우선, flake를 초기화한다.

1

nix flake init

이후, flake.nix에 아래처럼 작성해보자:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


{
 description = "A very basic flake";

 inputs = {
 nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";
 };

 outputs = {
 self,
 nixpkgs,
 }: let
 system = "x86_64-linux";
 in {
 devShells."${system}".default = let
 pkgs = import nixpkgs {inherit system;};
 in
 pkgs.mkShell {
 packages = with pkgs; [
 nodejs
 python3
 gnutar
 ];

 inputsFrom = [pkgs.bat];

 shellHook = ''
 echo "Welcome to nix flake shell!"
 echo "current python version: $(python --version)"
 echo "current node version: $(node --version)"
 '';

 ENVVAR = "test";
 };
 };
}

nix develop 또는 nix develop .#default로 쉘을 열어보자.

🐟 bash이외에 다른 쉘 사용

물론 리눅스에서 bash가 표준 쉘인것은 맞지만, 커스터마이징 가능하고 개발환경에서 더 선호되는 것은 zsh/fish등의 쉘일 것이다.

아래 명령으로 nix-shell에서 zsh쉘을 사용할 수 있다.

1

nix develop .#default -c zsh

기존에 깔아진 플러그인이나 설정 등은 모두 그대로 가져올 수 있다.
devShell은 환경을 만들어 주입할 뿐, 쉘 자체를 만드는 것은 아니다.

또는,shellHook의 맨 끝에 exec zsh를 넣는 방법도 있지만, 이러면 팀원들 모두가 zsh가 기본이 되기에, 조심해야 한다.

🫧 Pure 쉘과 Impure 쉘

위의 zsh스크린샷을 보면, starship은 지금 shell을 impure하다고 평가하고 있다.
왜 그런 것일까?

한번 pure한 쉘을 만들어보자.

1

nix-shell -p nodejs --pure

kubectl은 없어서 실행할 수 없지만, node는 실행할 수 있다.

1
2
3
4
5


[nix-shell:~/dev/devshell-test]$ kubectl
bash: kubectl: command not found

[nix-shell:~/dev/devshell-test]$ node --version
v22.21.1

이번엔 nix develop으로 쉘을 다시 열어보자.
여기서도 kubectl을 설치한 적이 없지만, 실행되었다.
현재 시스템의 kubectl을 실행한 것이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


~/dev/devshell-test on ☁️ (ap-northeast-2) took 7s
15:40:52 ❯ nix-shell -p nodejs --pure

~/dev/devshell-test on ☁️ (ap-northeast-2)
15:40:55 ❯ nix develop .#default -c zsh
Welcome to nix flake shell!
current python version: Python 3.13.11
current node version: v24.13.0

~/dev/devshell-test via ❄️ impure (nix-shell-env) on ☁️ (ap-northeast-2)
15:40:58 ❯ kubectl
kubectl controls the Kubernetes cluster manager.

 Find more information at: https://kubernetes.io/docs/reference/kubectl/

...

왜 이런 것이 가능한 것일까?
왜냐하면, impure 쉘은 시스템 환경에 대한 fallback이 있기 때문이다.

Pure한것이 맞지 않느냐고 생각할 수 있지만, 현실적으로 우리는 불순함 투성이이다.
같은 개발 환경을 공유해도, 이외의 유틸 도구는 각자 다르게 사용하고 싶을 수 있으며, 각자가 다른 credential을 가지는 경우가 대부분이다.

그래도 개발에 관한 부분들이 nix-shell내에서 선언한 패키지들로 먼저 참조되므로, 무관한 부분들은 fallback되어도 상관없을 것이다.
nix develop은 기본적으로 --impure이며, flake입력은 고정되지만 런타임 PATH는 시스템을 fallback한다.

🐍 Hands-On: Python 개발환경 구축

Python 3.12에서 uv를 이용하여 Fastapi 서버를 개발한다고 해보자.
Python과 uv를 설치하는데에는 Nix,
Python 패키지와 가상환경은 uv가 관리한다.
기본적으로 Nix가 받은 Python버전을 따르면, uv에서는 별도로 Python버전을 명시하지 않아도 된다.

Nix와 uv를 통한 개발환경 구축

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


{
 description = "Python Dev environment with Nix + UV";

 inputs = {
 nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
 };

 outputs = {
 self,
 nixpkgs,
 }: let
 system = "x86_64-linux";
 in {
 devShells."${system}".default = let
 pkgs = import nixpkgs {inherit system;};
 in
 pkgs.mkShell {
 name = "nix-shell-env"; # 원한다면 이름을 바꿔보기

 packages = with pkgs; [
 python312
 uv
 ];

 shellHook = ''
 echo "Welcome to nix flake shell"

 uv init 2>/dev/null

 uv venv --allow-existing
 source .venv/bin/activate

 uv sync

 echo -e "❄️❤️🐍 \e[32mNix Shell Initialized successfully!\e[0m"
 echo "Initialized successfully!"
 echo "To run, fastapi run(or dev) main.py"
 '';
 };
 };
}

이 flake는 Python 3.12와 uv를 설치한다.
이후, uv가 쉘 초기화 시 자동으로 가상환경을 활성화하여 Python 패키지를 동기화한다.

uv를 통해서 fastapi[standard]를 설치한다.

1

uv add fastapi[standard] # zsh의 경우, "fastapi[standard]"

이후, main.py에 아래와 같이 해보자:

1
2
3
4
5
6
7


from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
 return {"message": "hello nix + uv!"}

성공적으로 FastAPI 서버가 열린다!

가상환경 Deactivate

Python가상환경은 해당 쉘에서만 활성화 되기에, devshell을 빠져나오면 같이 deactivate된다.
아래 사진에서는 fastapi명령이 가상환경 + devshell에서는 가능하지만, devshell을 빠져나오고 나서는 가상환경도 같이 닫혔으므로 fastapi명령을 쓸 수 없다.

Proxmox Homelab 구성 - 3. 클러스터 앞단에 BGP라우터 설치

Sat, 31 Jan 2026 00:33:15 +0900

FRRouting은 Linux/Unix 플랫폼에서의 오픈 소스 라우팅 프로젝트이다.
다양한 라우팅 프로토콜을 지원한다.
우리는 쿠버네티스 클러스터 노드들의 앞단에 세워 쓸 것이고,
service를 외부에 광고하거나 로드 밸런서를 실제로 부하가 분산되도록
할 것이다.

💿 FRR 설치

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# add GPG key_
curl -s https://deb.frrouting.org/frr/keys.gpg | sudo tee /usr/share/keyrings/frrouting.gpg > /dev/null

FRRVER="frr-stable"

# Ubuntu 24.04
echo deb '[signed-by=/usr/share/keyrings/frrouting.gpg]' [https://deb.frrouting.org/frr](https://deb.frrouting.org/frr) \
 noble $FRRVER | sudo tee -a /etc/apt/sources.list.d/frr.list

# update and install FRR_
sudo apt update && sudo apt install frr frr-pythontools -y

# enable services
sudo systemctl enable --now frr

이후, /etc/frr/daemons에서 bgpd를 켜준 뒤, 재시작한다.

1
2
3
4


# vim /etc/frr/daemons
---

bgpd=yes ...

1

sudo systemctl restart frr

📜 BGP란

BGP(Border Gateway Protocol) 는 AS(Autonomous System)들을 연결하는 정책 기반 라우팅 프로토콜이다. 최선의 속도만이 아닌, 비용, 보안, 정치적인 사유로 AS들간의 통신을 설정하여 네트워크 트래픽을 제어한다

Well-known port 179를 이용하여 라우팅 정보를 교환한다. 연결이 된 이후에는 변경사항만 업데이트된다.

AS(Autonomous System)

인터넷은 자율 시스템(AS: Autonomous System) 이라는 수십만 개의 작은 네트워크로 나뉘어지는데, 이 각각의 네트워크는 기본적으로 하나의 조직이 운영하는 큰 라우터들의 큰 집합이다.

각 AS는 ASN이라는 고유의 식별 번호를 가진다. 2-octet값, 즉 16비트값으로, 최대 65535까지 가능하다.

64512 ~ 65535번은 private AS number들이다. 글로벌 인터넷에 노출되어서는 안된다.

Address Family

AF(Address Family) 는 BGP가 어떤 주소 종류와 라우팅 정보 종류를 다루는가에 대해 구분한다. BGP는 IPv4와 IPv6에 대한 AFI(Address Family Identifier)를 지원한다.

같은 BGP세션(TCP 179)에서 여러 종류의 커넥션들에 대해 각각 광고 여부와 정책, next-hop처리 등을 설정할 수 있다. 이때 서로 다른 처리를 위해 AF를 이용한다.

AF는 AFI/SAFI로 나뉜다:

AFI(Address Family Identifier): 주소 체계(IPv4? IPv6?)
SAFI(Subsequent AFI): 어떤 유형인지(unicast, multicast, vpn, evpn)

동작 과정

FRR의 BGP구현은 아래의 결정을 따른다: 위에 있을수록 더 우선되는 기준이다

Weight check
Local preference check
Local route check
AS path length check
Origin check
MED check
External check
IGP cost check
Multi-path check
Already-selected external check
Router-ID check
Cluster-List length check
Peer address

NOTE
BGP에 대해서는 여기를 더 참조할 수 있다.

🌐 쿠버네티스 앞단의 BGP라우터로 세팅하기

아래 내용을 /etc/frr/frr.conf에 작성하고, frr 서비스를 재시작한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


frr version 10.5.1
frr defaults traditional
hostname frr-router
log syslog informational
service integrated-vtysh-config
!
# 라우트맵 정의: 모든 경로 허용
route-map ALLOW-ALL permit 10
exit
!
# BGP 라우터 설정 (ASN 65000)
router bgp 65000
 # BGP 라우터 ID 설정
 bgp router-id 192.168.10.1
 # K8S-NODES라는 peer-group 생성
 neighbor K8S-NODES peer-group
 # K8S-NODES peer-group의 remote ASN을 65001로 설정
 neighbor K8S-NODES remote-as 65001
 # capability를 동적으로 협상 가능하게 하도록 설정(새로운 세션 없이)
 neighbor K8S-NODES capability dynamic
 # 192.168.10.0/24 대역의 노드들이 동적으로 BGP피어링이 가능하도록 설정
 bgp listen range 192.168.10.0/24 peer-group K8S-NODES
 !
 # IPv4 유니캐스트 Address family 설정
 address-family ipv4 unicast
 # K8S-NODES그룹에게 Next-hop을 자신으로 변경
 neighbor K8S-NODES next-hop-self
 # K8s-NODES그룹에서 받는 경로에 ALLOW_ALL 라우트맵 적용
 neighbor K8S-NODES route-map ALLOW-ALL in
 # K8s-NODES그룹으로 보내는 경로에 ALLOW_ALL 라우트맵 적용
 neighbor K8S-NODES route-map ALLOW-ALL out
 # ECMP(Equal-Cost Multi-Path) 설정 - 최대 경로 수를 64개 설정
 maximum-paths 64
 exit-address-family
exit
!

이제, 쿠버네티스 클러스터 쪽에서 연결을 시도해주면 된다.
다음 글에서 다룰 것이다.

아래는 BGP피어링이 잘 된 모습인데, Cilium 세팅을 해줄 것이다.

Cilium쪽에서 BGP Peering을 하는 것에 대한 내용은, 여기를 참고할 수 있다.

📚 References

Proxmox Homelab 구성 - 2. 쿠버네티스 클러스터 구축

Sat, 24 Jan 2026 10:47:26 +0900

Proxmox의 VM 및 LXC등을 Terraform/Opentofu로 관리하여 선언적으로 홈랩 인프라를 관리할 수 있다.
여기서는 bpg/proxmox(opentofu버전은 여기) Provider를 이용한다.

아래의 네트워크 토폴로지를 구성할 것이다:

⚙️ Proxmox에서 Terraform 유저 만들기

계정 생성

Terraform 사용을 위한 최소 권한의 계정을 만들어줄 것이다.

Proxmox 9에서는 아래의 명령을 쓰면 된다:

1
2
3


pveum role add TerraformProv -privs "Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit Pool.Allocate Pool.Audit Sys.Audit Sys.Console Sys.Modify VM.Allocate VM.Audit VM.Clone VM.Config.CDROM VM.Config.Cloudinit VM.Config.CPU VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.Migrate VM.PowerMgmt SDN.Use VM.GuestAgent.Audit"
pveum user add terraform-prov@pve --password <password>
pveum aclmod / -user terraform-prov@pve -role TerraformProv

각 줄마다 다음과 같다:

terraform user를 위한 role생성(vm생성, 네트워크 관리 등을 위한 최소 권한)
사용자 생성
user에게 role을 바인딩

토큰 생성

비밀번호 대신 API 토큰을 사용하는 것이 권장된다.

1

pveum user token add terraform-prov@pve mytoken

이 명령은 terraform-prov@pve에게 mytoken이라는 id의 토큰을 만든다.

나온 값을 안전한 곳에 저장해주자.

기본적으로, token이 user의 권한을 다 계승받는 것이 아니다. Privilege Separation이 되어있다. 그래서, role을 별도로 바인딩해줘야 한다.

1

pveum aclmod / -token 'terraform-prov@pve!mytoken' -role TerraformProv

🫥 `.gitignore`

.gitignore에 다음 파일들을 넣어주자

1
2
3
4
5


.terraform/
.DS_Store
*.tfstate
*.tfstate.backup
*tfvars

📂 폴더 구조

현재는 terragrunt나 s3 remote backend를 세팅하지 않았다. 당장은 부분마다 불편하더라도 폴더별로 init -> plan -> apply를 하는식으로 단순하게 사용한다. 때문에, provider.tf나 variables.tf등에서 반복적인 작업의 부분이 생길 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


.
├── 00.network
│   ├── main.tf
│   ├── provider.tf
│   ├── terraform.tfstate
│   ├── terraform.tfvars
│   └── variables.tf
├── 01.templates
│   ├── main.tf
│   ├── outputs.tf
│   ├── provider.tf
│   ├── terraform.tfstate
│   ├── terraform.tfvars
│   └── variables.tf
├── 10.routers
│   ├── main.tf
│   ├── outputs.tf
│   ├── provider.tf
│   ├── terraform.tfstate
│   ├── terraform.tfvars
│   └── variables.tf
├── 11.nodes
│   ├── main.tf
│   ├── outputs.tf
│   ├── provider.tf
│   ├── terraform.tfstate
│   ├── terraform.tfvars
│   └── variables.tf
├── 98.cloud-init
│   ├── frr-cloud-config.yaml
│   └── general-vm-config.yaml
├── 99.modules
│   ├── template
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   ├── provider.tf
│   │   └── variable.tf
│   └── vm
│   ├── main.tf
│   ├── outputs.tf
│   ├── provider.tf
│   └── variable.tf

📦 Provider 설정

각 세부폴더별 provider를 다음과 같이 세팅한다:

SSH 에이전트 세팅

ssh키가 없다면, 생성한다.

1

ssh-keygen

사용하려는 Opentofu Provider가 파일을 조작할 때, SSH Agent를 이용하기에, SSH 키를 배포해야 한다.

1
2
3
4
5
6
7
8
9


# SSH Agent 실행
eval $(ssh-agent -s)

# SSH Agent에게 키 목록 추가
ssh-add ~/.ssh/id_rsa
ssh-add ~/.ssh/id_ed25519

# 노드에 키 전달
ssh-copy-id root@<proxmox-node>

`provider.tf`

provider.tf에 아래 내용을 추가한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


terraform {
 required_providers {
 proxmox = {
 source = "bpg/proxmox"
 version = "0.93.0"
 }
 }
}

provider "proxmox" {
 endpoint = "https://<proxmox-node>:8006"
 api_token = var.proxmox_api_token
 insecure = true

 ssh {
 agent = true
 username = "root"
 }
}

variable.tf에 proxmox_api_token값을 저장한다.

1
2
3


variable "proxmox_api_token" {
 type = string
}

이후, provider를 세팅해준다.

1

tofu init

🧱 모듈

테라폼 코드의 재사용성을 위해, 모듈화를 진행해주었다. 여기서는 두 가지의 핵심 모듈이 있다:

탬플릿 모듈 - 클라우드 이미지를 참조하여 proxmox에서 template vm으로 기초적인 뼈대를 생성하는 모듈
vm모듈 - 탬플릿을 참조하여 vm을 생성한 뒤, cloud-init을 이용하여 세부 설정

보통 Proxmox에서 vm을 생성하는 패턴은 다음과 같다:

클라우드 이미지로부터 기본 세팅된 탬플릿 vm생성
탬플릿 vm으로부터 클론
cloud-init으로 개별화

이를 통해서 다음의 이점을 가진다:

빠른 vm생성
일관성
재현성
자동화 친화적

참고로, 모듈의 provider.tf에는 provider "proxmox"{} 부분이 없어도 된다. 모듈에서는 자격 증명을 요구하지 않기 때문이다.

탬플릿 모듈

탬플릿 모듈은 클라우드 이미지를 설치하여 최소한의 기본 설정을 할당한다. provider.tf는 생략.

변수 정의

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


# 99.modules/template/variable.tf
variable "template_id" {
 type = number
}

variable "template_name" {
 type = string
}

variable "ve_node_name" {
 type = string
}

variable "datastore_id" {
 type = string
 default = "local"
}

variable "image_url" {
 type = string
}

입력받을 변수를 정의한다.

template_id: 탬플릿 vm의 id
template_name: 탬플릿 vm의 이름
ve_node_name: 생성될 Proxmox 노드
datastore_id: 가상디스크를 할당할 스토리지명
image_url: 클라우드 이미지를 설치할 수 있는 URL

`main.tf`

template vm의 이름과 어느 노드에서 띄울지, id등을 정한다. 그리고, 기본적인 cpu코어 수, 메모리, 디스크 설정 등을 해준다. 핵심은 template=true로 지정했으며, 클라우드 이미지를 디스크에 설치한다는 것이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58


# 99.modules/template/main.tf
resource "proxmox_virtual_environment_vm" "template" {
 name = var.template_name
 node_name = var.ve_node_name
 vm_id = var.template_id

 template = true # Template
 started = false

 machine = "q35" # modern vm type <-> pc: legacy system
 bios = "ovmf" # UEFI
 description = "Managed by Terraform"

 cpu {
 cores = 2
 }

 memory {
 dedicated = 2048
 }

 # Required if bios == ovmf
 efi_disk {
 datastore_id = var.datastore_id
 type = "4m" # Recommended
 }

 disk {
 datastore_id = var.datastore_id
 file_id = proxmox_virtual_environment_download_file.cloud_image.id # file ID for a disk image
 interface = "virtio0"
 iothread = true
 discard = "on" # pass discard/trim requests to the underlying storage
 size = 20
 }

 # Cloud_init config
 initialization {
 datastore_id = var.datastore_id
 ip_config {
 ipv4 {
 address = "dhcp"
 }
 }
 }

 network_device {
 bridge = "vmbr0"
 }
}

# Download Cloud image
resource "proxmox_virtual_environment_download_file" "cloud_image" {
 content_type = "iso"
 datastore_id = var.datastore_id
 node_name = var.ve_node_name
 url = var.image_url
}

`outputs.tf`

template vm의 id를 다른 생성하려는 vm에서 참조하려면, id가 필요하므로 output으로 별도 저장해준다.

1
2
3
4


# 99.modules/template/outputs.tf
output "id" {
 value = proxmox_virtual_environment_vm.template.id
}

vm 모듈

이제, vm모듈을 만든다. vm모듈은 template vm의 id를 참조하여 clone한 뒤, 별도의 cloud-init설정을 주입하도록 할 것이다.

`variables.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


# 99.modules/vm/variables.tf
variable "vm_name" {
 type = string
}

variable "node_name" {
 type = string
}

variable "vm_id" {
 type = number
}

variable "template_id" {
 type = string
}

variable "cpu_cores" {
 type = number
}

variable "memory" {
 type = number
}

variable "datastore_id" {
 type = string
}

variable "networks" {
 type = list(object({
 bridge = string
 ip = string
 gw = string
 }))
}

variable "ssh_keys" {
 type = list(string)
}

variable "username" {
 type = string
}

variable "cloud_init_data" {
 type = string
}

이미 익숙한 변수들이 보인다. 추가적으로, 다음의 변수들이 보인다:

참조할 template_id
덮어씌울 컴퓨팅 스펙
여러 네트워크 링크를 위한 정보
ssh 키
사용자명
cloud init 데이터

`main.tf`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


# 99.modules/vm/main.tf
resource "proxmox_virtual_environment_vm" "vm" {
 name = var.vm_name
 node_name = var.node_name
 vm_id = var.vm_id
 clone {
 vm_id = var.template_id
 }

 agent {
 enabled = true
 }

 cpu {
 cores = var.cpu_cores
 }
 memory {
 dedicated = var.memory
 }

 dynamic "network_device" {
 for_each = var.networks
 content {
 bridge = network_device.value.bridge
 }
 }

 initialization {
 datastore_id = var.datastore_id
 user_data_file_id = proxmox_virtual_environment_file.cloud_config.id
 user_account {
 username = var.username
 keys = var.ssh_keys
 }

 dynamic "ip_config" {
 for_each = var.networks
 content {
 ipv4 {
 address = ip_config.value.ip
 gateway = ip_config.value.gw != "" ? ip_config.value.gw : null
 }
 }
 }
 }
}

resource "proxmox_virtual_environment_file" "cloud_config" {
 node_name = var.node_name
 datastore_id = var.datastore_id
 content_type = "snippets"

 source_raw {
 data = var.cloud_init_data
 file_name = "${var.vm_name}.cloud-config.yaml"
 }
}

Proxmox는 기본적으로 Shutdown, Reboot등을 ACPI로 제어하여, VM안에서 qemu-guest-agent가 필요하지 않다. 그러나, 간혹 통하지 않는 VM이 있다고 한다. 이러면 destroy시 무한로딩이 걸릴 수 있다. 그래서, qemu-guest-agent를 활성화시키는 것을 보장하기로 약속하는 플래그로 agent.enabled = true를 설정한다.

단, qemu-guest-agent가 설치되어야 하는데, 대부분의 클라우드 이미지에는 없을 것이다. 그래서, cloud-init을 통해 qemu-geust-agent를 설치해줘야 한다.

이 vm은 template vm으로부터 vm을 클론하고, 입력받은 스펙대로 새로 오버라이드하며, cloud-init을 이식해준다. cloud-init데이터 또한 변수처리하여 유연하게 받을 수 있도록 세팅해줬다.

outputs.tf

출력 결과 표시를 위해, output으로 ip주소를 넣어주었다.

1
2
3
4


# 99.modules/vm/outputs.tf
output "ips" {
 value = proxmox_virtual_environment_vm.vm.ipv4_addresses
}

🌐 내부 네트워크 생성

vmbr1이라는 가상 네트워크 인터페이스를 만들어준다.
proxmox 내부 네트워크를 위해 만들어줬다.

1
2
3
4
5
6


# 00.network/main.tf
resource "proxmox_virtual_environment_network_linux_bridge" "vmbr1" {
 node_name = "pve-01"
 name = "vmbr1"
 comment = "In-proxmox network"
}

이후, 적용해준다.

1

tofu apply

대시보드에서 vmbr1이 생긴 것을 확인할 수 있다.

🐣 탬플릿 생성

이제, 모듈을 참조해서 자원을 만들어보자. Ubuntu 24.04 LTS 클라우드 이미지를 기반으로 탬플릿을 생성해준다.

1
2
3
4
5
6
7
8
9


# 01.templates/main.tf
module "ubuntu_template" {
 source = "../99.modules/template"
 template_id = 100
 template_name = "ubuntu-template"
 ve_node_name = "pve-01"
 datastore_id = "local"
 image_url = "https://cloud-images.ubuntu.com/noble/20251113/noble-server-cloudimg-amd64.img"
}

outputs.tf로 id를 참조할 수 있도록 출력해준다.

1
2
3
4


# 01.templates/outputs.tf
output "id" {
 value = module.ubuntu_template.id
}

적용해주면, Ubuntu 24.04를 기반으로 한 탬플릿 vm이 생성된다.

1

tofu init

↔️ 라우터 vm 생성

라우터 역할을 할 vm을 생성해준다.
이 vm에서는 FRRouting BGP + NAT + Tailscale Subnet Router를 제공해줄 것이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


# 10.routers/main.tf
locals {
 # 공개 키를 여기에 넣기
 ssh_keys = [
 ...
 ]

 vm_name = "frr-router"
 username = "ubuntu"
}

data "terraform_remote_state" "ubuntu_template" {
 backend = "local"
 config = {
 path = "../01.templates/terraform.tfstate"
 }
}

module "frrouter" {
 source = "../99.modules/vm"
 node_name = "pve-01"
 vm_name = local.vm_name
 vm_id = 200
 template_id = data.terraform_remote_state.ubuntu_template.outputs.id
 cpu_cores = 2
 memory = 2048
 username = local.username
 datastore_id = "local"
 networks = [
 { bridge = "vmbr0", ip = "192.168.0.8/24", gw = "192.168.0.1" },
 { bridge = "vmbr1", ip = "192.168.10.1/24", gw = "" }
 ]
 ssh_keys = local.ssh_keys
 cloud_init_data = templatefile("${path.root}/../98.cloud-init/frr-cloud-config.yaml", {
 hostname = local.vm_name
 username = local.username
 ssh_keys = local.ssh_keys
 })
}

Ubuntu template으로부터 clone시키고, 별도의 cloud-init을 주입하여 NAT셋업을 해준다.
SSH 키도 같이 주입해준다.

Cloud-init

qemu-guest-agent와 기타 필수 프로그램을 설치한다.
이후, 패킷을 포워딩하도록 커널 모듈을 활성화해주고, iptables의 포워딩 규칙도 추가하여 proxmox 내부 네트워크에서 외부로 NAT가 가능하도록 정책을 적용해준다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


# 98.frr-cloud-config.yaml
#cloud-config
hostname: ${hostname}
manage_etc_hosts: true
user: ${username}
ssh_authorized_keys:
%{ for key in ssh_keys ~}
 - ${key}
%{ endfor ~}

packages:
 - qemu-guest-agent
 - curl
 - vim
 - iptables-persistent

runcmd:
 - apt update
 - apt upgrade -y
 - systemctl enable --now qemu-guest-agent
 - cat << EOF | tee /etc/sysctl.d/99-forward.conf
 net.ipv4.ip_forward = 1
 net.ipv6.conf.all.forwarding = 1 
 EOF
 - sysctl --system
 - iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
 - iptables -A FORWARD -i eth1 -o eth0 -j ACCEPT
 - iptables -A FORWARD -i eth0 -o eth1 -m state --state RELATED,ESTABLISHED -j ACCEPT
 - netfilter-persistent save

 - echo "Cloud-init finished at $(date)" > /var/log/cloud-init-done.log

`outputs.tf`

IP를 조회할 수 있도록 output을 만들어준다.
쿠버네티스 노드들이 기본 게이트웨이를 참조할 때도 필요하다.

1
2
3
4


# 10.routers/outputs.tf
output "frr_ip" {
 value = module.frrouter.ips
}

적용

적용 시, 라우터 vm이 생성되고, 두 개의 네트워크 인터페이스로 공유기의 네트워크와 proxmox클러스터 내부 네트워크에 둘다 연결된다.

1

tofu init

🐥 k8s노드 vm 생성

이제, 쿠버네티스 노드들을 위한 vm들을 생성해준다. 반복문을 이용해서 값만 변경하여 여러 개 생성한다.

template vm의 id와 라우터의 내부망 ip를 remote_state로 참조해온다. 그뒤, 3개의 노드를 생성한다. 기본 게이트웨이로 앞에서 만든 라우터로 트래픽이 향하도록 만든 것을 알 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73


# 11.nodes/main.tf
data "terraform_remote_state" "ubuntu_template" {
 backend = "local"
 config = {
 path = "../01.templates/terraform.tfstate"
 }
}
data "terraform_remote_state" "frr" {
 backend = "local"
 config = {
 path = "../10.routers/terraform.tfstate"
 }
}

locals {
 # 공개 키를 여기에 넣기
 ssh_keys = [
 ...
 ]

 ubuntu_template_id = data.terraform_remote_state.ubuntu_template.outputs.id
 frroute_ip = data.terraform_remote_state.frr.outputs.frr_ip[2][0]

 k8s_nodes = {
 "cp-1" : {
 vm_name = "cp-1"
 vm_id = "1010",
 cpu_cores = 4
 memory = 4096
 networks = [
 { bridge = "vmbr1", ip = "192.168.10.10/24", gw = local.frroute_ip }
 ]
 }
 "worker-1" : {
 vm_name = "worker-1"
 vm_id = "1100",
 cpu_cores = 4
 memory = 4096
 networks = [
 { bridge = "vmbr1", ip = "192.168.10.100/24", gw = local.frroute_ip }
 ]
 }
 "worker-2" : {
 vm_name = "worker-2"
 vm_id = "1101",
 cpu_cores = 4
 memory = 4096
 networks = [
 { bridge = "vmbr1", ip = "192.168.10.101/24", gw = local.frroute_ip }
 ]
 }
 }
}

module "k8s-node" {
 source = "../99.modules/vm"
 node_name = "pve-01"
 for_each = local.k8s_nodes
 vm_name = each.value.vm_name
 vm_id = each.value.vm_id
 template_id = local.ubuntu_template_id
 cpu_cores = each.value.cpu_cores
 memory = each.value.memory
 username = "ubuntu"
 datastore_id = "local"
 networks = each.value.networks
 ssh_keys = local.ssh_keys
 cloud_init_data = templatefile("${path.root}/../98.cloud-init/general-vm-config.yaml", {
 hostname = each.value.vm_name
 username = "ubuntu"
 ssh_keys = local.ssh_keys
 })
}

Cloud-init

여기서는 별도의 큰 작업 없이, 일부 필수프로그램만 받아주며 ssh키만 추가한다. 또한, NAT설정을 하도록 커널 모듈 로딩과 방화벽 설정을 해주었다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


# 98.cloud-init/general-vm-config.yaml
#cloud-config
hostname: ${hostname}
manage_etc_hosts: true
user: ${username}
ssh_authorized_keys:
%{ for key in ssh_keys ~}
 - ${key}
%{ endfor ~}

packages:
 - qemu-guest-agent
 - curl
 - vim
 - iptables-persistent

write_files:
 - path: /etc/sysctl.d/99-forward.conf
 owner: root:root
 permissions: '0644'
 content: |
 net.ipv4.ip_forward = 1
 net.ipv6.conf.all.forwarding = 1

runcmd:
 - apt update
 - apt upgrade -y
 - systemctl enable --now qemu-guest-agent
 - sysctl --system
 - iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
 - iptables -A FORWARD -i eth1 -o eth0 -j ACCEPT
 - iptables -A FORWARD -i eth0 -o eth1 -m state --state RELATED,ESTABLISHED -j ACCEPT
 - netfilter-persistent save
 - echo "Cloud-init finished at $(date)" > /var/log/cloud-init-done.log

`outputs.tf`

IP를 조회할 수 있도록 outputs를 사용한다.

1
2
3
4
5
6


output "k8s_node_ips" {
 value = {
 for k, ip in module.k8s-node :
 k => ip.ips
 }
}

노드가 여럿이므로 반복문을 이용한다.

적용

적용 시, 3개의 노드가 생성된다.

1

tofu apply

🔐 Tailscale 설치

Tailscale은 Wireguard기반의 VPN을 지원해주는 서비스이다.
이를 이용해서 Proxmox 클러스터 내부의 vm들에 접근할 수 있도록 해줄 것이다.
그러나, 각각의 VM이 tailnet VPN에 가입되는것은 번거롭기에, Subnet Router 기능을 이용해서 라우터 VM에만 VPN을 가입시키고, 트래픽을 중개시켜줄 것이다.

Router에 Tailscale설치

bastion host(FRRouter)에 접속해서 Tailscale을 설치해준다.

1
2
3
4
5


ssh bastion

curl -fsSL https://tailscale.com/install.sh | sh

sudo tailscale up

Subnet router 기능 이용하기

공식 문서에 따르면, 원래는 패킷 포워딩설정을 먼저 해줘야 하지만, 우리는 이미 cloud-init에서 했기에 건너뛴다.

광고할 서브넷을 세팅해준다.

192.168.10.0/24 - Kubernetes Nodes
172.20.0.0/24 - LoadBalancer VIPs

1

sudo tailscale set --advertise-routes="192.168.10.0/24,172.20.0.0/24"

이후, Admin Console에서 승인해준다.

확인

이제, 우리는 내부 네트워크 노드에 모두 접근 가능하다!
Ping을 해봐도 된다.

SSH를 이용한 접속

아래와 같은 ssh config를 작성해두면 편하다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


Host bastion
 User ubuntu
 Hostname 192.168.0.8
 IdentityFile ~/.ssh/id_rsa

Host cp-1
 User ubuntu
 Hostname 192.168.10.10
 IdentityFile ~/.ssh/id_rsa

Host worker-1
 User ubuntu
 Hostname 192.168.10.100
 IdentityFile ~/.ssh/id_rsa

Host worker-2
 User ubuntu
 Hostname 192.168.10.101
 IdentityFile ~/.ssh/id_rsa

이후, 각각 SSH로 접속해보자.

1
2
3
4
5
6
7


ssh bastion
# Ctrl + D 또는 exit으로 나온 뒤
ssh cp-1
# Ctrl + D 또는 exit으로 나온 뒤
ssh worker-1
# Ctrl + D 또는 exit으로 나온 뒤
ssh worker-2

만약, 이전에 같은 호스트 및 정보로 vm을 사용하다가 삭제 후 재생성 등으로 인해서, ~/.ssh/known_hosts의 정보가 충돌하는 경우가 있는데, 이 경우 ~/.ssh/known_hosts의 해당 호스트 정보를 제거하고 다시 접속을 시도해보면 된다.

☸️ 쿠버네티스 설치

이전에 만들어준 Ansible을 활용한 Kubernetes의 요소들을 설치하는 플레이북이 있다. 이를 이용하자. 아래 링크에서 설치에 대해 도움받을 수 있을 것이다.

자세한 내용은 이 게시글에서 확인가능하다.

ansible.cfg와 inventory.ini는 아래를 참고하는 것이 편하다.

ansible.cfg 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[defaults]
inventory = ./inventory.ini
remote_user = ubuntu
ask_pass = false

[privilege_escalation]
become = true
become_method = sudo
become_user = root
become_ask_pass = false

inventory.ini 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[masters]
cp-1 ansible_host=cp-1 ansible_port=22

[workers]
worker-1 ansible_host=worker-1 ansible_port=22
worker-2 ansible_host=worker-2 ansible_port=22

[k8s_nodes:children]
masters
workers

설치 확인

설치 이후, 노드들이 모두 READY인지 확인해보자.

1
2
3
4
5


root@cp-1:~# kubectl get no
NAME STATUS ROLES AGE VERSION
cp-1 Ready control-plane 16m v1.35.0
worker-1 Ready <none> 11m v1.35.0
worker-2 Ready <none> 10m v1.35.0

🪪 자격 증명 가져오기

우선, Control Plane에서 ubuntu유저의 것으로 가져오자.

1
2
3
4


# cp-1에서
mkdir -p ~/.kube
sudo cp /etc/kubernetes/admin.conf ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config

이후, 작업할 컴퓨터에서 scp로 가져온 뒤, 기존의 kubeconfig와 병합한다.

1
2
3
4
5
6
7


# 내 컴퓨터에서
scp ubuntu@cp-1:~/.kube/config ~/.kube/config.homelab

# 클러스터명, 계정명, 컨텍스트명을 수정. 기존것들과 다르게 unique해야 함
vim ~/.kube/config.homelab

KUBECONFIG=~/.kube/config:~/.kube/config.homelab kubectl config view --merge --flatten > ~/.kube/config

이제, 마음껏 kubectl을 써주면 된다!
다음은 Cilium BGP Peering을 위한 FRR 셋업과 Ceph스토리지 생성 등을 알아볼 것이다.

Proxmox Homelab 구성 - 1. Proxmox 초기 세팅

Sun, 11 Jan 2026 14:10:58 +0900

처음 Proxmox를 쓰기에 앞서, 기본적인 세팅 과정을 밟는다.
유료 라이선스 구독이 없기에, 별도의 레포지토리로 갈아탄다.
홈랩에서 간단한 사용이기에, 스토리지도 단순화시킬 것이다.

⬇️ Repository 제거

우선, 유료 라이선스가 없기에, 구독이 없는 상태에서 쓰는 레포지토리를 이용해야 한다.
Node -> Updates -> Repositories에서 proxmox 레포지토리를 제거한다.

그리고, No Subscription 레포지토리와 Ceph Squid No-Subscription을 추가해준다.

이후, Updates에서 Refresh하고 Upgrade해준다.
또는 쉘에서 apt update && apt upgrade해주면 된다.

이후, 재부팅 해준다.

💾 (Optional) lvm스토리지 제거

처음에 local과 local-lvm스토리지가 생기는데, 둘은 역할이 분리되어 있다:

local:
- 파일 기반 스토리지
- ISO / 백업 / 템플릿, qcow2이미지
local-lvm:
- 블록 기반 스토리지
- VM disk(raw 이미지), LXC rootfs 저장

단순함을 위해, local-lvm을 없애고, local만 사용하도록 할 것이다.

Datacenter -> Storage로 이동한다.
local에 모든 content타입들을 추가해준다.

그 뒤, local-lvm을 remove한다.

이제, Node 쉘에서 아래 명령어를 실행하여 실제 local-lvm의 LV를 제거한다.

1

lvremove /dev/pve/data

이후, root에 나머지 공간을 할당한다.

1

lvresize -l +100%FREE /dev/pve/root

이제, 파일시스템도 확장해준다.

1

resize2fs /dev/mapper/pve-root

Triton Inference Server: Optimization

Sat, 10 Jan 2026 22:48:09 +0900

Triton Inference Server에서는 지연시간을 줄이고, 처리량을 늘리는 여러 기능이 있다.
우선은, 단일 모델에서의 지연과 처리량 트레이드오프를 이해하는데 집중한다.

Model Analyzer는 단일 GPU에서 여러 모델들을 최적으로 올릴지에 대한 고민으로 GPU 메모리 사용량의 이해를 돕는다.

이미 클라이언트 애플리케이션이 있다고 해도, Performance Analyzer에 익숙해질 필요가 있다.
Performance Analyzer는 모델의 성능을 최적화하는데 기본적인 도구이다.
예시에서는 QuickStart를 따라해서도 쉽게 시작할 수 있는 ONNX Inception 모델을 쓴다.

🎠 기본적인 실행 해보기

perf-analyzer를 실행해본다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 모델: inception_onnx
# url: 클러스터 내 tritonserver svc(현재 replica 1개임)
# percentile: 95(95%의 요청이 최소 몇 초 내로 끝나는지)
# in-flight동시요청: 1~4개까지 늘려보기
root@perf-analyzer-6bdc45d864-w4ttw:/workspace# perf_analyzer \
 -m inception_onnx \
 -u <triton_server_ip>:8000 \
 --percentile=95 \
 --concurrency-range=1:4
Inferences/Second vs. Client p95 Batch Latency
Concurrency: 1, throughput: 205.285 infer/sec, latency 4910 usec
Concurrency: 2, throughput: 229.494 infer/sec, latency 8644 usec
Concurrency: 3, throughput: 229.91 infer/sec, latency 12978 usec
Concurrency: 4, throughput: 229.833 infer/sec, latency 17323 usec

참고로, 공식 문서에서의 예시는 아래와 같은 수치가 나온다:

1
2
3
4
5
6
7


$ perf_analyzer -m inception_graphdef --percentile=95 --concurrency-range 1:4
...
Inferences/Second vs. Client p95 Batch Latency
Concurrency: 1, throughput: 62.6 infer/sec, latency 21371 usec
Concurrency: 2, throughput: 73.2 infer/sec, latency 34381 usec
Concurrency: 3, throughput: 73.2 infer/sec, latency 50298 usec
Concurrency: 4, throughput: 73.4 infer/sec, latency 65569 usec

현재 초당 230개정도의 추론을 처리한다.
1개의 동시요청에서는 처리량이 약간 적은데, 다음 요청을 받기까지의 유휴가 생기기 때문이다.
2개의 동시요청부터는 처리량이 오르는데, 다른 통신동안 작업이 겹치기 때문이다.

🚀 최적화 세팅

대부분의 모델에서 Triton 성능 개선에 큰 도움을 주는 기능은 동적 배칭이다.
그러나, 모델이 지원하지 못할 수도 있다.

Dynamic Batcher

Dynamic Batcher는 단일의 추론 요청들을 큰 배치로 묶어서 효율적으로 추론한다. 동적 배치를 추가해주면 된다.

1

dynamic_batching { }

dynamic batcher는 많은 양의 동시 요청을 견디도록 해준다

1
2
3
4


dynamic_batching {
 perferred_batch_size: [4, 8, 16]
 max_queue_delay_microseconds: 100 # 100ms
}

성공적으로 batching이 된다면, latency가 늘어나지 않으면서도 처리량이 늘어나는것을 볼 수 있다.
아래는 공식문서에서의 예제이다. 공식문서에서는 quickstart 모델들로 할 수 있다고 하는데, 정작 inception_graphdef는 not found여서 따라할 수는 없었다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


$ perf_analyzer -m inception_graphdef --percentile=95 --concurrency-range 1:8
...
Inferences/Second vs. Client p95 Batch Latency
Concurrency: 1, throughput: 66.8 infer/sec, latency 19785 usec
Concurrency: 2, throughput: 80.8 infer/sec, latency 30732 usec
Concurrency: 3, throughput: 118 infer/sec, latency 32968 usec
Concurrency: 4, throughput: 165.2 infer/sec, latency 32974 usec
Concurrency: 5, throughput: 194.4 infer/sec, latency 33035 usec
Concurrency: 6, throughput: 217.6 infer/sec, latency 34258 usec
Concurrency: 7, throughput: 249.8 infer/sec, latency 34522 usec
Concurrency: 8, throughput: 272 infer/sec, latency 35988 usec

perf_analyzer와 서버를 같은 시스템에서 띄울 때, 다음의 휴리스틱 기반의 간단한 룰을 이용하면, 쉽게 목표값을 구할 수 있다고 한다.

최소 지연을 구하려면, concurrency=1, dynamic batching 비활성화, 모델 instance 1개로만 세팅해서 보기
최대 처리량을 보려면, dynamic batching을 가능하다면 활성화하고, instance_count를 정한 뒤, concurrency = 2 * max_batch_size * instance_count

1
2
3
4


$ perf_analyzer -m inception_graphdef --percentile=95 --concurrency-range 8
...
Inferences/Second vs. Client p95 Batch Latency
Concurrency: 8, throughput: 267.8 infer/sec, latency 35590 usec

Model Instances

Triton은 각 모델이 추론 인스턴스를 몇 개를 띄울지를 정하게 할 수 있다.
기본적으로는 1개를 가짖지만, instance group을 이용해서 여러 개의 인스턴스를 만들 수 있다.
일반적으로 두 개의 인스턴스를 쓸 때 처리량이 늘어날 수 있다.
CPU 와 GPU의 전환작업 및 겹치는 연산, 또는 작은 모델이 GPU 자원을 전부 쓰지 못하는 경우에 효과적이다.

아래의 규칙을 config.pbtxt에 넣고 서버를 재시동한다.

1

instance group [ { count: 2 } ]

다시 perf_analyzer를 돌렸더니, 아래와 같다고 한다.(이번에도 File Not Found로 직접 따라할 순 없었다)

1
2
3
4
5
6
7


$ perf_analyzer -m inception_graphdef --percentile=95 --concurrency-range 1:4
...
Inferences/Second vs. Client p95 Batch Latency
Concurrency: 1, throughput: 70.6 infer/sec, latency 19547 usec
Concurrency: 2, throughput: 106.6 infer/sec, latency 23532 usec
Concurrency: 3, throughput: 110.2 infer/sec, latency 36649 usec
Concurrency: 4, throughput: 108.6 infer/sec, latency 43588 usec

1개의 인스턴스일때 대비 처리량이 늘어난 것을 볼 수 있다.

Dynamic Batching과 instance group 복제를 둘 다 적용시킬 수도 있다.

1
2


dynamic_batching { }
instance_group [ { count: 2 }]

아래 수치도 공식 문서에서의 예제이다.

1
2
3
4


$ perf_analyzer -m inception_graphdef --percentile=95 --concurrency-range 16
...
Inferences/Second vs. Client p95 Batch Latency
Concurrency: 16, throughput: 289.6 infer/sec, latency 59817 usec

dynamic batcher + 1개 인스턴스의 경우보다 더 별로인 것으로 보인다.
왜냐하면 이 모델이 dynamic batcher를 쓰는 것만으로 자원을 충분히 많이 쓰는 탓에 성능적인 이점을 보지 못하는 것이다.
인스턴스를 늘려서 더 얻는 것은 없고, 오히려 스케줄링 및 경합으로 더 느려질 수도 있다.

성능 개선으로 dynamic batcher이냐 model instance 복제이냐는 모델에 따라 다르다.
sweet-spot을 찾는 것은 많은 경험 및 실험이 필요하다.

🎢 추가 최적화

NUMA노드, ONNX with TensorRT, ONNX with OpenVIVO에서의 최적화 기법들이 있다고 하는데, 이는 당장 지금 보진 않았다.
보고싶다면 여기에서 참조..

💨 Hands-on

간단하지만 좀 무거운 선형회귀 모델을 만들어줄 것이다.
아래의 구조를 만들어주자.

1
2
3
4
5


model_repository
└── linear_model
 ├── 1
 │ └── model.pt
 └── config.pbtxt

모델 레포지토리 셋업

이 코드를 실행했을때의 model.pt를 레포지토리에 넣는다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


import torch
import torch.nn as nn

class LinearModel(torch.nn.Module):
 def __init__(self):
 super().__init__()
 self.layers = torch.nn.Sequential(
 *[torch.nn.Linear(1, 1) for _ in range(1000)]
 )

 def forward(self, x):
 for layer in self.layers:
 x = layer(x)
 return x


model = LinearModel()
model.eval()

example_input = torch.randn(1, 1)
scripted_model = torch.jit.trace(model, example_input)

scripted_model.save("model.pt")

config.pbtxt를 다음과 같이 저장한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


name: "linear_model"
platform: "pytorch_libtorch"

input [
 {
 name: "INPUT"
 data_type: TYPE_FP32
 dims: [1]
 }
]

output [
 {
 name: "OUTPUT"
 data_type: TYPE_FP32
 dims: [1]
 }
]

`docker-compose.yaml`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


services:
 triton:
 container_name: triton
 image: nvcr.io/nvidia/tritonserver:25.09-py3
 volumes:
 - ./model_repository:/models
 command:
 - tritonserver
 - --model-repository=/models
 ports:
 - 8000:8000
 - 8001:8001
 - 8002:8002
 perf_analyzer:
 container_name: perf_analyzer
 image: nvcr.io/nvidia/tritonserver:25.09-py3-sdk
 command:
 - sleep
 - infinity

이후, 컨테이너들을 실행한다.

1

docker compose up -d

동적 배치 없이 테스트

perf_analyzer를 실행한다.

1

docker exec -it perf_analyzer /bin/bash

1~4로 concurrency를 올려보아도, 처리량이 늘어나는 데에는 한계가 있다.
오히려 latency만 선형적으로 늘어나고 있다.

1
2
3
4
5
6
7


perf_analyzer -m linear_model -u triton:8000 --percentile=95 --concurrency-range=1:4 --measurement-interval 15000
(...)
Inferences/Second vs. Client p95 Batch Latency
Concurrency: 1, throughput: 465.277 infer/sec, latency 2548 usec
Concurrency: 2, throughput: 541.307 infer/sec, latency 4175 usec
Concurrency: 3, throughput: 535.462 infer/sec, latency 6284 usec
Concurrency: 4, throughput: 519.308 infer/sec, latency 8732 usec

concurrency를 16까지 올려보자.

1
2
3
4


perf_analyzer -m linear_model -u triton:8000 --percentile=95 --concurrency-range=16 --measurement-interval 15000
(...)
Inferences/Second vs. Client p95 Batch Latency
Concurrency: 16, throughput: 506.553 infer/sec, latency 35164 usec

동적 배치를 포함한 테스트

이제, 동적 배치를 추가해보자. 기존 컨테이너들을 내린다.

1

docker compose down

config.pbtxt를 아래와 같이 바꾼다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


name: "linear_model"
platform: "pytorch_libtorch"

max_batch_size: 32 

input [
 {
 name: "INPUT"
 data_type: TYPE_FP32
 dims: [1]
 }
]

output [
 {
 name: "OUTPUT"
 data_type: TYPE_FP32
 dims: [1]
 }
]

dynamic_batching {
 preferred_batch_size: [4, 8, 16]
 max_queue_delay_microseconds: 100
}

다시 컨테이너들을 올려준다.

1

docker compose up -d

다시 perf_analyzer에 접속한다.

1

docker exec -it perf_analyzer /bin/bash

concurrency를 1~4까지 늘려보자.
latency가 크게 늘어나지 않으면서도 처리량이 늘어나는 것을 볼 수 있다.

1
2
3
4
5
6
7


perf_analyzer -m linear_model -u triton:8000 --percentile=95 --concurrency-range=1:4 --measurement-interval 15000
(...)
Inferences/Second vs. Client p95 Batch Latency
Concurrency: 1, throughput: 518.028 infer/sec, latency 2287 usec
Concurrency: 2, throughput: 655.595 infer/sec, latency 3397 usec
Concurrency: 3, throughput: 945.922 infer/sec, latency 3525 usec
Concurrency: 4, throughput: 1200.72 infer/sec, latency 3694 usec

concurrency를 16까지 올려보자.

1
2
3
4


perf_analyzer -m linear_model -u triton:8000 --percentile=95 --concurrency-range=16 --measurement-interval 15000
(...)
Inferences/Second vs. Client p95 Batch Latency
Concurrency: 16, throughput: 4141.76 infer/sec, latency 5251 usec

📚 References

Proxmox Homelab 구성 - 0. Proxmox 설치하기

Sat, 10 Jan 2026 14:51:41 +0900

홈랩 머신으로 미니PC를 구매했다.
기종은 UM870 Slim 32G Ram + 1TB SSD인데, 기존에 가지고 있던 하이닉스 Platinum P41 2TB로 교체시켰다.

Proxmox를 설치하여 미니PC 안에서 여러 가상 머신들 및 컨테이너들을 띄우고 실험하고, 쿠버네티스 공부 등에 활용할 것이다.
나중에는 서비스를 운영하거나, 내 개인 사용 서비스를 셀프호스팅 하는데 쓸 예정이다.
Openstack과 고민했지만, 일단 단일 노드이기도 하고, 너무 과한 것 같아서 당장은 Proxmox로 시작한다.

💉 Proxmox 설치 media 만들기

우선, Proxmox 홈페이지에서 Proxmox VE를 설치해준다.

Ventoy를 사용한다면, ventoy 파티션에 iso를 넣으면 된다.
Ventoy를 사용하지 않는다면, 아래 과정을 따른다:

여기서는 usb가 /dev/sda에 있다고 가정한다. 파티션 테이블을 새로 생성해준다.

1

sudo parted /dev/sda --script mklabel gpt

이후, dd를 이용해서 설치 미디어를 만들어준다.

1

sudo dd if=~/Downloads/proxmox-ve_*.iso of=/dev/sda bs=4M status=progress

🏗️ Proxmox 설치

우선, EULA에 동의해주자.

그 뒤, 설치할 디스크를 선택한다.

국가와 타임존, 키보드 레이아웃을 선택한다.

루트 패스워드를 입력한다.

네트워크 설정을 해준다. Proxmox 노드가 고정IP를 쓰도록 해주는 것이 좋다. Hostname은 임의로 지어줬다.

이후, 설치하면 된다.

🚪 접속

설치 미디어를 빼고 재부팅해보자.
설정해둔 비밀번호로 root에 로그인할 수 있다.
또한, ssh연결도 가능하다.

<노드 주소>:8006에 접속하면 대시보드를 볼 수 있다.

Triton Inference Server: Python Backend

Tue, 06 Jan 2026 13:15:02 +0900

Triton Inference Server에서 가장 단순한 방법인 Python Backend에 대해 알아볼 것이다.
성능은 Python의 GIL등에 의해 조금 떨어지며, C/C++, CUDA native한 Pytorch, Onnx등의 다른 Backend가 성능이 더 좋다.
대신, 간편하게 모델을 올릴 수 있다.

🐍 `model.py` 작성

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67


import triton_python_backend_utils as pb_utils

class TritonPythonModel:
 """
 Python 모델 `model.py`는 항상 TritonPythonModel클래스명을 가져야 한다.
 """

 @staticmethod
 def auto_complete_config(auto_complete_model_config):
 """
 만약, 직접 config.pbtxt를 작성할 예정이고, --disable-auto-complete-config 옵션을 항상 킬 예정이라면, 이 부분을 구현할 필요가 없다.
 """

 def initialize(self, args):
 """
 `initialize`는 모델이 로딩되었을 때, 단 한 번만 실행된다.
 이 모델의 관련된 상태를 불러오는 데 사용된다.
 이 부분도 optional하다.

 Parameters
 ----------
 args : dict
 key, value모두 string이다.
 * model_config: 모델 config를 담는 JSON문자열
 * model_instance_kind: 모델 인스턴스의 종류("cpu", "cuda" 등)
 * model_instance_device_id: 모델 인스턴스의 디바이스 id
 * model_repository: 모델 레포지토리 경로
 * model_version: 모델 버전
 * model_name: 모델 이름
 """
 print('Initialized...')

 def execute(self, requests):
 """
 `execute`는 반드시 구현되어야 하는 함수이다.
 argument로 pb_utils.InferenceRequest의 리스트를 받는다.
 이 함수는 추론 요청이 올 때 실행된다.

 Parameters
 ----------
 requests : list
 pb_utils.InferenceRequest의 리스트

 Returns
 -------
 list
 pb_utils.InferenceResponse 리스트.
 응답의 길이는 `requests`와 같아야 한다.
 """

 responses = []

 # 모든 Python Backend는 리스트의 아이템을 정확히 한 번 다뤄야한다.
 for request in requests:
 # 여기에서 각 요청에 대한 추론이 이뤄지도록 하고,
 # 각각의 응답을 순서 그대로 담도록 해야 한다.

 # pb_utils.InferenceRenponse의 리스트를 반환
 # len(pb_utils.InferenceResponse) == len(pb_utils.InferenceRequest)
 return responses

 def finalize(self):
 """
 `finalize`는 모델 언로드 시 반드시 한 번 실행된다.
 종료 이전 필요한 cleanup 작업들을 실행하면 된다.
 """
 print('Cleaning up...')

4 가지의 함수 구현을 할 수 있다:

`auto_complete_config`

서버가 --disable-auto-complete-config옵션 없이 실행할 때 실행된다.
이 메서드의 구현은 optional하다.

더 자세한 내용은 여기에서확인하면 된다.

`initialize`

initialize는 모델의 로딩 시에 정확히 한 번 실행된다.
구현은 optional하며, 여기에서 추론 이전의 중요한 작업들을 할 수 있다.
initialize함수에서, args라는 Python 딕셔너리를 입력받는다.
key와 value 모두 string이다.

key	description
`model_config`	모델 config를 담은 JSON 문자열
`model_instance_kind`	모델 인스턴스 종류를 담은 문자열
`model_instance_device_id`	모델 인스턴스 디바이스 ID를 담은 문자열
`model_repository`	모델 레포지토리 경로
`model_version`	모델 버전
`model_name`	모델 이름

`execute`

execute함수는 추론 요청이 오면 실행된다.
모든 Python Model은 execute 함수를 구현해야 한다.
요청으로는 InferenceRequest 리스트를 받는다.
두 가지 구현 방법이 있다.

모델로부터 디커플링된 응답을 받고 싶은지 아닌지에 따라 다르다.

Default Mode

한 요청에 한 응답을 받는, 일반적인 방법이다.
응답으로는 InferenceResponse 오브젝트의 리스트를 반환해야 한다.
requests의 길이와 같아야 한다.
워크플로우는 아래와 같다:

execute 함수가 N개의 pb_utils.InferenceRequest 배치를 받는다.
각각에 대응하는 pb_utils.InferenceResponse를 response배열에 append한다.
response배열을 응답한다
- 응답의 길이는 N이어야 한다
- 리스트의 각 요소는 각각의 request에 대응하는 배열이어야 한다

Error Handling

응답에 에러가 있다면, TritonError객체로 에러 메시지를 쓸 수 있다.
아래는 예시이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import triton_python_backend_utils as pb_utils

class TritonPythonModel:
 def execute(self, requests):
 responses = []
 for request in requests:
 if an_error_occured:
 responses.append(pb_utils.InferenceResponse(
 error = pb_utils.TritonError("An Error Occurred")))
 return responses

23.09버전부터는 pb_utils.TritonError는 에러 코드를 넣을 수 있게 되었다.
예를 들어, 아래와 같이 넣을 수 있다:

1

pb_utils.TritonError("The file is not found", pb_utils.TritonError.NOT_FOUND)

에러 코드가 없다면, pb_utils.TritonError.INTERNAL이 기본으로 쓰일 것이다.
지원되는 에러 코드는 다음과 같다:

pb_utils.TritonError.UNKNOWN
pb_utils.TritonError.INTERNAL
pb_utils.TritonError.NOT_FOUND
pb_utils.TritonError.INVALID_ARG
pb_utils.TritonError.UNAVAILABLE
pb_utils.TritonError.UNSUPPORTED
pb_utils.TritonError.ALREADY_EXISTS
pb_utils.TritonError.CANCELLED (23.10 부터)

Request Cancellation 핸들링

실행 중에 클라이언트로부터 취소를 받을 수 있다.
23.10부터는, request.is_cancelled()로 요청의 취소 여부를 알 수 있다.
예시는 다음과 같다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


import triton_python_backend_utils as pb_utils

class TritonPythonModel:
 ...
 def execute(self, requests):
 responses = []
 for request in requests:
 if request.is_cancelled():
 responses.append(pb_utils.InferenceResponse(
 error=pb.utils.TritonError("Message", pb_utils.TritonError.CANCELLED)))
 else:
 ...
 return responses

요청 취소 확인은 optional하지만, 요청이 더 이상 필요하지 않을 때, 일찍 종료할 수 있도록 전략을 취해주는 것이 좋다.

Decoupled Mode

이 모드는 요청에 대해 0개 또는 여러 개의 응답을 보낼 때 사용된다.
이 모드를 쓰려면, config의 model-transaction-policy가 decouped로 되어있어야 한다.

디커플모드에서, 모델은 반드시 요청마다 InferenceResponseSender 객체를 써야 한다.
워크플로우는 아래와 같다:

execute함수가 pb_utils.InferenceRequest배열을 받는다.
각 pb_utils.InferenceRequest를 순회하며 아래 동작을 수행한다
- InferenceRequest.get_response_sender()를 이용하여InferenceResponseSender객체를 얻는다.
- pb_utils.InferenceResponse를 만든다.
- InferenceResponseSender.send()를 이용하여 응답을 보낸다. 만약 마지막 요청의 것이였다면, InferenceResponseSender.sned()에 pb_utils.TRITONSERVER_RESPONSE_COMPLETE_FINAL플래그를 넘겨야 한다. 아니라면, 계속 반복을 하면된다
함수의 리턴값은 None이된다.

유즈 케이스는 다음과 같다:

모델이 아무 응답 데이터를 보내지 않을때
응답과 요청의 순서가 유지되지 않을때
모델의 다른 스레드로 넘겨질때. 즉, execute내부에서 새로운 스레드를 만들어서 넘기고, execute에서는 닫을 수 있도록.

24.04부터, async def execute(self, requests)가 decoupled python models에서 지원된다.
AsyncIO 이벤트 루프에서 코루틴으로 돌아간다.
현재 요청이 대기중이더라도 다음 모델 인스턴스의 실행이 이뤄질 수 있다.
주어진 요청들이 AsyncIO에 의해 동시 요청될 수 있다.
동시성의 이점을 얻기 위해서, 이벤트 루프에서 대기가 있으면 안된다.

`finalize`

Triton Server로부터 모델이 언로드될때의 마무리 클린업 작업을 할 수 있다.

❇️ 모델 config 파일

모든 Python Triton 모델은 config.pbtxt를 작성해야 한다.
backend필드에서는 python으로 써야 하고,
platform은 쓰면 안된다.

아래의 폴더 구조를 가진다:

1
2
3
4
5


models
└── add_sub(모델명)
 ├── 1
 │ └── model.py
 └── config.pbtxt

🐙 파라미터 확장

더 자세한 내용을 여길 참조

Inference Request 파라미터

Inference Request에서 inference_request.parameters()함수로 파라미터를 받을 수 있다.
이 함수는 JSON문자열을 반환하며, key는 파라미터 오브젝트들의 키, 값은 파라미터 필드의 값이다.
json.loads로 딕셔너리로 변환하여 쓸 수 있다.

23.11릴리즈부터는, 파라미터들은 생성 중에 제공될 수 있다.

1

request = pb_utils.InferenceRequest(parameters={"key": "value"}, ...)

키는 str, 값은 bool, int, str이어야 한다.

Inference Response 파라미터

Inference Response 파라미터는 Inference Response객체의 생성중 옵셔널하게 세팅될 수 있다.
파라미터는 키-값 쌍을 가지고, 역시 key는 str, 값은 bool, int, str이다.

1
2
3


response = pb_utils.InferenceResponse(
 output_tensors, parameters={"key": "value"}
)

🏦 Python 런타임과 라이브러리 관리

Python Backend는 현재의 Python환경에 있는 라이브러리를 쓸 수 있다.
virtualenv, conda environment, 또는 Python 전역 시스템으로 쓰일 수 있다.
이 라이브러리들은 Python 버전이 Python backend stub과 매칭되는 버전인 경우에만 쓰일 수 있다.

예를 들어, Python 3.9환경을 쓰려는데, Python backend stub이 3.12라면, 커스텀 Python 벡엔드 Stub을 만들어야 한다.
Stub은 C로 구현된 Triton Server가 Python 벡엔드를 libpython을 통해서 실행할 수 있도록 해주는 다리의 역할을 하는 프로그램이라고 보면 된다.

Custom Python Backend Stub 빌드하기

Note: Triton 컨테이너의 기본 버전인 Python 3.12와 다른 경우에만 하면 된다.
Python backend는 model.py에 연결하기 위해 Triton C++ Core에서 stub process를 쓴다.
이러한 stub 프로세스는 특정 libpython<X>.<Y>.so의 특정 버전과 동적 링크가 된다.

기본 버전과 다른 Python 버전을 쓴다면, 직접 Python Backend stub을 써야한다:

아래의 소프트웨어 패키지 설치:
- cmake
- rapidjson, libarchive
원하는 Python 버전이 당신의 환경에서 있어야 한다.
만약 conda를 쓴다면, 환경을 conda activate <env-name>으로 활성화해야 한다.
Python backend 레포지토리를 Clone하고, Python backend stub을 컴파일한다 <GIT_BRANCH_NAME>을 원하는 브랜치명으로 해야한다. r<xx.yy>가 릴리즈의 브랜치이다.

1
2
3
4
5
6


git clone https://github.com/triton-inference-server/python_backend -b
<GIT_BRANCH_NAME>
cd python_backend
mkdir build && cd build
cmake -DTRITON_ENABLE_GPU=ON -DTRITON_BACKEND_REPO_TAG=<GIT_BRANCH_NAME> -DTRITON_COMMON_REPO_TAG=<GIT_BRANCH_NAME> -DTRITON_CORE_REPO_TAG=<GIT_BRANCH_NAME> -DCMAKE_INSTALL_PREFIX:PATH=`pwd`/install ..
make triton-python-backend-stub

이제, Python backend stub을 파이썬 버전에 맞게 접근해야 한다.
ldd를 이용할 수 있다.

1
2
3
4


ldd triton_python_backend_stub
...
libpython3.6m.so.1.0 => /home/ubuntu/envs/miniconda3/envs/python-3-6/lib/libpython3.6m.so.1.0(0x00007fbb69cf3000)
...

libpython<major>.<minor>.so.1.0에서 <major>.<minor>가 원하는 Python 버전인지 확인하면 된다.
이후, triton_python_backend_stub을 커스텀 Python backend stub으로 하면 된다.
만약, model_a가 있다면, 폴더 구조를 아래와 같이 하면 된다:

1
2
3
4
5
6


models
|-- model_a
 |-- 1
 | |-- model.py
 |-- config.pbtxt
 `-- triton_python_backend_stub

Custom 실행 환경 만들기

만약 필요한 의존성을 담고 싶다면, 커스텀 실행 환경을 만들면 된다.
Python backend는 conda-pack을 지원한다.

1
2
3
4


conda-pack
Collecting packages...
Packing environment at '/home/iman/miniconda3/envs/python-3-6' to 'python-3-6.tar.gz'
[########################################] | 100% Completed | 4.5s

패키지를 받기전, PYTHONNOUSERSITE 환경변수를 True로 해준다.

1

export PYTHONNOUSERSITE=True

만약 이 변수가 없으면, conda 환경 밖에 설치되고, tar file에 격리된 환경에서 필요한 의존성이 다 담기지 못할 수 있다.

대신, Python backend는 unpacked된 실행환경도 지원한다.
conda create -p를 이용하여 활성화 스크립트를 제공할 수 있다.
스크립트는 $path_to_conda_pack/lib/python<your.python.version>/site-packages/conda_pack/scripts/posix/activate에 있다.
서버 로딩 시간을 줄일 수 있다.

별도의 conda환경을 만들고 나서는, Python backend에게 해당 환경을 쓰도록 해야한다.
config.pbtxt에서 아래의 내용을 추가해서 환경에 참조할 수 있다.

1
2
3
4
5
6
7


name: "model_a"
backend: "python"
...
parameters: {
 key: "EXECUTION_ENV_PATH",
 value: {string_value: "home/ubuntu/miniconda3/envs/python-3-6/python3.6.tar.gz"}
}

또한, 모델 레포지토리 내에서 상대 경로를 이용할 수도 있다:

1
2
3
4
5
6
7


name: "model_a"
backend: "python"
...
parameters: {
 key: "EXECUTION_ENV_PATH",
 value: {string_value: "$$TRITON_MODEL_DIRECTORY/python3.6.tar.gz"}
}

이 경우, python3.6.tar.gz는 모델 폴더의 아래와 같은 위치에 있어야 한다:

1
2
3
4
5
6
7


models
|-- model_a
| |-- 1
| | `-- model.py
| |-- config.pbtxt
| |-- python3.6.tar.gz
| `-- triton_python_backend_stub

모델 로딩시간을 줄이기 위해, 아래와 같이 unpack할 수 있다:

1
2


mkdir -p $pwd/models/model_a/python3.6
tar -xvf $pwd/models/model_a/python3.6.tar.gz -C $pwd/models/model_a/python3.6

그 뒤, EXECUTION_ENV_PATH는 unpack된 디렉토리로 하면 된다.

1
2
3
4


parameters: {
 key: "EXECUTION_ENV_PATH",
 value: {string_value: "$$TRITON_MODEL_DIRECTORY/python3.6"}
}

상대 경로를 이용한 방법은 클라우드 오브젝트 저장소에서도 유용하게 쓰인다.

Important Notes

Python 인터프리터의 버전은 triton_python_backend_stub과 일치해야 한다.
기본으로 충분하다면, 굳이 커스텀 Python Backend Stub을 쓸 이유가 없다. conda-pack으로 라이브러리만 불러와도 충분하다. 현재 stub의 기본 버전은 Python3.12이다.
하나의 실행 환경을 여러 모델에서 공유할 수 있다. config.pbtxt에서 같은 곳을 참조하면 된다.
만약 $$TRITON_MODEL_DIRECTORY가 EXECUTION_ENV_PATH에서 쓰인다면,EXECUTION_ENV_PATH의 최종적인 위치는 $$TRITON_MODEL_DIRECTORY를 떠나면 안된다.
$$TRITON_MODEL_DIRECTORY가 쓰이지 않았다면, 클라우드의 경로를 쓸 수 없다.
만약 Python backend stub을 직접 컴파일하길 원한다면, 공식 Triton NGC container에서 빌드하는것을 권장한다. 아니라면, 컴파일된 stub이 오류가 날 수 있다.
“GLIBCXX_3.4.30 not found"에러가 뜬다면, conda 버전을 업그레이드하고, conda install -c conda-forge libstdcxx-ng=12 -y로 libstdcxx-ng=12를 설치하는것을 추천한다. 비슷하게, “GLIBCXX_3.4.32 not found"라는 에러가 보인다면, conda install -c conda-forge libstdcxx-ng=13 -y를 실행하면 될 것이다.

⚽ Hands-On

Triton의 Python Backend로 모델을 서빙해보자.
이번 예시에서는 주어진 정수에 1을 더해주는 간단한 모델을 만들어줄 것이다.
Python 3.8환경에서 numpy를 포함시켜서 서빙시켜 볼 것이다.

폴더 구조를 아래와 같이 만들 것이다:

1
2
3
4
5
6
7


model_repository
└── add_one
 ├── 1
 │ └── model.py
 ├── config.pbtxt
 ├── add_one_env.tar.gz
 └── triton_python_backend_stub

개발 환경 세팅

Triton Python Backend는 vscode에서의 개발환경을 지원한다.
vscode에서 Dev Containers 확장을 설치한다.

프로젝트 루트에 .devcontainer라는 디렉토리를 생성하고, 아래의 두 파일을 만든다:

devcontainer/devcontainer.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


{
 "name": "Python Backend",

 "build": {
 "dockerfile": "Dockerfile"
 },
 "customizations": {
 "vscode": {
 "extensions": [
 "ms-python.vscode-pylance",
 "ms-python.python",
 "ms-vscode.cpptools-extension-pack",
 "ms-vscode.cmake-tools",
 "github.vscode-pull-request-github"
 ]
 }
 },
 "postCreateCommand": "sudo chown -R triton-server:triton-server ~/.cache",

 // "--gpus=all"은 nvidia gpu가 없으면 제거
 "runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined", "--gpus=all", "--shm-size=2g", "--ulimit", "stack=67108864" ],
 "mounts": [
 "source=${localEnv:HOME}/.ssh,target=/home/triton-server/.ssh,type=bind,consistency=cached",
 "source=${localEnv:HOME}/.cache/huggingface,target=/home/triton-server/.cache/huggingface,type=bind,consistency=cached"
 ],
 "remoteUser": "triton-server"
}

.devcontainer/Dockerfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48


# Copyright 2024, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
# * Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions and the following disclaimer in the
# documentation and/or other materials provided with the distribution.
# * Neither the name of NVIDIA CORPORATION nor the names of its
# contributors may be used to endorse or promote products derived
# from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
# OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

FROM nvcr.io/nvidia/tritonserver:25.09-py3 # 원하는 버전에 맞추기

ARG USERNAME=triton-server

RUN apt-get update \
 && apt-get install -y sudo

RUN pip3 install transformers torch

# Create the user
RUN apt-get update \
 && apt-get install -y sudo \
 && echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME \
 && chmod 0440 /etc/sudoers.d/$USERNAME

RUN pip3 install pre-commit ipdb

RUN mkhomedir_helper triton-server

RUN apt-get install -y cmake rapidjson-dev

USER ${USERNAME}

이후, 명령 팔레트에서 Dev Containers: Reopen in Container를 실행한다.

이제, DevContainer에서 작업할 수 있다.
그러나, LSP에서 Python backend utils를 인식하지는 못하는 듯하다.

나중에 DevContainer에서 빠져나올때는 명령 팔레트에서 Reopen하되, Container말고 기존의 로컬 옵션을 이용한다.

Python 3.8 custom stub 만들기

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


# 컨테이너 안에서 
# 패키지 업데이트
apt update && apt install -y rapidjson-dev libarchive-dev

# Miniconda 설치
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
sudo bash Miniconda3-latest-Linux-x86_64.sh -b -p /opt/miniconda
export PATH="/opt/miniconda/bin:$PATH"

# TOS 승인
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r

# conda 환경 초기화
conda init
source ~/.bashrc

# conda 환경 생성
conda create -n py38 python=3.8 -y
conda activate py38
pip install cmake==3.31.10

# Triton Python Backend 레포지토리 클론 및 빌드 작업 경로로 디렉토리 이동
git clone https://github.com/triton-inference-server/python_backend -b r25.09 # 자신에게 맞는 버전의 브랜치를 쓸 것.
cd python_backend
mkdir build && cd build

# 빌드
# GPU를 쓰지 않는다면, `-DTRITON_ENABLE_GPU=OFF`로 할 것.
# 여기서도 Triton 버전을 알맞게 표시할 것
cmake -DTRITON_ENABLE_GPU=ON \
 -DTRITON_BACKEND_REPO_TAG=r25.09 \
 -DTRITON_COMMON_REPO_TAG=r25.09 \
 -DTRITON_CORE_REPO_TAG=r25.09 \
 -DCMAKE_INSTALL_PREFIX:PATH=$(pwd)/install ..

make triton-python-backend-stub

# libpython3.8.so.1.0을 링크하는지 확인
ldd triton_python_backend_stub | grep python

# 빌드된 아티팩트 이동
cp triton_python_backend_stub /workspaces/triton-devcontainer/model_repository/add_one/triton_python_backend_stub

ldd로 링크를 확인하면, 아래와 같다:

`conda pack`으로 필요한 의존성 패킹하기

1
2
3
4
5
6


export PYTHONNOUSERSITE=True

pip install numpy
pip install conda-pack

conda pack -n py38 -o add_one_env.tar.gz

주의: conda pack과 custom stub

custom stub을 빌드하고 나서, 이후에 빌드한 컨테이너를 빠져나온 뒤에는 lld에서 libpython 링크가 not found로 보인다.
그래서 빌드를 잘못한 것은 아닌가 걱정할 수 있다.
그러나, conda pack을 압축풀어서 안을 확인해보면, libpython이 있다.
공식적으로 적혀있는 것을 찾지는 못했지만, 모델을 로딩하면서, conda pack안에있는 libpython에 링크하여 동작하는 듯 하다.
즉, 다른 파이썬 버전에서는 custom stub + conda pack이 필수적이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


~/triton-devcontainer on ☁️ (ap-northeast-2)
# ldd에서 not found로 보임
20:55:46 ❯ ldd model_repository/add_one/triton_python_backend_stub | grep python
 libpython3.8.so.1.0 => not found

# conda pack 압축해제
~/triton-devcontainer on ☁️ (ap-northeast-2)
20:55:51 ❯ tar -xvf model_repository/add_one/add_one_env.tar.gz -C add_one_env

(...)

# libpython이 conda pack안에 있다
~/triton-devcontainer on ☁️ (ap-northeast-2)
21:02:17 ❯ ls add_one_env/lib | grep python
libpython3.8.so -> libpython3.8.so.1.0
libpython3.8.so.1.0
libpython3.so
python3.8

간단한 `model.py`

model_repository/add_one/1/model.py에 아래와 같이 작성한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


import triton_python_backend_utils as pb_utils
import numpy as np
import sys

class TritonPythonModel:
 """
 Triton Python Model
 """

 def initialize(self, args):
 pb_utils.Logger.log_info("Model Initializing...")
 pb_utils.Logger.log_info(sys.version) # 모델 로딩시의 버전을 확인해봅시다

 def execute(self, requests):
 responses = []
 for request in requests:
 input_tensor = pb_utils.get_input_tensor_by_name(request, "INPUT")
 input_array = input_tensor.as_numpy()

 output_array = input_array + 1

 output_tensor = pb_utils.Tensor(
 "OUTPUT",
 output_array.astype(np.int32)
 )

 response = pb_utils.InferenceResponse(
 output_tensors=[output_tensor]
 )

 responses.append(response)

 return responses

 def finalize(self):
 """finalizer"""
 pb_utils.Logger.log_info("Model cleanup...")

`config.pbtxt` 작성

model_repository/add_one/config.pbtxt에는 아래와 같이 작성한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


name: "add_one"
backend: "python"

input [
 {
 name: "INPUT"
 data_type: TYPE_INT32
 dims: [ -1 ]
 }
]

output [
 {
 name: "OUTPUT"
 data_type: TYPE_INT32
 dims: [ -1 ]
 }
]

instance_group [
 {
 kind: KIND_CPU
 }
]

parameters: {
 key: "EXECUTION_ENV_PATH",
 value: {
 string_value: "$$TRITON_MODEL_DIRECTORY/add_one_env.tar.gz"
 }
}

테스트 및 요청 날려보기

model_repository를 볼륨으로 마운트해서, 서버를 띄워보자.

1

docker run --rm -p 8000:8000 -p 8001:8001 -p 8002:8002 -v ./model_repository:/models nvcr.io/nvidia/tritonserver:25.09-py3 tritonserver --model-repository=/models # 태그 알맞게 작성!

로그를 확인해보자. Python 3.8버전을 쓰고있다!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


=============================
== Triton Inference Server ==
=============================

...

I0120 10:28:48.767944 1 model_lifecycle.cc:473] "loading: add_one:1"
I0120 10:28:48.772835 1 python_be.cc:1851] "Using Python execution env /models/add_one/add_one_env.tar.gz"
I0120 10:28:51.613833 1 python_be.cc:2289] "TRITONBACKEND_ModelInstanceInitialize: add_one_0_0 (CPU device 0)"
I0120 10:28:51.732199 1 model.py:11] "Model Initializing..."
I0120 10:28:51.732443 1 model.py:12] "3.8.20 (default, Oct  3 2024, 15:32:15) \n[GCC 11.2.0]" # << 여기!!
I0120 10:28:51.737114 1 model_lifecycle.cc:849] "successfully loaded 'add_one'"

...

I0120 10:28:51.737425 1 server.cc:638] 
+---------+-------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Backend | Path                                                  | Config                                                                                                                                                        |
+---------+-------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+
| python  | /opt/tritonserver/backends/python/libtriton_python.so | {"cmdline":{"auto-complete-config":"true","backend-directory":"/opt/tritonserver/backends","min-compute-capability":"6.000000","default-max-batch-size":"4"}} |
+---------+-------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+

I0120 10:28:51.737493 1 server.cc:681] 
+---------+---------+--------+
| Model   | Version | Status |
+---------+---------+--------+
| add_one | 1       | READY  |
+---------+---------+--------+

...

I0120 10:28:51.743777 1 grpc_server.cc:2562] "Started GRPCInferenceService at 0.0.0.0:8001"
I0120 10:28:51.744013 1 http_server.cc:4789] "Started HTTPService at 0.0.0.0:8000"
I0120 10:28:51.786121 1 http_server.cc:358] "Started Metrics Service at 0.0.0.0:8002"

Curl을 이용해서 간단히 요청을 날려보자.
성공적으로 응답받는 것을 볼 수 있다!

📚 References

Triton Inference Server: Model Repository

Sun, 04 Jan 2026 15:04:40 +0900

🍰 Repository Layout

레포지토리 경로는 서버 시작 시, --model-repository를 통해서 정해진다. 이 옵션은 여러 번 사용되어 여러 모델 레포지토리에 연결되도록 할 수 있다.

모델 레포지토리는 다음과 같은 형식이어야 한다:

1

tritonserver --model-repositry=<model-repository-path>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


 <model-repository-path>/
 <model-name>/
 [config.pbtxt]
 [<output-labels-file> ...]
 [configs]/
 [<custom-config-file> ...]
 <version>/
 <model-definition-file>
 <version>/
 <model-definition-file>
 ...
 <model-name>/
 [config.pbtxt]
 [<output-labels-file> ...]
 [configs]/
 [<custom-config-file> ...]
 <version>/
 <model-definition-file>
 <version>/
 <model-definition-file>
 ...
 ...

모델 레포지토리 디렉토리에는 0개 이상의 서브디렉토리를 가진다.
서브디렉토리는 상응하는 모델에 대한 레포지토리 정보를 담는다.
config.pbtxt 파일은 모델의 configuration정보를 담는다.
일부 모델에서는 필수적으로 작성해야하지만, 자동 생성이 지원되는 경우도 있다.

각 디렉토리는 적어도 1개 이상의 모델 버전을 표현하는 서브디렉토리를 가져야 한다.
각 모델은 특정 벡엔드에서 실행된다.
각 서브디렉토리 버전 안에는 벡엔드에 따른 요구되는 파일들이 있다.
예를 들면, PyTorch Backend를 쓰는 경우, model.pt가 요구된다.

🗺️ Model Repository의 위치

로컬 경로, 또는 클라우드 스토리지에 접근할 수 있다.

Local Filesystem

모델 경로는 절대경로로 주어져야 한다.

1

tritonserver --model-repository=/path/to/model/repository

Cloud Storage

Google Cloud

Google Cloud Stroage에 있는 모델 레포지토리에 접근하기 위해서, gs:// prefix로 시작하는 경로를 이용한다.

1

tritonserver --model-repository=gs://bucket/path/to/model/repository ...

자격 증명은 다음의 순서로 적용된다:

GOOGLE_APPLICATION_CREDENTIALS 환경변수
- 환경 변수가 credential JSON 파일을 포함한 장소를 가져야 한다.
- Authorized user credential먼저 시도되고, 그 이후 service account credential을 이용한다.
Attach된 service account
Anonymous Credential(public bucket)
- 이 경우, 버킷과 그 안의 객체들은 모든 사용자들에게 get과 list권한이 주어져야 한다.

기본적으로, Triton은 원격 모델 레포지토리로부터 모델을 받아서 로컬의 임시 저장소에 저장한다.
서버가 종료되면, 지워진다.
리모트 모델 레포지토리가 로컬에 저장되어있게 하도록 하고 싶으면, TRITON_GCS_MOUNT_DIRECTORY 환경변수를 지정해주면 된다.

1

export TRITON_GCS_MOUNT_DIRECTORY=/path/to/your/directorty

로컬 머신에서 존재하는 경로이며, 비어있도록 보장해줘야 한다.

S3

(Cloudflare R2, MinIO도 S3 API를 이용하면 된다)
s3:// prefix를 이용하면 S3 API를 이용한다.

1

tritonserver --model-repository=s3://bucket/payh/to/model/repository ...

로컬이나 프라이빗 인스턴스인 경우(MinIO, Ceph등), host와 port를 따라적으면 된다.

1

tritonserver --model-repository=s3://http://host:port/bucket/path/to/model/repository...

기본적으로, Triton은 HTTP를 이용한다.
S3가 HTTPS를 지원하고, HTTPS를 이용하게 하고 싶으면, https://로 주면 된다.

1

tritonserver --model-repository=s3://https://host:port/bucket/path/to/model/repository...

S3를 사용할때, credential과 기본 리전은 aws config 또는 환경변수를 통해 받는다.
환경변수가 더 높은 우선순위를 가진다.

AWS에서 모델 레포지토리가 카피되길 원한다면, TRITON_AWS_MOUNT_DIRECTORY환경변수에 설정해주면 된다.
이것도 역시 디렉토리가 존재하고 비어있도록 해주자.

1

export TRITON_AWS_MOUNT_DIRECTORY=/path/to/your/local/directory

Azure Storage

Azure에서는, as:// prefix를 쓰면 된다.

1

tritonserver --model-repository=as://account_name/container_name/path/to/model/repository ...

Azure Storage를 쓸때에는, AZURE_STORAGE_ACCOUNT와 AZURE_STORAGE_KEY 환경변수를 써서 접근할 수 있도록 해야한다.

Azure Storage에서 모델 레포지토리가 카피되길 원한다면, TRITON_AZURE_MOUNT_DIRECTORY환경변수에 설정해주면 된다.
이것도 역시 디렉토리가 존재하고 비어있도록 해주자.

1

export TRITON_AZURE_MOUNT_DIRECTORY=/path/to/your/local/directory

`cloud_credential.json`

Triton에서 단일 파일에 자격증명을 저장하려면, TRITON_CLOUD_CREDENTIAL_PATH환경변수값으로 경로를 넣어주면 된다.

1

export TRITON_CLOUD_CREDENTIAL_PATH="cloud_credential.json"

아래와 같은 형식을 가진다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


{
 "gs": {
 "": "PATH_TO_GOOGLE_APPLICATION_CREDENTIALS",
 "gs://gcs-bucket-002": "PATH_TO_GOOGLE_APPLICATION_CREDENTIALS_2"
 },
 "s3": {
 "": {
 "secret_key": "AWS_SECRET_ACCESS_KEY",
 "key_id": "AWS_ACCESS_KEY_ID",
 "region": "AWS_DEFAULT_REGION",
 "session_token": "",
 "profile": ""
 },
 "s3://s3-bucket-002": {
 "secret_key": "AWS_SECRET_ACCESS_KEY_2",
 "key_id": "AWS_ACCESS_KEY_ID_2",
 "region": "AWS_DEFAULT_REGION_2",
 "session_token": "AWS_SESSION_TOKEN_2",
 "profile": "AWS_PROFILE_2"
 }
 },
 "as": {
 "": {
 "account_str": "AZURE_STORAGE_ACCOUNT",
 "account_key": "AZURE_STORAGE_KEY"
 },
 "as://Account-002/Container": {
 "account_str": "",
 "account_key": ""
 }
 }
}

가장 긴 prefix 매칭이 되는대로 자격 증명을 사용한다. 위의 예시에서는, gs://gcs-bucket-002/model_repositry인경우는 “gs://gcs-bucket-002"에, 나머지는 ““에 있는 자격증명을 이용할것이다.
TRITON_CLOUD_CREDENTIAL_PATH환경변수가 셋되어있지 않다면, 기존 방법으로 자격증명을 이용할것이다.

클라우드 스토리지 캐싱

현재 파일 캐싱을 진행하지는 않지만, 프록시를 주입하여 repository agent API를 통해 구현될 수 있다.
로컬디렉토리 먼저 체크하고, 클라우드 스토리지로부터 불러오는 전략을 사용할 수 있다.

🏴󠁩󠁤󠁳󠁬󠁿 모델 버전

각 모델은 하나 이상의 버전을 가져야 한다.
숫자로 명명되어야 하며, 0으로 시작하거나 숫자가 아닌 서브디렉토리는 무시된다.

📁 모델 파일

각 backend별로 요구사항이 다르다.

📚 References

https://docs.nvidia.com/deeplearning/triton-inference-server/user-guide/docs/user_guide/model_repository.html

Triton Inference Server Configuration

Fri, 02 Jan 2026 23:08:29 +0900

Model Repository의 각 모델은 환경 설정이 필요하다.
config.pbtxt로 작성하는데, Modelconfig Protobuf를 의미한다.

⚙️ 최소한의 Model Configuration

모델에서 platform 과 backend(같이 쓰일수도 있고, 따로 쓰일수도 있다), 최대 배치사이즈, input, output은 반드시 작성되어야 한다.

아래는 두 개의 입력값 input0과 input1을 받아 output0을 출력하는 모델이다.
차원은 모두 16엔트리의 float32로 된 텐서이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


platform: "tensorrt_plan"
max_batch_size: 8

input [
 {
 name: "input0"
 data_type: TYPE_FP32
 dims: [16]
 },
 {
 name: "input1"
 data_type: TYPE_FP32
 dims: [16]
 }
]
output [
 {
 name: "output0"
 data_type: TYPE_FP32
 dims: [16]
 }
]

🫆 Name, Platform, Backend

Model configuration name은 옵셔널하다.
명시적으로 모델 이름을 적을 수 있으나, 반드시 폴더의 모델명과 같아야 한다.
생략가능하다.

Platform 및 Backend는 각각의 Backend의 구성마다 다르게 적어야 한다.
예를 들어, Python backend의 경우, 반드시 backend: "python"으로 적어야 한다.

📐 Model Transaction Policy

model_transcation_policy는 모델에서 예상되는 트랙잭션을 기술한다.

Decoupled

이 불리언값은 모델이 받는 요청수와 응답수가 상이할 수 있음을 나타낸다.
기본은 false이다. 일반적으로는 하나의 요청에 하나의 응답을 답한다는 의미이다.

🧃 Maximum Batch Size

max_batch_size 프로퍼티는 최대 배치 사이즈를 정한다.
Triton이 dynamic batcher나 sequence batcher를 사용할 경우, 1 이상으로 설정하면 된다.

배치를 지원하지 않는 모델의 경우, 0으로 되어야 한다.

🛜 Input과 Output

각 모델의 input과 output은 다음을 명시해야 한다:

name
datatype
shape 이들은 모델에서 기대하는 값에 매치해야 한다.

Pytorch Backend에서의 특별한 이름 관례

TorchScript 모델 파일에서의 불충분한 inputs/outputs의 메타데이터로 인해, name 어트리뷰트는 네이밍 컨벤션을 가진다.

(Input한정) input이 Tentor의 덱셔너리가 아니면, 모델의 정의의 forward함수의 인자와 같아야 한다. 예를 들어, Torchscript 모델이ㅡ forward 함수가 forward(self, input0, input1)이라면, 첫 번째와 두 번째의 input의 이름은 각각 “input0”, “input1"이 되어야 한다.
<name>__<index>: <name>은 아무 string이나 될 수 있고, <index>는 대응되는 input/output에 상응하는 위치이ㅡ 인덱스가 될 수 있다. 두 입력과 출력이 있으면, “INPUT__0”, “INPUT__1”, “OUTPUT__0”, “OUTPUT__1"과 같이 될 수 있다.
만약 모든 입력 또는 출력이 같은 네이밍 컨벤션을 따르지 않는다면, model configurations에서의 엄격한 순서를 따진다. 즉, configurations에서의 순서가 실제 모델에서의 입력 순서가 된다.

Pytorch backend는 Tensor의 딕셔너리를 입력으로 하는 것 역시 허용한다.
Dictionary 타입의 단일 입력 모델이 문자열 매핑이 되는 경우에만 지원된다.
예를 들어, 다음과 같은 형식의 입력을 요구한다.

1

{'A': tensor1, 'B': tensor2}

입력 이름은 위의 네이밍 컨벤션을 따르지 않고, 대신 특정 텐서에 대한 key값을 쓴다.
여기서는, A는 tensor1을, B는 tensor2를 가리킨다.

datatype은 모델의 종류에 따라 다르게 할 수 있다.
input shape은 모델이 기대하는 입력 텐서의 shape을 말한다.
output shape은 모델이 기대하는 출력 텐서의 shape을 말한다.
둘다 빈 shape을 허용하지 않는다.

input과 output shape들은 max_batch_size와 input이나 output의 dims 프로퍼티를 통해서 특정된다.
max_batch_size가 0 이상이면, 전체 shape은 [-1] + dims이다.
max_batch_size가 0이라면, 전체 shape은 dims의 꼴일 뿐이다.

예를 들어, 아래 config에서 “input0"의 shape은 [-1, 16]이고, “output0"의 shape은 [-1, 4]이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


 platform: "tensorrt_plan"
 max_batch_size: 8
 input [
 {
 name: "input0"
 data_type: TYPE_FP32
 dims: [ 16 ]
 }
 ]
 output [
 {
 name: "output0"
 data_type: TYPE_FP32
 dims: [ 4 ]
 }
 ]

max_batch_size를 0으로 바꾸면, “input0"은 [16]이 되고, “output0"은 [4]가 된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


 platform: "tensorrt_plan"
 max_batch_size: 0
 input [
 {
 name: "input0"
 data_type: TYPE_FP32
 dims: [ 16 ]
 }
 ]
 output [
 {
 name: "output0"
 data_type: TYPE_FP32
 dims: [ 4 ]
 }
 ]

가변길이의 shape인 input-output을 가진 모델은, input과 output config에서 -1을 이용할 수 있다.
예를 들어, 만약 모델이 2차원 입력 텐서를 원하는데, 첫 차원은 4의 길이지만, 두 번째 차원은 길이가 무한정 늘어날 수 있다면, dims: [4, -1]이 되는것이다.
Triton은 추론 요청을 두 번째의 차원이 0 이상이라면 받을 것이다.

reshape 프로퍼티는 입력 shape와 실제 모델 내부의 shape이 다른 경우 설정가능하다.
model output과 원하는 출력이 다른경우에도 reshape를 설정할 수 있다.

🤖 Auto-Generated Model Configuration

일부 경우에 config.pbtxt를 자동 작성하는것이 제공된다.
기본적으로, 최소한의 모델 설정을 하려고 시도한다.
그러나, --disable-auto-complete-config으로 실행하면, 자동완성을 비활성화한다.
그러나, 이와 상관없이 기본적으로 instance_group부분이 없으면 완성해준다.

TensorRT, ONNX, OpenVINO모델에서 자동완성을 지원해준다.
Python models에서는, auto_complete_config함수에서 set_max_batch_size, add_input, add_output등으로 max_batch_size, input, output의 생성을 구현할 수 있다.
Triton이 Python model에서 최소의 모델 구성을 형성하는데 도움을 준다.
다른 모델 유형들은 다 직접 작성해야한다.

커스텀 벡엔드를 개발할 때, 요구된 세팅들을 넣고 TRITONBACKNED_ModelSetConfig API를 호출하여 Triton core에서 설정을 업데이트할 수 있다.
어떻게 하는지는 OnnxRuntime을 참조하면 된다.
현재는 inputs, outpus, max_batch_size, dynamic_batching을 구현할 수 있다.
모델 이름의 backend필드는 <model_name>.<backend_name>으로 해야한다.

Triton이 자동생성해준 model configuration을 보려면, curl을 이용하면 된다:

1

curl <server-ip>:8000/v2/models/<model name>/config

JSON 표현으로 반환하는데, 이를 config.pbtxt로 대응되게 작성할 수 있다.
Triton은 최소한의 부분만 생성해줄 뿐이고, 추가적인 부분들은 config.pbtxt를 수정해야 한다.

🎨 Custom Model Configuration

가끔은 하나의 모델 레포지토리에서 여러 Triton 인스턴스가 접근할 수 있다.
최고의 성능을 위해서는, 구성이 다르게 되어야 할 수 있다.
--model-config-name옵션으로 커스텀 모델 config를 쓸 수 있게 할 수 있다.

예를 들어, tritonserver --model-repository=</path/to/model/repository> --model-config-name=h100이면, 이 서버는 커스텀 config인 h100.pbtxt를 /path/to/model/repository/model-name/configs에서 찾는다.

만약 있다면, 해당 configuration을 쓴다.
없다면, 기본 config.pbtxt를 쓰거나, 자동 생성된 model configuration을 쓴다.

Custom model configuration은 Explicit과 Poll 방식에서도 모두 잘 동작한다.
서버가 띄워져있는 동안에도 동적으로 모델을 로드할 수 있다.

주의 커스텀 config 이름에는 공백이 있으면 안된다.

예시1. --model-config-name=h100

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


.
└── model_repository/
 ├── model_a/
 │ ├── configs/
 │ │ ├── v100.pbtxt
 │ │ └── **h100.pbtxt**
 │ └── config.pbtxt
 ├── model_b/
 │ ├── configs/
 │ │ └── v100.pbtxt
 │ └── **config.pbtxt**
 └── model_c/
 ├── configs/
 │ └── config.pbtxt
 └── **config.pbtxt**

예시2. --model=config-name=config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


.
└── model_repository/
 ├── model_a/
 │ ├── configs/
 │ │ ├── v100.pbtxt
 │ │ └── h100.pbtxt
 │ └── **config.pbtxt**
 ├── model_b/
 │ ├── configs/
 │ │ └── v100.pbtxt
 │ └── **config.pbtxt**
 └── model_c/
 ├── configs/
 │ └── **config.pbtxt**
 └── config.pbtxt

예시3. --model-config-name이 없으면

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


.
└── model_repository/
 ├── model_a/
 │ ├── configs/
 │ │ ├── v100.pbtxt
 │ │ └── h100.pbtxt
 │ └── **config.pbtxt**
 ├── model_b/
 │ ├── configs/
 │ │ └── v100.pbtxt
 │ └── **config.pbtxt**
 └── model_c/
 ├── configs/
 │ └── config.pbtxt
 └── **config.pbtxt**

👨‍🚀 기본 Max Batch Size와 Dynamic Batcher

모델이 auto-complete기능을 사용할때, 기본 최대 배치 사이즈는 --backend-config=default-max-batch-size=<int>라는 CLI argument로 될 것이다.
기본적으로 4이다.
현재, 다음 backend들은 기본 배치값을 사용하면서 동적 배치를 켠다:

Onnxruntime backend
TensorRT backend
- TensorRT 모델은 이미 자신만의 max batch size를 명시적으로 가지고있다. 그래서, default-max-batch를 사용하지 않는다. 최대 batch size가 1보다 크면, 설정 파일에 scheduler가 없으면 동적 배치가 자동으로 활성화된다.

공통적으로, 최대 배치 사이즈가 1보다 크면, scheduler 설저이 없으면 자동으로 동적 배치가 지원된다.

🥚 Datatypes

아래의 테이블이 Triton이 지원하는 tensor 데이터타입이다.

Model Config	TensorRT	ONNX Runtime	PyTorch	API	NumPy
TYPE_BOOL	kBOOL	BOOL	kBool	BOOL	bool
TYPE_UINT8	kUINT8	UINT8	kByte	UINT8	uint8
TYPE_UINT16		UINT16		UINT16	uint16
TYPE_UINT32		UINT32		UINT32	uint32
TYPE_UINT64		UINT64		UINT64	uint64
TYPE_INT8	kINT8	INT8	kChar	INT8	int8
TYPE_INT16		INT16	kShort	INT16	int16
TYPE_INT32	kINT32	INT32	kInt	INT32	int32
TYPE_INT64	kINT64	INT64	kLong	INT64	int64
TYPE_FP16	kHALF	FLOAT16		FP16	float16
TYPE_FP32	kFLOAT	FLOAT	kFloat	FP32	float32
TYPE_FP64		DOUBLE	kDouble	FP64	float64
TYPE_STRING		STRING		BYTES	dtype(object)
TYPE_BF16	kBF16			BF16

TensorRT에서는 각 값이 nvinfer::DataType namespace에 있다.
예를 들어, 32비트 부동소수점은 nvinfer::DataType::kFLOAT이다.

ONNX Runtime에서는 ONNX_TENSOR_ELEMENT_DATA_TYPE_.에 있다.
예를 들어, ONNX_TENSOR_ELEMENT_DATA_TYPE_FLOAT는 32비트 부동소수점 데이터타입이다.

Pytorch에서 각 값은 torch네임스페이스에 있다. torch::kFloat는 32비트 부동소수점 데이터타입이다.

Numpy에서는 모두 numpy모듈에 있다. ex: numpy.float32

💠 Reshape

Reshape는 Triton Inference API와 실제 모델이 원하는 shape이 서로 다를 때 사용된다.

Triton에서는 input/output의 dims는 반드시 비어있지 않아야 한다.
그러나, 현실의 모델은 배치를 지원하여 [batch_size]만을 입력으로 받는 경우도 있다.
실제 모델은 [batch_size]를 입력받길 원하지만, Triton API에서는 [batch_size, 1]을 요구한다.

그럴 때에는 아래와 같이 설정해주면 된다.

1
2
3
4
5
6
7


input [
 {
 name: "in"
 dims: [ 1 ]
 reshape: { shape: [ ] }
 }
]

출력에서는 [batch_size]를 출력해야 하지만, Triton API에서는 [batch_size, 1]로 출력해야 한다.
아래와 같이 해주면 된다.

1
2
3
4
5
6
7


 output [
 {
 name: "in"
 dims: [ 1 ]
 reshape: { shape: [ ] }
 }
 ]

즉,

dims: Inference API 기준의 shape
reshape.shape: 실제 모델의 shape 이다.

🧊 Shape Tensors

shape tensors를 지원하는 모델에서, is_shape_tensor프로퍼티가 지정될 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


 name: "myshapetensormodel"
 platform: "tensorrt_plan"
 max_batch_size: 8
 input [
 {
 name: "input0"
 data_type: TYPE_FP32
 dims: [ 1 , 3]
 },
 {
 name: "input1"
 data_type: TYPE_INT32
 dims: [ 2 ]
 is_shape_tensor: true
 }
 ]
 output [
 {
 name: "output0"
 data_type: TYPE_FP32
 dims: [ 1 , 3]
 }
 ]

Triton은 batch + [dim]의 꼴로 차원이 형성된다.
그러나, shape tensor에서는, 첫 번째 shape의 값이 배치이다.
위의 config로는 추론 요청이 다음과 같은 shape이어야 한다.

1
2
3


 "input0": [ x, 1, 3]
 "input1": [ 3 ]
 "output0": [ x, 1, 3]

“input1"이 [2]가 아닌 [3]임을 주목하라.
myshapetensormodel은 배치 모델이고, 배치 사이즈는 추가 값으로 제공되어야 한다.
Triton은 이런 shape 값들을 합산하여 응답 배치차원을 만든다.

현재는 TensorRT에서만 지원된다.

👥 Instance Groups

Triton은 여러 추론 요청들이 동시에 처리될 수 있도록 여러 인스턴스를 제공한다.

Multiple Model Instances

기본적으로, 시스템에서 각 가능한 GPU에서 모델의 인스턴스가 하나 생긴다.
intance-group을 세팅하여 특정 GPU 또는 모든 GPU에 여러 개의 인스턴스를 띄울 수 있도록 할 수 있다.

예를 들어, 아래의 configuration은 가능한 각 시스템 GPU에 두 개의 모델 인스턴스를 올릴 것이다.

1
2
3
4
5
6


instance_group [ 
 {
 count: 2
 kind: KIND_GPU
 }
]

아래의 configuration은 0번에는 하나, 1,2번에는 2개의 인스턴스를 둔다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


 instance_group [
 {
 count: 1
 kind: KIND_GPU
 gpus: [ 0 ]
 },
 {
 count: 2
 kind: KIND_GPU
 gpus: [ 1, 2 ]
 }
 ]

CPU Model Instance

Instance group은 CPU에서도 올릴 수 있다.
아래의 설정으로는 CPU환경의 인스턴스가 2개 있는 것이다.

1
2
3
4
5
6


 instance_group [
 {
 count: 2
 kind: KIND_CPU
 }
 ]

🚀 Response Cache

response_cache에는 enable 불리언값을 받고, 캐시를 설정할 수 있다.

1
2
3


response_cache {
 enable: true
}

추가로, --cache-config가 설정되어야 한다.

여기에서 응답 캐시에 대한 더 많은 정보를 가질 수 있다.

Triton Inference Server: 소개

Sat, 27 Dec 2025 17:29:02 +0900

Triton Inference Server는 Nvidia에서 제공하는 오픈소스 모델 서빙 소프트웨어이다.
컨테이너의 형태로 제공되며, 여러 모델들을 로딩하여 API를 제공한다.
다음의 기능들을 제공한다:

REST / gRPC API
Prometheus Metrics
Python, Tensorflow, Pytorch, ONNX, TensorRT, vLLM, FIL 등 다양한 backend
여러 모델들을 로딩하며 버저닝
모델은 컨테이너의 볼륨을 마운트하거나 클라우드 오브젝트 및 호환 스토리지 이용 가능
liveness, readines probe
kserve와 연동가능

🍰 내부 구조

컨테이너 안에는 지원하는 모든 벡엔드들이 들어있고, 모델 레포지토리로부터 모델들을 로딩하며 실제 필요한 벡엔드만 로딩한다.
C API를 통해서 HTTP/gRPC API가 제공된다.
각 요청들은 스케줄러에 의해 적절히 배치된다.
이후, 프레임워크 벡엔드들에서 요청이 처리된다.
각 벡엔드들은 C++ shared library(.so)로 구현되어 있으며, 동적으로 로딩될 수 있다.
메트릭 등은 HTTP API로 제공된다.

🐋 Tritonserver 컨테이너

Tritonserver의 컨테이너 이미지 형식은 nvcr.io/nvidia/triotnserver:<yy.mm>-py3을 따른다.
매월 새로운 릴리스가 나온다.

시작 command는 tritonserver --model-repository=/models이다.
모델 저장소는 보통 /models로 시작하며, 볼륨을 줄때 모델 레포지토리 폴더를 마운트해준다.
또는 오브젝트 스토리지를 이용할 수 있다.

모델 레포지토리의 폴더 구조는 아래와 같다.
이후 글에서 폴더 구조에 대해 더 자세히 알아볼 것이다. 아래는 Pytorch backend의 예시이다.

1
2
3
4
5
6
7
8


model_repository
|
+-- resnet50 // 모델 이름
 |
 +-- config.pbtxt // 필수 configuration file
 +-- 1 // 모델 버전
 |
 +-- model.pt // 모델 파일(torchscript)

예시 시작은 아래와 같다. model_repository에 아래 형식처럼 구조를 가져야 한다:

1

docker run --rm -p8000:8000 -p8001:8001 -p8002:8002 -v/full/path/to/docs/examples/model_repository:/models nvcr.io/nvidia/tritonserver:<xx.yy>-py3 tritonserver --model-repository=/models

Kubernetes 에서 YAML로 선언할 때에는 아래의 예시가 있다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82


# https://kubernetes.io/docs/concepts/workloads/controllers/deployment/
apiVersion: apps/v1
kind: Deployment
metadata:
 name: triton-inference-server
 namespace: triton
 labels:
 app: triton-inference-server
spec:
 selector:
 matchLabels:
 app: triton-inference-server
 replicas: 1
 strategy:
 rollingUpdate: # GPU가 한 장일때는 이와 같이 작성 -> 다운타임 존재
 maxSurge: 0
 maxUnavailable: 1
 type: RollingUpdate
 template:
 metadata:
 annotations:
 kubectl.kubernetes.io/default-container: triton-inference-server
 labels:
 app: triton-inference-server
 spec:
 containers:
 - name: triton-inference-server
 image: nvcr.io/nvidia/tritonserver:25.09-py3 # YY-MM
 imagePullPolicy: IfNotPresent
 args:
 - tritonserver
 - --model-repository=/models
 - --strict-model-config=false
 - --log-verbose=1
 - --disable-auto-complete-config # config.pbtxt 자동생성 비활성화
 ports:
 - containerPort: 8000 # http
 name: http
 - containerPort: 8001 # grpc
 name: grpc
 - containerPort: 8002 # prometheus
 name: prometheus
 resources:
 requests:
 cpu: "2"
 memory: 2Gi
 limits:
 cpu: "4"
 memory: 4Gi
 nvidia.com/gpu: 1 # GPU 한 장
 startupProbe:
 httpGet:
 path: /v2/health/ready
 port: 8000
 timeoutSeconds: 5
 successThreshold: 1
 failureThreshold: 10
 periodSeconds: 10
 livenessProbe:
 httpGet:
 path: /v2/health/live
 port: 8000
 timeoutSeconds: 2
 failureThreshold: 5
 periodSeconds: 10
 readinessProbe:
 httpGet:
 path: /v2/health/ready
 port: 8000
 timeoutSeconds: 2
 successThreshold: 1
 failureThreshold: 5
 periodSeconds: 10
 volumeMounts:
 - name: triton-models
 mountPath: /models
 volumes:
 - name: triton-models
 persistentVolumeClaim:
 claimName: triton-models-pvc
 restartPolicy: Always
---

Cloudflare API를 이용한 Cloudflare DDNS Agent 개발

Tue, 23 Dec 2025 23:15:30 +0900

홈서버의 IP는 고정으로 가지기에 매우 힘들기에, DDNS를 세팅해줘야 한다.
현재 Cloudflare에서 도메인을 구매하여 DNS서비스를 이용하고 있는데,
Cloudflare에서의 DDNS 구축 설명에서는 Cloudflare API를 통해 자체개발하거나, DDClient를 이용하라고 한다.

직접 Cloudflare API를 Go 언어를 통해서 개발해보려고 한다.

📦 Cloudflare API 의존성 설치

Cloudflare API를 위한 코드를 받아준다.

1

go get github.com/cloudflare/cloudflare-go/v6

⚙️ 환경변수 설정

필요한 환경변수들은 아래와 같다:

1
2
3


CF_API_TOKEN # Cloudflare API token (DNS_READ, DNS_WRITE requried)
ZONE_ID # Cloudflare zone ID
DOMAIN_NAME # DNS record name to update (e.g. home.example.com)

💻 코드

전체 코드는 아래와 같다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100


package main

import (
 "context"
 "fmt"
 "io"
 "log"
 "net/http"
 "os"

 "github.com/cloudflare/cloudflare-go/v6"
 "github.com/cloudflare/cloudflare-go/v6/dns"
 "github.com/cloudflare/cloudflare-go/v6/option"
)

func main() {
 // Get IP..
 ip := getIP()
 name := os.Getenv("DOMAIN_NAME")
 zoneID := os.Getenv("ZONE_ID")

 client := cloudflare.NewClient(
 option.WithAPIToken(os.Getenv("CF_API_TOKEN")),
 )
 page, err := client.DNS.Records.List(context.TODO(), dns.RecordListParams{
 ZoneID: cloudflare.F(zoneID),
 })
 if err != nil {
 panic(err.Error())
 }

 res := page.Result
 for i := range res {
 if res[i].Name == name {
 if res[i].Content == ip {
 fmt.Println("DDNS record is up to date.")
 return
 } else {
 fmt.Printf("Updating DDNS record: A %v -> %v\n", res[i].Content, ip)
 updateRecord(client, zoneID, res[i].ID, name, ip)
 return
 }
 }
 }

 fmt.Printf("No such domain name: %v\n", name)
 fmt.Printf("Creating New Record...")
 createRecord(client, zoneID, name, ip)
}

func getIP() string {
 ipProvider := "https://api.ipify.org"
 res, err := http.Get(ipProvider)
 if err != nil {
 log.Fatalf("Error while requesting Public IP to %v: %v", ipProvider, err)
 }
 defer res.Body.Close()
 ip, err := io.ReadAll(res.Body)
 if err != nil {
 log.Fatalf("Error while reading response data from %v: %v", ipProvider, err)
 }

 return string(ip)
}

func updateRecord(client *cloudflare.Client, zoneID, dnsRecordID, name, newIP string) {
 recordResponse, err := client.DNS.Records.Edit(
 context.TODO(),
 dnsRecordID,
 dns.RecordEditParams{
 ZoneID: cloudflare.F(zoneID),
 Body: dns.ARecordParam{
 Name: cloudflare.F(name),
 TTL: cloudflare.F(dns.TTL1),
 Type: cloudflare.F(dns.ARecordTypeA),
 Content: cloudflare.F(newIP),
 },
 },
 )
 if err != nil {
 panic(err.Error())
 }
 fmt.Printf("%+v\n", recordResponse)
}

func createRecord(client *cloudflare.Client, zoneID, name, ip string) {
 recordResponse, err := client.DNS.Records.New(context.TODO(), dns.RecordNewParams{
 ZoneID: cloudflare.F(zoneID),
 Body: dns.ARecordParam{
 Name: cloudflare.F(name),
 TTL: cloudflare.F(dns.TTL1),
 Type: cloudflare.F(dns.ARecordTypeA),
 Content: cloudflare.F(ip),
 },
 })
 if err != nil {
 panic(err.Error())
 }
 fmt.Printf("%+v\n", recordResponse)
}

IP 가져오기

ipify API를 통해서 Public IP주소를 쉽게 가져올 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


func main() {
 // Get IP..
 ip := getIP()
// ...
}

// ...

func getIP() string {
 ipProvider := "https://api.ipify.org"
 res, err := http.Get(ipProvider)
 if err != nil {
 log.Fatalf("Error while requesting Public IP to %v: %v", ipProvider, err)
 }
 defer res.Body.Close()
 ip, err := io.ReadAll(res.Body)
 if err != nil {
 log.Fatalf("Error while reading response data from %v: %v", ipProvider, err)
 }
 return string(ip)
}

`main.go` 주요 로직

퍼블릭 IPv4주소를 가져온 뒤, Cloudflare Client를 생성한다.
그 뒤, 도메인에 대한 DNS 레코드들을 가져온다.

각 레코드에 대해서, 이 서버가 광고하길 원하는 이름을 찾는다.
있다면, 업데이트를 시도하고, 없다면, 새로 만들기를 시도한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


func main() {
// ...
 name := os.Getenv("DOMAIN_NAME")
 zoneID := os.Getenv("ZONE_ID")

 client := cloudflare.NewClient(
 option.WithAPIToken(os.Getenv("CF_API_TOKEN")),
 )
 page, err := client.DNS.Records.List(context.TODO(), dns.RecordListParams{
 ZoneID: cloudflare.F(zoneID),
 })
 if err != nil {
 panic(err.Error())
 }

 res := page.Result
 for i := range res {
 if res[i].Name == name {
 if res[i].Content == ip {
 fmt.Println("DDNS record is up to date.")
 return
 } else {
 fmt.Printf("Updating DDNS record: A %v -> %v\n", res[i].Content, ip)
 updateRecord(client, zoneID, res[i].ID, name, ip)
 return
 }
 }
 }

 fmt.Printf("No such domain name: %v\n", name)
 fmt.Printf("Creating New Record...")
 createRecord(client, zoneID, name, ip)
}

레코드 업데이트

레코드를 업데이트하는 코드이다.
cloudflare.F()는 Cloudflare SDK에서의 제네릭 헬퍼이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


func updateRecord(client *cloudflare.Client, zoneID, dnsRecordID, name, newIP string) {
 recordResponse, err := client.DNS.Records.Edit(
 context.TODO(),
 dnsRecordID,
 dns.RecordEditParams{
 ZoneID: cloudflare.F(zoneID),
 Body: dns.ARecordParam{
 Name: cloudflare.F(name),
 TTL: cloudflare.F(dns.TTL1), // Auto-TTL
 Type: cloudflare.F(dns.ARecordTypeA), // A Record
 Content: cloudflare.F(newIP),
 },
 },
 )
 if err != nil {
 panic(err.Error())
 }
 fmt.Printf("%+v\n", recordResponse)
}

레코드 생성

New()로 새로운 레코드 생성 요청을 할 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


func createRecord(client *cloudflare.Client, zoneID, name, ip string) {
 recordResponse, err := client.DNS.Records.New(context.TODO(), dns.RecordNewParams{
 ZoneID: cloudflare.F(zoneID),
 Body: dns.ARecordParam{
 Name: cloudflare.F(name),
 TTL: cloudflare.F(dns.TTL1),
 Type: cloudflare.F(dns.ARecordTypeA),
 Content: cloudflare.F(ip),
 },
 })
 if err != nil {
 panic(err.Error())
 }
 fmt.Printf("%+v\n", recordResponse)
}

🏗️ 빌드

이제, 프로그램을 빌드한다.

1
2
3


go build -o ddns-agent main.go
chmod +x ddns-agent
sudo mv ddns-agent /usr/local/bin/ddns-agent

🔄 자동으로 동작하게 하기

광고하길 원하는 서버에서 주기적으로 동작시켜야 한다.
Cron을 이용할 수 있지만, 더 깔끔한 관리를 위해 Systemd가 관리하도록 해보자.

Linux(Systemd)

/etc/systemd/system/ddns.service파일을 생성해서, 아래와 같이 작성한다.
Environment=<key>=<value>에서 환경변수 값을 채워주자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


# /etc/systemd/system/ddns.service
[Unit]
Description=DDNS Agent (Cloudflare)
# Execute when network service is available
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot # Job-like service
ExecStart=/usr/local/bin/ddns-agent # Execute binary
# Environment variables
Environment=CF_API_TOKEN=xxxx
Environment=ZONE_ID=xxxx
Environment=DOMAIN_NAME=xxxx

## Security
# No privilege escalation
NoNewPrivileges=true
# Isolate tmpfs
PrivateTmp=true
# ReadOnly System directories(/etc, /usr, ...)
ProtectSystem=strict
# Cannot Access /home
ProtectHome=true

[Install]
WantedBy=multi-user.target # Multi-user unit

/etc/systemd/system/ddns.timer파일을 만들어서, 주기적으로 동작하는 트리거를 만든다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# /etc/systemd/system/ddns.timer
[Unit]
Description=Run DDNS Agent periodically

[Timer]
OnBootSec=30 # First execution: 30s after boot
OnUnitActiveSec=5min # 5-min period
Persistent=true # Ensures executed once after inactivate time

[Install]
WantedBy=timers.target # Timer unit

아래 명령으로 적용한다.

1
2
3


sudo systemctl daemon-reload
sudo systemctl enable ddns.timer
sudo systemctl start ddns.timer

잘 등록되어있는지 확인한다.

1

systemctl list-timers | grep ddns

MacOS(launchd)

MacOS를 쓰는 경우, Systemd 대신, Launchd를 쓴다.

사용자 로그인세션부터가 아닌 부팅시점부터 도리고 싶다면, LaunchAgents 대신 LaunchDaemons를 써야 한다.

yourname에는 홈 유저네임을 쓰면 된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


# ~/Library/LaunchAgents/com.yourname.ddns-agent.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
 <key>Label</key>
 <string>com.yourname.ddns-agent</string>

 <!-- Program -->
 <key>ProgramArguments</key>
 <array>
 <string>/usr/local/bin/ddns-agent</string>
 </array>

 <!-- EnvironmentVariables key and its dictionary -->
 <key>EnvironmentVariables</key>
 <dict>
 <key>CF_API_TOKEN</key>
 <string>YOUR_CF_API_TOKEN</string>
 <key>ZONE_ID</key>
 <string>YOUR_CF_ZONE_ID</string>
 <key>DOMAIN_NAME</key>
 <string>YOUR_DDNS_RECORD_NAME</string>
 </dict>

 <!-- AutoRun when Startup -->
 <key>RunAtLoad</key>
 <true/>

 <key>StartInterval</key>
 <integer>300</integer> <!-- 5 mins interval-->

 <!-- stdout/stderr -->
 <key>StandardOutPath</key>
 <string>/usr/local/var/log/ddns.log</string>
 <key>StandardErrorPath</key>
 <string>/usr/local/var/log/ddns.err</string>
</dict>
</plist>

아래 명령으로 적용한다.

1
2
3


mkdir -p /usr/local/var/log # 로그 존재하도록 정리
launchctl load ~/Library/LaunchAgents/com.yourname.ddns-agent.plist
launchctl start com.yourname.ddns-agent

잘 등록되어있는지 확인한다:

1

launchctl list | grep ddns

📚 References

Cloudflare API(Go)

AWS Route53 + API Gateway로 DR Failover구성하기

Wed, 03 Dec 2025 20:18:09 +0900

대학교 조별과제로 공중화장실 위치를 알려주는 간단한 서비스를 만들었다.
공공데이터를 이용하여 공중화장실 및 개방화장실 데이터를 DynamoDB에 저장하고, Geohash로 쿼리하여 주변 화장실들을 필터링하는 Lambda함수를 만들어서 서버리스 기반의 서비스를 구축했다.
DynamoDB는 글로벌 테이블로 만들어서 최종일관성(eventually consistency)모델을 따르도록 했다.

아키텍처는 다음과 같다:

내가 맡은 부분은 DR구축이었는데, 이 과정을 기록하려고 한다.

🏷️ 도메인 구매

가비아에서 550원짜리 .shop 도메인을 구매하였다.

🌲 Route53 호스팅영역 생성

호스팅 영역을 생성한다.
도메인 주소는 가비아에서 구입한 도메인주소로 한다.
생성 시, NS레코드에 4개의 값이 있는데, 이걸 가비아에서 네임서버로 등록한다.

🪪 ACM 인증서 생성

루트도메인(2LD)과 그 아래 서브도메인을 커버하는 인증서를 만들기 위해,
example.com과 *.example.com을 만든다.
인증 방법은 간단하고, 권장되고, 자동으로 인증되는 DNS인증을 이용하면 된다.
이메일 인증은 권장되지 않고, 오히려 해당 도메인에서의 admin과 같은 별도의 메일주소가 필요해서 번거롭다.

Route53에서 레코드를 생성을 누르고, 시간이 지나면, 발급된다.

🚪 API Gateway에서 커스텀 도메인 추가

Route53에 API Gateway를 연결하려면, API Gateway에 커스텀 도메인을 붙여서 레코드를 생성해야 한다. ACM인증서에서 만들어둔 인증서를 선택한다. 이후, API 매핑을 구성한다.

👼 DR리전에서 구성

똑같이 DR리전(여기서는 도쿄)에서도 똑같은 인프라를 구성해준다.

DynamoDB 글로벌 테이블을 활성화
Lambda 함수 생성
API Gateway연결
ACM생성(ACM은 리전단위 서비스이다)
커스텀 도메인 생성(여기서도 api.example.com으로 똑같이 만들어준다.)

🫀 Health check API 만들기

헬스체크 API를 별도로 만들어서, /health로 요청 시, 정상이면 200, 비정상 시 다른 응답을 주는 Lambda 함수를 실행할 것이다.
서울리전에 단순라우트로 레코드를 추가해서, 헬스체크 엔드포인트를 만들 것이다.

헬스체크 함수 추가

헬스체크 Lambda함수를 생성한다.
예시 함수는 다음과 같다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


import json
import os

def lambda_handler(event, context):
 failover = os.environ.get("FAILOVER", "0")

 if failover == "1":
 return {
 'statusCode': 500,
 'body': json.dumps('Unhealthy!')
 }

 return {
 'statusCode': 200,
 'body': json.dumps('Healthy!')
 }

이후, 구성 -> 환경 변수에서 FAILOVER=0으로 해둔다.

API Gateway에 연동

API Gateway에 Lambda함수를 연동한다.

커스텀 도메인 추가 & 호스팅 존에 단순 라우트 연동

seoul.example.com으로 커스텀 도메인을 만들어준다. API 매핑도 추가해준다.

Route53의 호스팅 영역에서 단순레코드를 하나 만들어준다.
seoul.example.com으로 레코드 이름을 만들고, 유형은 A.
별칭을 활성화하고, API Gateway API에 대한 별칭 -> 아시아 태평양(서울) -> 커스텀 도메인에 바인딩된 API Gatewawy 도메인으로 연동해주면 된다.

상태 확인 추가

Route53에서 상태 확인을 하나 생성한다.
이번에는 엔드포인트 리소스를 이용할 것이고, 도메인 이름으로 한 뒤, 커스텀 도메인주소로 요청을 넣도록 하면 된다.
임계치나 간격은 전략에 맞게 설정하면 된다. 참고로, 고급 구성에서 SNI를 비활성화하여 TLS에러를 해결할 수 있다. SNI가 커스텀 도메인 기반의 인증을 시도하지만, CloudFront와 미스매치로 TLS 핸드셰이크에 오류가 생길 수 있기 때문인듯 하다.

🎥 DNS 레코드 추가

이제 본격적으로 DR대비 레코드를 추가하자.
이름을 api.example.com으로 하고, 유형을 A, 대상으로 커스텀 도메인의 Cloudfront 배포 도메인으로 연결한다.
그리고 라우팅 대상으로 커스텀 도메인의 API Gateway 도메인이름으로 해준다.
헬스 체크로는 방금 만들어준 헬스체크와 연동하면 된다.

도쿄리전도 똑같은 api.example.com으로 만들어주고, A유형, 커스텀 도메인의 Cloudfront 배포 도메인으로 만들어주면 된다.

🧪 테스트 해보기

우선, 평시에는 서울리전으로부터 데이터가 온다. API 요청에도 AWS_REGION환경변수로 어느 리전의 Lambda함수가 실행되었는지 볼 수 있다. 헬스 체크 lambda에서 환경 변수를 수정하여 500을 반환하도록 해보았다.

이제부터, 헬스 체크에 실패한다.
Route53의 헬스체크는 여러 리전들로부터 집계하여 18%미만으로 2XX, 3XX응답을 받지 못하면, 헬스 체크에 실패함으로 간주한다.
이제는 도쿄리전으로부터 데이터가 옴을 볼 수 있다.

다시 FAILOVER=0으로 환경 변수를 바꿔보자. 이제 또 다시 서울리전으로부터 응답이 올 것이다.

📚 후기

직접 서버리스 아키텍처와 DR을 구성한건 처음이었는데, Failover 및 Failback이 되는 과정을 직접 보니 재밌었다.
DNS 수준에서의 DR을 구현해냈다.
다음에는 Cloudwatch Alarm + Lambda를 이용한 다른 헬스체크 및 트리거로 시도해보고 싶다.
또는, 여름 KDT에서 팀원이 Global Accelerator기반의 DR을 해보았는데, 나도 GA기반으로 직접 해보고싶다.

ArgoCD: Private Repository로부터 Pull할 수 있도록 설정

Tue, 18 Nov 2025 16:12:01 +0900

ArgoCD에 Repository 추가

우리는 항상 퍼블릭한 저장 공간만을 사용하는 것이 아니다.
오히려 프로덕션에서는 Private 레포지토리를 이용하는경우가 거의 대부분이다.

아래와 같이 Secret을 추가해주면 된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: v1
kind: Secret
metadata:
 name: repo-k8s-https
 namespace: argocd
 labels:
 argocd.argoproj.io/secret-type: repository # 이 label이 핵심
stringData:
 type: git
 url: <private-git-repo> # GitHub, GitLab 등
 username: <username>
 password: <Personal Access Token>

ArgoCD Web UI에서도 아래와 같이 뜨는것을 확인할 수 있다:

ArgoCD: App of Apps 패턴 사용하기

Sat, 15 Nov 2025 14:16:33 +0900

🪆 App of Apps 패턴이란

ArgoCD에는 Application이라는 배포 단위를 가진다.
그러나, Application들 자체는 GitOps로 관리되지 못한다.
그래서, 이 문제에 대한 해결 방법으로, Application들을 감시하는 Root Application을 만들어서, 단일 배포 시작점으로 만든 뒤, 하위 Application들을 GitOps로 관리하는 App of Apps라는 패턴을 사용할 수 있다.

이후에는 Root App을 제외하고는 모두 선언형으로 관리되어, Application CRD의 명령형 관리영역을 단일 지점으로 줄일 수 있다.

🍳 Root App 예시

아래의 디렉토리 구조를 가정한다:

1
2
3
4
5
6
7
8
9


.
├── apps # 서비스할 애플리케이션들의 yaml
├── argocd
│   ├── apps # apps/ 디렉토리의 Application들
│   ├── infra # infra/ 디렉토리의 Application들
│   └── root-app.yaml # Root Application
└── infra # Infra 레벨의 yaml
 ├── network
 └── storage

root-app.yaml에는 아래와 같이 작성해주면 된다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# Root-App.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
 name: root-app
 namespace: argocd
spec:
 project: default
 sources:
 # Apps를 위해서
 - repoURL: <your-git-repo>
 targetRevision: HEAD
 path: argocd/apps
 directory:
 recurse: true
 # Infra를 위해서
 - repoURL: <your-git-repo>
 targetRevision: HEAD
 path: argocd/infra
 directory:
 recurse: true
 destination:
 server: https://kubernetes.default.svc  # in-cluster.
 namespace: argocd
 syncPolicy:
 automated:
 prune: true
 selfHeal: true

이제, 적용해준다.

1

kubectl apply -f argocd/root-app.yaml

이제, 클러스터를 옮겨도 Root App을 통해서 한 번에 여러 애플리케션들을 연쇄적으로 업데이트 할 수 있다.

ArgoCD: 레포지토리 구조와 App 배포하기

Fri, 07 Nov 2025 13:37:38 +0900

레포지토리 구조 전략을 알아보고, 배포의작은 단위인 Application 배포도 해보자

레포지토리 구조

쿠버네티스 yaml 레포지토리의 구조를 아래와 같이 하였다.
이 방법 외에도 정답은 많다, 하나의 전략일 뿐이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


.
├── apps
│  ├── service-a
│  ├── service-b
│   └── service-c
│  ├── deploy.yaml
│   └── svc.yaml
├── argocd
│  ├── app
│ │ ├── service-a.yaml
│  │ ├── service-b.yaml
│   │ └── service-c.yaml
│   └── infra
│   └── cilium-core.yaml
└── infra
 └── network
 └── cilium-core
 └── values.yaml

apps: 서비스할 애플리케이션에 대한 yaml들을 각 서브폴더 안에 넣는다. 예를 들면, deployment와 service등이 있다.
argocd: ArgoCD는 Application이라는 CRD로 배포 단위를 묶는다. argocd/app 서브폴더에 apps의 Application들을 선언해줄 것이고, argocd/infra 서브폴더에 infra의 Application들을 선언해줄 것이다.
infra: 인프라 요소들(네트워킹, 스토리지 등)도 GitOps로 관리하면 깔끔한 운영이 가능하다. 여기서는 Cilium을 ArgocD가 감시하도록 만들 것이다.

Application yaml 예시

아래는 Cilium을 Application으로 관찰하기 위한 예시이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
 name: cilium-core
 namespace: argocd
spec:
 project: default
 sources:
 - repoURL: https://github.com/fudoge/kube-manifests-lab.git # 당신의 레포지토리로 하세요
 targetRevision: main
 ref: values
 - chart: cilium
 repoURL: https://helm.cilium.io/
 targetRevision: 1.18.1
 helm:
 releaseName: cilium
 valueFiles:
 - $values/infra/network/cilium-core/values.yaml
 destination:
 server: https://kubernetes.default.svc
 namespace: kube-system
 syncPolicy:
 syncOptions:
 - RespectIgnoreDifferences=true
 ignoreDifferences:
 - kind: Secret
 name: cilium-ca
 namespace: kube-system
 jsonPointers:
 - /data
 - kind: Secret
 name: hubble-relay-client-certs
 namespace: kube-system
 jsonPointers:
 - /data
 - kind: Secret
 name: hubble-server-certs
 namespace: kube-system
 jsonPointers:
 - /data

apiVersion: argoproj.io/v1alpha1: Argo 프로젝트의 CRD를 위한 API버전.
.spec: Application: Application 리소스. ArgoCD의 기본적인 서비스단위이다.
.metadata.name: Application의 이름.
spec.project: 어느 Project에 속하는지 정한다. 여러 Application들을 Project로 묶어 관리가능하다. 지금은 default로 했다.
spec.sources[0]을 보면, cilium helm 레포지토리로부터 차트를 받음을 알 수 있다. 버전은 1.18.1로 정했고, helm의 릴리즈명은 cilium, values파일은 $values/infra/network/cilium-core/values.yaml로부터 가져옴을 알 수 있다.
spec.sources[1]을 보면, github의 쿠버네티스 마니페스트 레포지토리로부터 값을 가져옴을 알 수 있다. main브랜치로 정하고, values로 참조할 수 있도록 설정한 것을 볼 수있다. 즉, spec.sources[0]에서 $values로 끌어와서 사용함을 볼 수 있다.
spec.destination에는 적용 대상이 적혀있다. 자신의 클러스터의 kube-system에 배포하라는 의미이다.
spec.syncPolicy.syncOptions에서 RespectIgnoreDifferences=true로 설정된 것을 볼 수 있다. 아래의 ignoreDifferences를 활성화시키기 위해서이다.
spce.ignoreDifferences들의 요소를 보자. cilium-ca, hubble-relay-client-certs, hubble-server-certs들의 .data부분을 무시한다는 의미이다. 이 작성법은 RFC6902 JSON patches기반이다. 이 부분을 무시하는 이유는, Cilium의 이 시크릿들이 주기적으로 자동 롤링되기 때문에, GitOps의 추적에는 무시하는 것이 좋다.

아래는 Triton Inference Server를 Application으로 배포하는 예시이다: 앞에서는 sources로 참조했는데, 이번에는 source로 참조하는 것을 볼 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
 name: triton-dta-inference-server
 namespace: argocd
spec:
 project: default
 source:
 repoURL: https://github.com/fudoge/kube-manifests-lab.git
 targetRevision: main
 path: apps/triton-dta-inference-server
 destination:
 server: https://kubernetes.default.svc
 namespace: triton-dta
 syncPolicy:
 automated:
 enabled: true
 syncOptions:
 - CreateNamespace=true

spec.syncPolicy.automated.enabled를 true로 두면, 자동으로 Sync된다.

Application 적용해보기

레포지토리를 커밋 및 푸시해주자. 그 뒤, 이 애플리케이션을 적용하여 만들어보자.

1

kubectl apply -f argocd/infra/cilium-core.yaml

Refresh후, Sync해주자.
Warning메시지가 뜨는데, 기존 Cilium에는 없던 argocd관련 어노테이션들이 추가되기 때문이다.
그냥 replace로 덮어씌우면 된다. 혹시 걱정된다면 diff로 뭐가 다른지 확인해보면 된다.
이제, ArgoCD가 Cilium의 코어 리소스들을 추적한다.
그러면서 롤링되는 시크릿은 동기화 추적으로부터 벗어나도록 했다.

잘 된것을 확인할 수 있다!

ArgoCD: 시작하기

Thu, 06 Nov 2025 11:15:27 +0900

🐙 ArgoCD란

ArgoCD는 선언형 GitOps를 제공하는 쿠버네티스 오퍼레이터이다.
GitOps란, 인프라 및 애플리케이션의 설정과 원하는 상태를 Git에 저장하고, 해당 Git 레포지토리를 Single Source of Truth로 두는 방법이다.
GitOps의 이점은 다음과 같다:

선언적으로 정리된 시스템의 상태들을 Git과 연동
배포 속도 향상
쉬운 감사 및 롤백
높은 안정성 및 일관성

🔬 ArgoCD 내부 구조

ArgoCD는 다음의 세 가지 구성요소를 가진다:

API Server gRPC, REST API를 제공하는 서버이다.
Web UI, CLI, CI/CD시스템으로부터 상호작용하여, 애플리케이션 작업, repository 및 credential 관리, 인증 및 인가, RBAC관리, Git webhook 이벤트 수신 등의 다양한 역할을 한다.
Repository Server 애플리케이션의 manifest의 로컬 캐시를 유지한다.(레포지토리를 영구히 받아 저장하지는 않는다, 즉 stateless하다)
레포지토리, revision(commit, tag, branch), 어플리케이션 경로, 탬플릿 세팅(파라미터, helm values 등)의 입력을 받아서 k8s manifest를 생성한다.
Application Server 지속적으로 클러스터의 상태와 레포지토리에서 쓰인 desired state와 비교한다.
즉, Kubernetes API와 상호작용하며 실제 작업을 맡는 역할을 한다.

🚀 클러스터에 ArgoCD 설치

명령어를 통한 설치

1
2


kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Helm을 통한 설치

여기에서 다양한 values 옵션을 참고 가능하다.

ArgoCD CLI 설치

ArgoCD Installation을 참고한다.

🖥️ ArgoCD Dashboard에 접속

Port-forward, NodePort, LoadBalancer, Ingress, Gateway API등을 이용할 수 있다.

Port-forward로 접근

1

kubectl port-forward -n argocd svc/argocd-server 8080:80

이후. localhost:8080으로 들어가면 된다.

LoadBalancer로 노출시키기

MetalLB / Cilium L2 Announcement / 기타 클라우드 로드 밸런서가 있을 시, 이용하능하다

1

kubectl patch svc argocd-server -n argocd -p '{"spec": {"type": "LoadBalancer"}}'

CLI로 비밀번호 받기

아래 명령어로 최초의 admin 비밀번호를 얻을 수 있다.

1

argocd admin initial-password -n argocd

Web UI 접속

ID: admin, Password: <CLI를통해 받은 비밀번호>를 이용하여 로그인할 수 있다.

Cilium: L2 LoadBalancer를 노출해보자

Sun, 02 Nov 2025 14:52:39 +0900

온프레미스 환경에서 L2 브로드캐스팅을 이용해서 로드밸런서를 만들어보자.

💾 설치

아래의 helm values들이 필요하다:

1
2
3
4


installCRDs: true

l2announcements:
 enabled: true

1
2
3


helm upgrade cilium cilium/cilium \
 -n kube-system \
 -f values.yaml

🏊 IP풀 및 정책 생성

우선, IP할당 풀을 만들어준다. cilium-ip-pool.yaml

1
2
3
4
5
6
7


apiVersion: "cilium.io/v2alpha1"
kind: CiliumLoadBalancerIPPool
metadata:
 name: "local-nw-pool"
spec:
 blocks:
 - cidr: "192.168.0.240/29" # 공유기 DHCP대역과 겹치지 않는것이 좋다

L2광고정책도 생성해준다. cilium-l2-announcement.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: "cilium.io/v2alpha1"
kind: CiliumL2AnnouncementPolicy
metadata:
 name: local-l2
spec:
 nodeSelector:
 matchLabels:
 name: "worker1" # 이렇게 하면, name=worker1을 가진 노드에서 광고한다.
 interfaces:
 - enp6s0 # 본인 네트워크 인터페이스로
 externalIPs: true
 loadBalancerIPs: true

아래와 같이 하면, failover도 지원된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


apiVersion: cilium.io/v2alpha1
kind: CiliumL2AnnouncementPolicy
metadata:
 name: local-l2
spec:
 nodeSelector:
 matchLabels: # 다음의 label을 가지면 ok
 l2candidate: "true"
 interfaces: # 다음의 인터페이스를 가지면 ok
 - enp1s0
 - enp2s0
 - enp3s0
 - enp4s0
 - enp5s0
 - enp6s0
 externalIPs: true
 loadBalancerIPs: true

여러 노드에 l2candidate=true label을 붙여주면 된다.

1
2


kubectl label node worker1 l2candidate=true
kubectl label node worker2 l2candidate=true

✅ 테스트

test.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


# https://kubernetes.io/docs/concepts/workloads/pods/
apiVersion: v1
kind: Pod
metadata:
 name: "nginx"
 namespace: default
 labels:
 app: "nginx"
spec:
 containers:
 - name: nginx
 image: "nginx:latest"
 resources:
 limits:
 cpu: 200m
 memory: 500Mi
 requests:
 cpu: 100m
 memory: 200Mi
 ports:
 - containerPort: 80
 name: http
 restartPolicy: Always
---
# https://kubernetes.io/docs/concepts/services-networking/service/
apiVersion: v1
kind: Service
metadata:
 name: nginx
 namespace: default
spec:
 selector:
 app: nginx
 type: LoadBalancer
 ports:
 - name: nginx
 protocol: TCP
 port: 80
---

lease리소스는 ARP 광고를 수행할 리더노드를 선출한다.

1

kubectl -n kube-system get lease | grep l2

External-IP가 나온 것을 볼 수 있다.

1
2
3
4
5


16:12:28 in ~/cilium-lab/helm_install took 4.7s …
➜ kubectl get svc
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 21d
nginx LoadBalancer 10.102.139.71 192.168.0.32 80:31861/TCP 21h

결과를 확인해보자:

1

curl 192.168.0.32/index.html

주의 L2 announcement는 한 service당 하나의 노드에만 붙을 수 있다.

집에서 Vaultwarden으로 비밀번호 서버 운영하기 (w. TailScale VPN)

Sat, 01 Nov 2025 13:37:44 +0900

집에서 쓰는 맥미니에서 bitwraden의 경량버전인 vaultwarden을 운영해서 실제 개인 사용을 위한 패스워드 서버로 쓸 것이다.

전체 아키텍처는 다음과 같다:

🔒 Vaultwarden 시작하기

docker-compose 작성

docker-compose.yaml에 아래와 같이 작성한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


name: "vaultwarden-server"
services:
 vaultwarden:
 container_name: vaultwarden
 image: "vaultwarden/server@sha256:d89a6d21e361254670c24a4272b4b5f245e402c284f2f55de2c379fdbcfa1fa5" # vaultwarden 1.35.2 linux/arm64/v7
 restart: "always"
 volumes:
 - "./vw-data:/data"
 environment:
 - DOMAIN=https://${SERVER_DOMAIN}
 - WEBSOCKET_ENABLED=true
 - ROCKET_PORT=80
 - ROCKET_ADDRESS=0.0.0.0
 - LOG_LEVEL=WARN
 ports:
 - "8080:80"

.env파일에 SERVER_DOMAIN에 대한 값을 작성해주었다.

대시보드 접속하기

docker compose up -d를 실행한 뒤, localhost:8080에 접속해서 계정을 생성하자.

로그인한 뒤, Import Data에서 기존 비밀번호 데이터를 삽입한다.
나는 iCloud KeyChain로부터 export한 데이터를 가져왔다.

우선, 기본적인 vaultwarden서버 세팅이 완료되었다.
그러나, 우린 이 서버에 안전하게 접근해야 한다!

🌐 TailScale 세팅하기

TailScale은 WireGuard 프로토콜을 기반으로 한 분산 VPN 서비스이다.
자세한 내용은 이 게시글에서 확인가능하다.

TailScale 공식 홈페이지에 접속한다.
로그인 후, 정보를 입력한다.

기기들에 클라이언트를 설치해서 연결해준다.
여기서는 우선 핸드폰이랑 서버로 쓸 기기에 설치해주었다.

ping을 보내보자. 잘 보내닌다!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


00:14:28 in ~/vaultwarden-sever on 🐳 v28.3.0
➜ ping 100.87.71.24 -t 4
PING 100.87.71.24 (100.87.71.24): 56 data bytes
64 bytes from 100.87.71.24: icmp_seq=0 ttl=64 time=98.555 ms
64 bytes from 100.87.71.24: icmp_seq=1 ttl=64 time=7.591 ms
64 bytes from 100.87.71.24: icmp_seq=2 ttl=64 time=74.451 ms
64 bytes from 100.87.71.24: icmp_seq=3 ttl=64 time=5.851 ms
^C
--- 100.87.71.24 ping statistics ---
4 packets transmitted, 4 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 5.851/46.612/98.555/40.796 ms

✅ HTTPS 세팅하기

이제 어디서나 홈서버와 내 다른 기기들은 서로 통신할 수 있게 되었다.
Vaultwarden은 외부 클라이언트로부터 SSL/TLS연결을 요구한다. 그러므로, https를 세팅해줘야 한다.

도메인 설정 및 인증서 발급

TailScale의 대시보드에서 [DNS]에 들어간 뒤, MagicDNS가 켜져 있는지 확인한다.
아래처럼 비활성화 버튼이 있다면 켜진 것이다.

그 아래에 HTTPS Certificates가 있다.
Enable HTTPS를 눌러주자..

Let’s Encrypt에 의해 인증서가 발급되는데, 실제 인터넷에 도메인이 등록되는 것은 아니지만, Let’s Encrypt에 인증서 발행 장부에 기록된다고 한다.
기본적으로 난독화를 위해 tailnet의 이름이 들어간다고 한다.
<host>.<tailnet_name>.ts.net 과 같이 생성된다.
그러나, tailnet의 이름은 커스텀 가능하다.

tailscale cert 명령으로 인증서를 발급받는다.

Caddy를 리버스 프록시로 사용하기

Caddy는 고성능 리버스 프록시로, 간결한 설정 파일 구조를 가진다.
또한, 인증서 갱신도 Tailscale과 조합이 좋다.
단, 컨테이너 환경에서는 tailscaled가 systemd에 의해 관리되지 않으므로, 별도 갱신 스크립트로 대체하였다.

docker-compose.yaml의 services의 하위에 다음을 추가한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


 caddy:
 container_name: caddy
 image: "caddy@sha256:87aa104ed6c658991e1b0672be271206b7cd9fec452d1bf3ed9ad6f8ab7a2348" # caddy 2.10.2 - linux/arm64/v8
 restart: "always"
 volumes:
 - "./caddy/caddy-data:/data"
 - "./caddy/conf:/etc/caddy"
 - "./caddy/certs:/certs:ro"
 ports:
 - "443:443"
 - "80:80"
 depends_on:
 - vaultwarden

caddy/conf/Caddyfile에 아래와 같이 작성한다: tls의 값에는 자신의 서버의 DNS주소를 써야 한다.

1
2
3
4
5
6
7
8


s-mac-mini.tail274d3c.ts.net {
 tls /certs/s-mac-mini.tail274d3c.ts.net.crt /certs/s-mac-mini.tail274d3c.ts.net.key

 log {
 level WARN
 }
 reverse_proxy vaultwarden:80
}

인증서를 caddy/certs에 옮겨주자.

1
2


mv <host>.<tailnet_name>.ts.net.crt /caddy/certs/<host>.<tailnet_name>.ts.net.crt
mv <host>.<tailnet_name>.ts.net.key /caddy/certs/<host>.<tailnet_name>.ts.net.key

아래 사진의 좌물쇠표시에 주목하자. https가 성공적으로 적용되었다!

아쉽게도, 맥미니 호스트 Tailscale + Caddy 컨테이너 조합으로는 인증서 자동 갱신을 할 수 없다.
그래서, 아래와 같이 쉘 스크립트를 구성하여 cron에 등록하여 인증서를 자동갱신하도록 하였다.
Tailscale이 발급받는 인증서의 유효기간은 90일이고, 30일 이내인경우에만 실제로 재발급해주며, 이외의 경우에는 같은 인증서를 발급 해준다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


#! /bin/bash

set -euo pipefail

BIN="/usr/local/bin"
BASE_DIR="/Users/<you>/vaultwarden-server"
CERT_DIR="${BASE_DIR}/caddy/certs"
BASE_URL="<url>"
CERT="${BASE_URL}.crt"
KEY="${BASE_URL}.key"

TMPDIR=$(mktemp -d)

if ! tailscale cert --cert-file "${TMPDIR}/${CERT}" --key-file "${TMPDIR}/${KEY}" "${BASE_URL}"; then
 echo "tailscale cert failed"
 exit 1
fi

mv "${TMPDIR}/${CERT}" "${CERT_DIR}/${CERT}"
mv "${TMPDIR}/${KEY}" "${CERT_DIR}/${KEY}"
rm -rf "${TMPDIR}"

if ! docker exec caddy caddy reload --config /etc/caddy/Caddyfile --force; then
 echo "Caddy reload failed"
 exit 1
fi

이 방법 외에도, Caddy container를 tailnet에 가입시켜 운영할 수도 있다.
여기서는 자동 인증서 갱신이 가능하다.
여기서는 별도로 컨테이너를 가입시킨 형태를 원하진 않아서 이 방법을 사용하지 않았다.
Caddy-Tailscale참조.

📱 Bitwarden 클라이언트로 로그인해보기

모바일에서 로그인

Bitwarden 앱을 다운로드 받고, Self-hosted를 선택하고 로그인하여 이용해주면 된다.

브라우저 확장 프로그램

Bitwarden 확장프로그램을 다운받은 뒤, Self-hosted에서 로그인해주면 된다.

🫙 AWS S3에 백업하기(w. Terraform)

이제 다음문제는, 혹시 모를 상황에 대비하여 vaultwarden의 데이터를 백업하는 것이다.
오브젝트 스토리지인 AWS S3(Simple Storage Service)를 이용하자.
11-nines의 내구성을 자랑하며, 비용이 매우 저렴하다.
여기서는 이틀간 S3 Standard 스토리지 클래스를 이용하다가, 이후 180일까지 S3 Glacier Deep Archive를 이용하는 정책을 이용하여 비용을 절감할 것이다.

IAM계정 생성 및 자격증명 등록

AWS 콘솔의 IAM에 접속해서, Terraform을 위한 IAM계정을 생성해서, 액세스 키를 만들어서 발급한 뒤, aws configure를 통해서 aws-cli에 자격증명을 넣는다.

backend 생성

아래와 같이 backend.tf를 작성한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_s3_bucket" "terraform_state" {
 bucket = "my-homeserver-backup" # 원하는 이름 지정

 lifecycle {
 prevent_destroy = true
 }
}

resource "aws_s3_bucket_versioning" "enabled" {
 bucket = aws_s3_bucket.terraform_state.id
 versioning_configuration {
 status = "Enabled"
 }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "default" {
 bucket = aws_s3_bucket.terraform_state.id
 rule {
 apply_server_side_encryption_by_default {
 sse_algorithm = "AES256"
 }
 }
}

resource "aws_s3_bucket_public_access_block" "public_access" {
 bucket = aws_s3_bucket.terraform_state.id
 block_public_acls = true
 block_public_policy = true
 ignore_public_acls = true
 restrict_public_buckets = true
}

resource "aws_dynamodb_table" "terraform_locks" {
 name = "homeserver-backup-locks" # 원하는 이름 지정
 billing_mode = "PAY_PER_REQUEST"
 hash_key = "LockID"
 attribute {
 name = "LockID"
 type = "S"
 }
}

벡엔드 저장소를 생성해준다:

1
2


terraform init
terraform apply

vaultwarden 데이터를 저장할 S3저장소와 SNS토픽, 자동화에 쓸 IAM계정을 생성한다.
main.tf

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124


terraform {
 backend "s3" {
 }
}

// S3 bucket
resource "aws_s3_bucket" "vaultwarden_backup" {
 bucket = var.backup_bucket_name

 tags = {
 Name = "vaultwarden-backup-bucket"
 }

}

resource "aws_s3_bucket_server_side_encryption_configuration" "backup_sse" {
 bucket = aws_s3_bucket.vaultwarden_backup.id
 rule {
 apply_server_side_encryption_by_default {
 sse_algorithm = "AES256"
 }
 }
}

resource "aws_s3_bucket_public_access_block" "vault_public_access" {
 bucket = aws_s3_bucket.vaultwarden_backup.id
 block_public_acls = true
 block_public_policy = true
 ignore_public_acls = true
 restrict_public_buckets = true
}

resource "aws_s3_bucket_lifecycle_configuration" "backup_lifecycle" {
 bucket = aws_s3_bucket.vaultwarden_backup.id

 rule {
 id = "move-to-glacier"
 status = "Enabled"

 filter {
 prefix = ""
 }

 transition {
 days = 2
 storage_class = "DEEP_ARCHIVE"
 }

 expiration {
 days = 180
 }
 }
}


// SNS
resource "aws_sns_topic" "email_notifications" {
 name = "noti-on-backup-failure-topic"
}

resource "aws_sns_topic_subscription" "admin_email_subscription" {
 topic_arn = aws_sns_topic.email_notifications.arn
 protocol = "email"
 endpoint = var.notification_email
}

// IAM user to backup
resource "aws_iam_user" "vw_backup_usr" {
 name = "vaultwarden-backup-usr"
 path = "/"

 tags = {
 Purpose = "backup"
 Service = "vaultwarden"
 ManagedBy = "terraform"
 }
}

data "aws_iam_policy_document" "vw_backup_min" {
 statement {
 sid = "S3ListBucketForPrefix"
 actions = ["s3:ListBucket", "s3:GetBucketLocation"]
 resources = [aws_s3_bucket.vaultwarden_backup.arn]

 condition {
 test = "StringLike"
 variable = "s3:prefix"
 values = ["*"]
 }
 }

 statement {
 sid = "S3ListBucketMultipartUploads"
 actions = ["s3:ListBucketMultipartUploads"]
 resources = [aws_s3_bucket.vaultwarden_backup.arn]
 }

 statement {
 sid = "S3ObjectCpOnly"
 actions = [
 "s3:GetObject",
 "s3:PutObject",
 "s3:AbortMultipartUpload",
 "s3:ListMultiPartUploadParts",
 ]
 resources = ["${aws_s3_bucket.vaultwarden_backup.arn}/*"]
 }

 statement {
 sid = "SnsPublishOnly"
 actions = ["sns:Publish"]
 resources = [aws_sns_topic.email_notifications.arn]
 }
}

resource "aws_iam_policy" "vw_backup_min" {
 name = "vw-backup-minimal"
 policy = data.aws_iam_policy_document.vw_backup_min.json
}

resource "aws_iam_user_policy_attachment" "vw_backup_attach" {
 user = aws_iam_user.vw_backup_usr.name
 policy_arn = aws_iam_policy.vw_backup_min.arn
}

적용하여 S3 + Dynamodb로 벡엔드를 관리하도록 리소스를 생성한다.

backend.tf(참고로, 위에랑 다르다. 변수화되어있는 것을 볼 수 있다.)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


provider "aws" {
 region = var.region
}

resource "aws_s3_bucket" "terraform_state" {
 bucket = var.state_bucket_name

 lifecycle {
 prevent_destroy = true
 }
}

resource "aws_s3_bucket_versioning" "enabled" {
 bucket = aws_s3_bucket.terraform_state.id
 versioning_configuration {
 status = "Enabled"
 }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "default" {
 bucket = aws_s3_bucket.terraform_state.id
 rule {
 apply_server_side_encryption_by_default {
 sse_algorithm = "AES256"
 }
 }
}

resource "aws_s3_bucket_public_access_block" "public_access" {
 bucket = aws_s3_bucket.terraform_state.id
 block_public_acls = true
 block_public_policy = true
 ignore_public_acls = true
 restrict_public_buckets = true
}

resource "aws_dynamodb_table" "terraform_locks" {
 name = var.state_dynamodb_table
 billing_mode = "PAY_PER_REQUEST"
 hash_key = "LockID"
 attribute {
 name = "LockID"
 type = "S"
 }
}

variables.tf

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


variable "region" {
 description = "AWS region"
 type = string
 default = "ap-northeast-2"
}

variable "state_bucket_name" {
 description = "S3 bucket for Terraform state"
 type = string
}

variable "state_dynamodb_table" {
 description = "DynamoDB table for state locking"
 type = string
}

variable "backup_bucket_name" {
 description = "S3 bucket for Vaultwarden backup"
 type = string
}

variable "notification_email" {
 description = "Email address for SNS notification"
 type = string
}

backend.hcl에 값을 넣어주자.

1
2
3
4
5


bucket = # 처음에 정한 상태 벡엔드 버킷명
key = # dynamodb lock을 위한 키
region = # ap-northeast-2
dynamodb_table = # 처음에 정한 table name
encrypt = # true

terraform.tfvars

1
2
3
4
5


region = # ap-northeast-2
state_bucket_name = # 처음에 정한 상태 벡엔드 버킷명
state_dynamodb_table = # 처음에 정한 table name
backup_bucket_name = # 백업버킷으로 할 이름
notification_email = # 알림받을 이메일주소

바뀐 벡엔드로 상태를 이전시키고, 다시 적용시킨다:

1
2


terraform init
terraform apply

백업 스크립트

vaultwarden의 데이터를 자동으로 업로드하도록 해보자.
아래는 vaultwarden컨테이너를 잠시 중단하고, 복사를 뜬 다음 다시 컨테이너를 실행시키고, 복사본을 압축하여 aws s3에 올리는 작업을 한다.
이후, 결과를 sns토픽에 발행한다.

최종적으로, 복사본 폴더와 압축파일을 정리한다.

이 스크립트를 cron에 등록해주었다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


#! /bin/bash

set -euo pipefail

BIN="/usr/local/bin"

BASE_DIR="/Users/<you>/vaultwarden-server"
BACKUP="vw-$(date +%F)"
S3_BUCKET="<s3 bucket>"
SNS_TOPIC="<sns topic arn>"

ZIPFILE="backup-${BACKUP}.tar.gz"


${BIN}/docker pause vaultwarden > /dev/null
tar -czf "${ZIPFILE}" -C "${BASE_DIR}" vw-data
${BIN}/docker unpause vaultwarden > /dev/null

if ${BIN}/aws s3 cp "${ZIPFILE}" "${S3_BUCKET}" --profile backup-manager > /dev/null; then
 ${BIN}/aws sns publish --topic-arn ${SNS_TOPIC} --message "Backup Success: ${ZIPFILE} at $(date)" --profile backup-manager
else
 ${BIN}/aws sns publish --topic-arn ${SNS_TOPIC} --message "Backup Failed: ${ZIPFILE} at $(date)" --profile backup-manager
 exit 1
fi

rm -f ${ZIPFILE}

스크립트에서 profile이 backup-manager인것을 알 수 있는데, 이 프로필을 쓰도록, 아까 Terraform으로 생성된 IAM계정에서 별도로 키를 발급받아서 아래와 같은 형식으로 추가해주면 된다:

1
2
3
4
5
6
7
8


# ~/.aws/config
[default]
region = ap-northeast-2
output = yaml

[profile backup-manager]
region = ap-northeast-2
output = yaml

1
2
3
4
5
6
7
8


# ~/.aws/credentials
[default]
aws_access_key_id = ******
aws_secret_access_key = *****

[backup-manager]
aws_access_key_id = *****
aws_secret_access_key = ******

SNS 가 보낼 이메일 대상에 이메일을 등록했으면, 확인 이메일이 와있을 것이다. 확인해주면 된다.

이제, 스크립트 실행 후 백업 결과가 이메일로 올 것이다!

gitignore

Terraform을 쓸 때는, 다음과 같은 파일들을 추적하지 않는 것이 좋다:

1
2
3
4
5
6


.terraform/
.DS_Store
*.tfstate
*.tfstate.backup
*tfvars
backend.hcl

🖥️ 모니터링

node_exporter를 이용한 서버 자원 수집

node_exporter는 노드의 메트릭을 수집하는 프로그램이다.
리눅스였다면 이것도 컨테이너로 띄워서 볼륨 마운트만 해주면 되지만, macOS에서는 컨테이너 대신 직접 데몬으로 띄우는 게 낫다.

아래 명령어로 설치하고 실행해주자

1
2


brew install node_exporter
brew services start node_exporter

Prometheus를 이용한 메트릭 수집

Prometheus는 주기적으로 각종 메트릭 데이터들을 수집해서 시계열 데이터베이스에 저장하고, Grafana등의 대시보드에서 이를 출력할 수 있다.
docker-compose.yaml의 services의 요소로 아래를 넣어주자:

1
2
3
4
5
6
7
8
9


 prometheus:
 container_name: prometheus
 image: "prom/prometheus@sha256:23031bfe0e74a13004252caaa74eccd0d62b6c6e7a04711d5b8bf5b7e113adc7" # prometheus 3.7.2 - linux/arm/v7
 restart: "always"
 volumes:
 - "./prometheus-data:/prometheus"
 - "./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml"
 ports:
 - "9090:9090"

그 뒤, prometheus/prometheus.yml에 다음을 작성한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


global:
 scrape_interval: "15s" # 15초에 한번씩
 scrape_timeout: "10s" # 타임아웃 10초
 evaluation_interval: "1m" # Alert나 recording규칙 평가 (지금은 쓰이지 않음)

scrape_configs: # 메트릭 수집 경로
 - job_name: "prometheus" # 자신
 static_configs:
 - targets:
 - prometheus:9090
 - job_name: "node_exporter" # node_exporter
 static_configs:
 - targets:
 - "host.docker.internal:9100" # 컨테이너 내부가 아닌, 호스트 데몬이므로 이렇게 접근
 - job_name: "loki" # loki
 metrics_path: "/metrics"
 static_configs:
 - targets: ["loki:3100"]

Promtail을 이용한 로그 포워딩

Promtail은 로그를 수집하여 로그 중앙 수집기로 보내는 역할을 한다.
docker-compose.yaml의 services에 아래와 같이 추가한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


 promtail:
 container_name: promtail
 image: "grafana/promtail@sha256:086e4e85d2eb383fb04ea83c0f5074da81df56e415062ca888dba426abd8dfa5" # promtail 3.5 - linux/arm/v7
 restart: "always"
 volumes:
 - "/var/log:/var/log:ro"
 - "/var/lib/docker/containers:/var/lib/docker/containers:ro"
 - "./promtail/promtail-config.yml:/etc/promtail/config.yml"
 - "./promtail-positions/:/var/lib/promtail"
 command: "--config.file=/etc/promtail/config.yml"

promtail/promtail-config.yml에 아래와 같이 적는다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


server: # listen port
 http_listen_port: 9080
 grpc_listen_port: 0

clients: # 수집된 데이터를 보낼 대상
 - url: http://loki:3100/loki/api/v1/push

positions:
 filename: "/var/lib/promtail/positions.yaml"

scrape_configs:
 - job_name: system # 시스템 로그 가져오기
 static_configs:
 - targets:
 - localhost
 labels:
 job: varlogs
 host: host
 __path__: /var/log/*.log
 - job_name: docker # docker 컨테이너들 로그 가져오기
 static_configs:
 - targets:
 - localhost
 labels:
 job: docker
 __path__: /var/lib/docker/containers/*/*.log

추가로, promtail-positions/positions.yaml을 생성해놔준다.
이는 책갈피 같은 역할을 하여, 이전까지 읽은 기록을 기반으로 컨테이너 재실행 시에도 추적할 수 있다.

1

touch promtail/positions.yaml`

Loki를 이용한 로그 중앙수집

Loki는 로그를 중앙수집해주는 역할을 한다.
docker-compose.yaml에서 services에 아래를 추가한다:

1
2
3
4
5
6
7
8
9


 loki:
 container_name: loki
 image: "grafana/loki@sha256:0eaee7bf39cc83aaef46914fb58f287d4f4c4be6ec96b86c2ed55719a75e49c8" # loki 3.5 - linux/arm/v7
 restart: "always"
 volumes:
 - "./loki-data:/loki"
 - "./loki/local-config.yaml:/etc/loki/local-config.yaml"
 ports:
 - "3100:3100"

loki/local-config.yaml을 생성하여 설정해준다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


auth_enabled: false # 프로덕션 환경에서는 비추천.

server:
 http_listen_port: 3100 # 3100포트로 Listen

common: # 단일 노드, 메모리 기반 메타데이터 저장 클러스터 세팅(공유안함)
 ring:
 instance_addr: localhost
 kvstore:
 store: inmemory
 replication_factor: 1
 path_prefix: /loki

schema_config: # 저장 스키마 및 인덱싱. 시계열 + 파일시스템 기반.
 configs:
 - from: 2020-05-15
 store: tsdb
 object_store: filesystem
 schema: v13
 index:
 prefix: index_
 period: 24h

storage_config: # 실제 로그 청크 저장소 설정
 filesystem:
 directory: /loki/chunks

Grafana Dashboard

Grafana는 여러 data sources로부터 대시보드를 꾸릴 수 있다.
docker-compose.yaml의 services에 아래를 추가하자:

1
2
3
4
5
6
7
8


 grafana:
 container_name: grafana
 image: "grafana/grafana@sha256:b882588a1b66697f1e444e798b15ecd810aba8ce430f98a3a4feecbab561a6b8" # grafana 12.3.0-18925857539 - linux/arm/v7
 restart: "always"
 volumes:
 - "./grafana-data:/var/lib/grafana"
 ports:
 - "3000:3000"

이제, 서버의 3000번 포트로 접속해보자:
최초 사용자 id와 비밀번호는 admin/admin이다.

Prometheus나 Loki등의 Data source를 가져올 수 있다.
같은 docker network에 속해있으므로, service:port 엔드포인트를 통해서 연결할 수 있다.

[Dashboards] - [New]를 통해서 새로운 대시보드를 만든다:

여기서는 기존에 이미 있는 탬플릿을 Import할것이다. ID에 아래의 숫자를 넣으면 된다:

1860: Node Exporter Full
노드의 컴퓨팅 자원 메트릭을 확인할 수 있다. 아쉽게도 맥에서는 완전한 지원이 안 되나 보다.
13639: Logs/App
로그 데이터를 볼 수 있다.
10880: Loki/Promtail
로그 수집 상태를 볼 수 있다.

🫥 gitignore

세부 데이터들은 추적하지 않는 것이 좋다

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


/caddy
/vw-data
/promtail-positions
/loki-data
/grafana-data
/prometheus-data
.env
/backup
autobackup.sh
rerollcert.sh

🚀 실행하기

아래의 셀 스크립트를 이용해서 mac이 잠자기 모드에 빠지지 않게 실행되도록 했다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


#!/bin/bash

set -euo pipefail

echo "☕️ Keeping the Mac awake..."
caffeinate -i -s &

CAFFEINATE_PID=$!

echo "🐳 Starting docker containers..."
docker compose up -d

docker compose ps
echo "🚀 Containers are up! Enjoy it!"
echo -e "To stop: \033[31mkill ${CAFFEINATE_PID} && docker compose down \033[0m"

🏁 향후 고려할 업그레이드 사항

클라우드 백업 이중화: 최근 AWS 버지니아 북부 장애사건으로, 멀티클라우드의 중요성이 대두되고 있는데, 더 긴 주기로 한번씩 다른 클라우드 오브젝트 스토리지에 저장하는 것도 괜찮을 듯 하다.
macOS에서의 node-exporter 지원이 시원찮아서 다른 대안을 이용해볼까 싶다.. 예를 들면 influxDB + telegraf..
AlertManager 추가
Grafana Dashboard를 추가로 직접 구성
로그 데이터를 클라우드로
또 무언가 생각나면 추가해볼 예정이다..

당장은 시간이 부족하거나, 필요성을 잘 못느끼겠는 이유로 하지 못한 것들인데, 추가로 더 하고싶긴 하다.

Repository

TailScale은 어떻게 동작하는가

Fri, 31 Oct 2025 12:51:26 +0900

TailScale은 WireGuard기반의 VPN서비스이다.
기존의 IPSec, OpenVPN과 같은 전통적인 VPN보다 더 빠른 성능을 제공한다.

🔒 Data Plane: WireGuard

Base Layer는 오픈소스 WireGuard패키지로 구성되어있고, Go 구현체를 사용한다.
WireGuard는 컴퓨터, VM, 컨테이너들(WireGuard에서는 “endpoint"라고 하고, TailScale에서는 “node"라고 부른다.)간의, 네트워크 밖의 다른 노드들과 경량의 암호화 터널을 만들어준다.

WireGuard는 기존 IPSec, OpenVPN보다 더 단순한 구조로 간단하면서, 강력하고, 성능이 좋다.
전통적인 VPN들이 수만 줄로 구현되어있는 반면, 약 4천 줄의 코드로 구현되어있다.
2017년 Jason A. Donefeld가 백서를 공개했다.
최신 암호 프리미티브들을 사용한다:

암호화: ChaCha20
메시지 인증: Poly1305
키 교환: Curve25519
해시: BLAKE2s
키 파생: HKDF

WireGuard 터널을 통해, IP패킷 전체를 암호화하여 UDP패킷의 페이로드에 담고, new IP Header를 만들어서 네트워크에 보낸다.

Hub and Spoke 네트워크

WireGuard를 세팅하는 가장 쉬운 방법은, 각 노드는 서로 Public Key, Public IP Address, Port Number를 모두 알아야 하기에, 10개의 노드를 연결하려면, 각각 9개의 Peer Node정보가 필요하다.

Hub-and-spoke 구조에서는, 하나의 중앙 허브 노드가 연결을 중개해주면 더 간단해진다. Hub 노드는 정적인 IP 주소를 가지고, 방화벽도 일부 관용되어있어 모두가 찾아 연결하기 쉽다.

그러나, 단점도 있다.
우선, 대부분의 회사들은 허브를 단일 지점으로 두고 싶어하지 않는다. 그들은 여러 지사를 가지고 있고, 여러 클라우드 데이터센터 리전/VPC를 가지고 있기 때문이다.
전통적인 VPN에서, 회사들은 단일 VPN 집중장치를 만들고, 각 지점들 간의 보조 터널을 생성한다.
그래서 VPN 집중장치에 접속해서, 최종 종착지로 통신한다.

이러한 전통적인 구성은 확장성이 떨어진다.
우선, 원격 사용자는 VPN 집중장치로부터 얼마나 거리가 되는 줄 모른다.
그들이 멀리 있다면, 긴 지연시간이 기다리고 있다.
또한, 데이터센터 역시 멀리 있다면 지연이 생긴다.
뉴욕에서 일하는 사람이 뉴욕에 있는 서버에 접근하려고 한다고 가정하자.
그러나 샌프란시스코에 있는 VPN 집중장치를 거쳐야 한다면, 곤욕일 것이다.

다행히도, WireGuard는 다르다.
Multi Hub를 두어서 경량의 터널을 몇 개씩 둘 수 있다.

이제 다음 과제는, 각 데이터센터는 각각 정적인 IP주소, 방화벽으로부터 열린 포트, WireGuard 키들의 집합이 필요하다는 것이다.
새로운 사용자가 추가되면, 이 다섯 서버들 모두에게 새로운 키를 주면 된다.
새로운 서버를 추가할 때, 각 유저들에게 서버의 배포 키를 하나씩 주면 된다.

Mesh Networks

이전에 Hub-and-spoke를 보았다.
WireGuard로 세팅하기 짜증날 수는 있어도, 어렵지는 않다.
그러나, hub-and-spoke로부터 근본적으로 어색한 점은 또 있다.
이 구조에서는 개별 노드들이 서로 통신할 수 없다.
옛날 사람들이라면 알겠지만, 꼭 중앙 기관을 거칠 필요없이 파일을 주고받던 시대가 있었다.
그리고, 그게 원래 인터넷의 근본이였다!
슬프게도, hub-and-spoke모델로 인터넷은 발달되었고, 그 중심에는 대형 클라우드 업체들이 자리잡아 임대료를 받고 있다.

모든 노드들끼리 서로 직접 연결되면 어떨까?
이를 메시 네트워크라고 한다.

P2P 애플리케이션을 만드는 데에 매우 이상적일 것이다.
10-노드 네트워크에는 $10 \times 9 = 90$개의 WireGuard 터널 엔드포인트 설정이 필요하다.

모든 노드는 자신의 키에 9개씩을 더 알아야 하고, 키를 새로 발급받거나 사용자의 추가 및 제거가 있을 시, 업데이트 작업이 복잡해진다.

그리고, 노드들은 서로를 찾을 수 있어야 한다.
고정 IP도 없고, 이동 시에 다시 연결할 필요가 있다.

카페, 호텔, 공항과 같이 방화벽이 있는 곳에서는 또 수신연결을 위한 포트를 열어줘야 하기도 한다.

그리고, 회사의 보안 및 컴플라이언스 요구사항이 있다면, 이제는 중앙 허브가 없으므로 각 노드 간의 트래픽을 감사(audit)하거나, 차단(block)하기 힘들어진다.
TailScale은 이런 복잡한 문제들을 해결해준다!

⚙️ Control Plane: 키 교환 및 코디네이션

모두가 정적인 IP를 가지고 있다고 가정하고, 방화벽이 없어서 포트 개방도 부담없다고 해보자.
어떻게 WireGuard 암호화 키를 관리하도록 할것인가?

오픈소스 TailScale 노드 소프트웨어를 제공한다.
코디네이션 서버라고 부른다. TailScale의 서비스의 경우, login.tailscale.com이다.
공개 키들에 대한 공유 박스라고 보면 된다.

다시 hub-and-spoke로 돌아온 거 아니냐는 의문이 생길 수 있다.
그러나, 좀 다르다. 트래픽을 중개하지 않기 때문이다.
그저 약간의 암호화 키 교환을 돕고 정책을 수립할 뿐, Data Plane은 메시로 이루어져있다.

각 노드들은 랜덤한 공개/비밀키 페어를 생성하고, 퍼블릭 키를 자격증명으로 연관짓는다.
노드는 코디네이션 서버에 접속하여 Public Key와 노드 자신의 인터넷 주소와 도메인을 알려준다.
노드는 코디네이션 서버로부터 공개키와 접속 정보들을 얻어서 다른 노드들들의 정보를 얻을 수 있다.
노드는 적절한 공개키를 이용하여 WireGuard연결을 맺는다.

Private Key는 노드 밖으로 절대 노출되는 일이 없음을 주목하자.
이 덕분에, 오직 두 노드만이 세션 안에서 패킷을 풀어볼 수 있다.
즉, TailScale 노드들은 종단간 암호화가 유지되어, 제로-트러스트 네트워킹을 실현한다.

로그인 및 2FA

어떻게 코디네이션 서버가 각 노드의 인증정보와 공캐기를 바인딩 할 수 있을까?
인증 결정에는 다양한 방법이 있다.
명백한 방법은 PSK(Pre-Shared Keys)라고 불리는 username+password의 시스템이다.
각 노드가 사용자 이름과 패스워드로 로그인해서, 공개키를 업로드하고 다른 공개키들과 접속 정보들을 다운로드하면 된다.
2FA(2-Factor Authentication)을 이용할 수도 있다.
SMS, Google Authenticator, Microsoft Authenticator등 다양한 방법이 있다.

시스템 관리자는 머신 인증서를 넣어주는 방법도 있다.
사용자 계정대신 기기에 영속적으로 남는 키이다.
맞는 사용자계정과 패스워드를 가지고 있는 악의적인 노드가 접속하지 못하게 막을 수 있다.

TailScale은 코디네이션 서버를 이러한 컨셉에 맞게 운영한다.
대신 인증 부분을 직접 운영하진 않고, OAuth2, OIDC(OpenID Connect), 또는 SAML제공자들을 통해서 운영하고 있다.

신원 제공자들은 도메인, 패스워드, 2FA세팅 등을 가지고 있다.
Google Docs, Office 365 등에서의 세팅을 해주면 된다. 비밀의 사용자계정과 로그인데이터가 다른 서비스에서 호스팅되기에, Tailscale은 중앙 코디네이션 서버를 신뢰성있고, 관리 복잡도를 최소화하며 운영할 수 있다.
이런 구조 덕분에, Tailscale 도메인은 로그인 즉시 바로 활성화된다.

클라이언트에서 설치에서 접속하게되면, 도메인 전용의 보안 키 교환함이 생겨서, 다른 기기들과 공개키를 교환할 수 있다.
그 이후, 노드가 서로의 공개키를 자동으로 내려받고, WireGuard 설정을 자동으로 구성해서, 노드 간의 P2P터널을 생성할 수 있다!

NAT Traversal

그러나, 여기서 끝이 아니다!
아까는 모든 노드가 정적 IP를 가지고 있고, 방화벽 포트도 열려 있는것으로 간주했다.
현실에서는, 카페에서도 써야 하고, 공항에서도 써야 한다. 집에서도 우린 와이파이를 쓰고, 야외에서는 셀룰러 네트워크를 쓸 수도 있다.
NAT와 방화벽이 둘러싸인 실제 환경에서는, 매우 골치아프다.

아래와 같은 상황일 것이다:

대부분의 방화벽은 “내가 보낸 UDP에 대한 트래픽만 허용"한다. 즉, 두 클라이언트가 서로 동시에 패킷을 보내면, 양쪽 방화벽은 동시에 응답 허용 상태가 되어 통신이 가능해진다!
이를 Simultaneous Transmission이라고 한다. 처음에 2.2.2.2가 7.7.7.7에게 보낸 트래픽은 닿지 않는다.
그러나, 응답을 받으려고 잠시 포트가 열려 있다. 두 방화벽은 서로 자신이 보낸 트래픽에 대한 응답인줄 알고 서로의 트래픽을 승인한다.

다음 문제는, NAT환경을 뚫는 것이다. NAT는 ip:port를 모두 바꿔버린다.
그래서, 자신의 Public ip:port를 알 수 없다.
이 문제를 해결해주는 것이 STUN이다.
STUN 서버로부터 자신의 퍼블릭 네트워크 주소를 알아낼 수 있다.

그러나, NAT는 너무 제각각이고, 수많은 장비들이 꼬여있을 수도 있다.
이를 ICE(Interactive Connectivity Establishment) 프로토콜이 해결해준다.
그 방법은 바로.. 모든 경우의 수를 시도하고, 최선을 찾는 것이다.

상대방과 통신하기위해, 로컬 소켓으로부터 후보 엔드포인트들을 모으기 시작한다.
후보는 ip:port의 꼴이다.

IPv6 ip:ports
IPv4 LAN ip:ports
STUN에 의해 알려진 IPv4 WAN ip:ports
포트 매핑 프로토콜에 의해 할당된 IPv4 WAN ip:ports
정적으로 설정된 엔드포인트들

그 뒤, 사이드 채널을 통해서 후보 리스트를 교환하고, 서로의 엔드포인트들에 probe를 보낸다.
이 패킷들은 두 개의 의무를 가진다.

방화벽과 NAT를 뚫기
헬스체킹 “ping"과 “pong"패킷을 교환하며, 서로의 경로가 유효한지 확인한다.

몇 가지 경우들이 통과된다면, 최고의 경로를 평가하여 해당 경로에 터널을 생성한다. 처음에는 LAN > WAN > WAN + NAT와 같은 고정된 순서를 고려했지만,
동적 점수화 방식으로 변경하여, 실제 RTT와 성공률을 기반으로 경로를 선택한다.
물론, 대부분 LAN > WAN > WAN + NAT의 순서로 되긴 한다.

터널이 생성되고 통신을 하는 와중에도, 주기적으로 헬스체크 및 프로브가 이루어진다.
더 좋게 평가된 경로가 발견된다면, 해당 경로로 업그레이드 될 수도 있다.

비대칭적인 통신 흐름은 다시 문을 막게 하는 원인이 될 수 있다. ICE는 경로가 닫히지 않도록, 즉, NAT나 방화벽의 stateful하고 일시적인 허용 정책을 유지시키기 위해 주기적으로 신호를 교환하도록 되어있다.

터널 Failover를 위해, warm state의 경로들을 일부 유지시킨다.
그 뒤, 기존 사용중이던 경로가 실패하면, 다운그레이드하여 사용한다.

즉, NAT Traversal의 구현에는 다음이 필요하다:

UDP 기반 프로토콜
프로그램에서 직접 소켓 접근
Control Plane(Peer간 주소 및 공개키 등을 교환할, 또는 DERP 폴백)
2개 이상의 STUN서버
릴레이 네트워크(DERP, TURN폴백용, optional)

그리고 다음의 절차를 가진다:

로컬 IP수집: 자신의 네트워크 인터페이스의 모든 IP주소들을 확인한다.
STUN요청: NAT로 변환된 주소를 보기 위해, ip:ports를 알아낸다. 동시에 NAT유형도 파악할 수 있다.
Port Mapping 프로토콜 시도하여 더 많은 WAN ip:ports를 제공받는다.
IPv6-only인경우, NAT64존재도 확인하여, STUN으로 NAT64주소도 알아낸다.
수집된 모든 후보군들을 상대와 교환
우선, 빠른 통신이 되도록 DERP와 같은 relay경로로 시작(optional)
가진 모든 엔드포인트 조합(ip:ports)로 Ping-Pong으로 프로빙한다.
최선의 경로를 찾아서, 선택한다.
현재 경로가 장애가 있을 시, 다운드레이드한다.

모든 통신은 e2e암호화가 되도록 보장해야 한다.

TailScale은 이를 제공한다.

더 자세한 부분에 대해서는, 여기를 참고.

DERP

일부 트래픽에서는 UDP가 아예 막힐 수도 있다.
TailScale에서는 DERP(Designated Encrypted Relay for Packets)서버를 제공하여 트래픽을 중개해준다.
ICE표준의 TURN서버와 같은 역할을 한다.
단, 구식의 TURN 방식이 아닌, HTTPS 스트림이나 WireGuard 키를 이용한다.

아래처럼 동작한다:

노드의 비밀키는 노드 혼자만 가지고 있기에, DERP서버는 데이터 내용을 열람할 수 없다.

많은사람들이 OpenVPN방식도 제공하냐고 궁금해하지만, WireGuard 자체의 기능으로는 없고, TailScale서버에서 추가적으로 제공하는 기능이다.

ACL과 보안 정책들

사람들은 VPN을 보안 소프트웨어라고 생각한다.
그리고, 충분히 그렇게 생각할만 하다. 인증과 암호기술이 들어가기 때문이다.
그러나, 실제로는 “연결성"에 더 집중한 것이 VPN의 근본이다.

기본 hub-and-spoke모델의 VPN제공자들은, 보안적 특성들도 붙여서 방화벽과 높은 응집도를 가진 제품들을 내놓았다.
그렇게 현재는 VPN에 보안정책들을 제공하는 것도 중요하다.
어떻게 메시 네트워크에서 보안 정책을 제공할까?
TailScale이 내놓은 정답은, 모든 각 노드에서 정책을 가지고 있으면 된다는 것이다.

이를 쉽게 하기 위해, 코디네이션 서버에서 정책들이 관리되도록 하고, 각 노드들에게 배포되게 하면 된다.

실제로는, 정책에 따라서 가져갈 수 있는 공개키가 규칙에 따라 일부 제한되는 방식으로 되어있다.
그래서, 노드는 허용된 공개키만 가져갈 수 있는 것이다.
이러한 방식은 프로토콜에 무관하기에, non-web 기반의 서비스들의 보안에 특히 더 좋다.

감사 로그

다른 걱정은, 감사에 대한 것일 것이다.
현대 방화벽들은 트래픽을 차단하지 않는다. 로깅까지 한다.
P2P로 통신하는데, 어떻게 로그를 남길까?

이 해답은, 각 노드에서 비동기적으로 중앙 수집기에 보내는 것이다.
또 하나의 부산물은, 통신은 전이중적이기에, 중복 로그가 잡힌다는 것이다.
이 덕분에, 로그 수정 공격이 힘들 것이다.
동시에 두 개의 로그를 변환해야 하기 때문이다.

실시간으로 스트림되기에, 윈도우는 매우 짧을 것이고, 탬퍼링 공격을 매우 힘들게 만들 것이다. TailScale은 중앙수집 서비스 역시 제공한다.

📚 References

Cilium Replace Kube Proxy

Thu, 30 Oct 2025 14:39:44 +0900

✅ Kube-Proxy를 대체했을 때의 장점

Cilium과 같은 CNI플러그인만이 컨테이너 네트워킹 설정을 하는 곳이 아니다.
kube-proxy 데몬셋은 Kubernetes의 서비스 모델에서의 중요한 부분을 맡는데, 리눅스 컨테이너의 네트워킹 스택과 상호작용을 한다.
kube-proxy는 iptables 규칙을 조작하여 service에서 Pod로 트래픽이 흐르도록 포워딩규칙을 조작한다.
Kube-proxy는 여러 iptables 규칙을 설치한다.
Service가 추가되면, iptables의 리스트는 지수적으로 증가한다!
이는 대규모 클러스터에서 성능 저하가 온다.

eBPF로, kube-proxy의 기능을 Cilium에서 대체하는 것이 가능하다.
iptables규칙의 빈번한 수정을 줄이고, 리소스 오버헤드를 줄여 클러스터의 스케일링에서의 속도를 더 빠르게 한다.

🍳 Kube-proxy의 기능

기본적으로, Cilium은 ClusterIP Service만 eBPF로 처리하지만, kube-proxy replacement를 켜면, NodePort, LoadBalancer, ExternalIP, HostPort 모두 전부 eBPF로 처리한다.

🚀 Kube-Proxy Replacement 활성화하기

helm upgrade로 kubeProxyReplacement 옵션을 켤 수 있다.

1
2
3
4
5
6
7
8


API_SERVER_IP=<your_api_server_ip>
API_sERVER_PORT=<your_api_server_port>
helm upgrade cilium cilium/cilium \
 -n kube-system \
 --reuse-values \
 --set kubeProxyReplacement=true \
 --set k8sServiceHost=API_SERVER_IP \
 -- set k8sServicePort=6443

또는, values.yaml에 아래와 같이 추가한다:

1
2
3
4


# values.yaml
kubeProxyReplacement: true
k8sServiceHost: "192.168.0.4" # API Server IP
k8sServicePort: 6443

그 뒤, 적용한다.

1
2
3


helm upgrade cilium cilium/cilium \
 -n kube-system
 -f values.yaml

이제, kube-proxy를 제거한다.

1
2
3
4
5


kubectl delete -n kube-system ds kube-proxy

16:56:42 in ~/cilium-lab/helm_install …
➜ kubectl delete -n kube-system ds kube-proxy
daemonset.apps "kube-proxy" deleted

🐣 처음부터 kube-proxy없는 클러스터 만들기

kube-proxy를 없애고 kind 클러스터를 만들려면, 아래와 같이 해주면 된다:

1
2
3
4
5
6
7
8
9


kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
- role: worker
- role: worker
networking:
 disableDefaultCNI: true
 kubeProxyMode: none

1

kind create cluster --config kind-no-kp-config.yaml

kubeadm에서 kube-proxy없는 클러스터를 만들려면, 아래와 같이 해주면 된다:

1

kubeadm init --skip-phases=addon/kube-proxy

👀 kube-proxy가 대체되었는지 확인하기

Cilium Agent에서 검증할 수 있다:

1
2
3
4
5
6
7


kubectl -n kube-system exec ds/cilium -- cilium status | grep KubeProxyReplacement

#####
17:10:34 in ~
➜ kubectl -n kube-system exec ds/cilium -- cilium status | grep KubeProxyReplacement
KubeProxyReplacement: True [enp6s0 192.168.0.10 fe80::3256:fff:fe01:8c89 (Direct Routing)]
#####

NodePort Service를 만들어서 잘 되는지 보는 방법도 있다.
아래의 yaml을 작성하자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


apiVersion: apps/v1
kind: Deployment
metadata:
 name: my-nginx
spec:
 selector:
 matchLabels:
 run: my-nginx
 replicas: 2
 template:
 metadata:
 labels:
 run: my-nginx
 spec:
 containers:
 - name: my-nginx
 image: nginx
 ports:
 - containerPort: 80

적용해주자.

1

kubectl apply -f my-nginx.yaml

Pod들이 띄워져있는지 확인한다:

1
2
3
4
5
6
7
8


kubectl get po -l run=my-nginx -o wide
#####
17:15:17 in ~/kube-practice …
➜ kubectl get po -l run=my-nginx -o wide
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
my-nginx-7d9b55c9f-8jwm7 1/1 Running 0 21s 10.0.1.154 worker1 <none> <none>
my-nginx-7d9b55c9f-wtl64 1/1 Running 0 21s 10.0.0.179 master <none> <none>
#####

NodePort Service를 만들어주자.

1

kubectl expose deploy my-nginx --type=NodePort --port=80

Service가 있는지 조회하자.

1
2
3
4
5
6
7
8


kubectl get svc my-nginx

#####
17:16:19 in ~/kube-practice …
➜ kubectl get svc my-nginx
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
my-nginx NodePort 10.102.47.19 <none> 80:31825/TCP 12s
#####

Cilium Client에서 service list라는 커맨드를 이용하면, Cilium의 eBPF가 kube-proxy를 대체하고 새로운 NodePort를 쓰고 있는 것을 볼 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


17:16:31 in ~/kube-practice …
➜ kubectl -n kube-system exec ds/cilium -- cilium service list
ID Frontend Service Type Backend
3 10.96.0.10:53/TCP ClusterIP 1 => 10.0.0.54:53/TCP (active)
 2 => 10.0.0.236:53/TCP (active)
4 10.96.0.10:53/UDP ClusterIP 1 => 10.0.0.54:53/UDP (active)
 2 => 10.0.0.236:53/UDP (active)
5 10.96.0.10:9153/TCP ClusterIP 1 => 10.0.0.54:9153/TCP (active)
 2 => 10.0.0.236:9153/TCP (active)
6 10.104.90.115:8080/TCP ClusterIP 1 => 10.0.1.161:8080/TCP (active)
7 10.96.0.1:443/TCP ClusterIP 1 => 192.168.0.4:6443/TCP (active)
9 10.98.77.75:8080/TCP ClusterIP 1 => 10.0.0.138:8080/TCP (active)
10 10.100.242.234:80/TCP ClusterIP 1 => 10.0.0.41:80/TCP (active)
 2 => 10.0.1.81:80/TCP (active)
11 10.100.44.200:443/TCP ClusterIP 1 => 192.168.0.10:4244/TCP (active)
14 10.99.76.169:3000/TCP ClusterIP 1 => 10.0.1.13:3000/TCP (active)
15 10.100.106.101:9090/TCP ClusterIP 1 => 10.0.1.139:9090/TCP (active)
16 10.109.184.54:80/TCP ClusterIP 1 => 10.0.1.225:4245/TCP (active)
17 10.103.253.41:80/TCP ClusterIP 1 => 10.0.1.110:8081/TCP (active)
18 0.0.0.0:30209/TCP NodePort 1 => 10.0.1.161:8080/TCP (active)
20 0.0.0.0:31872/TCP NodePort 1 => 10.0.0.138:8080/TCP (active)
22 0.0.0.0:31825/TCP NodePort 1 => 10.0.0.179:80/TCP (active)
 2 => 10.0.1.154:80/TCP (active)
24 10.102.47.19:80/TCP ClusterIP 1 => 10.0.0.179:80/TCP (active)

0.0.0.0:31825가 Pod IP:80으로 바인딩된 것을 볼 수 있다.
(어느 노드포트로 되었는지는 각자 다를 수 있다.)
또한, Curl로도 검증이 가능하다. Cilium Agent에 접속해보자.

1
2
3


kubectl -n kube-system exec -ti ds/cilium -- /bin/bash
apt upgrade
apt install curl -y

localhost:Nodeport로 요청을 날려보자. Pod로 잘 서비스가 되는 것을 볼 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


root@worker1:/home/cilium# curl localhost:31825
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

추가로, iptables의 사용이 없어야 한다.
Cilium Agent에서 이 명령을 해보자:

1

iptables-save | grep KUBE-SVC

아무 출력이 없어야 정상이다.

Cilium: Transparent Encryption

Wed, 22 Oct 2025 14:29:18 +0900

🍪 개요

Cilium은 IPSec와 WireGuard 트래픽 암호화를 모두 지원한다.
이번에는 네트워크 보안을 향상하기 위해 transparent encryption을 해볼 것이다.

🫥 Transparent Encryption이란?

클러스터 내부의 마이크로서비스는 클러스터 노드 사이를 통신한다.
그러나, 이 노드들의 네트워크 토폴로지가 분리되어있을 수도 있다.
클라우드 VPC나 자사 데이터센터의 Private Network에서도 물리적인 분리가 있을 수 있기에, 완전히 신뢰가능한 안전이 보장된다고 하기에는 어렵다.
이러한 노드들의 트래픽을 보호할 필요가 있고, 특히나 PCI(금융)나 HIPPA(의료) 규제 등을 위해서는 더욱 그렇다.
암호화를 요구하기 때문이다.
Transparent Encryption은 이러한 요구사항을 만족한다.

Kubernetes 자체의 네이티브 기능으로는 데이터 암호화가 없다.
클러스터 관리자가 구현에 대해 결정하는 문제이다.
Cilium은 노드 간 암호화를 WireGuard 또는 IPSec를 이용하여 지원하고, 애플리케이션 코드의 수정은 하나도 필요없다.
(그래서 투명한 암호화라 하는것이다. 애플리케이션 계층은 암호화가 일어나는지도 모르니 말이다.)

여기서는 WireGuard기반의 통신 암호화를 이용한다.

🔒 WireGuard 또는 IPSec를 쓰는 이유

WireGuard와 IPSec는 in-kernel의 투명한 트래픽 암호화를 제공하는 프로토콜이다.
WireGaurd는 사용하기 쉽고, 경량의 VPN(Virtual Private Network)이고, 리눅스 커널 내부에서 제공된다.
WireGuard는 Peer-to-Peer기반의 VPN 솔루션이다.
VPN이 각 컴퓨터간 연결되고, 서로 공개 키를 공유한다.
더 자세한 내용은 이 게시글에서 확인가능하다.

IPSec는 비슷하지만, 더 전통적이고, FIPS(미국 연방 정보 처리 표준)을 준수한다.
WireGuard나 IPSec가 Cilium에서 활성화되면, 각 노드의 CIlium Agent는 클러스터 내 Cilium 노드들 간의 암호화 터널을 생성한다.

🤓 Transparent Encryption 활성화하기

helm upgrade를 통해서 암호화를 활성화한다

1
2
3


helm upgrade cilium cilium/cilium --namespace kube-system \
 --set encryption.enabled=true \
 --set encryption.type=wireguard

파일로 하길 원한다면, 아래를 values에 추가하여 적용해주면 된다.

1
2
3
4


# Encryption
encryption:
 enabled: true
 type: wireguard

1

helm upgrade cilium cilium/cilium -n kube-system -f values.yaml

daemonest을 롤아웃 해주고, 다시 켜지기까지 기다려보자:

1
2
3


kubectl rollout restart ds/cilium -n kube-system

cilium status --wait

🏋 실습

이전 실습의 상태에서 계속한다.

상황

베이더는 반역자 스파이들이 임페리얼 쿠버네티스 클러스터 내부에서 네트워크 통신을 감청하고 있을지 모른다는 걱정을 하고 있다.

플랫폼 팀은 노드간 통신을 암호화 하는것을 목표로 한다.
다행히도, 당신의 팀은 이미 Cilium을 쓰고 있다.
노드 간 통신의 투명한 암호화를 쉽게 적용할 수 있다.

투명 암호화 활성화하기

아직 활성화가 안되어있다면, 위를 참고하여, Transparent Encryption을 활성화하자.
Cilium Pod들이 재시작되면, CiliumNode라는 커스텀 리소스를 업데이트한다.
CiliumNode는 Cilium에 의해 관리되는 노드를 말한다.

1
2
3
4
5
6
7
8
9


kubectl get -n kube-system CiliumNodes

########################################################
15:35:23 in ~/kube-practice …
➜ kubectl get -n kube-system CiliumNodes
NAME CILIUMINTERNALIP INTERNALIP AGE
master 10.0.0.115 192.168.0.4 17d
worker1 10.0.1.242 192.168.0.10 17d
#########################################################

노드에 public key가 생긴 것을 볼 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# worker1 대신 본인의 노드를 넣자. 
kubectl get -n kube-system CiliumNode worker1 -o json | jq .metadata.annotations

##################################################################
15:45:30 in ~/kube-practice …
➜ kubectl get -n kube-system CiliumNode worker1 -o json | jq .metadata.annotations
{
 "network.cilium.io/wg-pub-key": "u2i7vxpbamnGhg/C1DetSl6pTK2APvx8uWPCdxGlfXM="
}
##################################################################

암호화 인터페이스 검사하기

Cilium Agent Client를 이용하여 Agent가 암호화를 활성화했는지 볼 수 있다.

1
2
3
4
5
6
7


kubectl exec -n kube-system -ti ds/cilium -- cilium status | grep Encryption

#####
15:48:16 in ~/kube-practice …
➜ kubectl exec -n kube-system -ti ds/cilium -- cilium status | grep Encryption
Encryption: Wireguard [NodeEncryption: Disabled, cilium_wg0 (Pubkey: u2i7vxpbamnGhg/C1DetSl6pTK2APvx8uWPCdxGlfXM=, Port: 51871, Peers: 1)]
#####

이 Agent는 WIreGuard가 활성화되어있으며, Peer의 개수도 보인다.
현재 여기서는 2노드 구성이라 1개의 Peer가 있다고 보인다.
3노드 구성이면 2개의 Peer가, n노드 구성이면 n-1개의 Peer가 있다고 보면 된다.

노드의 네트워크 장치를 확인해보자. cilium_wg0이라는 새로운 디바이스를 볼 수 있다.
(Cilium Agent는 호스트 네트워크 모드를 쓴다)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


kubectl exec -n kube-system -ti ds/cilium -- ip link | grep cilium

#####
15:53:11 in ~/kube-practice …
➜ kubectl exec -n kube-system -ti ds/cilium -- ip link | grep cilium
3: cilium_net@cilium_host: <BROADCAST,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default
4: cilium_host@cilium_net: <BROADCAST,MULTICAST,NOARP,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT group default qlen 1000
5: cilium_vxlan: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UNKNOWN mode DEFAULT group default
78: cilium_wg0: <POINTOPOINT,NOARP,UP,LOWER_UP> mtu 1420 qdisc noqueue state UNKNOWN mode DEFAULT group default

#####

새로운 WireGuard 링크가 다른 노드와의 통신에 쓰이는 것을 확인해보자.
Agent의 bash쉘을 열어주자.

1

kubectl exec -n kube-system -ti po/cilium-kw52z -- /bin/bash

tcpdump를 설치하자.

1
2


apt-get update
apt-get -y install tcpdump

설치가 되면, cilium_wg0으로 패킷을 캡처해보자.

1

tcpdump -n -i cilium_wg0

같은 노드에서 돌아가는 것을 사용할 것이므로, 노드에서 돌아가는 tiefighter를 찾아보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


kubectl describe node worker1

...
Non-terminated Pods: (14 in total)
 Namespace Name CPU Requests CPU Limits Memory Requests Memory Limits Age
 --------- ---- ------------ ---------- --------------- ------------- ---
 cilium-monitoring grafana-5c9877b8cd-pdnwh 0 (0%) 0 (0%) 0 (0%) 0 (0%) 92m
 cilium-monitoring prometheus-bf7c454c-wtmrs 0 (0%) 0 (0%) 0 (0%) 0 (0%) 92m
 cilium-test-1 client-64d966fcbd-9vpvf 0 (0%) 0 (0%) 0 (0%) 0 (0%) 17d
 cilium-test-1 client2-5f6d9498c7-hzv2q 0 (0%) 0 (0%) 0 (0%) 0 (0%) 17d
 cilium-test-1 echo-same-node-6868c899c7-vp722 0 (0%) 0 (0%) 0 (0%) 0 (0%) 17d
 cilium-test-1 host-netns-nfqbl 0 (0%) 0 (0%) 0 (0%) 0 (0%) 17d
 default deathstar-74c8f5ff5c-rp7rx 0 (0%) 0 (0%) 0 (0%) 0 (0%) 12d
 default test 100m (0%) 200m (0%) 200Mi (0%) 500Mi (0%) 8d
 default tiefighter 0 (0%) 0 (0%) 0 (0%) 0 (0%) 12d
 default xwing 0 (0%) 0 (0%) 0 (0%) 0 (0%) 12d
 kube-system cilium-envoy-7qzk6 0 (0%) 0 (0%) 0 (0%) 0 (0%) 8d
 kube-system cilium-kw52z 100m (0%) 0 (0%) 10Mi (0%) 0 (0%) 29m
 kube-system cilium-operator-79d9c74856-r8f8f 0 (0%) 0 (0%) 0 (0%) 0 (0%) 29m
 kube-system kube-proxy-2kjpc 0 (0%) 0 (0%) 0 (0%) 0 (0%) 17d

착륙 요청을 몇 번 해보자.

1

kubectl exec tiefighter -- curl -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing

아래는 실체 캡처이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73


root@worker1:/home/cilium# tcpdump -n -i cilium_wg0
tcpdump: verbose output suppressed, use -v[v]... for full protocol decode
listening on cilium_wg0, link-type RAW (Raw IP), snapshot length 262144 bytes
07:05:59.518821 IP 192.168.0.10.43111 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.50644 > 10.0.0.236.53: 53090+ A? deathstar.default.svc.cluster.local.default.svc.cluster.local. (79)
07:05:59.518831 IP 192.168.0.10.43111 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.50644 > 10.0.0.236.53: 53348+ AAAA? deathstar.default.svc.cluster.local.default.svc.cluster.local. (79)
07:05:59.520362 IP 192.168.0.4.39105 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 54165
IP 10.0.0.236.53 > 10.0.1.65.50644: 53348 NXDomain*- 0/1/0 (172)
07:05:59.520395 IP 192.168.0.4.39105 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 54165
IP 10.0.0.236.53 > 10.0.1.65.50644: 53090 NXDomain*- 0/1/0 (172)
07:05:59.520459 IP 192.168.0.10.40573 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.36559 > 10.0.0.54.53: 736+ A? deathstar.default.svc.cluster.local.svc.cluster.local. (71)
07:05:59.520465 IP 192.168.0.10.40573 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.36559 > 10.0.0.54.53: 60926+ AAAA? deathstar.default.svc.cluster.local.svc.cluster.local. (71)
07:05:59.521630 IP 192.168.0.4.46335 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 54165
IP 10.0.0.54.53 > 10.0.1.65.36559: 60926 NXDomain*- 0/1/0 (164)
07:05:59.521657 IP 192.168.0.4.46335 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 54165
IP 10.0.0.54.53 > 10.0.1.65.36559: 736 NXDomain*- 0/1/0 (164)
07:05:59.521680 IP 192.168.0.10.48073 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.58437 > 10.0.0.236.53: 11665+ A? deathstar.default.svc.cluster.local.cluster.local. (67)
07:05:59.521684 IP 192.168.0.10.48073 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.58437 > 10.0.0.236.53: 22672+ AAAA? deathstar.default.svc.cluster.local.cluster.local. (67)
07:05:59.523037 IP 192.168.0.4.45455 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 54165
IP 10.0.0.236.53 > 10.0.1.65.58437: 22672 NXDomain*- 0/1/0 (160)
07:05:59.523150 IP 192.168.0.4.45455 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 54165
IP 10.0.0.236.53 > 10.0.1.65.58437: 11665 NXDomain*- 0/1/0 (160)
07:05:59.523174 IP 192.168.0.10.44086 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.53147 > 10.0.0.54.53: 31723+ A? deathstar.default.svc.cluster.local. (53)
07:05:59.523177 IP 192.168.0.10.44086 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.53147 > 10.0.0.54.53: 20628+ AAAA? deathstar.default.svc.cluster.local. (53)
07:05:59.524483 IP 192.168.0.4.43299 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 54165
IP 10.0.0.54.53 > 10.0.1.65.53147: 20628*- 0/1/0 (146)
07:05:59.524675 IP 192.168.0.4.43299 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 54165
IP 10.0.0.54.53 > 10.0.1.65.53147: 31723*- 1/0/0 A 10.100.242.234 (104)
07:05:59.524811 IP 192.168.0.10.36177 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.44882 > 10.0.0.41.80: Flags [S], seq 3572931691, win 65170, options [mss 1330,sackOK,TS val 2392963435 ecr 0,nop,wscale 7], length 0
07:05:59.525522 IP 192.168.0.4.54866 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 53764
IP 10.0.0.41.80 > 10.0.1.65.44882: Flags [S.], seq 427175017, ack 3572931692, win 64582, options [mss 1330,sackOK,TS val 1346063423 ecr 2392963435,nop,wscale 7], length 0
07:05:59.525558 IP 192.168.0.10.36177 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.44882 > 10.0.0.41.80: Flags [.], ack 1, win 510, options [nop,nop,TS val 2392963435 ecr 1346063423], length 0
07:05:59.525572 IP 192.168.0.10.36177 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.44882 > 10.0.0.41.80: Flags [P.], seq 1:119, ack 1, win 510, options [nop,nop,TS val 2392963435 ecr 1346063423], length 118: HTTP: POST /v1/request-landing HTTP/1.1
07:05:59.526735 IP 192.168.0.4.54866 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 53764
IP 10.0.0.41.80 > 10.0.1.65.44882: Flags [.], ack 119, win 504, options [nop,nop,TS val 1346063424 ecr 2392963435], length 0
07:05:59.530260 IP 192.168.0.4.54866 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 53764
IP 10.0.0.41.80 > 10.0.1.65.44882: Flags [P.], seq 1:164, ack 119, win 504, options [nop,nop,TS val 1346063427 ecr 2392963435], length 163: HTTP: HTTP/1.1 200 OK
07:05:59.530276 IP 192.168.0.10.36177 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.44882 > 10.0.0.41.80: Flags [.], ack 164, win 509, options [nop,nop,TS val 2392963440 ecr 1346063427], length 0
07:05:59.530335 IP 192.168.0.10.36177 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.44882 > 10.0.0.41.80: Flags [F.], seq 119, ack 164, win 509, options [nop,nop,TS val 2392963440 ecr 1346063427], length 0
07:05:59.531423 IP 192.168.0.4.54866 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 53764
IP 10.0.0.41.80 > 10.0.1.65.44882: Flags [F.], seq 164, ack 120, win 504, options [nop,nop,TS val 1346063429 ecr 2392963440], length 0
07:05:59.531442 IP 192.168.0.10.36177 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 5951
IP 10.0.1.65.44882 > 10.0.0.41.80: Flags [.], ack 165, win 509, options [nop,nop,TS val 2392963441 ecr 1346063429], length 0
07:06:00.509943 IP 192.168.0.10.35854 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 6
IP 10.0.1.242.35328 > 10.0.0.70.4240: Flags [S], seq 2866463020, win 65170, options [mss 1330,sackOK,TS val 733236680 ecr 0,nop,wscale 7], length 0
07:06:00.509969 IP 192.168.0.10.46438 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 6
IP 10.0.1.242 > 10.0.0.70: ICMP echo request, id 65139, seq 0, length 32
07:06:00.511058 IP 192.168.0.4.49247 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 4
IP 10.0.0.70.4240 > 10.0.1.242.35328: Flags [S.], seq 690249742, ack 2866463021, win 64582, options [mss 1330,sackOK,TS val 1259062935 ecr 733236680,nop,wscale 7], length 0
07:06:00.511058 IP 192.168.0.4.42590 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 4
IP 10.0.0.70 > 10.0.1.242: ICMP echo reply, id 65139, seq 0, length 32
07:06:00.511161 IP 192.168.0.10.35854 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 6
IP 10.0.1.242.35328 > 10.0.0.70.4240: Flags [.], ack 1, win 510, options [nop,nop,TS val 733236681 ecr 1259062935], length 0
07:06:00.511222 IP 192.168.0.10.35854 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 6
IP 10.0.1.242.35328 > 10.0.0.70.4240: Flags [P.], seq 1:101, ack 1, win 510, options [nop,nop,TS val 733236681 ecr 1259062935], length 100
07:06:00.512025 IP 192.168.0.4.49247 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 4
IP 10.0.0.70.4240 > 10.0.1.242.35328: Flags [.], ack 101, win 504, options [nop,nop,TS val 1259062936 ecr 733236681], length 0
07:06:00.512521 IP 192.168.0.4.49247 > 192.168.0.10.8472: OTV, flags [I] (0x08), overlay 0, instance 4
IP 10.0.0.70.4240 > 10.0.1.242.35328: Flags [P.], seq 1:76, ack 101, win 504, options [nop,nop,TS val 1259062937 ecr 733236681], length 75
07:06:00.512586 IP 192.168.0.10.35854 > 192.168.0.4.8472: OTV, flags [I] (0x08), overlay 0, instance 6
IP 10.0.1.242.35328 > 10.0.0.70.4240: Flags [.], ack 76, win 510, options [nop,nop,TS val 733236682 ecr 1259062937], length 0

참고로, DNS통신도 WireGuard에 의해 암호화될 수 있다. CoreDNS가 타 노드에 있는 경우이다.
오해가 있을 수 있는데, 여기서는 암호화된 데이터가 보이진 않는다. 대신, 나가는 데이터의 암호화 직전, 또는 오는 트래픽의 복호화 이후를 본 것 뿐이다.

암호화된 데이터는 실제로 나가는 데이터인 eth0에 실려있다.
다시 착륙요청을 여러 번 해보자. 이렇게 보이는 UDP 트래픽이 WireGuard 트래픽인 것으로 보인다.
WireGuard는 IP패킷을 암호화한 뒤, 새로운 UDP패킷의 페이로드에 담아서 보낸다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


tcpdump -n -i enp6s0
...
07:19:01.969043 IP 192.168.0.10.51871 > 192.168.0.4.51871: UDP, length 192
07:19:01.969050 IP 192.168.0.10.51871 > 192.168.0.4.51871: UDP, length 192
07:19:01.970441 IP 192.168.0.4.51871 > 192.168.0.10.51871: UDP, length 288
07:19:01.970476 IP 192.168.0.4.51871 > 192.168.0.10.51871: UDP, length 288
07:19:01.970610 IP 192.168.0.10.51871 > 192.168.0.4.51871: UDP, length 192
07:19:01.970613 IP 192.168.0.10.51871 > 192.168.0.4.51871: UDP, length 192
07:19:01.971858 IP 192.168.0.4.51871 > 192.168.0.10.51871: UDP, length 288
07:19:01.971885 IP 192.168.0.4.51871 > 192.168.0.10.51871: UDP, length 288
07:19:01.971945 IP 192.168.0.10.51871 > 192.168.0.4.51871: UDP, length 192
07:19:01.971948 IP 192.168.0.10.51871 > 192.168.0.4.51871: UDP, length 192
07:19:01.973390 IP 192.168.0.4.51871 > 192.168.0.10.51871: UDP, length 272
07:19:01.973417 IP 192.168.0.4.51871 > 192.168.0.10.51871: UDP, length 272
07:19:01.973477 IP 192.168.0.10.51871 > 192.168.0.4.51871: UDP, length 176
07:19:01.973485 IP 192.168.0.10.51871 > 192.168.0.4.51871: UDP, length 176
07:19:01.974599 IP 192.168.0.4.51871 > 192.168.0.10.51871: UDP, length 224
07:19:01.974704 IP 192.168.0.4.51871 > 192.168.0.10.51871: UDP, length 256
...

–

📚 마무리

Cilium의 투명 암호화가 켜지면, 노드간의 트래픽 WireGuard/IPSec에 의해 보호된다.
또한, 애플리케이션 개발자들이 암호화에 대한 신경을 쓸 이유는 하나도 없다.

Cilium: Prometheus metrics

Thu, 16 Oct 2025 14:18:00 +0900

🌡️ Cilium Operator Metrics

Cilium Operator의 Prometheus 메트릭은 Helm Chart옵션으로 활성화될 수 있으며, 주로 오퍼레이터 성능 저하를 진단하거나 경고를 발생시키는 데 필요한 가시성을 제공하는데 사용된다.
오퍼레이터 메트릭을 활성화하는 것은 Cilium의 설치 과정의 일부로 진행된다.
오퍼레이터 Pod에는 Prometheus 엔드포인트 자동 발견을 돕는 어노테이션이 추가된다.

오퍼레이터 메트릭에는 Cilium 오퍼레이터의 상태와 관련된 정보가 포함되며, 모든 메트릭은 cilium_operator_ 접두사로 시작한다.

🎯 Cilium Agent Metrics

Cilium Agent의 메트릭은 더 운영적인 면을 가지고 있다.
메트릭이 활성화 되어있다면, Prometheus 엔드포인트 자동 발견을 돕는 어노테이션이 추가되어있다.

또한, 각 에이전트의 내장 Envoy 프록시에 연결된 Prometheus 메트릭 엔드포인트를 가리키는 Headless cilium-agent service가 정의된다.
Pod가 단일 Prometheus 엔드포인트에 대해서만 어노태이션을 가질 수 있기 때문이다.
헤드리스 서비스는 파드 내의 추가적인 메트릭 엔드포인트를 Prometheus scraper가 DNS요청을 통해 발견할 수 있도록 해준다.

다름과 같은 메트릭을 제공한다:

Cluster Health
도달불가능한 노드 및 에이전트 상태 엔드포인트 관련 통계
Node Connectivity
네트워크 전체 노드 간 지연 관련 통계
Cluster Mesh
피어 클러스터 관련 통계
Datapath
커넥션 트래킹의 가비지 컬렉션 관련 통계
IPSec
IPSec 오류 관련 통계
eBPF
eVPF맵 연산 및 메모리 사용 관련 통계
Drop/Forward(L3/L4)
패킷 드롭/포워드 관련 통계
Policy
활성 정책 관련 통계
L7 Policy
내장 HTTP 프록시로의 L7 정책 리다이렉트 관련 통계
Identity
Identity ↔ IP주소 매칭 관련 통계
Kubernetes
수신된 Kubernetes 이벤트 관련 통계
IPAM
IP주소 할당 통계

🔭 Hubble Metrics

Hubble Metrics는 네트워크 플로우의 정보들 위주로 제공된다.

DNS
DNS 요청 통계
Drop
패킷 드롭관련 통계
Flow
총 플로우 처리량 통계
HTTP
HTTP 요청 관련 통계
TCP
TCP관련 통계
ICMP
ICMP요청 관련 통계
Port Distribution
목적지 포트 관련 통계

Hubble metrics가 활성화된다면, hubble-metrics라는 이름의 어노테이션된 헤드리스 서비스가 있다.
Hubble metrics가 기본적으로 활성화되지는 않기에, 필요한 메트릭을 명시적으로 요구해야 한다.
이때 flow context가 Prometheus 라벨에 매핑되며, 이를 통해 원하는 수준의 세밀한 관찰도 가능하다.

Hubble Metrics 컨텍스트 옵션

플로우는 너무 풍부하기에, 모든 메트릭을 매핑할순 없다.
따라서, 어떤 플로우 정보를 label로 포함할지 선택해야 한다.
또한, Hubble 메트릭은 Source와 Destination label을 설정할 수 있는 기능을 제공하며, 이를 통해 플로우 컨텍스트 중 가장 잘 표현할 수 있는 속성을 Label에 매핑할 수 있다.

이때 sourceContext와 destinationContext 옵션을 지원하는 플로우 속성 중 하나로 지정하면 된다.
예를 들어,

hubble_drop_total 메트릭의 source label을 Pod이름과 함께 매핑하고 싶다면, sourceContext=pod-name으로 하면 된다.
source label을 IP주소로 하고싶다면, sourceContext=ip로 하면 된다.

이처럼 source/destination label을 일관되게 지정해두면, 해당 label을 기반으로 대시보드를 구성하거나 Prometheus 쿼리 언어를 활용할 수 있다.
추가적으로, 더 많은 카디날리티가 필요하다면, labelContext 옵션을 통해 플로우 정보에서 가져온 추가 label을 메트릭에 포함하도록 설정할 수도 있다.

🍒 Prometheus 서버 준비하기

각 메트릭 엔드포인트는 두 가지의 어느테이션을 가진다:

prometheus.io/port
prometheus.io.scrape

클러스터에서 돌아가는 Prometheus server의 스크레이프 설정은 이러한 어노테이션을 가진 Pod와 headless service들을 찾아 메트릭을 수집하도록 구성할 수 있다.

⚙️ Cilium Helm Chart Options

Cilium을 더 자세하게 구성하고 싶다면, Helm Chart를 써야 한다고 했었다.
Chart Options은 다음과 같다:

Enabling Cilium Operator Metrics
- operator.prometheus.port: operator tcp port값. 기본 9962
- operator.prometheus.enabled: true/false, 기본 false
Enabling Cilium Agent Metrics
- prometheus.proxy.port: proxy metrics tcp port값. 기본 9964
- prometheus.port: agemtn metrics tcp port값. 9962
- prometheus.metrics: Cilium Agent metrics이 활성화/비활성화할 띄어쓰기로 구분되는 문자열
  Ex: “-cilium_node_connectivity_status + cilium_bpf_map_pressure”
- prometheus.enabled: true/false, 기본 false
Enabling Hubble Metrics
- hubble.metrics.enableOpenMetrics - true/false, 기본 false
- hubble.metrics.port: Hubble metrics tcp port값. 기본 9965
- hubble.metrics.enabled: 활성화할 메트릭, 콤마로 구분됨. 적어도 하나의 메트릭이 활성화되어야 함
  Ex: “{first-metric: metric-option1; metric-option2, second-metric, third-metric}”
- prometheus.enabled: true/false, 기본 false

💨 실습: Cilium Metrics

상황

팀의 SRE들은 임페리얼 갤러틱 쿠버네티스 서비스에서의 중요한 서비스들의 더 나은 성능 메트릭을 접근하길 원한다.
예를 들어, 특정 소스/데스티네이션 마이크로서비스간의 성능저하 이슈에 대해 경보를 받고싶어한다.

모든 TIE 파이터들이 동등하지 않고, 베이더의 착륙 요청이 다른 클러스터 네트워크 트래픽들 대비 더 타이트한 SLO 버짓 이내로 오면 모두에게 이익이 온다.
네트워크 플로우 컨텍스트에서 파생된 label들을 Hubble Prometheus 메트릭에 붙이면, 팀원들에게 더 풍부한 메트릭 기반 솔루션을 제공할 수 있다.

세팅하기

Helm기반의 Cilium설치를 할것이다.
기존 Cilium을 제거하려면, 다음을 실행한다:

1

cilium uninstall

kind를 쓴다면, 아래의 일반적인 Helm 인스트럭션을 쓸 수 있다.

1

helm install cilium/cilium --version 1.16.3 --namespace kube-system

바닐라 쿠버네티스 기준, 다음의 셋업으로 하면 된다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


# values.yaml
kubeProxyReplacement: false
k8sServiceHost: ""
k8sServicePort: ""

# Cilium Agent metrics
prometheus:
 enabled: true
 port: 9966
 metrics:
 - cilium_bpf_map_pressure
 - cilium_drop_totalcilium_forward_total
 - cilium_forward_total

# Operator metrics
operator:
 replicas: 1
 prometheus:
 enabled: true
 port: 9963

# Hubble
hubble:
 enabled: true
 relay:
 enabled: true
 ui:
 enabled: true
 metrics:
 enabledOpenMetrics: true
 port: 9965
 enabled:
 - dns
 - drop:sourceContext=pod;destinationContext=pod
 - tcp
 - flow
 - port-distribution
 - httpV2
 - policy

# IPAM
ipam:
 mode: cluster-pool # kubectl 무시
 operator:
 clusterPoolIPv4PodCIDRList: ["10.43.0.0/16"] # 클러스터 전체 CIDR. kubeadm과 똑같이 하는 것이 혼동이 적음
 clusterPoolIpv4MaskSize: 24 # Node단위 서브넷 CIDR
 clusterPoolIPv6PodCIDRList: ["fd00::/104"] # default
 clusterPoolIPv6MaskSize: 120 # default

# Masquerade(NAT)
enableIpv4Masquerade: true
enableIpv6Masquerade: false

# NetworkPolicy
enableNetworkPolicy: true

이 values.yaml을 적용해주자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


helm repo add cilium https://helm.cilium.io/
helm repo update

# 첫 설치:
helm install cilium cilium/cilium \
 -n kube-system -f values.yaml

# 이미 helm으로 설치했다면:
helm upgrade cilium cilium/cilium \
 -n kube-system -f values.yaml

이전 네트워크 정책들은 초기화해주자:

1

kubectl delete --all CiliumNetworkPolicies

Death Star API를 다시 설치해주자:

1

kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/refs/heads/main/examples/minikube/http-sw-app.yaml

간단한 CiliumNetworkPolicy 룰을 임페리얼 유닛에 적용한다:

1

kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/refs/heads/main/examples/minikube/sw_l3_l4_l7_policy.yaml

Cilium Metrics 수집 허용하기

혹시라도 메트릭 허용이 켜져있지 않다면, helm의 --set으로 넣어주자.

1
2
3
4
5


helm upgrade cilium cilium/cilium \
 --namespace -kube-system \
 --reuse-values \
 --set prometheus.enabled=true \
 --set operator.prometheus.enabled = true

cilium의 daemonset pod에서 어노테이션을 확인해주자. 본인의 데몬셋 포드에서 골라야 한다.

1
2
3
4
5
6
7


kubectl get -n kube-system pod/cilium-n6vzs -o json | jq .metadata.annotations
{
 "kubectl.kubernetes.io/default-container": "cilium-agent",
 "kubectl.kubernetes.io/restartedAt": "2025-10-01T17:05:21+09:00",
 "prometheus.io/port": "9966",
 "prometheus.io/scrape": "true"
}

cilium-n6vzs Pod를 골랐는데, 이는 deathstar-74c8f5ff5c-rp7rx가 같은 노드에 있기 때문이다.
Cilium Pod와 deathstar를 같은 노드에서 고르면, Cilium과 Hubble metrics가 TIE fighter 부터 Death star endpoint까지의 네트워크 플로우를 캡처할 것이다.
Death Star endpoint pod를 포함하는 Pod는 ingress 플로우 메트릭을 가질 것이다.
두 Pod를 띄우는 node는 한번에 ingress와 egress 플로우를 가질 것이다.

노드의 IP를 알아내자.

1
2


kubectl get -n kube-system po/cilium-n6vzs -o json | jq .status.podIP
192.168.0.10

prometheus에 metrics를 보내보자:

1
2
3
4
5


kubectl exec -it po/tiefighter -- curl http://192.168.0.10:9966/metrics
# HELP cilium_act_processing_time_seconds time to go over ACT map and update the metrics
# TYPE cilium_act_processing_time_seconds histogram
cilium_act_processing_time_seconds_bucket{le="0.005"} 0
cilium_act_processing_time_seconds_bucket{le="0.01"} 0

Prometheus 메트릭이 잘 측정되는것으로 보인다!
이제, xwing이 착륙시도를 해보자. 블로킹 정책 때문에 막힐 것이다.

1
2


kubectl exec xwing -- curl -s --connect-timeout 2 -XPOST deathstar.default.svc.cluster.local/v1/request-landing
command terminated with exit code 28

1
2
3
4
5
6
7
8
9


17:30:00 in ~/kube-practice took 2.2s …
➜ kubectl exec -it pod/xwing -- curl http://192.168.0.10:9966/metrics | grep drop_count_total
# HELP cilium_drop_count_total Total dropped packets, tagged by drop reason and ingress/egress direction
# TYPE cilium_drop_count_total counter
cilium_drop_count_total{direction="EGRESS",reason="Policy denied"} 1152
cilium_drop_count_total{direction="EGRESS",reason="Policy denied by denylist"} 307
cilium_drop_count_total{direction="EGRESS",reason="Unsupported L3 protocol"} 1587
cilium_drop_count_total{direction="INGRESS",reason="Policy denied"} 226
cilium_drop_count_total{direction="INGRESS",reason="Policy denied by denylist"} 23

Hubble Metrics 수집 활성화

혹시라도 hubble metrics가 비활성화 되어있다면, helm으로 추가해주자:
위에 제공된 helm values를 사용했다면, 이미 적용되어있다.

1

helm upgrade cilium cilium/cilium --version 1.18.2 -n kube-system --reuse-values --set hubble.enabled=true --set hubble.metrics.enabled="{dns,drop,tcp,flow,port-distribution,httpV2}"

Cilium 데몬셋을 다시 켜주자.

1

kubectl rollout restart ds/cilium -n kube-system

hubble metrics에 대한 headless service가 떠있을 것이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


17:45:06 in ~/kube-practice …
➜ kubectl get svc -n kube-system
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
cilium-envoy ClusterIP None <none> 9964/TCP 24h
hubble-metrics ClusterIP None <none> 9965/TCP 75s
hubble-peer ClusterIP 10.100.44.200 <none> 443/TCP 24h
hubble-relay ClusterIP 10.97.173.112 <none> 80/TCP 24h
hubble-ui ClusterIP 10.106.161.84 <none> 80/TCP 24h
kube-dns ClusterIP 10.96.0.10 <none> 53/UDP,53/TCP,9153/TCP 9d

17:45:21 in ~/kube-practice …
➜ kubectl describe svc/hubble-metrics -n kube-system
Name: hubble-metrics
Namespace: kube-system
Labels: app.kubernetes.io/managed-by=Helm
 app.kubernetes.io/name=hubble
 app.kubernetes.io/part-of=cilium
 k8s-app=hubble
Annotations: meta.helm.sh/release-name: cilium
 meta.helm.sh/release-namespace: kube-system
 prometheus.io/port: 9965
 prometheus.io/scrape: true
Selector: k8s-app=cilium
Type: ClusterIP
IP Family Policy: SingleStack
IP Families: IPv4
IP: None
IPs: None
Port: hubble-metrics 9965/TCP
TargetPort: hubble-metrics/TCP
Endpoints: 192.168.0.10:9965,192.168.0.4:9965
Session Affinity: None
Internal Traffic Policy: Cluster
Events: <none>

tiefighter pod에서 curl을 날려서 hubble metrics을 조회할 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


17:48:26 in ~/kube-practice …
➜ kubectl exec -it pod/tiefighter -- curl http://192.168.0.10:9965/metrics | grep hubble_drop
# HELP hubble_drop_total Number of drops
# TYPE hubble_drop_total counter
hubble_drop_total{protocol="ICMPv6",reason="UNSUPPORTED_L3_PROTOCOL"} 1

17:48:44 in ~/kube-practice …
➜ kubectl exec -it pod/tiefighter -- curl http://192.168.0.10:9965/metrics | grep hubble_tcp
# HELP hubble_tcp_flags_total TCP flag occurrences
# TYPE hubble_tcp_flags_total counter
hubble_tcp_flags_total{family="IPv4",flag="FIN"} 1217
hubble_tcp_flags_total{family="IPv4",flag="RST"} 2
hubble_tcp_flags_total{family="IPv4",flag="SYN"} 613
hubble_tcp_flags_total{family="IPv4",flag="SYN-ACK"} 610

xwing으로 다시 요청을 날려보자. drop 수가 늘어난 것을 볼 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


17:51:42 in ~/kube-practice …
➜ kubectl exec xwing -- curl -s --connect-timeout 2 -XPOST deathstar.default.svc.cluster.local/v1/request-landing
command terminated with exit code 28

17:55:38 in ~/kube-practice took 2.2s …
➜ kubectl exec -ti pod/tiefighter -- curl http://192.168.0.10:9965/metrics | grep hubble_drop
# HELP hubble_drop_total Number of drops
# TYPE hubble_drop_total counter
hubble_drop_total{protocol="ICMPv6",reason="UNSUPPORTED_L3_PROTOCOL"} 4
hubble_drop_total{protocol="TCP",reason="POLICY_DENIED"} 4

Hubble Metrics에 Flow Context 추가하기

Hubble metrics에 label context를 달아서 플로우 컨텍스트를 넣어줄수 있다.
soruce와 destination label을 넣어줄것이다.
helm values에서 drop sourceContext, destinationContext를 pod로 해주자.
위에 제공된 helm values를 사용했다면, 이미 적용되어있다.

1
2
3
4


helm upgrade cilium cilium/cilium --version 1.18.2 \
 -n kube-system --reuse-values \
 --set hubble.enabled=true \
 --set hubble.metrics.enalbed="{dns, drop:sourceContext=pod;destinationContext=pod, tcp, flow, port-distribution, httpV2}"

그 뒤, 다시 daemonset을 켜주자.

1

kubectl rollout restart daemonset/cilium -n kube-system

X-wing으로 착륙 요청을 몇 번 날려보자.

1

kubectl exec -it pod/xwing -- curl http://192.168.0.10:9965/metrics | grep hubble_drop

1
2
3
4
5


19:46:28 in ~/kube-practice …
➜ kubectl exec -it pod/xwing -- curl http://192.168.0.10:9965/metrics | grep hubble_drop
# HELP hubble_drop_total Number of drops
# TYPE hubble_drop_total counter
hubble_drop_total{destination="",protocol="ICMPv6",reason="UNSUPPORTED_L3_PROTOCOL",source=""} 1458

Grafana Dashboard

Cilium에서는 예시의 Grafana 대시보드 리소스를 제공한다.

1

kubectl apply -f https://raw.githubusercontent.com/cilium/cilium/refs/heads/main/examples/kubernetes/addons/prometheus/monitoring-example.yaml

로컬로 포트포워딩 해보자:

1

kubectl -n cilium-monitoring port-forward service/grafana --address 0.0.0.0 --address :: 3000:3000

http://localhost:3000에서 대시보드를 확인 가능하다.

Cilium: Hubble을 이용한 네트워크 관찰

Fri, 10 Oct 2025 13:58:10 +0900

Hubble은 분산 네트워크 시각화 플랫폼이다. 서비스들의 통신을 깊게 관찰하기 위해 Cilium과 eBPF위에서 투명하게, 즉 애플리케이션 코드 없이 동작한다.

Cilium 위에서 동작하기에, Hubble은 eBPF를 이용할 수 있다. eBPF를 이용함으로써, Hubble은 깊고 자세한 관찰성을 제공하는 동안 오버헤드를 제거하는 동적인 접근을 허용하는 프로그래머블한 관측, 즉 필요할 때 원하는 데이머만을 추출하는 관측을 제공한다.

🎯 Hubble이 제공하는 것들

Service dependencies & communication map
- 어떤 서비스들이 서로 통신하고 있고, 얼마나 자주 통신하는지
- 서비스의 의존 그래프가 어떻게 생겼는지
- 어떠한 HTTP 호출이 요청되고 있는지
- 어떠한 Kafka 토픽이 생산되고 소비되는지
Network moitoring & alerting
- 실패하고 있는 네트워크 통신이 있는지, 있으면 왜 실패하는지
- 어느 서비스가 최근 5분간 DNS문제를 겪었는지
- 어떤 서비스가 TCP 타임아웃이 났는지
- 응답받지 못한 TCP SYN응답이 있는지
Application monitoring
- HTTP 5xx 또는 4xx에러의 비율은 어떤지
- HTTP요청과 응답에 p95, p99는 어떤지
- 서비스의 성능 병목은 어느 지점인지
- 레이턴시는 어느 정도인지
Security observability
- 어느 서비스가 네트워크정책에 의해 연결이 막히는지
- 어느 서비스가 클러스터 외부와 통신하는지
- 어느 서비스가 특정 DNS이름을 질의했는지

이러한 모든 것들은 eBPF에 의해 가능해졌다. eBPF는 쿠버네티스 클러스터 내부에서 애플리케이션 워크로드들을 위한 네트워크 통신에 대해 깊은 시각화를 제공한다. Hubble과 함께라면, 이러한 정보들을 보고 쿠버네티스 메타데이터로 필터링할 수 있다.

🐝 Hubble 운영 컴포넌트들

CIlium에서 Hubble을 사용하면, 다음의 컴포넌트들이 구성된다

Hubble Server
- Cilium Agent의 일부로 동작하게 되며, 각 Node마다 존재한다.
- gRPC 옵저버 서비스를 구현하여, 노드의 네트워크 플로우에 접근하는 것을 지원한다.
- gRPC peer 서비스를 구현하여, Hubble relay가 peer Hubble Servers를 디스커버리 하도록 쓰인다.
Hubble Peer Kubernetes Service
- Kuberentes Service 리소스.
- Hubble Realy가 사용가능한 Hubbler Server들을 조회하도록 한다.
Hubble Relay Kubernetes Deployment
- 클러스터 내의 Hubble Server를 조회하기 위해, Cluster-wide의 범위의 Hubble Peer Service와 통신한다.
- Hubble Server와 gRPC API로 계속 연결을 유지한다.
- 클러스터 전역의 관찰성을 위해 API를 노출한다.
Hubble Relay Kubernetes Service
- Hubble UI Service에 의해 쓰인다
- Hubble CLI도구에 의해 노출될 수 있다
Hubble UI Kubernetes Deployment
- Hubble UI Kubernetes Service의 서비스 벡엔드로 동작한다
Hubble UI Kubernetes Service
- 클러스터 네트워킹 시각화에 쓰인다

즉, Hubble Server각 Cilium Agent에 동작하고, Hubbel Relay가 그런 Hubble Relay들의 플로우 데이터를 모으고, Hubble UI가 Hubble Relay로부터 데이터를 받아서 UI 대시보드를 만든다.

🌊 네트워크 플로우

모든 것이 Context

네트워크 플로우는 Hubble의 값에 대한 핵심 개념이다. 플로우는 tcpdump와 같은 곳에서의 패킷 캡처와 같다. 패킷 내용에 집중하는 대신, 플로우는 당신이 어떻게 Cilium-managed Kubernetes Cluster에서 패킷이 프르는지를 이해시켜주는 데 특화되어있다. 즉, 내용은 담지 않는다.

Flow는 맥락적인 정보를 담는다. 그 맥락적인 정보는 당신이 source/destination IP도 모른채로 해당 패킷이 클러스터 내에서 어디로 가는지와 어디서 드롭되고 포워딩되는지에 대해 디해하는 데 돕는다.

Kubernetes에서 IP란, 임시적인 자원이기에, 필터링과 같은 곳에서 신뢰성이 없다. 단순히 같은 IP주소를 몇 분간 캡처하는 것은 데이터센터의 VM에서나 하는 일이고, Kubernetes Pod의 네트워킹에서의 방법은 아니다. Flow는 Kubernetes 클러스터 내에서 더 내구성있는 맥략적 메타데이터를 제공한다.

더 나아가서, 당신은 플로우에 label을 달아서 context를 Prometheus 메트릭으로도 노출시킬 수도 있다. Flow는 당신의 네트워킹 대시보드에서 보일 수 있도록 하고, 애플리케잇녀 성능에 상응하여 스케일 업 또는 다운에 좋은 지표가 된다. Flow로부터 기반한 메트릭 label은 Cilium의 신원 모델에서의 큰 장점이다.

아래는 Hubble CLI도구로 캡처해서 얻은 플로우의 맥락적 메타데이터이다. 이 플로우는 Death Star 서비스 엔드포인트 노드에서 왔고, TIE fighter pod가 PUT Request를 거절받은 것을 볼 수 있다!

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


{
 "time": "2023-03-23T22:35:16.365272245Z",
 "verdict": "DROPPED",
 "Type": "L7",
 "node_name": "kind-kind/kind-worker",
 "event_type": {
 "type": 129
 },
 "traffic_direction": "INGRESS",
 "is_reply": false,
 "Summary": "HTTP/1.1 PUT http:‌//deathstar.default.svc.cluster.local/v1/exhaust-port"
 "IP": {
"source": "10.244.2.73",
 "destination": "10.244.2.157",
 "ipVersion": "IPv4"
 },
 "source": {
 "ID": 62,
 "identity": 63675,
 "namespace": "default",
 "labels": [...],
 "pod_name": "tiefighter"
 },
 "destination": {
 "ID": 601,
 "identity": 25788,
 "namespace": "default",
 "labels": [...],
 "pod_name": "deathstar-54bb8475cc-d8ww7",
 "workloads": [...]
 },
 "l4": {
 "TCP": {
 "source_port": 45676,
 "destination_port": 80
 }
 },
 "l7": {
 "type": "REQUEST",
 "http": {
 "method": "PUT",
 "Url": "http:‌//deathstar.default.svc.cluster.local/v1/exhaust-port",
 ...
 }
 }
}

JSON객체 안에 다양한 맥락적 정보가 들어있는 것을 볼 수 있다. 이러한 정보 덕에, 네트워킹 디버깅에서 유용한 정보가 된다.

플로우 필터링

만약 당신이 특정 Node로부터의 이벤트 플로우를 보고 싶다면, 당신은 hubble observe --follow로 Cilium Agent로부터 정보를 받아와서 Cilium datapath에서 각 패킷을 어떻게 평가하는지 볼 수 있다.

우선 지금은, 단일 노드에서의 플로우를 봐보도록 하자.

1
2
3


17:25:28 in ~/cilium-lab …
➜ kubectl -n kube-system exec -ti pod/cilium-5jhjt -c cilium-agent -- hubble observe --from-label "class=tiefigter" --to-label "class=deathstar" --verdict DROPPED --last 1 -o json
{"lost_events":{"source":"HUBBLE_RING_BUFFER","num_events_lost":"1"},"node_name":"kubernetes/worker1","time":"2025-09-28T08:25:44.749505064Z"}

--from-label 로 TIE fighter pod를 소스로 하고, --to-label로 deathstar 엔드포인트로 필터링했다. --verdict 필터는 드롭된 패킷들만 보도록 해준다.

Note
pod의 이름은 본인 클러스터 안에서의 Pod이름으로 해야 합니다

정보 스트림 통합

Cilium Agent의 Hubble Client를 이용하는건 Node의 상황만 보이기에, 한정적이다. 만약 당신이 같은 명령을 다른 노드에서 하면, 아무 것도 볼 수 없을 것이다.

Cluster전역에서 관찰하기 위해, Hubble Relay가 필요하다. Hubble CLI도구를 사용하여 Death Star 엔드포인트에 대한 플로우를 필터할 수 있다.

Hubble Relay 서비스는 뒤에서 Hubble Server API들과 통신한다. Hubble CLI가 설치되어있다면, 우린 Cluster단위의 Hubble Relay service에 접근가능하다. Hubble Relay 서비스를 노출시켜서, hubble명령어를 사용할 수 있다.

1
2
3
4
5
6


cilium hubble port-forward &
hubble status
Healthcheck (via localhost:4245): Ok
Current/Max Flows: 10,201/12,285 (83.04%)
Flows/s: 7.51
Connected Nodes: 3/3

포트포워딩이 되면, 당신은 Hubble CLI도구를 열어서 Cluster전역의 네트워크 흐름을 얻을 수 있다.

1
2
3
4
5


hubble observe --to-label "class=deathstar" --verdict DROPPED --all
Mar 24 01:41:14.758: default/tiefighter:58374 (ID:63675) -> default/deathstar-54bb8475cc-4pv5c:80 (ID:25788) http-request DROPPED (HTTP/1.1 PUT http:‌//deathstar.default.svc.cluster.local/v1/exhaust-port)
Mar 24 01:41:17.254: default/tiefighter:48852 (ID:63675) -> default/deathstar-54bb8475cc-d8ww7:80 (ID:25788) http-request DROPPED (HTTP/1.1 PUT http:‌//deathstar.default.svc.cluster.local/v1/exhaust-port)
Mar 24 01:41:26.495: default/xwing:59940 (ID:828) <> default/deathstar-54bb8475cc-d8ww7:80 (ID:25788) policy-verdict:none INGRESS DENIED (TCP Flags: SYN)
Mar 24 01:43:38.458: default/xwing:42378 (ID:828) <> default/deathstar-54bb8475cc-4pv5c:80 (ID:25788) policy-verdict:none INGRESS DENIED (TCP Flags: SYN)

출력 결과는 Death Star 벡엔드 Pod의 플로우를 포함한다. 아무것도 안해도 되긴 하지만, label로 필터를 해줄 수 있다. 모든 플로우 정보가 집계되기에, 필터를 해주는 것이 좋다.

Hubble UI를 연동하여 시각화

Hubble CLI 도구는 특정 문제를 진단하려는데, 클러스터 전반의 네트워크 흐름을 보고 싶을 때 좋다. 당신은 Hubble UI 서비스를 로컬에서 확인할 수 있다:

1

cilium hubble ui

자동 port-forward를 지원하고, local에서 볼 수 있도록 해준다. Hubble UI service는 반응형 서비스 맵을 제공하여 네트워크 흐름을 관찰할 수 있도록 해준다.

Hubble UI는 NetworkPolicy.io에서의 Hubble flow처럼 시각화를 제공한다.

💨 실습

상황

당신은 CiliumNetworkPolicy를 만들어서 Death Star API를 X-wing 요청으로부터 막았다. 그러나, Imperial cluster내부 전체에서는? X-wings가 또 다른 무언가와 통신한다면?

세팅

이전 NetworkPolicy까지 되어있음을 가정합니다. Hubble CLI도구를 깔아보자.

1
2
3


20:00:16 in ~ …
➜ hubble version
hubble v1.18.0@HEAD-766e8c9 compiled with go1.24.5 on linux/amd64

우선, Hubble Relay를 Cilium CLI로 포트포워드 한다:

1

cilium hubble port-forward &

이제, Hubble CLI는 통신가능하다. 추가 설정으로 원격에 포트포워드하지 않고도 가능하긴 하다.

1
2
3
4
5
6


20:01:56 in ~/cilium-lab …
✦ ➜ hubble status
Healthcheck (via localhost:4245): Ok
Current/Max Flows: 8,190/8,190 (100.00%)
Flows/s: 39.05
Connected Nodes: 2/2

이렇게 착륙 요청을 여러 번 날려보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


20:03:00 in ~/cilium-lab …
✦ ➜ kubectl exec tiefighter -- curl --connect-timeout 10 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
Ship landed

20:05:01 in ~/cilium-lab …
✦ ➜ kubectl exec tiefighter -- curl --connect-timeout 10 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
Ship landed

20:05:03 in ~/cilium-lab …
✦ ➜ kubectl exec tiefighter -- curl --connect-timeout 10 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
Ship landed

20:05:05 in ~/cilium-lab …
✦ ➜

Flow 메트릭에 변화가 생긴 것을 볼 수 있다.

1
2
3
4
5
6


20:05:56 in ~/cilium-lab …
✦ ➜ hubble status
Healthcheck (via localhost:4245): Ok
Current/Max Flows: 8,190/8,190 (100.00%)
Flows/s: 45.50
Connected Nodes: 2/2

X-wing 파드 플로우 필터링하기

X-wing으로 착륙요청을 날려보자. L3/4정책에 의해 트래픽이 막힌다.

1
2
3


20:06:01 in ~/cilium-lab …
✦ ➜ kubectl exec xwing -- curl --connect-timeout 2 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
command terminated with exit code 28

X-wing 요청이 거부된 걸 확인했다면, curl명령을 더 해서 Death Star service가 요청을 거부하는지 봐보자. Hubble CLI로 확인해보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43



20:13:14 in ~/cilium-lab …
✦ ➜ kubectl exec xwing -- curl --connect-timeout 2 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
command terminated with exit code 28

20:13:18 in ~/cilium-lab took 2.2s …
✦ ➜ kubectl exec xwing -- curl --connect-timeout 2 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
command terminated with exit code 28

20:13:21 in ~/cilium-lab took 2.2s …
✦ ➜ kubectl exec xwing -- curl --connect-timeout 2 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
command terminated with exit code 28

20:13:25 in ~/cilium-lab took 2.2s …
✦ ➜ kubectl exec xwing -- curl --connect-timeout 2 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
command terminated with exit code 28

20:13:28 in ~/cilium-lab took 2.2s …
✦ ➜ kubectl exec xwing -- curl --connect-timeout 2 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
command terminated with exit code 28

20:13:31 in ~/cilium-lab took 2.2s …
✦ ➜ hubble observe --label "class=xwing" --last 10
Sep 28 11:13:26.462: default/xwing:34428 (ID:13885) <> default/deathstar-74c8f5ff5c-h6rbl:80 (ID:24949) policy-verdict:none INGRESS DENIED (TCP Flags: SYN)
Sep 28 11:13:26.463: default/xwing:34428 (ID:13885) <> default/deathstar-74c8f5ff5c-h6rbl:80 (ID:24949) Policy denied DROPPED (TCP Flags: SYN)
Sep 28 11:13:28.467: default/xwing:46542 (ID:13885) -> kube-system/coredns-66bc5c9577-fsr7d:53 (ID:32219) to-overlay FORWARDED (UDP)
Sep 28 11:13:28.468: default/xwing:46542 (ID:13885) <- kube-system/coredns-66bc5c9577-fsr7d:53 (ID:32219) to-endpoint FORWARDED (UDP)
Sep 28 11:13:28.468: default/xwing:58261 (ID:13885) -> kube-system/coredns-66bc5c9577-qxshr:53 (ID:32219) to-overlay FORWARDED (UDP)
Sep 28 11:13:28.469: default/xwing:58261 (ID:13885) <- kube-system/coredns-66bc5c9577-qxshr:53 (ID:32219) to-endpoint FORWARDED (UDP)
Sep 28 11:13:28.469: default/xwing:43572 (ID:13885) -> kube-system/coredns-66bc5c9577-qxshr:53 (ID:32219) to-overlay FORWARDED (UDP)
Sep 28 11:13:28.470: default/xwing:43572 (ID:13885) <- kube-system/coredns-66bc5c9577-qxshr:53 (ID:32219) to-endpoint FORWARDED (UDP)
Sep 28 11:13:28.470: default/xwing:34440 (ID:13885) <> default/deathstar-74c8f5ff5c-rp7rx:80 (ID:24949) policy-verdict:none INGRESS DENIED (TCP Flags: SYN)
Sep 28 11:13:28.470: default/xwing:34440 (ID:13885) <> default/deathstar-74c8f5ff5c-rp7rx:80 (ID:24949) Policy denied DROPPED (TCP Flags: SYN)
Sep 28 11:13:28.473: default/xwing:60561 (ID:13885) -> kube-system/coredns-66bc5c9577-qxshr:53 (ID:32219) to-endpoint FORWARDED (UDP)
Sep 28 11:13:28.473: default/xwing:60561 (ID:13885) <- kube-system/coredns-66bc5c9577-qxshr:53 (ID:32219) to-overlay FORWARDED (UDP)
Sep 28 11:13:28.474: default/xwing:46542 (ID:13885) -> kube-system/coredns-66bc5c9577-fsr7d:53 (ID:32219) to-endpoint FORWARDED (UDP)
Sep 28 11:13:28.474: default/xwing:46542 (ID:13885) <- kube-system/coredns-66bc5c9577-fsr7d:53 (ID:32219) to-overlay FORWARDED (UDP)
Sep 28 11:13:28.475: default/xwing:58261 (ID:13885) -> kube-system/coredns-66bc5c9577-qxshr:53 (ID:32219) to-endpoint FORWARDED (UDP)
Sep 28 11:13:28.476: default/xwing:58261 (ID:13885) <- kube-system/coredns-66bc5c9577-qxshr:53 (ID:32219) to-overlay FORWARDED (UDP)
Sep 28 11:13:28.476: default/xwing:43572 (ID:13885) -> kube-system/coredns-66bc5c9577-qxshr:53 (ID:32219) to-endpoint FORWARDED (UDP)
Sep 28 11:13:28.477: default/xwing:43572 (ID:13885) <- kube-system/coredns-66bc5c9577-qxshr:53 (ID:32219) to-overlay FORWARDED (UDP)
Sep 28 11:13:29.528: default/xwing:34440 (ID:13885) <> default/deathstar-74c8f5ff5c-rp7rx:80 (ID:24949) policy-verdict:none INGRESS DENIED (TCP Flags: SYN)
Sep 28 11:13:29.528: default/xwing:34440 (ID:13885) <> default/deathstar-74c8f5ff5c-rp7rx:80 (ID:24949) Policy denied DROPPED (TCP Flags: SYN)

deathstar-xxx pod들 관련 통신을 볼 수 있다. 그러나, kube-system/coredns-xxxxx pod들도 볼 수 있다 DNS lookup이 있기 때문이다.

Hubble UI에서 확인해보자:

1

cilium hubble ui

Hubble flows는 xwing Pod가 kube-dns와 통신한다는 것을 보여준다. kube-dns를 클릭하면, kube-dns의 시점으로 플로우들이 보인다. xwing과 tiefighter Pod들이 Kube-dns를 쓰는 것을 볼 수 있다. xwing이 kube-dns도 못쓰게 해야한다.

DNS Deny Policy 생성

X-wing이 DNS를 쓸 수 없게 하려면, EgressDeny정책을 적용해주면 된다: xwing-dns-deny-policy.yaml을 만들자:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: "cilium.io/v2"
kind: CiliumNetworkPolicy
metadata:
 name: "xwing-dns-deny"
spec:
 endpointSelector:
 matchLabels:
 class: xwing
 egressDeny:
 - toEndpoints:
 - matchLabels:
 namespace: kube-system
 k8s-app: kube-dns

이 정책은 class=xwing으로 label이 붙은 모든 Pod의 k8s-app=kube-dnslabel이 붙은 Pod로의 통신을 모두 차단한다.

적용해보자.

1

kubectl apply -f xwing-dns-deny-policy.yaml

이제, xwing의 요청 에러가 다르게 뜬 것을 볼 수 있다:

1
2
3


20:29:59 in ~/cilium-lab took 2.2s …
➜ kubectl exec xwing -- curl --connect-timeout 2 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
command terminated with exit code 28

KubeDNS의 사용도 막힌 것을 볼 수 있다.

그러나, tiefighter는 잘 동작한다!

1
2
3


20:30:52 in ~/cilium-lab …
➜ kubectl exec tiefighter -- curl --connect-timeout 2 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
Ship landed

📚 요약

Hubble CLI도구와 Hubble UI로 네트워크 흐름을 챙겨볼 수 있게 되었다. Hubble CLI도구로, 당신은 시스템의 통신흐름을 관찰하고, 서비스의 엔드포인트 통신을 label로 필터링할 수 있다. Hubble UI로 서비스 맵을 그려서 시각화를 할 수 있고, 통신이 어떻게 되어가고 있는지 확인할 수 있다.

Cilium NetworkPolicy - 네트워크에 규칙 적용하기

Fri, 03 Oct 2025 19:26:13 +0900

🧑‍⚖️ 네트워크 정책의 종류

네트워크 정책은 사용자가 클러스터 내에서 무슨 트래픽이 허용되는지 정하도록 한다.
전통적인 방화벽은 source IP 또는 destination IP 및 포트 번호를 기반으로 permit 또는 deny를 시켰지만, Cilium은 label selector, namespace name, FQDN등과 같은 신원으로 룰을 생성해서 어떤 트래픽이 가능하고, 불가능한지를 정할 수 있도록 해준다.
쿠버네티스와 같이 IP주소가 계속 바뀌고 Pod가 계속 살아나고 죽는 환경에서 네트워크 정책을 짓기 좋게 해준다.

Cilium을 Kubernetes에서 실행할 때, Kubernetes Resource로 네트워크 정책을 정의할 수 있다.
Cilium Agent는 네트워크 정책의 업데이트를 위해 Kubernetes APIserver를 관찰하며, 중요한 eBPF 프로그램을 로딩하여 적용하고자 하는 네트워크 정책의 구현이 되도록 한다.

Kubernetes에서, Cilium은 세 가지 네트워크 정책이 가능하다:

L3/L4계층 정책을 지원하는 기본 Kubernetes의 NetworkPolicy
L3/L4/L7계층 정책을 지원하는 CiliumNetworkPolicy
네임스페이스를 벗어나 클러스터 전체의 정책을 위한 CiliumClusterwideNetworkPolicy

Cilium은 이 세 가지 정책을 동시에 지원한다.
그러나, 다양한 정책 타입을 사용할 때에는 주의해야 한다. 여러 정책 타입들 간의 허용된 트래픽들에 대한 이해가 어려워지기 때문이다.
세심한 주의가 없다면, 의도치 않은 정책이 될 수 있다.

networkpolicy.io의 시각화 도구는 서로 다른 정책 정의가 미치는 영향을 보는 데 도움을 준다.

📏 NetworkPolicy 리소스

NetworkPolicy 자원은 IP주소 또는 포트 레벨에서의 트래픽 흐름을 제어하는 L3/L4 계층의 전통적인 쿠버네티스 자원이다.
다음과 같은 것을 할 수 있다:

Label Matching을 이용한 L3/L4 Ingress 및 Egress 정책
클러스터 외부의 L3 IP/CIDR에 대한 L3 IP/CIDR Ingress 및 Egress정책
L4 TCP 및 ICMP 포트에 대한 Ingress 및 Egress 정책

📐 CiliumNetworkPolicy 리소스

CiliumNetworkingPolicy는 표준 NetworkPolicy의 확장이다. 다음의 기능들을 제공한다:

Ingress와 Egress를 특정 HTTP path로 제한하는 L7 HTTP 프로토콜 정책 룰
DNS, Kafka, gRPC등의 추가적인 L7 프로토콜 지원
클러스터 내부 통신에서의 Service이름 기반의 Egress 정책
특별한 Entity를 위한 Entity matching을 쓰는 L3/L4 Ingress 및 Egress 정책
DNS FQDN 매칭을 사용하는 L3 Ingress 및 Egress 정책

Cilium project documentation에서 일부 YAML 사용사례를 확인할 수 있다.
YAML만을 읽고, 어떤 트래픽이 허용되고 거부될지를 예측하는 것은 매우 어렵지만, 정확하게 의도된 정책을 만드는 것은 가만 둘 일이 아니다.
다행히도, networkpolicy.io에서는 이러한 작업을 더 쉽게 도와준다.

✍️ Networkpolicy.io Policy Editor

NetworkPolicy.io의 policy editor는 L3 및 L4 네트워크 정책을 찾아보고 만드는 것에 대해 좋은 방법을 제공한다.
시각적인 자료를 보여주고, 정책을 고를 수 있게 해준다.
Policy editor는 표준 Kubernetes NetworkPolicy와 CiliumNetworkPolicy 리소스를 제공한다.

위에는 정책들을 시각화해주는 서비스 맵이 있다.
초록 색은 허용, 붉은 색은 거부의 의미를 가진다.
이러한 UI를 보면서 클러스터 내외의 Ingress와 Egress 정책을 세울 수 있다.

좌측 하단에는, read-only YAML이 있다.
표준 Kubernetes NetworkPolicy또는 CiliumNetworkPolicy중에서 고를 수 있다.
또한 정책을 다운받아서 kubectl로 적용할 수도 있다.
기존 존재하는 policy 정의를 업로드할 수 있고, 시각화로 어떻게 동작하는지도 볼 수 있다.

정책을 시각화하는 것은 정책 룰이 의도한 대로 움직이는지 확인하기 좋다.
우측 하단에는, 일반적인 상황에서의 정책을 만드는 방법등을 알려준다.
Hubble flow를 업로드할수도 있고, Hubble이 무엇을 볼 수 있는지에 대한 일반적인 네트워크 정책을 생성할 수도 있다.
주의할 점은, 아직 L7지원은 안된다는 것이다.

✅ L7 CiliumNetworkPolicy이 가능한 것

CiliumNetworkPolicy가 기존 정책과 다른 점은, L7 protocol을 이해하는 정책에 있다. Cilium에서는, HTTP, Kafka, DNS등의 L7지원이 가능하다. L7정책 룰은 L4의 toPorts를 확장하여 networkpolicy.io에서의 만들어진 YAML 마니페스트에 추가하기도 쉽다. L7 정책 룰의 속성은 Cilium의 여러 프로토콜에 대해 다른 속성들을 가진다. https://docs.cilium.io/en/latest/security/policy/language/#layer-7-examples에 있지만, 여기서는 HTTP만 볼 것이다.

🕸️ L7 HTTP 정책

L7 HTTP 정책이 활성화되면, 해당 파드가 돌아가는 노드의 Cilium Agent는 local-only의 HTTP proxy service와 eBPF프로그램을 실행하여 패킷을 local HTTP proxy에서 포워드되도록 한다.

HTTP proxy는 L7 네트워크 정책을 따르고, 적절하게 패킷을 전달한다.
추가적으로, HTTP 프록시가 있다면, Hubble flows에서 L7관찰성을 제공받는다.

L7 HTTP 정책을 작성할 때, 다음의 필드들을 사용할 수 있다:

Path
URL에서 POSIX정규표현식이 적용되어 매칭된다.
공백 시, 모든 path허용으로 간주한다.
Method
요청의 HTTP 메서드이다(GET, POST, PUT, PATCH, DELETE).
공백 시, 모든 메서드 허용으로 간주한다.
Host
POSIX 정규표현식이 매칭되어 적용되는 요청의 host 헤더이다.
공백 시, 모든 host허용으로 간주한다.
Headers
필수로 요구하는 HTTP 헤더를 적어야 한다.
공백 시, 헤더에 상관없이 허용된다.

아래 예시는 app=myService라는 label을 가진 모든 endpoint들에 대해 TCP 80번 L4규칙을 업그레이드 하여 L7규칙들로 확장한다.
다음의 트래픽들만 허용된다:

GET /v1/path1
GET /v1/path1만 허용한다.
PUT /v2/path2.*
”/v2/path2.*”로 시작하는 모든 경로의 PUT을 허용한다.
Post .*/path3
”/path3”으로 끝나는 모든 path를 허용하고, HTTP 헤더로 X-My-Header가 true값을 가져야 트래픽이 허용된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


apiVersion: "cilium.io/v2"
kind: CiliumNetworkPolicy
metadata:
 name: "l7-rule"
spec:
 endpointSelector:
 matchLabels:
 app: myService
 ingress:
 - toPorts:
 - ports:
 - port: "80"
 protocol: TCP
 rules:
 http:
 - method: GET
 path: "/v1/path1"
 - method: PUT
 path: "/v2/path2.*"
 - method: POST
 path: ".*/path3"
 headers:
 - "X-My-Header: true"

L7규칙은 L4규칙에서 더 확장된 것 처럼 형상하고 있다.
즉, L7규칙은 L4규칙에서 시작해서 붙여나가는 식이 좋다.

🏃 실습: L4/L7 네트워크 정책

시나리오

당신은 Empire의 플랫폼 팀이 되어, IGKS(Imperial Galatic Kubernetes Service)에 Death Star API를 배포해야 한다.
서비스는 이미 배포가 되어있지만, Empire의 TIE 전투기들만이 착륙 요청을 할 수 있도록 보장해야 한다.

이 요청은 HTTP POST 메서드를 통해서만 가능해야 하고, 다른 경로에서는 PUT 메서드 등을 사용하지는 못하게 해야한다.
물론 TIE 파일럿들이 일부터 exhaust port에 뭔가를 할 일은 없겠지만, 우리는 사고에 대비해야 한다.

CiliumNetworkPolicy를 이용해야 한다. 이는 단순한 기술 문제가 아니라, 다스 베이더가 당신을 신뢰할 수 있을까에 대한 문제이다.
그의 불신을 사는 순간… 결과는 끔찍해진다.

즉, 목표는 TIE 전투기들이 오직 “착륙 요청”을 위한 HTTP POST요청만 가능하도록 Death Star 서비스에 접근을 제한하는 CiliumNetworkPolicy 리소스를 작성하는 것이다.

실습 세팅

우선, Cilium이 설치된 쿠버네티스 클러스터가 있어야 한다. Death Star 애플리케이션을 배포해야 한다. Cilium Project에는 Death Star demo application이 있다.

레포지토리에서 마니페스트를 받으면 된다.

1
2
3
4
5
6


01:27:13 in ~
➜ kubectl create -f https://raw.githubusercontent.com/cilium/cilium/HEAD/examples/minikube/http-sw-app.yaml
service/deathstar created
deployment.apps/deathstar created
pod/tiefighter created
pod/xwing created

잠깐! X-wings가 클러스터에 있다? 이게 무슨 일이지?
괜찮다. X-wings가 Death Star service에 접속하지 못한다.
Death Star 서비스는 만들어졌고, 오직 클러스터의 내부 IP만 가진다.
그러므로, 클러스터의 내부망에서만 접근 가능하다.

1
2
3
4
5


01:27:31 in ~
➜ kubectl get svc
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
deathstar ClusterIP 10.100.242.234 <none> 80/TCP 2m44s
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 5d7h

추가로, Cilium Endpoint가 각 Pod를 위해 생긴 것을 볼 수 있다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


01:30:15 in ~
➜ kubectl get po,CiliumEndpoint
NAME READY STATUS RESTARTS AGE
pod/deathstar-74c8f5ff5c-h6rbl 1/1 Running 0 3m11s
pod/deathstar-74c8f5ff5c-rp7rx 1/1 Running 0 3m11s
pod/tiefighter 1/1 Running 0 3m11s
pod/xwing 1/1 Running 0 3m11s

NAME SECURITY IDENTITY ENDPOINT STATE IPV4 IPV6
ciliumendpoint.cilium.io/deathstar-74c8f5ff5c-h6rbl 24949 ready 10.0.0.41
ciliumendpoint.cilium.io/deathstar-74c8f5ff5c-rp7rx 24949 ready 10.0.1.81
ciliumendpoint.cilium.io/tiefighter 59640 ready 10.0.1.65
ciliumendpoint.cilium.io/xwing 13885 ready 10.0.1.97

Cilium은 각 Death Star 벡엔드 Pod에 해당하는 Endpoint를 만들어주었다.
X-wing과 TIE 전투기 Pod들 역시 그렇다.

Note
deathstar-* 엔드포인트는 같은 IDENTITY ID를 가진다.
이전 챕터에서 언급했듯이, 같은 Cilium신원을 가진다.
label의 조합이 같기 때문이다.
Cilium Agent는 이 Identity ID로 적절한 네트워크 정책을 매칭한다.

아직 아무런 네트워크 정책이 없다.
양쪽 다 Death Star 벡엔드 파드에 내릴 수 있다.

둘다 착륙을 시켜보자:

1
2
3
4
5
6
7


01:32:18 in ~ …
➜ kubectl exec xwing -- curl -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
Ship landed

01:50:48 in ~ …
➜ kubectl exec tiefighter -- curl -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
Ship landed

Death Star 서비스에 정책을 주어서, 원하는 Pod만 착륙할 수 있도록 해보자!

Empore의 Ingress 허용 정책

X-wing Pod들이 Death Star의 서비스 엔드포인트에 접속하지 못하게 하는 가장 간단한 방법은 Label기반의 L3정책이다.
L3정책은 모든 포트들을 막아버린다.
포트 번호 기반으로 막고 싶다면, L4를 이용해야 한다.

xwing Pod는 org=alliance를, tiefighter Pod는 org=empire label을 가진다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


01:51:01 in ~ …
➜ kubectl describe pod/xwing
Name: xwing
Namespace: default
Priority: 0
Service Account: default
Node: worker1/192.168.0.10
Start Time: Sun, 28 Sep 2025 01:27:30 +0900
Labels: app.kubernetes.io/name=xwing
 class=xwing
 org=alliance
01:54:55 in ~ …
➜ kubectl describe pod/tiefighter
Name: tiefighter
Namespace: default
Priority: 0
Service Account: default
Node: worker1/192.168.0.10
Start Time: Sun, 28 Sep 2025 01:27:30 +0900
Labels: app.kubernetes.io/name=tiefighter
 class=tiefighter
 org=empire

TCP 80번 포트를 참조하는 L4네트워크 정책은 org=empire라벨을 한 Pod만 허용하고, xwing Pod들을 Death Star 서비스 엔드포인트로부터 차단한다.
우리는 networkpolicy.io의 policy editor를 이용할 수 있다.

가운데를 수정해서, Policy의 이름을 넣어주고, Endpoint selector에 deathstar의 label을 넣어준다.

Ingress측에 Namespace자원에 Pod selector로 org=empire, To ports에는 80|TCP로 입력한다.

이제, YAML은 아래와 같이 나올 것이다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


apiVersion: cilium.io/v2
kind: CiliumNetworkPolicy
metadata:
 name: allow-empire-in-namespace
spec:
 endpointSelector:
 matchLabels:
 org: empire
 class: deathstar
 ingress:
 - fromEndpoints:
 - matchLabels:
 org: empire
 toPorts:
 - ports:
 - port: "80"
 protocol: TCP

이 L4정책이 deathstar-* Pod service endpoint단위의 제어만 하고, Death Star service, 즉 L7수준의 제어는 되지 않는 것을 명심하라.

만약 Pod의 Egress 접근을 제어하고 싶다면, client pod의 egress정책을 설정해서 toServices정보를 지정해주면 된다.
이렇게도 위와 동일하게 가능은 하지만, 이 상황에서는 Ingress규칙만 사용하는 것이 더 간단하다.

만약 Pod마다 어느 곳에 트래픽을 보낼 수 있는지 구체적으로 관리하고 싶을 때 Egress를 써주는것이 적절하다.

이제, 실제로 적용해보자.

1
2
3


02:34:33 in ~/cilium-lab …
➜ kubectl apply -f allow-empire-in-namespace.yaml
ciliumnetworkpolicy.cilium.io/allow-empire-in-namespace created

이제, X-Wing은 더이상 API를 날릴 수 없다.
타임아웃이 나오는 것을 확인할 수 있다.

1
2
3


02:39:29 in ~/cilium-lab …
➜ kubectl exec xwing -- curl --connect-timeout 10 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
command terminated with exit code 28

그러나, tiefigher Pod는 성공한다:

1
2
3


02:39:43 in ~/cilium-lab took 10.2s …
➜ kubectl exec tiefighter -- curl --connect-timeout 10 -s -XPOST deathstar.default.svc.cluster.local/v1/request-landing
Ship landed

이제 X-wing Pod는 아무 액세스도 없다.
그러나, org=empire라면 모든 API를 누릴 수 있다.
실수로 자원 고갈 요청을 날렸다고 해보자:

1
2
3


02:40:56 in ~/cilium-lab …
➜ kubectl exec tiefighter -- curl -s -XPUT deathstar.default.svc.cluster.local/v1/exhaust-port
Panic: deathstar exploded

이런! 그러나 우리는 L7정책을 할당하여 이를 해결할 수 있다.

L7 HTTP 정책 만들기

기존 YAML에서 path기반 정책을 확장해보자.
아래 규칙은 org와 class label을 매칭하려든다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


apiVersion: cilium.io/v2
kind: CiliumNetworkPolicy
metadata:
 name: allow-empire-in-namespace
spec:
 endpointSelector:
 matchLabels:
 org: empire
 class: deathstar
 ingress:
 - fromEndpoints:
 - matchLabels:
 org: empire
 class: tiefighter
 toPorts:
 - ports:
 - port: "80"
 protocol: TCP
 rules:
 http:
 - method: "POST"
 path: "/v1/request-landing"
 - fromEndpoints:
 - matchLabels:
 org: empire
 class: maintenance-droid
 toPorts:
 - ports:
 - port: "80"
 protocol: TCP
 rules:
 http:
 - method: "PUT"
 path: "/v1/exhaust-port"

저장 후, 적용해보자.

1
2
3


02:46:21 in ~/cilium-lab took 1m 44.9s …
➜ kubectl apply -f allow-empire-in-namespace.yaml
ciliumnetworkpolicy.cilium.io/allow-empire-in-namespace configured

이제, TIE 전투기들은 자원고갈 API요청에 대해 HTTP 403 응답을 받는다.
Cilium Agent에 내장된 HTTP proxy가 대신 응답해준 것이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


02:46:25 in ~/cilium-lab …
➜ kubectl exec tiefighter -- curl -v -s -XPUT deathstar.default.svc.cluster.local/v1/exhaust-port
* Trying 10.100.242.234:80...
* Connected to deathstar.default.svc.cluster.local (10.100.242.234) port 80 (#0)
> PUT /v1/exhaust-port HTTP/1.1
> Host: deathstar.default.svc.cluster.local
> User-Agent: curl/7.88.1
> Accept: */*
>
Access denied
< HTTP/1.1 403 Forbidden
< content-length: 15
< content-type: text/plain
< date: Sat, 27 Sep 2025 17:49:09 GMT
< server: envoy
<
{ [15 bytes data]
* Connection #0 to host deathstar.default.svc.cluster.local left intact

X-wing은 L4정책으로 접근하지 못해서 HTTP 메시지도 못받고 타임아웃이 난다.
우리는 TIE 전투기들이 착륙 요청만 날릴 수 있고, 자원고갈 API는 요청할 수 없게 되었다.

Note
L3/4 정책과 L7정책의 응답 차이는 구현이 다르기 때문이다.
L3/4이에서는 eBPF프로그램이 패킷을 드롭하고, 네트워크의 블랙홀에 빠지게 된다.
L7 네트워크 정책은 HTTP proxy가 요청에 대해 결정하고, HTTP 상태 메시지와 사유를 같이 응답하며 응답을 거절한다.

📚 결론

CiliumNetworkPolicy는 Pod간 통신에서 안전하게 접근제어를 하는 방식 중 하나이다.
Pod들의 통신에서 전체 권한을 주기보다, CiliumNetworkPolicy를 통해서 최소 권한으로 유지하는 것이 좋다.
이렇게 최소 권한으로 유지하는 것은 서비스가 의도지 않게 동작하는 것을 막아주고, 보안에도 좋다.

Cilium의 내부 구조 및 동작

Tue, 30 Sep 2025 19:11:06 +0900

Cilium을 설치하면, 다양한 운영 컴포넌트들이 설치된다.

🧱 Cilium 구성요소

Cilium Operator

Cilium Operator는 클러스터 전체에서 딱 한번만 처리하면 되는 일을 수행한다.
즉, Agent들이 중복으로 수행하지 않는, 상위 레벨의 관리 작업을 수행한다.
Cilium은 데이터 경로(critical path)에 위치하지 않는데, 이 말은 통신에 직접 개입하지 않는다는 것이다.
즉, Operator가 잠깐 다운되어도, 이미 통신하는 Pod들간에는 아무 영향이 없다!. 물론, 오랫동안 다운이라면 IP를 할당받지 못하거나, 새로운 네트워크 정책이 적용되지 않을 수 있다.

즉, Operator는 Cilium에서의 Control Plane이라 할 수 있다.

Cilium Agent

Cilium Agent는 daemonset으로 동작하여 노드 당 하나씩 동작한다.
에이전트는 다음의 일을 한다:

Kubernetes API server와 클러스터 상태 연동을 위한 상호작용
eBPF프로그램을 로딩하고 eBPF테이블을 업데이트하기 위한 리눅스 커널과의 상호작용
새롭게 스케줄된 워크로드에 대해 알림을 받도록 유닉스 소켓을 이용한 Cilium CNI플러그인 프로그램과 상호작용
네트워크 정책의 요구에 기반한 온디맨드 DNS 및 Envoy 프록시를 생성
Hubble 필요시 gRPC서비스를 생성

Cilium Client

노드의 Cilium의 상태와 eBPF 맵을 리소스를 관찰하기 위해 Cilium Agent의 Pod 데몬셋은 클라이언트 실행파일과 함께 동반한다.
클라이언트는 daemonset과 REST API로 통신한다.

Note
Cilium CLI와는 다른 것이다.
Cilium client는 Cilium Agent Pod내부에 존재하여 Cilium Agent의 운영에 대해 진단 도구가 된다.
일반적인 운영에서는 Cilium Client를 사용할 일이 없다.

Cilium CNI Plugin

Cilium Agent daemonset이 처음 초기화되면, 호스트 노드의 특정 파일시스템에 CNI plugin 실행 파일을 설치한다.
그 뒤, 이 실행파일을 사용하도록 노드의 설정을 변경한다(kubelet설정을 변경)

요구가 오면, Cilium CNI플러그인이 유닉스 소켓을 통해 daemonset에게 요청을 전달한다.
즉, kubelet → Agent daemonset을 위한 창구라고 보면 된다.
실제 네트워크 작업은 Agent daemonset에서 동작한다.

Hubble Server

각 노드에서 Hubble Server가 동작하며, Cilium으로부터 eBPF 기반의 시각정보를 받는다.
Cilium Agent에 통합되어 고성능에 오버헤드가 적다.
네트워크 흐름을 얻고 Prometheus 메트릭을 얻는 데 gRPC를 사용한다.

Hubble Relay

Hubble이 활성화되면, 각 노드의 Cilium Agent는 Hubble gRPC서비스를 시작하여 노드-로컬 관찰성을 제공한다.
클러스터 전역의 관찰성을 위해, Hubble Relay Deployment가 클러스터에서 동작하고, 두 가지 서비스가 동작한다:

Hubble Observer Service
Hubble Peer Service

Hubble Relay Deployment 는 각 노드의 Cilium Agent로부터 gRPC요청을 날려서 클러스터 전역의 네트워크 관찰성을 제공한다.
Hubble Peer Service 는 클러스터 내 새로운 Hubble-활성화 Agent를 탐지할 수 있게 해준다.
당신은 CLI도구와 GUI를 이용하여 Hubble Observer Service에 상호작용할 수 있다.

Hubble CLI & GUI

Hubble CLI(hubble)는 hubble-relay또는 로컬 서버로부터 네트워크 플로우 이벤트를 받을 수 있는 gRPC API를 요청할 수 있는 CLI 도구이다.
GUI(hubble-ui)는 시각적으로 의존 및 연결 맵을 제공한다.

Cluster Mesh API Server

Cluster Mesh API Server는 여러 클러스터 간에 service를 공유하도록 해준다.
고가용성이나 재해복구에 매우 유용하다. Cluster Mesh를 활성화하면, 각 클러스터에 별도의 etcd가 설치된다. 이 etcd는 해당 클러스터의 Pod들의 Cilium Identity를 저장한다.
그리고, 다른 클러스터에서 접근가능하게 프록시 서비스를 개방한다.

Cilium Agent는 다른 클러스터의 etcd 프록시에 접속해서, 클러스터에 어떤 Identity가 있는지 물어볼 수 있다.
즉, 메시 내에서 신원이 전체 공유된다.
이는 글로벌 서비스로 확장할 수 있게 해준다.

📍 Endpoint

Cilium은 애플리케이션 컨테이너에게 IP주소를 할당함으로써 네트워크에서 가용 가능하도록 한다.
공통의 IP주소를 공유하는 모든 애플리케이션 컨테이너, 즉 Pod는 Endpoint라는 것으로 묶인다.
즉, 1 Pod = 1 Endpoint를 가진다.
Cilium은 Pod에게 1개의 Endpoint를 제공한다.
Endpoint는 Cilium의 기본 네트워크 단위이다.

🪪 Identity

Cilium이 효율으로 동작하는 데에는 Identity가 중요한 역할을 한다.
모든 Cilium Endpoint는 label기반의 Identity를 가진다.

Cilium Identity는 Label로 정해지고, 클러스터 전역에서 고유해야 한다.
보안에 관련된 label조합이 똑같은 Pod들은 모두 똑같은 Identity를 부여받는다..

위 그림에서, role=frontend를 가진 모든 Pod들은 다 똑같은 10번 Identity를 받는다.
이러한 Identity는 각각 고유한 정수값을 가져서, eBPF에서 정책조회가 매우 빠르다.

Cilium - 클러스터에 설치하기

Mon, 22 Sep 2025 23:29:21 +0900

이번에는 Cilium을 쿠버네티스에 설치할 것이다.
여기서는 Cilium 1.18.1, Kubernetes 1.34를 사용한다

ℹ️ 설치 방법

설치 방법에는 두 가지가 있다:

Cilium CLI tool
단순한 설치가 가능하다.
Helm Chart
더 디테일한 환경 설정도 가능하다.
Cilium documentation을 참고해서 설치 할 수 있다.

우선 Cilium CLI Tool 을 이용해서 설치한다.

🧾 요구사항

외부 CNI가 설치되기를 위해서, 쿠버네티스 클러스터가 준비되어있어야 한다.
kubectl역시 필요하다.

아래 섹션을 통해 kind환경에서 간단하게 할 수 있지만, 이 레포지토리를 참고하면, ansible을 이용해서 쉽고 빠르게 쿠버네티스를 구성할 수 있다.

🐳 Kind세팅

만약, 별도 클러스터가 있다면, 건너뛰어도 좋다.
여기서는 간단하게 Kind로 쿠버네티스를 구성하는 법을 설명한다.

요구사항:

아래는 3-노드에 기본 CNI가 비활성화된 kind클러스터 yaml이다.

1
2
3
4
5
6
7
8
9


# kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
 - role: control-plane
 - role: worker
 - role: worker
networking:
 disableDefaultCNI: true

1

kind create cluster --config=kind-config.yaml

kind는 클러스터를 만들고, kubectl 컨텍스트에 자동으로 컨텍스트를 추가한다.
컨텍스트를 확인해 보자. kind-kind라고 나오면 성공.

1

kubectl config current-context

아직은 CNI가 없기에, NotReady상태일 것이다.

1

kubectl get nodes

💻 Cilium CLI 설치

Cilium CLI를 로컬에 설치한다.

1
2
3
4
5
6


18:36:03 in ~ …
➜ cilium version
cilium-cli: v0.18.7 compiled with go1.25.0 on linux/amd64
cilium image (default): v1.18.1
cilium image (stable): v1.18.1
cilium image (running): unknown. Unable to obtain cilium version. Reason: release: not found

🚀 Cilium 설치

이제 CLI로 Cilium을 설치할 수 있다:

1
2
3
4
5


18:36:08 in ~ …
➜ cilium install
ℹ️ Using Cilium version 1.18.1
🔮 Auto-detected cluster name: kubernetes
🔮 Auto-detected kube-proxy has been installed

설치되는 데에 시간이 좀 걸린다. cilium status --wait으로 설치될 때까지 기다려보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


18:37:49 in ~ …
➜ cilium status --wait
 /¯¯\
 /¯¯\__/¯¯\  Cilium: OK
 \__/¯¯\__/ Operator: OK
 /¯¯\__/¯¯\  Envoy DaemonSet: OK
 \__/¯¯\__/ Hubble Relay: disabled
 \__/ ClusterMesh: disabled

DaemonSet cilium Desired: 1, Ready: 1/1, Available: 1/1
DaemonSet cilium-envoy Desired: 1, Ready: 1/1, Available: 1/1
Deployment cilium-operator Desired: 1, Ready: 1/1, Available: 1/1
Containers: cilium Running: 1
 cilium-envoy Running: 1
 cilium-operator Running: 1
 clustermesh-apiserver
 hubble-relay
Cluster Pods: 2/2 managed by Cilium
Helm chart version: 1.18.1
Image versions cilium quay.io/cilium/cilium:v1.18.1@sha256:65ab17c052d8758b2ad157ce766285e04173722df59bdee1ea6d5fda7149f0e9: 1
 cilium-envoy quay.io/cilium/cilium-envoy:v1.34.4-1754895458-68cffdfa568b6b226d70a7ef81fc65dda3b890bf@sha256:247e908700012f7ef56f75908f8c965215c26a27762f296068645eb55450bda2: 1
 cilium-operator quay.io/cilium/operator-generic:v1.18.1@sha256:97f4553afa443465bdfbc1cc4927c93f16ac5d78e4dd2706736e7395382201bc: 1

18:38:32 in ~ took 35.0s …
➜

Hubble 을 미리 활성화해 놓자. 나중에 쓸 것이다. 이 명령어는 Hubble을 위해 Cilium 에이전트를 재구성하고 재실행한다.
또한 클러스터 전역에 네트워크 관찰성을 위해 Hubble 컴포넌트를 활성화한다.

1

cilium hubble enable --ui

cilium status명령으로 Hubble 컴포넌트를 확인할 수 있다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


➜ cilium status
 /¯¯\
 /¯¯\__/¯¯\  Cilium: OK
 \__/¯¯\__/ Operator: OK
 /¯¯\__/¯¯\  Envoy DaemonSet: OK
 \__/¯¯\__/ Hubble Relay: OK
 \__/ ClusterMesh: disabled

DaemonSet cilium Desired: 2, Ready: 2/2, Available: 2/2
DaemonSet cilium-envoy Desired: 2, Ready: 2/2, Available: 2/2
Deployment cilium-operator Desired: 1, Ready: 1/1, Available: 1/1
Deployment hubble-relay Desired: 1, Ready: 1/1, Available: 1/1
Deployment hubble-ui Desired: 1, Ready: 1/1, Available: 1/1
Containers: cilium Running: 2
 cilium-envoy Running: 2
 cilium-operator Running: 1
 clustermesh-apiserver
 hubble-relay Running: 1
 hubble-ui Running: 1
Cluster Pods: 7/7 managed by Cilium
Helm chart version: 1.18.1
Image versions cilium quay.io/cilium/cilium:v1.18.1@sha256:65ab17c052d8758b2ad157ce766285e04173722df59bdee1ea6d5fda7149f0e9: 2
 cilium-envoy quay.io/cilium/cilium-envoy:v1.34.4-1754895458-68cffdfa568b6b226d70a7ef81fc65dda3b890bf@sha256:247e908700012f7ef56f75908f8c965215c26a27762f296068645eb55450bda2: 2
 cilium-operator quay.io/cilium/operator-generic:v1.18.1@sha256:97f4553afa443465bdfbc1cc4927c93f16ac5d78e4dd2706736e7395382201bc: 1
 hubble-relay quay.io/cilium/hubble-relay:v1.18.1@sha256:7e2fd4877387c7e112689db7c2b153a4d5c77d125b8d50d472dbe81fc1b139b0: 1
 hubble-ui quay.io/cilium/hubble-ui-backend:v0.13.2@sha256:a034b7e98e6ea796ed26df8f4e71f83fc16465a19d166eff67a03b822c0bfa15: 1
 hubble-ui quay.io/cilium/hubble-ui:v0.13.2@sha256:9e37c1296b802830834cc87342a9182ccbb71ffebb711971e849221bd9d59392: 1

✅ Cilium 운영 검증

Cilium CLI도구는 또한 연결성 테스트를 특정 쿠버네티스 네임스페이스 내에서 할 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


19:01:23 in ~ …
➜ cilium connectivity test --request-timeout 30s --connect-timeout 10s
✨ [kubernetes] Deploying client3 deployment...
✨ [kubernetes] Deploying echo-other-node service...
✨ [kubernetes] Deploying other-node deployment...
✨ [host-netns] Deploying kubernetes daemonset...
✨ [host-netns-non-cilium] Deploying kubernetes daemonset...
🔭 Enabling Hubble telescope...
⚠️ Unable to contact Hubble Relay, disabling Hubble telescope and flow validation: rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing: dial tcp 127.0.0.1:4245: connect: connection refused"
ℹ️ Expose Relay locally with:
 cilium hubble enable
 cilium hubble port-forward&
ℹ️ Cilium version: 1.18.1
🏃[cilium-test-1] Running 123 tests ...

✅ [cilium-test-1] All 77 tests (662 actions) successful, 46 tests skipped, 1 scenarios skipped.

연결 테스트에는 수많은 테스트들이 있다.
새로운 버전의 Cilium을 받는다면, 기본 연결 테스트의 수가 더 늘어난 형태일 수도 있다.
처음에는 많은 대기시간이 필요하다. 실행을 위해 컨테이너 이미지도 받아오는 등의 초기 세팅과정이 들어있기 때문이다.
최소 10분은 예상하고 시작해야 한다.

테스트를 하려면..
연결 테스트는 최소 두 개 이상의 워커 노드를 요구한다.
연결 테스트 파드는 control-plane에서 열리지 않는다.

☸️ kubectl로 조회하기

Cilium이 설치되면, kubectl로 노드들이 준비된 것을 확인할 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


18:46:50 in ~ …
➜ kubectl get nodes
NAME STATUS ROLES AGE VERSION
master Ready control-plane 51m v1.34.1
worker1 Ready <none> 15m v1.34.1

19:02:18 in ~ …
➜ kubectl get daemonsets -A
NAMESPACE NAME DESIRED CURRENT READY UP-TO-DATE AVAILABLE NODE SELECTOR AGE
cilium-test-1 host-netns 2 2 2 2 2 <none> 55s
cilium-test-1 host-netns-non-cilium 0 0 0 0 0 cilium.io/no-schedule=true 55s
kube-system cilium 2 2 2 2 2 kubernetes.io/os=linux 25m
kube-system cilium-envoy 2 2 2 2 2 kubernetes.io/os=linux 25m
kube-system kube-proxy 2 2 2 2 2 kubernetes.io/os=linux 51m

19:02:26 in ~ …
➜ kubectl get deployments -A
NAMESPACE NAME READY UP-TO-DATE AVAILABLE AGE
cilium-test-1 client 1/1 1 1 16m
cilium-test-1 client2 1/1 1 1 16m
cilium-test-1 client3 1/1 1 1 64s
cilium-test-1 echo-other-node 1/1 1 1 64s
cilium-test-1 echo-same-node 1/1 1 1 16m
kube-system cilium-operator 1/1 1 1 25m
kube-system coredns 2/2 2 2 51m
kube-system hubble-relay 1/1 1 1 23m
kube-system hubble-ui 1/1 1 1 23m

성공적으로 Cilium이 설치된 것을 확인할 수 있다!

Cilium - Cilium이란?

Mon, 22 Sep 2025 23:14:14 +0900

🐝 Cilium

Cilium은 워크로드 간의 네트워크 연결을 제공하고, 보안을 책임지고, 관찰성을 부여하는 오픈 소스, 클라우드 네이티브 솔루션이다.
쿠버네티스 환경에서, Cilium은 Pod 간의 연결을 제공하는 네트워크 플러그인으로 동작한다.
네트워크 정책과 투명한 암호화로 보안을 제공하고, Hubble 컴포넌트는 투명성을 제공한다.
eBPF덕분에, Cilium의 기능들은 모두 커널에 직접 프로그래밍되어 애플리케이션의 워크로드에서 완전 투명하게 보일 수 있다.

🕸️ 대규모 네트워크에서의 컨테이너 네트워킹 문제 해결

동적이고 복잡한 마이크로서비스 세계에서, 네트워크 IP와 포트 주소를 맞추는 것은 매우 절망적일 수 있다.
전통적인 도구들은 컨테이너 네트워킹에서 비효율적이고, 안전하지 못했다.
Cilium은 대규모의, 동적으로 컨테이너화된 환경에서 컨테이너와 쿠버네티스에서의 HTTP, gRPC, Kafka와 같은 API 프로토콜들을 네티이브하게 이해한다.
전통적인 방화벽보다 더 단순하고 강력하다.

🌐 eBPF

Cilium은 쿠버네티스와 같은 마이크로서비스 플랫폼에서 네트워크 스택을 생성해준다.
eBPF는 Cilium의 보안 시각화와 제어 로직을 리눅스 커널 수준에서 제공한다.
eBPF는 리눅스 커널을 프로그래머블하게 만들어서, Cilium과 같은 애플리케이션이 커널의 서브시스템으로 들어가게 한다.
eBPF가 커널에서 동작하기에, Cilium의 보안 정책은 애플리케이션 코드나 컨테이너의 설정을 건드리지 않도록 한다.
eBPF 프로그램이 리눅스 네트워크 경로로 들어가서, 패킷이 네트워크 소켓에 들어올 때, 정책에 따라 패킷을 드롭하는 등에 사할 수 있다.
eBPF는 이전에는 불가능했던 수준의 세밀함과 효율성으로 시스템과 애플리케이션을 가시화하고 제어할 수 있게 해준다.
애플리케이션을 변경할 필요 없이 완전히 투명하다.
Cilium은 효율적인 ID개념을 도입하여, 쿠버네티스의 label과 같은 컨텍스트 정보를 eBPF기반 네트워킹 로직에 결합하여 eBPF의 강력한 기능을 활용한다.

🍯 Cilium이 제공하는 것들

네트워킹

파드와 다른 컴포넌트들을 포함한 통신을 제공한다.
L3계층에서의 단순한 플랫 레이어를 구현하여, 여러 클러스터와 애플리케이션 컨테이너들이 통신할 수 있게 해준다.
기본적으로, Cilium은 모든 호스트간 걸치는 가상의 네트워크인 오버레이 네트워킹 모델을 지원한다.
오버레이 네트워크에서의 트래픽은 서로 다른 호스트간 캡슐화된다.

이것이 기본적으로 사용되는 이유는, 최소한의 인프라와 호스트간 IP만 연결된 통합만을 요구하여 설정이 단순하기 때문이다.
또한, 네이티브 라우팅 네트워크 모델 또한 옵션으로 제공되는데, 각 호스트에서 전통적인 라우팅 테이블을 이용해서 파드 또는 외부 IP주소들간의 통신을 좌우한다.

이 모드는 네트워크 인프라에 대한 이해도가 높은 사용자들에게 제공된다.
이는 IPv6네트워크에서 잘 어울리고, 클라우드 네트워크 라우터나 기존 라우팅 데몬 등에서도 잘 동작한다.

신원확인 네트워크 정책

네트워크 정책은 어느 워크로드가 다른 워크로드에 통신하도록 허용되는지를 정의하여 Deployment가 다른 예상치 못한 트래픽으로부터 통신하지 않게 한다.
Cilium은 네이티브 Kubernetes NetworkPolicies를 강제할 수도 있고, 향상된 CiliumNetworkPolicy라는 CRD를 쓰게할 수도 있다.
IP주소 및 포트 기반의 방화벽 워크로드는 기존 쿠버네티스 환경에서 모든 노드의 방화벽 규칙을 조작하게 하여 방화벽 규칙을 새로 구성시킨다.
이는 확장에 매우 어렵다.

이 상황을 피하기 위해, Cilium은 애플리케이션 컨테이너 그룹에 Kubernetes label과 같은 메타데이터로 신원을 부여한다.
이 신원은 애플리케이션 컨테이너로부터 방출된 패킷에 연관되어, 패킷을 수신하는 노드의 eBPF 프로그램이 리눅스 방화벽 없이 효율적으로 신원을 확인할 수 있도록 한다.

예를 들어, deployment가 확장되어, 새로운 Pod가 클러스터 어딘가에 생기면, 새로운 Pod는 기존 Pod들과 같은 신원을 가진다.
eBPF 프로그램은 네트워크 정책의 잦은 업데이트를 시키지 않는다. Pod identity가 있기 때문이다!
전통적인 방화벽이 L3~4의 정책을 시행했다면, Cilium은 REST/HTTP, gRPC, Kafka와 같은 L7급 정책까지도 추가로 가능하다.

애플리케이션 프로토콜에 대응하는 네트워크 정책을 만드는 것을 제공할 수 있다:

HTTP GET을 /public/.*.에 대해서만 허용하고, 나머지 거부
REST호출의 HTTP 헤더가 X-Token: [0-9+] 을 반드시 가지도록 설정

투명 암호화

서비스 간의 통신 중의 암호화는 PCI 또는 HIPPA와 같은 규제에서 필수 요구사항이 되었다.
Cilium은 설정하기 쉬운 투명 암호화를 제공한다.
IPSec이나 WireGuard를 이용하는데, 그들이 활성화되면, 노드 간의 보안 트래픽이 아무 재설정을 요구하지 않고 활성화된다.

멀티-클러스터 네트워킹

Cilium의 Cluster Mesh 는 서로 다른 쿠버네티스 클러스터의 서비스 간의 통신을 쉽게 지원한다.
서비스를 서로 다른 리전의 클러스터에 배포하여 고가용서을 보장시킬 수도 있다.

로드 밸런싱

Cilium은 애플리케이션 컨테이너와 외부 서비스 간 분산된 로드밸런싱을 제공한다.
Cilium은 기존의 kube-proxy를 대체하여 standalone load balancer로 동작할 수 있다.
로드밸런싱은 eBPF에 구현어있고, 이는 해시 테이블을 이용하여 거의 무한한 확장성을 가져 효율적이다.

향상된 네트워크 관찰성

Cilium은 클러스터 내의 네트워킹 문제를 쉽게 식별하고 고칠 수 있게 제공한다.
Cilium은 Hubble이란 네트워크 관찰성 도구를 포함한다.
Hubble은 관찰성을 부여하여 Cilium의 트래픽 필터링을 더 쉽게 하여 신원 컨셉을 더 쉽게 만든다.

또한 다음을 제공한다:

L3/4, L7네트워크 트래픽에 대한 가시성 제공
메타데이터와 함께 이벤트 모니터링

패킷이 드롭되면, 도구는 소스와 목적지 IP 뿐만 아니라, 송신자와 수신자의 전체 label정보들도 추출해준다.

Prometheus 메트릭 export와 조합이 좋다
GUI로 보기 쉽게 제공한다

Prometheus 메트릭

Cilium과 Hubble은 네트워크 성능과 지연 등을 Prometheus로 제공하여 Cilium 메트릭을 대시보드에 통합할 수 있다.

서비스 메시

Cilium은 Ingress와 Gateway API 호환을 제공하고, 사이드카 제공 없이 서비스 메시의 모든 스펙을 구현한다.

AWS Solutions Architect Associate(SAA-C03) 후기

Wed, 17 Sep 2025 19:35:32 +0900

클라우드 교육수료 이후, 최대 10만원 지원을 받게 되어 교육 동안 다루었던 AWS 관련 자격증을 따야겠다는 생각을 했고, 그렇게 고른 것이 AWS SAA이다.

ℹ️ 시험 정보

AWS Solutions Architect Associate(SAA-C03)

비용: 150달러(25년 9월기준 약 19~20만원)
평가기준
- 보안 아키텍처 설계
- 복원력을 갖춘 아키텍처 설계
- 고성능 아키텍처 설계
- 비용에 최적화된 아키텍처 설계
문제: 65문제지만, 실제로는 50문제만 반영, 더미 15문제

응시장소는 처음에 온라인으로 했으나, 여권이 만료되어서 오프라인으로 응시했다.
오프라인으로는 신분증(주민등록증, 운전면허증)과 영문이름이 적힌 신용/체크카드가 필요하다.
서울 압구정의 헤럴드 테스트센터를 이용했다.
한국인 분이 시험을 진행해주셨고, 마침 시험장에 혼자여서 편하게 볼 수 있었다.

✍️ 시험 준비

2주의 기간을 잡았고, 10일정도 강의만, 4일정도는 연습문제들을 달렸다.

다음 두 가지의 강의를 구매했다:

각각 2만원 이내에 구매할 수 있다.

우선, 국룰이라고 불리는 Stephane Maarek의 강의를 들었다.
이론 위주로 배속으로 들었다.

기존에 유명한 examtopics의 문제들은 풀지 않았는데, 공식 정답은 일부 틀려있고, discussion을 보려니 귀찮고 혼란스러웠기 때문이다.
그리고, “문제 풀고 답 확인"이라는 패턴보다, 모의고사 형식으로 문제를 푼 뒤, 한 번에 피드백을 원했는데, Tutorials Dojo의 모의고사는 이러한 것들을 지원해주어서 매우 편리했다.
문제 난이도 역시 일반적인 덤프들보다 더 어려웠다.
섹션 카드도 제공해줘서 핵심 개념들을 보는 데에도 도움이 되었다.

🧑‍💻 시험 응시

130분의 응시 시간이 주어지지만, 영어가 모국어가 아니면 30분을 더 받을 수 있다.
나는 이 제도가 영문으로 시험을 보는 경우에만 적용인줄 알았는데, 아니였나 보다.

문제는 기본 주요 자원 및 서비스들(EBS, EFS, VPC, EC2, S3, SQS, SNS, Kinesis, ECS, CloudFront)등에 대한 것들이 어럽게 나오는 경향이 있다.
나머지 서비스들은 그래도 이름과 역할정도는 알긴 해야 할 것 같다.

Tutorials Dojo에서 본 적이 있는 문제들도 일부 보았고, 생소한 문제도 일부 있었다.
시간 소요는 80분정도 걸렸던 거 같다.

시험에서 중요한 것은 “무엇을 원하는지” 인 듯하다.
예를 들자면, 비용 효율성을 원한다고 나오면, 성능이 좀 부족하더라도 비용이 더 저렴한 솔루션이 정답이다.

🚀 시험 결과

시험이 끝난 밤, 밤에 메일을 확인해보니 합격 이메일이 와있었다!
주어진 링크를 따라가면 Open Badge형식의 전자배지를 수령받을 수 있다.

좋은 결과가 나와서 기쁘다.

🛌 시험 후기 및 마무리

자격증에 합격해서 기쁘지만, 여전히 갈 길이 멀다.
이론적으로 무엇을 어디에 쓸지 안다고 하더라도, 실전 경험이 부족한 상태이다.
또한, 자격증이 있다고 빠삭해지는 건 아닌 것 같다. 아무래도 자격증을 위한 공부를 하다보니 그런 점도 있는 것 같다.

다음 자격증은 쿠버네티스 자격증들(cka, ckad, cks)에 도전할 것이다.
또 잘 준비해서 좋은 결과가 있었으면 좋겠다.

Kubernetes - Ansible을 이용한 클러스터 구성

Sun, 07 Sep 2025 22:50:05 +0900

플레이북 GitHub Repository 이 게시글은 다음의 작업에 대해 설명한다:

Ansible 을 활용하여 쿠버네티스 클러스터의 필수 요소 설치를 자동화
- containerd
- kubelet
- kubeadm
- kubectl
kubeadm으로 Control Plane 구성
Cilium을 CNI(Container Network Interface) 플러그인으로 설치
마스터 자격 증명 가져오기

Ansible은 Red Hat의 오픈 소스 IaC도구로, 서버 자원의 구성 관리를 자동화하여 휴먼 에러를 줄이고, 생산성을 높여준다.

Ansible은 다음의 장점을 가진다:

YAML기반으로 IaC(Infrastructure as Code) 실현
멱등성(Idempotence) - 여러 번 실행해도 크래시가 생기지 않는다
- 그러나, 이미 생성된 클러스터의 노드에 대해서 다시 실행하면, 오류가 발생할 수 있다
- 기본 필요사항들의 설치까지만 멱등성이 보장된다.
- 노드를 추가하고 싶을 시, 인벤토리에 기존 노드들은 제거하고 돌리시는게 좋다

🎬 Ansible 시작을 위한 기본 세팅

Ansible의 구성 요소는 다음과 같다:

controller
- 구성 대상이 되는 서버들에게 명령을 내리는 호스트
inventory
- 대상 서버들에 대한 정보
playbook
- 대상 서버들에 대한 명령집 파일
- playbook은 여러 개의 play들로 구성
- 각 play에는 1개 이상의 task로 구성됨
- 각 play마다 대상 host가 있음

Ansible은 대상 서버에서 작업을 취하기 위해, ssh로 접속하여 동작한다.

즉, Ansible이 접속할 수 있는 사용자를 대상 서버에서 만들어줘야 한다.

각 서버에 아래의 작업들을 해야 한다:

각 서버에 ansible 유저 생성

adduser로 사용자를 생성한다.

useradd 를 내부적으로 사용하며, 최초 비밀번호 초기화 등의 더 많은 기능들을 제공한다.

1

adduser ansible

쿠버네티스 설치를 위해, 권한이 필요하다.

또한, 완전한 자동화를 위해 패스워드 입력을 생략시킬 것이다

1
2
3
4
5
6
7


#/etc/sudoers.d/ansible에서 아래와 같이 작성
ansible ALL=(ALL) NOPASSWD:ALL

# ansible 사용자는
# 모든 명령어를 sudo권한으로 사용가능하며
# 모든 명령어를 비밀번호 없이 사용가능하다
# 실제로는 최소권한을 주는 것이 낫다.

ssh 키 생성

(로컬, 즉 컨트롤러에서) ssh key를 생성한다.

1
2
3
4
5
6


ssh-keygen -N '' -f ~/.ssh/id_rsa -b 2048 -t rsa

# no passphrase
# save private key to ~/.ssh/id_rsa
# 2048 b
# type rsa

로컬에서 각 서버로 키 배포

1

ssh-copy-id -i <key-file> -p <port> ansible@<server-ip>

⚙️ ansible.cfg 및 inventory.ini 작성

Ansible은 /etc/ansible/ansible.cfg의 값을 기본적으로 참조하지만,

현재 작업 디렉토리에서의 ansible.cfg가 있다면, 그 설정 파일을 우선으로 읽는다.

ansible.cfg는 ansible명령을 실행할 때의 환경 설정 파일이다.
inventory.ini는 대상 호스트들의 정보가 담겨있는 파일이다.

ansible.cfg 예시

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


[defaults]
inventory = ./inventory.ini # inventory.ini가 쓸 인벤토리 파일임을 명시
remote_user = ansible # ssh 유저는 ansible
aks_pass = false # 패스워드 묻지 않음(SSH키 이용)

[privilege_escalation]
become = true # 권한 상승 허용
become_method = sudo # 권한 상승 방법은 sudo(sudo > su)
become_user = root # 권한 상승되어 root로서 동작
become_ask_pass = false # 권한 상승 비밀번호를 묻지 않음. true로 두면 과정에서 비밀번호 물음

inventory.ini 예시

1
2
3
4
5
6
7
8
9


[masters]
master ansible_host=192.168.64.10 ansible_port=22

[workers]
worker1 ansible_host=192.168.64.12 ansible_port=22

[k8s-nodes:children] # 호스트 그룹 상속
masters
workers

또는, ~/.ssh/config 파일에서 정리해두면, 해당 hostname을 간단하게 쓸 수 있다

🚀 Ansible을 이용한 모든 노드들에 대해 필수 구성요소 설치

본격적으로 쿠버네티스를 설치한다.

각 노드들은 ubuntu 24.04를 기준으로 한다.

준비사항

사전 확인 할것들은 다음과 같다:

2GB이상 RAM
2코어 이상의 CPU/vCPU
클러스터 전체는 네트워크에 연결되어야 함(퍼블릭/프라이빗 상관없음)
MAC주소 및 product_uuid가 모두 고유해야 함
- ip link 또는 ifconfig -a로 MAC주소 확인
  - sudo cat/sys/class/dmi/id/product_uuid로 product_uuid확인 가능
hostname이 모두 고유해야 함
시간이 알맞게 동기화되어있어야 함
네트워크 어댑터가 2개 이상인 경우, 신경써야 함
- 기본 라우트 설정 등
스왑 비활성화(kubelet이 제대로 작동하려면 스왑은 꺼야 함) → 플레이북에서 자동화한다
6443포트가 방화벽에 막히지는 않는지 확인해야 함(kube-apiserver 위해)
- iptables/firewalld, 보안 그룹 등
- cni에 따라 추가로 필요한 게 있을 수 있음

순서

시스템 업데이트 및 업그레이드
NTP서버 동기화(현재 플레이북에 없음)
ufw비활성화(현재 플레이북에 없음)
스왑 제거
커널 설정 변경(br_netfilter, overlay, iptables, forwarding)
- br_netfilter는 브릿지 네트워크 패킷을 iptables에서 볼 수 있게 해준다.
- overlay는 컨테이너의 파일 시스템인 overlayfs를 사용할 수 있도록 해준다
- net.ipv4.ip_forward로 ipv4 패킷 포워딩을 활성화한다.
- net.bridge-nf-call-iptables, net.bridge-nf-call-ip6tables을 활성화하여 리눅스 브릿지를 통과하는 IPv4 및 IPv6 트래픽이 iptables의 규칙을 통과하도록 해준다
컨테이너 런타임 설치(containerd)
- containerd는 Docker로부터 제공받을 수 있다
containerd 초기 설정 + cgroup설정(SystemdCgroup=true) + 재시동
- systemd와 통합하여 리소스 제한 및 격리를 관리시킨다
kubelet, kubeadm, kubectl 설치
버전 고정
kubelet 실행

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159


---
- name: Install Kubernetes essentials on all nodes
 hosts: k8s_nodes
 become: true
 gather_facts: true
 vars:
 docker_repo_codename: '{{ ansible_lsb.codename | default(''noble'') }}' # noble: 24.04
 k8s_minor: v1.34
 k8s_keyring: /etc/apt/keyrings/kubernetes-apt-keyring.gpg
 k8s_list: /etc/apt/sources.list.d/kubernetes.list
 containerd_pause_image: registry.k8s.io/pause:3.10.1
 tasks:
 - name: Update apt cache
 apt:
 update_cache: yes
 cache_valid_time: 3600
 - name: Upgrade all packages to the latest version
 apt:
 upgrade: dist
 - name: Disable swap temporarily
 command: swapoff -a
 when: ansible_swaptotal_mb | default(0) > 0
 - name: Disable swap permanently
 ansible.posix.mount:
 name: none
 fstype: swap
 state: absent
 - name: Ensure kernel modules are enabled (br_netfilter, overlay)
 modprobe:
 name: '{{ item }}'
 state: present
 persistent: present
 loop:
 - br_netfilter
 - overlay
 - name: Enable iptables and forwarding via sysctl config
 sysctl:
 name: '{{ item }}'
 value: "1"
 reload: yes
 sysctl_file: /etc/sysctl.d/k8s.conf
 state: present
 sysctl_set: yes
 loop:
 - net.bridge.bridge-nf-call-ip6tables
 - net.bridge.bridge-nf-call-iptables
 - net.ipv4.ip_forward
 - name: Install required packages
 apt:
 name:
 - ca-certificates
 - curl
 - gnupg
 - lsb-release
 state: present
 update_cache: yes
 - name: Ensure keyrings directory exists
 file:
 path: /etc/apt/keyrings
 state: directory
 mode: "0755"
 - name: Download Docker GPG key
 get_url:
 url: https://download.docker.com/linux/ubuntu/gpg
 dest: /etc/apt/keyrings/docker.asc
 mode: "0644"
 - name: Convert Docker GPG key to dearmored keyring
 command: /usr/bin/gpg --dearmor -o /etc/apt/keyrings/docker.gpg /etc/apt/keyrings/docker.asc
 args:
 creates: /etc/apt/keyrings/docker.gpg
 - name: Add Docker APT repository
 apt_repository:
 repo: deb [arch={{ (ansible_architecture == 'aarch64') | ternary('arm64', 'amd64' )}} signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu {{ docker_repo_codename }} stable
 state: present
 filename: docker
 - name: Update apt and install containerd.io
 apt:
 name: containerd.io
 state: present
 update_cache: yes
 ## cgroup
 - name: Setup containerd config directory
 ansible.builtin.file:
 path: /etc/containerd
 state: directory
 - name: Generate default containerd config
 command: containerd config default
 register: containerd_config
 - name: Write containerd config.toml
 copy:
 dest: /etc/containerd/config.toml
 content: '{{ containerd_config.stdout }}'
 - name: Set SystemdCgroup=true in containerd
 replace:
 path: /etc/containerd/config.toml
 regexp: SystemdCgroup = false
 replace: SystemdCgroup = true
 - name: Ensure CRI sandbox_image matches kubeadm expected pause image
 replace:
 path: /etc/containerd/config.toml
 regexp: ^\s*sandbox_image\s*=\s*".*"\s*$
 replace: ' sandbox_image = "{{ containerd_pause_image }}"'
 - name: Restart and enable containerd
 systemd:
 name: containerd
 state: restarted
 enabled: true
 - name: state the kubernetes keyring file
 stat:
 path: '{{ k8s_keyring }}'
 register: k8s_keyring_stat
 - name: Download Kubernetes apt signing key
 get_url:
 url: https://pkgs.k8s.io/core:/stable:/{{ k8s_minor }}/deb/Release.key
 dest: /tmp/k8s_key.gpg
 mode: "0644"
 timeout: 30
 - name: Ensure temporary GNUPG home for dearmor
 file:
 path: /etc/apt/keyrings/gnupg
 state: directory
 mode: "0700"
 owner: root
 group: root
 - name: Dearmor Kubernetes Release.key to keyring (idempotent)
 command: |
 /usr/bin/gpg --dearmor --yes --batch --no-tty --output {{ k8s_keyring }} /tmp/k8s_key.gpg
 environment:
 GNUPGHOME: /etc/apt/keyrings/gnupg
 args:
 creates: '{{ k8s_keyring }}'
 - name: Ensure permissions on Kubernetes keyring
 file:
 path: '{{ k8s_keyring }}'
 mode: "0644"
 - name: Configure Kubernetes apt repository
 copy:
 dest: '{{ k8s_list }}'
 mode: "0644"
 content: |
 deb [signed-by={{ k8s_keyring }}] https://pkgs.k8s.io/core:/stable:/{{ k8s_minor }}/deb/ /
 - name: apt-get update for Kubernetes repo
 apt:
 update_cache: yes
 - name: Install kubelet, kubeadm, kubectl for {{ k8s_minor }}
 apt:
 name:
 - kubelet
 - kubeadm
 - kubectl
 state: present
 - name: Hold kube packages (no unintended upgrades)
 command: apt-mark hold kubelet kubeadm kubectl
 changed_when: false
 - name: Enable kubelet
 systemd:
 name: kubelet
 enabled: true
 state: started

설치하기

k8s-install.yml을 실행하여 플레이북을 실행한다

1

ansible-playbook k8s-install.yml

🕹️ Control Plane 초기화

단일 Control Plane 구성

kubeadm init으로 Control Plane을 초기화한다

1

kubeadm init --pod-network-cidr=10.43.0.0/16

조금만 기다리면, 아래와 같은 결과가 나온다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


Your Kubernetes control-plane has initialized successfully!

To start using your cluster, you need to run the following as a regular user:

 mkdir -p $HOME/.kube
 sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
 sudo chown $(id -u):$(id -g) $HOME/.kube/config

Alternatively, if you are the root user, you can run:

 export KUBECONFIG=/etc/kubernetes/admin.conf

You should now deploy a pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the options listed at:
 https://kubernetes.io/docs/concepts/cluster-administration/addons/

Then you can join any number of worker nodes by running the following on each as root:

kubeadm join 192.168.0.4:6443 --token <token> \
 --discovery-token-ca-cert-hash sha256:<hash>

HA구성

(미완, 추후 추가예정)

🛜 네트워크 플러그인 설치

쿠버네티스에는 여러 네트워크 플러그인이 존재합다

Flanner
Calico
Cilium
기타(클라우트 환경 CNI 등)

여기서는 떠오르고 있는 CNI인 Cilium을 설치합다.

Cilium은 L7정책, 네트워크 가시성, 서비스 메시 등의 기능들을 강력히 제공합다

기존 kube-proxy제거

1

kubectl delete kube-proxy -n kube-system

cilium CLI를 이용한 설치

Linux 기준

1
2
3
4
5
6
7


CILIUM_CLI_VERSION=$(curl -s https://raw.githubusercontent.com/cilium/cilium-cli/main/stable.txt)
CLI_ARCH=amd64
if [ "$(uname -m)" = "aarch64" ]; then CLI_ARCH=arm64; fi
curl -L --fail --remote-name-all https://github.com/cilium/cilium-cli/releases/download/${CILIUM_CLI_VERSION}/cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}
sha256sum --check cilium-linux-${CLI_ARCH}.tar.gz.sha256sum
sudo tar xzvfC cilium-linux-${CLI_ARCH}.tar.gz /usr/local/bin
rm cilium-linux-${CLI_ARCH}.tar.gz{,.sha256sum}

1

cilium install --version 1.18.1

helm을 이용한 설치

cilium CLI 대신, helm으로 설치도 가능하다

1
2
3


helm install cilium cilium/cilium --version 1.18.1 \
 --namespace kube-system \
 --set kubeProxyReplacement=true # kube-proxy를 대체하기

설치 확인

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


root@ubuntu:~# cilium status --wait
 /¯¯\
 /¯¯\__/¯¯\  Cilium: OK
 \__/¯¯\__/ Operator: OK
 /¯¯\__/¯¯\  Envoy DaemonSet: OK
 \__/¯¯\__/ Hubble Relay: disabled
 \__/ ClusterMesh: disabled

DaemonSet cilium Desired: 1, Ready: 1/1, Available: 1/1
DaemonSet cilium-envoy Desired: 1, Ready: 1/1, Available: 1/1
Deployment cilium-operator Desired: 1, Ready: 1/1, Available: 1/1
Containers: cilium Running: 1
 cilium-envoy Running: 1
 cilium-operator Running: 1
 clustermesh-apiserver
 hubble-relay
Cluster Pods: 2/2 managed by Cilium
Helm chart version: 1.18.1
Image versions cilium quay.io/cilium/cilium:v1.18.1@sha256:65ab17c052d8758b2ad157ce766285e04173722df59bdee1ea6d5fda7149f0e9: 1
 cilium-envoy quay.io/cilium/cilium-envoy:v1.34.4-1754895458-68cffdfa568b6b226d70a7ef81fc65dda3b890bf@sha256:247e908700012f7ef56f75908f8c965215c26a27762f296068645eb55450bda2: 1
 cilium-operator quay.io/cilium/operator-generic:v1.18.1@sha256:97f4553afa443465bdfbc1cc4927c93f16ac5d78e4dd2706736e7395382201bc: 1
root@ubuntu:~#

연결 테스트하기

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


cilium connectivity test
ℹ️ Monitor aggregation detected, will skip some flow validation steps
✨ [kubernetes] Creating namespace cilium-test-1 for connectivity check...
✨ [kubernetes] Deploying echo-same-node service...
✨ [kubernetes] Deploying DNS test server configmap...
✨ [kubernetes] Deploying same-node deployment...
✨ [kubernetes] Deploying client deployment...
✨ [kubernetes] Deploying client2 deployment...
⌛ [kubernetes] Waiting for deployment cilium-test-1/client to become ready...
⌛ [kubernetes] Waiting for deployment cilium-test-1/client2 to become ready...
⌛ [kubernetes] Waiting for deployment cilium-test-1/echo-same-node to become ready...
⌛ [kubernetes] Waiting for pod cilium-test-1/client-64d966fcbd-72mrh to reach DNS server on cilium-test-1/echo-same-node-65dd6bdb5c-dl4g8 pod...
⌛ [kubernetes] Waiting for pod cilium-test-1/client2-5f6d9498c7-4cdpn to reach DNS server on cilium-test-1/echo-same-node-65dd6bdb5c-dl4g8 pod...
⌛ [kubernetes] Waiting for pod cilium-test-1/client-64d966fcbd-72mrh to reach default/kubernetes service...
⌛ [kubernetes] Waiting for pod cilium-test-1/client2-5f6d9498c7-4cdpn to reach default/kubernetes service...
⌛ [kubernetes] Waiting for Service cilium-test-1/echo-same-node to become ready...
⌛ [kubernetes] Waiting for Service cilium-test-1/echo-same-node to be synchronized by Cilium pod kube-system/cilium-rl58t
⌛ [kubernetes] Waiting for NodePort 192.168.0.4:32364 (cilium-test-1/echo-same-node) to become ready...
ℹ️ Skipping IPCache check
🔭 Enabling Hubble telescope...
⚠️ Unable to contact Hubble Relay, disabling Hubble telescope and flow validation: rpc error: code = Unavailable desc = connection error: desc = "transport: Error while dialing: dial tcp 127.0.0.1:4245: connect: connection refused"
ℹ️ Expose Relay locally with:
 cilium hubble enable
 cilium hubble port-forward&
ℹ️ Cilium version: 1.18.1
🏃[cilium-test-1] Running 123 tests ...

(중략)
.........

✅ [cilium-test-1] All 74 tests (295 actions) successful, 49 tests skipped, 0 scenarios skipped.

👬 Worker Node 조인시키기

kubeadm init의 결과로, 아래와 같은 부분이 있는데, 이를 Worker Node에서 실행하면 된다

1
2


kubeadm join <Control-Plane>:6443 --token <token> \
 --discovery-token-ca-cert-hash sha256:<hash>

🔑 관리자 자격 증명 가져오기

context를 내 로컬(개인 PC 및 노트북)에 가져오면, 원격으로 kubectl명령어를 사용할 수 있다.
context는 클러스터 정보 및 자격 증명의 조합 을 말합다.

처음 kubectl을 사용하는 경우

kubeadm init의 결과로, 아래와 같은 부분이 나왔을 겁니다.
즉, Control Plane의 /etc/kubernetes/admin.conf를 자신의 ~/.kube/config로 가져오면 된다.
scp등을 이용할 수 있다.

1
2
3


mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

기존 config에 context를 추가하는 경우

우선, admin의 설정 파일을 로컬로 가져온다

1

scp <remote-user>:<control-plane>:/etc/kubernetes/admin.conf ~/admin.conf

그 뒤, 기존 설정 파일과 가져온 설정파일을 병합한다

1

KUBECONFIG=~/.kube/config:~/admin.conf kubectl config view --flatten > ~/merged; mv ~/merged ~/.kube/config

(Optional)컨텍스트의 이름을 변경할 수 있다.

1

kubectl config rename-context kubernetes-admin@kubernetes <새 컨텍스트 이름>

💻 CLI 도구 모음

Tekton: Git 레포지토리로부터 Pull 해오기

Mon, 18 Aug 2025 01:15:38 +0900

🔖 Pipeline 정의

Community Hub에서 재사용 가능한 Task와 Pipeline들이 공유되고 있다.
여기서는 하나의 Task를 써볼 것이다. pipeline.yaml을 작성한다.

Pipeline 선언

1
2
3
4


apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
 name: clone-read

clone-read이름은 PipelineRun에서 참조할 Run이 된다.
CLI에서 로그 확인 및 파이프라인 제거 등에도 쓰일 수 있다.

파라미터 입력

spec에서 파라미터 리스트를 입력할 수 있다.

1
2
3
4
5
6
7


spec:
 description: | 
 This pipeline clones a git repo, then echoes the README file to the stdout.
 params:
 - name: repo-url
 type: string
 description: The git repo URL to clone from.

여기서는 repo-url이란 이름의 파라미터를 하나 쓰고 있다.

Workspace 정의

1
2
3
4
5


workspaces:
- name: shared-data
 description: | 
 This workspace contains the cloned repo files, so they can be read by the
 next task.

Task가 코드를 받아올 shared-data을 정의한다.

Task 정의

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


tasks:
- name: fetch-source
 taskRef:
 name: git-clone
 workspaces:
 - name: output
 workspace: shared-data
 params:
 - name: url
 value: $(params.repo-url)

fetch-source라는 이 task는 git-clone이라는 다른 Task를 참조하는데, community hub에서 받아와야 한다.
Task에는 사용할 params와 workspaces를 정의가능하다.

🏃 PipelineRun 정의

실제 인스턴스가 될 PipelineRun을 만들어주자.

PipelineRun 선언

pipelinerun.yaml을 만들어주자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
 generateName: clone-read-run-
spec:
 pipelineRef:
 name: clone-read
 podTemplate:
 securityContext:
 fsGroup: 65532

이 PipelineRun은 pipelineRef를 이용하여 clone-read로부터 인스턴스를 만든다.

Workspace 실제 사용

1
2
3
4
5
6
7
8
9


workspaces:
- name: shared-data
 volumeClaimTemplate:
 spec:
 accessModes:
 - ReadWriteOnce
 resources:
 requests:
 storage: 1Gi

이 PVC정의는 shared-data 워크스페이스와 매칭된다.

파라미터 입력

1
2
3


params:
- name: repo-url
 value: https://github.com/tektoncd/website

Tekton에서 제공되는 공식 저장소 주소를 입력한다.

📜 두 번째 Task 정의

리스트에 새로운 Task 추가하기

pipeline.yaml에 새로운 Task를 리스트에 추가해보자:

1
2
3
4
5
6
7


- name: show-readme
 runAfter: ["fetch-source"]
 taskRef:
 name: show-readme
 workspaces:
 - name: source
 workspace: shared-data

커스텀 Task 정의

show-readme.yaml을 아래와 같이 작성하자:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
 name: show-readme spec:
 description: Read and display README file.
 workspaces:
 - name: source
 steps:
 - name: read
 image: alpine:latest
 script: | 
 #!/usr/bin/env sh
 cat $(workspaces.source.path)/README.md

workspace에서 이전 작업에서 받은 레포지토리에서 cat명령을 수행한다.

🚀 파이프라인 실행하기

외부 Task 설치

tkn 명령으로 git-clone Task를 설치한다.

1

tkn hub install task git-clone

또는 kubectl로도 설치 가능하다.

1
2


kubectl apply -f \
https://raw.githubusercontent.com/tektoncd/catalog/main/task/git-clone/0.6/git-clone.yaml

파일 적용하기

우선 정의한 Task부터 설치한다

1

kubectl apply -f show-readme.yaml

Pipeline을 적용시킨다:

1

kubectl apply -f pipeline.yaml

PipelineRun을 적용시킨다:

1

kubectl create -f pipelinerun.yaml

아래와 같은 로그가 뜬다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


➜ tkn pipelinerun logs clone-read-run-01 -f
[fetch-source : clone] + '[' false '=' true ]
[fetch-source : clone] + '[' false '=' true ]
[fetch-source : clone] + '[' false '=' true ]
[fetch-source : clone] + CHECKOUT_DIR=/workspace/output/
[fetch-source : clone] + '[' true '=' true ]
[fetch-source : clone] + cleandir
[fetch-source : clone] + '[' -d /workspace/output/ ]
[fetch-source : clone] + rm -rf /workspace/output//lost+found
[fetch-source : clone] + rm -rf '/workspace/output//.[!.]*'
[fetch-source : clone] + rm -rf '/workspace/output//..?*'
[fetch-source : clone] + test -z
[fetch-source : clone] + test -z
[fetch-source : clone] + test -z
[fetch-source : clone] + git config --global --add safe.directory /workspace/output
[fetch-source : clone] + /ko-app/git-init '-url=https://github.com/tektoncd/website' '-revision=main' '-refspec=' '-path=/workspace/output/' '-sslVerify=true' '-submodules=true' '-depth=1' '-sparseCheckoutDirectories='
[fetch-source : clone] {"level":"info","ts":1755359404.1654475,"caller":"git/git.go:176","msg":"Successfully cloned https://github.com/tektoncd/website @ a5a5f1de2ff535ff82f63830fb3f9d03773eb71c (grafted, HEAD, origin/main) in path /workspace/output/"}
[fetch-source : clone] {"level":"info","ts":1755359404.190729,"caller":"git/git.go:215","msg":"Successfully initialized and updated submodules in path /workspace/output/"}
[fetch-source : clone] + cd /workspace/output/
[fetch-source : clone] + git rev-parse HEAD
[fetch-source : clone] + RESULT_SHA=a5a5f1de2ff535ff82f63830fb3f9d03773eb71c
[fetch-source : clone] + EXIT_CODE=0
[fetch-source : clone] + '[' 0 '!=' 0 ]
[fetch-source : clone] + git log -1 '--pretty=%ct'
[fetch-source : clone] + RESULT_COMMITTER_DATE=1754472027
[fetch-source : clone] + printf '%s' 1754472027
[fetch-source : clone] + printf '%s' a5a5f1de2ff535ff82f63830fb3f9d03773eb71c
[fetch-source : clone] + printf '%s' https://github.com/tektoncd/website

[show-readme : read] # TektonCD Website
[show-readme : read]
[show-readme : read] This repo contains the code behind [the Tekton org's](https://github.com/tektoncd)
[show-readme : read] website at [tekton.dev](https://tekton.dev).
[show-readme : read]
[show-readme : read] For more information on the Tekton Project, see
[show-readme : read] [the community repo](https://github.com/tektoncd/community).
[show-readme : read]
[show-readme : read] For more information on contributing to the website see:
[show-readme : read]
[show-readme : read] * [CONTRIBUTING.md](CONTRIBUTING.md)
[show-readme : read] * [DEVELOPMENT.md](DEVELOPMENT.md)

전체 마니페스트

show-readme.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
 name: show-readme
spec:
 description: Read and display README file.
 workspaces:
 - name: source
 steps:
 - name: read
 image: alpine:latest
 script: | 
 #!/usr/bin/env sh
 cat $(workspaces.source.path)/README.md

pipeline.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
 name: clone-read
spec:
 description: | 
 This pipeline clones a git repo, then echoes the README file to the stout.
 params:
 - name: repo-url
 type: string
 description: The git repo URL to clone from.
 workspaces:
 - name: shared-data
 description: | 
 This workspace contains the cloned repo files, so they can be read by the
 next task.
 - name: git-credentials
 description: My ssh credentials
 tasks:
 - name: fetch-source
 taskRef:
 name: git-clone
 workspaces:
 - name: output
 workspace: shared-data
 - name: ssh-directory
 workspace: git-credentials
 params:
 - name: url
 value: $(params.repo-url)
 - name: show-readme
 runAfter: ["fetch-source"]
 taskRef:
 name: show-readme
 workspaces:
 - name: source
 workspace: shared-data

pipelinerun.yaml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
 generateName: clone-read-run-
spec:
 pipelineRef:
 name: clone-read
 podTemplate:
 securityContext:
 fsGroup: 65532
 workspaces:
 - name: shared-data
 volumeClaimTemplate:
 spec:
 accessModes:
 - ReadWriteOnce
 resources:
 requests:
 storage: 1Gi
 - name: git-credentials
 secret:
 secretName: git-credentials
 params:
 - name: repo-url
 value: git@github.com:tektoncd/website.git

📚 결론

Task는 직접 정의할 수 있고, 커뮤니티에서 만들어진 Task를 사용할 수 있다.
Params로 파라미터를 넣을 수 있고, Workspace로 작업 공간을 공유할 수 있다.
적용 순서는 다음과 같다:
- Task 설치 및 적용
- Pipeline 적용
- PipelineRun 적용

Tekton 시작하기: 소개 및 설치

Sun, 17 Aug 2025 23:02:54 +0900

🧑‍🚀 Tekton이란

Tekton 은 Kubernetes Native CI/CD 솔루션이다.
Tekton은 쿠버네티스의 확장으로 설치되며, 쿠버네티스에서 커스텀 리소스로 존재하여, CLI로도 다뤄질 수 있다.

💜 Tekton의 장점

Customizable:
Task, Pipeline, Step, Workspace, Resource 등이 모두 CRD(Custom Resource Definition) 로 되어 있어서, 조합 및 확장가능하다.
Reusable:
같은 Task를 여러 Pipeline에서 재사용 할 수 있고, 파라미터나 워크스페이스를 적용하면 다양한 워크플로우에 재사용할 수 있다.
Tekton Hub에서 공개된 Task도 가져다 쓸 수 있다.
Expandable:
미리 만들어진 Task들로 파이프라인을 구성할 수 있고, 새로운 Task를 조직해서 표준으로 공유 가능하다.
Standardized:
쿠버네티스 네이티브 방식으로 편하게 관리할 수 있다.
kubectl로 관리 가능하고, Knative 또는 ArgoCD와의 궁합이 좋다.
Scalable:
쿠버네티스 자원이기에, 노드만 추가된다면 파이프라인도 더 확장된다.
리소스 제한도 직접 지정 가능하다.

즉, 가볍고, 유연하고, 확장 가능한 파이프라인을 구성할 수 있다.
게다가, RBAC, 네임스페이스 격리 의 쿠버네티스 장점들이 그대로 녹아있다.

🆚 Tekton vs Other Solutions

물론 Tekton이 완벽한 것은 아니지만, 다른 솔루션들 대비해서 여러 강점들을 보인다:

Jenkins 는 강력하지만, 오래 된 도구이며, 플러그인 및 에이전트 관리에 대한 복잡함과, Groovy에 대한 진입 장벽이 있다.

쿠버네티스에서 Jenkins를 이용할 수도 있지만, Tekton 대비 리소스 오버헤드가 크다.
그에 비해, Tekton은 마치 서버리스처럼 클러스터에서 동작한다.
또한, Tekton은 YAML로 관리되어, 파이프라인을 더 간결한 코드로 관리할 수 있다.

GitHub Actions 나 GitLab CI 도 강력하지만…

무료로 제공받는 Runner는 캐시 효율이 떨어진다.
자체 Runner를 사용하면, 별도의 서버 관리의 불편함이 생긴다.

Tekton도 단점이 있다.

러닝 커브(GitHub Actions, GitLab CI보다 어려움)
레퍼런스 및 커뮤니티 규모 작음
UI 제한적

👥 Tekton 구성요소

Tekton Pipelines
쿠버네티스 CRD로, CI 파이프라인을 정의하고 실행하는 핵심 컴포넌트
Tekton Triggers
이벤트(Webhook 등)로 파이프라인을 자동으로 시작하게 함
Tekton CLI
Tekton 리소스를 조회/실행/로그확인 하는 CLI도구
Tekton Dashboard
파이프라인/태스크 상태와 로그를 확인할 수 있는 웹 UI
Tekton Catalog
커뮤니티에서 공유되는 표준 Task/Pipeline 저장소
Tekton Hub
Catalog의 웹 포털
Tekton Operator
Tekton 설치 및 업데이트를 오퍼레이터 패턴으로 관리
Tekton Chain
빌드 아키텍트의 서명 및 프로비넌스 기록을 자동화하는 공급망 보안 컴포넌트

기본 개념

Task:
- 여러 Step(컨테이너 실행 단위)를 정의
- Step들은 하나의 Pod에서 순차적으로 실행되며, 하나의 Step 결과를 다음의 Step에서 활용가능(공유 볼륨 또는 워크스페이스)
Pipeline:
- 여러 단계의 복잡한 워크로드
- Task간 순서를 정의 가능하며, 이전 Task 결과를 다음 Task에서 활용가능
- 복잡한 CI/CD를 정의하는 상위 개념
TaskRun:
- Task가 실행된 인스턴스 및 기록
- 실행 로그, 성공 및 실패 상태, 사용된 파라미터 등을 담음
PipelineRun:
- Pipeline의 실행 인스턴스
- 내부적으로 여러 TaskRun이 실행되며, 전체 실행의 상태 및 결과 기록
- CI/CD파이프라인의 실행 히스토리로 남음

활용의 구분은 다음과 같다:

Task:
- 작은 작업
- 단독 실행 가능한 단순 워크로드
Pipeline:
- 여러 단계의 복잡한 워크로드
- 조건 분기, 에러 핸들링 등의 다양한 패턴 지원
- 엔드 투 엔드 CI/CD

🚀 Tekton 설치

Install Tekton Pipeline

Install Tekton CLI

📦 StorageClass 정의하기

Tekton은 영속적인 스토리지가 필요하다.
StorageClass를 정의하여 PV를 할당받을 수 있도록 해야 한다.

AWS EKS기준, 아래와 같다:

먼저, EKS Pod Identity 에이전트를 설치하여 Pod에게 IAM 권한을 부여하도록 해야 한다.
그 뒤, CSI 드라이버를 구성해줘야 한다.

StorageClass 정의 예시는 다음과 같다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
 name: gp3
provisioner: ebs.csi.aws.com
parameters:
 type: gp3
 fsType: ext4
 encrypted: "true"
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true

📚 요약

Tekton은 쿠버네티스 네이티브의 CI/CD 파이프라인 솔루션이다.
쿠버네티스에서 경량으로 동작하며, 쿠버네티스의 RBAC, namespace등의 기능, 오토스케일링 기능 등, 자원 할당 및 제한, 노드 선택 등의 다양한 기능을 사용할 수 있다.
러닝커브와 부족한 UI, 적은 레퍼런스가 단점이다.

Kubernetes: ServiceAccount

Sun, 17 Aug 2025 21:18:44 +0900

🔐 ServiceAccount란

ServiceAccount 란, 쿠버네티스 내에서 고유한 식별을 제공하는 kube-apiserver에 접근하는 자원을 위한 계정이다.
쉽게 생각하면, Pod의 쿠버네티스 클러스터 내 계정이라고 볼 수 있다.

ServiceAccount는 다음의 특징을 가진다:

Namespaced:
각 ServiceAccount는 쿠버네티스 네임스페이스에 종속된다.
모든 네임스페이스는 생성 이후, 기본 ServiceAccount를 가진다.
Lightweight:
ServiceAccount는 클러스터에 존재하고, Kubernetes API에 정의된다.
특정 작업의 허용을 위해, 빠르게 ServiceAccount를 만들어줄 수 있다.
Portable:
복잡한 워크로드 내에서의 설정 번들에서 시스템 컴포넌트로 사용될 수 있다.

ServiceAccount는 User Account와는 다르다.
기본적으로 User Account는 쿠버네티스의 API Server에 존재하지 않는다.
대신, API Server는 사용자 자격 증명을 불투명 데이터로 다룬다.
사용자 계정을 다양한 방법으로 인증 가능하다.
일부 쿠버네티스 배포판은 확장 API를 제공할 수 있다.

Description	ServiceAccount	User or Group
Location	Kubernetes API(ServiceAccount Object로 존재)	외부
Access Control	Kubernetes RBAC 또는 인가 메커니즘	Kubernetes RBAC 또는 다른 자격증명 및 접근 메커니즘들
Intended Use	워크로드 및 자동화	사람

Default ServiceAccount

쿠버네티스 클러스터가 생성되면, 자동으로 default ServiceAccount가 만들어진다.
가지고 있는 권한은 딱히 없다.
만약 제거된다면, 자동으로 다시 생성된다.
RBAC 가 켜져 있다면, “API-discovery”, 즉 API조회 수준의 작업밖에 할 수 없다.

Pod를 띄울 때 아무 SA를 주지 않으면, 해당 SA가 붙는다(spec.serviceAccountName으로 SA를 줄 수 있다)
이게 취약점이 될 수 있는데, 기본 SA 토큰이 주입되기 때문이다.
그래서, SA를 잘 지정하거나, automountServiceAccount를 false로 하여 자동 토큰 마운트를 비활성화할 필요가 있다.

🧱 ServiceAccount의 사용 사례

다음과 같은 상황에서 자격 증명을 주는 것이 필요할 수도 있다:

Pod들이 Kubernetes API와 통신이 필요한 경우
- Secrets에 저장된 정보를 Read-Only로 제공
- namespace간 통신
외부 서비스와 Pod들이 통신하는 경우
- 클라우드 제공자 또는 신뢰 관계에 있는 외부 제공자와의 상호작용
imagePullSecret을 사용하여 프라이빗 이미지 레지스트리에 제공하는 경우
Kubernetes API 서버와 통신이 필요한 외부 서비
서드 파티 보안 소프트웨에서의 사용

🔌 ServiceAccount를 사용하는 방법

ServiceAccount를 사용하기 위해서는 다음을 따르면 된다:

ServiceAccount 오브젝트를 생성
RBAC와 같은 인가 메커니즘을 ServiceAccount Object에 적용
Pod 생성에서 ServiceAccount 할당

ServiceAccount에 권한 할당하기

role-based access control(RBAC) 메커니즘으로 각 ServiceAccount에 최소권한을 할당할 수 있다.
Role을 만들어서, ServiceAccount에 Role을 bind해주면 된다.
Pod들이 필요한 기능에서의 권한만 사용하도록 할당을 해줄 수 있다.

Namespace간 접근

RBAC 를 이용하여 하나의 namespace에서 다른 namespace의 자원을 불러올 수 있도록 한다.
예를 들어, 모니터링 및 보안 도구들은 별도 네임스페이스에서 클러스터의 애플리케이션들로부터 여러 상태를 불러올 수 있는 것이다.

ServiceAccount를 Pod에 적용하기

spec.serviceAccountName으로 Pod에 ServiceAccount를 적용가능하다.
v1.22 이후로, 특정 볼륨으로 토큰이 마운트된다. 이 토큰은 수명이 짧고, 자동으로 업데이트되게 되어있다.
이전에는 Secret으로 정적 토큰이 긴 수명을 가졌다.

ServiceAccount credentials 받아오기

만약 일반적이지 않는 위치에 ServiceAccount를 마운트 시키고 싶거나, 다른 이유로 자격 증명을 별도 저장하고 싶다면, 다음의 방법들이 있다:

TokenRequest API: 애플리케이션으로 API 요청을 보내는 방법이다.
토큰은 수명이 짧고, 자동으로 갱신 요청을 직접 해야 한다.
Kubernetes API에 접근하기 어려운 애플리케이션이라면, 사이드카 컨테이너를 붙여서 공유 볼륨을 이용하면 되겠다.
Token Volume Projection: v1.20 이후로 가능한데, Pod spec에 projected volume을 지정하는 것이다.
kubelet은 해당 volume에 ServiceAccount 토큰을 주입하고, 자동 갱신해준다.
현재 가장 많이 쓰이는 방법이다.

이외에도, Service Account Token Secrets, LegacyServieAccountNoAutoGeneration feature gate도 있지만, 이들은 권장되지 않고, 버전 지원이 안 될수도 있다.

Note 클러스터 밖에서 실행되는데 자격 증명이 필요하다면, TokenRequest API또는 별도의 자격 증명 이용 방법이 권장된다.

✅ ServiceAccount credentials 인가

ServiceAccount는 JWT(Json Web Token) 을 사용한다.
API 서버에 접근하고자 하면, Authorization: Bearer <token>을 http 헤더에 붙이면 된다.
API 서버는 다음의 방법으로 토큰을 검증한다:

토큰 서명 검증
토큰이 만료되었는지 검증
참조 유효성 확인(해당 ServiceAccount및 관련 오브젝트가 존재하는지 체크)
토큰이 현재 유효한지 검증(nbf 검증)
Audience Claim을 확인

TokenRequest API로 발급된 토큰은 Pod 라이프사이클과 묶인 bound token을 제공한다. Pod가 삭제되면 같이 무효화되고, 특정 짧은 유효기간에 자동 회전(새 토큰으로 교체)된다.

💂 별도의 검증 방법

외부에서 SA에 대한 검증이 필요하다면, 다음의 방법이 있다:

TokenReview API(권장)
OIDC discovery

Object Lifecycle과 동기화된 토큰 검증이 가능해서 권장된다.

🟰 대안

Webhook Token Authentication등의 별도 검증 방안을 사용할 수 있다.
Pod에 별도 자격 증명을 부여할 수 있다. (X.509등)
클러스터 외부 OIDC 및 IAM 등 이용
기타 등등…

📚 요약

ServiceAccount는 쿠버네티스 리소스가 사용하는 계정이다.
토큰은 JWT를 이용한다.
발급은 TokenRequest API 이용 또는 Token Volume Projection이 권장된다. 단기 자격증명이여서 수명이 짧에 보안에 좋다.
- 오브젝트와 생명 주기가 동기화되어, 오브젝트의 존재 여부를 판단할 수도 있으며, 오브젝트 삭제 시에는 바로 만료 처리되어 안전하다.
외부에서 토큰 검증을 하려면, TokenReview API를 이용하는 것이 권장된다.
TokenRequest API를 이용하려면, admin인증서, 또는 클라우드 IAM, 기존 권한있는 SA 토큰 등이 필요하다.

Terraform: 반복문과 제어문

Thu, 07 Aug 2025 21:34:46 +0900

🔁 반복문

Count를 이용한 반복

테라폼 리소스에는 count라는 meta-argument가 있다.
count는 생성하고자 하는 리소스 사본 수만 정의하면 된다.

3명의 IAM 사용자는 다음과 같이 생성할 수 있다:

1
2
3
4


resource "aws_iam_user" "example" {
 count = 3
 name = "riveroverflow"
}

그러나, 이는 오류가 발생한다.
각 사용자의 이름이 유일해야 하는데, 같은 이름을 가지기 때문이다.

대신, count.index를 쓰면 각각의 반복을 가리키는 인덱스를 얻을 수 있다:

1
2
3
4


resource "aws_iam_user" "example" {
 count = 3
 name = "riveroverflow.${count.index}"
}

terraform plan을 해보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


Terraform will perform the following actions:

 # aws_iam_user.example[0] will be created
 + resource "aws_iam_user" "example" {
 + arn = (known after apply)
 + force_destroy = false
 + id = (known after apply)
 + name = "riveroverflow.0"
 + path = "/"
 + tags_all = (known after apply)
 + unique_id = (known after apply)
 }

 # aws_iam_user.example[1] will be created
 + resource "aws_iam_user" "example" {
 + arn = (known after apply)
 + force_destroy = false
 + id = (known after apply)
 + name = "riveroverflow.1"
 + path = "/"
 + tags_all = (known after apply)
 + unique_id = (known after apply)
 }

 # aws_iam_user.example[2] will be created
 + resource "aws_iam_user" "example" {
 + arn = (known after apply)
 + force_destroy = false
 + id = (known after apply)
 + name = "riveroverflow.2"
 + path = "/"
 + tags_all = (known after apply)
 + unique_id = (known after apply)
 }

Plan: 3 to add, 0 to change, 0 to destroy.

이름이 riveroverflow.[0~2]를 갖는 것을 볼 수 있다.

그러나, 일반적으로 이런 이름을 사용하지는 않는다.
대신, 아래와 같이 배열을 이용하면 여러 고유한 이름을 가진 3개의 IAM 사용자를 생성할 수 있다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_iam_user" "example" {
 count = length(var.names) # 길이를 구하는 내장 함수
 name = var.names[count.index] # 인덱스 참조
}

variable "names" {
 type = list(string)
 default = ["UserA", "UserB", "UserC"]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


Terraform will perform the following actions:

 # aws_iam_user.example[0] will be created
 + resource "aws_iam_user" "example" {
 + arn = (known after apply)
 + force_destroy = false
 + id = (known after apply)
 + name = "UserA"
 + path = "/"
 + tags_all = (known after apply)
 + unique_id = (known after apply)
 }

 # aws_iam_user.example[1] will be created
 + resource "aws_iam_user" "example" {
 + arn = (known after apply)
 + force_destroy = false
 + id = (known after apply)
 + name = "UserB"
 + path = "/"
 + tags_all = (known after apply)
 + unique_id = (known after apply)
 }

 # aws_iam_user.example[2] will be created
 + resource "aws_iam_user" "example" {
 + arn = (known after apply)
 + force_destroy = false
 + id = (known after apply)
 + name = "UserC"
 + path = "/"
 + tags_all = (known after apply)
 + unique_id = (known after apply)
 }

Plan: 3 to add, 0 to change, 0 to destroy.

리소스에 count를 쓰면, 하나의 리소스가 아니라 리소스의 배열이 된다.
이제, 배열 조회 구문과 결합하여, 아래와 같이 사용되어야 한다:

1

<PROVIDER>_<TYPE>.<NAME>[INDEX].ATTR

예를 들어, 유저 하나의 arn을 원한다면, 아래와 같이 할 수 있다:

1
2
3


output "user_a_arn" {
 value = aws_iam_user.example[0].arn # 0번 인덱스 참조
}

모든 유저의 arn을 원한다면, 아래와 같이 쓸 수 있다:

1
2
3


output "user_all_arn" {
 value = aws_iam_user.example[*].arn # 모든 인덱스 참조
}

그러나, count는 전체 리소스를 반복할 수는 있지만, 리소스 내의 인라인 블록을 반복할 수는 없다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


resource "aws_security_group" "example" {
 count = 2
 name_prefix = my-sg

 ingress {
 from_port = 8080
 to_port = 8080
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

이 선언은 보안 그룹을 두개만들 뿐, ingress를 여러 개 만들지 못한다.

또한, 위의 3개의 IAM계정을 생성하는 것에서, UserB를 없앤다고 해보자.

1
2
3
4


variable "names" {
 type = list(string)
 default = ["UserA", "UserC"] # UserB 제거
}

이 경우, 인덱스가 당겨져서 names[1] = "UserC"가 된다.

for_each 표현식

for_each를 사용하면, 리스트, 집합, 맵을 사용하여 전체 리소스의 여러 복사도 가능하고, 리소스 내 인라인 블록의 여러 복사를 생성할 수 있다.

1
2
3
4
5


resource "<PROVIDER>_<TYPE>" "<NAME>" {
 for_each <COLLECTION>

 [CONFIG...]
}

PROVIDER: aws와 같은 공급자
TYPE: instance와 같은 리소스 유형
NAME: 테라폼 코드 내부에서의 리소스 식별자
COLLECTION: 루프를 처리할 집합 또는 맵
(리스트는 지원하지 않는다)

1
2
3
4


resource "aws_iam_user" "example" {
 for_each = toset(var.names)
 name = each.value
}

이렇게 하면, names의 요소들로 IAM 유저들을 만든다.
리스트는 지원하지 않기에, 집합 또는 맵으로 바꿔야 한다.

for_each로 생성된 요소는 리소스 맵이 된다.
모든 요소의 arn을 출력하고 싶다면, 아래처럼 해야 한다:

1
2
3


output "all_arns" {
 value = values(aws_iam_user.example)[*].arn
}

for_each를 사용해서 리소스를 맵으로 처리하면, 컬렉션 중간의 항목도 안전하게 제거할 수 있는 이점이 있다.
리소스가 아닌 맵으로 결과가 저장되기 때문이다.

for_each는 여러 개의 인라인 블록을 만들 수 있다는 것이 장점이다.

모듈에서 아래와 같이 변수 추가를 한다고 해보자:

1
2
3
4


variable "custom_tags" {
 type = map(string)
 default = {}
}

루트 모듈에서는 이렇게 사용가능하다:

1
2
3
4
5
6
7


module "mymodule" {
 source = "";

 custom_tags = {
 Name = "foo"
 }
}

모듈 안에서는 이렇게 동적인 tag를 생성할 수 있다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


resource "aws_instance" "myec2" {
 ami = var.ami
 instance_type = var.instance_type

 dynamic "tag" {
 for_each = var.custom_tags
 content {
 key = tag.key
 value = tag.value
 propagate_at_launch = true
 }
 }
}

for 표현식

단일 값의 반복문은 어떨까?
for의 기본 구문을 다음과 같다: for <ITEM> in <LIST> : <OUTPUT>

1
2
3
4
5
6
7
8


variable "names" {
 type = list(string)
 default = ["UserA", "UserB", "UserC"]
}

output "upper_names" {
 value = [for name in var.names : upper(name)]
}

upper_names으로 이름들이 전부 대문자로 출력된다.
(USERA, USERB, USERC)

아래는 길이가 5 이하인 이름만 출력한다:

1
2
3
4
5
6
7
8


variable "names" {
 type = list(string)
 default = ["Ronaldo", "Messi", "Neymar"]
}

output "upper_names" {
 value = [for name in var.names : upper(name) if length(name) <= 5] # [MESSI] 만 출력됨
}

Map의 반복은 다음과 같다: [ for <KEY>, <VALUE> in <MAP> : <OUTPUT> ]
이는 리스트가 반환된다.

다음과 같이 Map으로의 출력도 가능하다:

1
2


[for <ITEM> in <LIST> : <OUTPUT_KEY> => <OUTPUT_VALUE>] # List to Map
{for <KEY>, <VALUE> in <MAP> : <OUTPUT_KEY> => <OUTPUT_VALUE>} # Map to Map

for 문자열 지시자

문자열 지시자를 사용하면 문자열 내에서 for 반복문, if와 같은 제어문을 사용할 수 있다.
사용법은 아래와 같다:

1

%{ for <ITEM> in <COLLECTION> }<BODY>%{ endfor }

COLLECTION: 반복할 리스트 또는 맵
ITEM: COLLECTION의 각 항목에 할당할 로컬 변수의 이름
BODY: ITEM을 참조할 수 있는 각각의 반복을 렌더링할 대상

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


variable "names" {
 type = list(string)
 default = ["Ronaldo", "Messi", "Neymar"]
}

output "for_directive" {
 value = <<EOF
 %{for name in var.names}
 ${name}
 %{endfor}
 EOF
}

terraform apply를 실행해보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


terraform apply

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

for_directive = <<EOT

 Ronaldo

 Messi

 Neymar

🟰 조건문

반복문이 있듯이, 조건문도 존재한다.

Count를 이용한 조건문

count = <EXPRESSION> ? 1 : 0>을 이용하면, 조건식에 따라서 해당 리소스를 생성할지 말지에 대한 여부를 정할 수 있다.

아래 예시에서, make_ec2가 true라면 인스턴스를 생성하고, false라면 생성하지 않는다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


resource "aws_instance" "ec2" {
 count = var.make_ec2 ? 1 : 0

 ami = var.ami
 instance_type = var.instance_type
}

variable "make_ec2" {
 type = bool
}

이를 응용하면, 범용 프로그래밍 언어에서의 if-else를 사용할 수 있다.
아래는 isadmin이 true이면 admin사용자를 만들고, 아니라면 user를 만든다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


resource "aws_iam_user" "user" {
 name = "user"
 count = var.isadmin ? 1 : 0
}

resource "aws_iam_user" "admin" {
 name = "admin"
 count = var.isadmin ? 0 : 1
}

variable "isadmin" {
 type = bool
}

for_each와 for를 이용한 조건문

for_each로도 조건 논리가 가능하다.
빈 컬렉션이라면, 0개의 리소스 또는 인라인 블록이 생성되고,
비지 않은 컬렉션이라면, 1개 이상의 리소스 또는 인라인 블록이 생성될 것이다.
비어 있는지에 대한 여부는 for를 이용하면 된다.

아래 예제는 enabled된 사용자만 생성한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


variable "users" {
 default = [
 { name = "alice", enabled = true },
 { name = "bob", enabled = false },
 { name = "carol", enabled = true }
 ]
}

resource "null_resource" "enabled_users" {
 for_each = {
 for user in var.users : user.name => user
 if user.enabled
 }
}

아래 예제는 prod환경만 필터링한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


variable "servers" {
 default = {
 server1 = { env = "prod" }
 server2 = { env = "dev" }
 server3 = { env = "prod" }
 }

}

locals {
 prod_servers = {
 for name, config in var.servers : name => config
 if config.env == "prod"
 }
}

if 문자열 지시자 조건문

CONDITION은 불리언으로 평가되는 조건식이고, TRUEVAL은 CONDITION이 true로 평가되면 렌더링할 표현식이다.
else절도 포함 가능하다.

1
2
3


% {if <CONDITION> }<TRUEVAL>%{ endif }

% {if <CONDITION> }<TRUEVAL>%{ else }<FALSEVAL>%{ endif }

❗️ 테라폼을 사용할 때의 주의 사항

count와 for_each의 제한 사항

리소스 출력을 count또는 for_each에서 참조할 수 없음
plan단계에서 count와 for_each를 계산할 수 있어야 한다.
즉, 하드코딩된 값인 경우 참조 가능하지만, 이후에 계산되는 리소스 출력은 쓸 수 없다는 뜻이다.

plan이 유효함에도 실패

plan이 성공적이라고 해도 실제 적용이 오류가 나는경우가 많다.

대부분의 이유는, Terraform만을 사용하지 않고 일부를 콘솔에서 직접 건드렸다가 충돌이 나는 경우가 대부분이다.
tfstate는 테라폼이 관리하는 해당 루트 모듈에서의 상태만을 담기 때문이다.

테라폼을 사용하면 되도록 테라폼만 쓰자..
기존 인프라가 있다면 import를 쓰자..

리팩토링의 까다로움

코드에서의 식별자를 바꾸는 상황에서, 시스템 중단이 생길 수 있다. 같은 자원임에도 다르게 식별되어 삭제 후 재생성되기 때문 이다.
이러한 사소한 변화에도 민감하게 반응하기 때문에, 신중한 조정이 필요하다.

적용하기 이전에 참사를 줄이기 위해서..

항상 plan명령 사용
파기하기 전에 생성하기(create_before_destroy또는 수작업)
식별자 변경을 위한 상태 변경: terraform state mv를 이용
일부 매개변수를 변경할 수 없음
리소스의 공식 문서 참조 필요

최종 일관성

일부 클라우드 공급자의 API는 비동기적이며, 결국 일관성을 관리한다.
변경사항의 적용이 전체 시스템에 전파되는 데에는 시간이 걸리므로, 일정 기간 일관성 없는 응답을 받을 수 있다.

예를 들어, EC2의 생성이 되었다고 뜨지만, 아직 프로비저닝중인 경우가 있다.

VPC가 생성었는데 상태 동기화가 늦어서 리소스 생성의 오류가 날 수도 있다.
그러나, 이러한 문제는 대부분 terraform apply를 한번 더 선언해주면 해결된다.

📚 요약

count, for_each, for, if는 반복문 및 조건문, 그리고 필터링에 쓰인다.
테라폼의 구성을 리팩토링하는 것은 까다로우므로, 신중한 선택이 필요하다.

Terraform: 모듈(Modules)

Tue, 05 Aug 2025 20:51:30 +0900

🧱 모듈

Terraform은 기본적으로 현재 디렉토리에 있는 모든 .tf파일들을 불러와서, 하나의 구성 파일로 보고 의존 관계를 정리한 뒤, 자원을 순서에 맞게 생성한다.
이렇게 구성된 것들을 재사용할 수는 없을까?

모듈을 이용하면 코드를 재사용할 수 있다.
모듈은 재사용, 유지 관리 및 테스트 가능한 Terraform 코드를 작성하는 핵심 요소이다.

모듈은 조직 내에서 공유될 수도 있고, 온라인에 배포되어 사용될 수도 있다.

폴더에 있는 모든 Terraform 구성 파일 세트는 모듈이다.
모듈에서 직접 실행되면, 루트 모듈이라고 한다.
보통 모듈의 구성은 프로젝트의 modules/<리소스 종류>에 정의된다.

모듈 정의 및 사용 예시

간단한 EC2 서버 모듈을 하나 만들어보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


# modules/ec2/main.tf

provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_instance" "example" {
 ami = "ami-08943a151bd468f4e" # Ubuntu 22.04
 instance_type = var.instance_type
 vpc_security_group_ids = [aws_security_group.example_sg.id]

 user_data = <<-EOF
 #!/bin/bash
 apt-get update -y
 apt-get install -y apache2
 echo "<h2> Hello World! </h2>" > /var/www/html/index.html
 systemctl enable apache2
 systemctl start apache2
 EOF

 user_data_replace_on_change = true

 tags = {
 "Name" = "ec2"
 "environment" = var.environment
 }
}

resource "aws_security_group" "example_sg" {
 name = "myweb-sg"
 vpc_id = data.aws_vpc.default.id

 ingress {
 from_port = 80
 to_port = 80
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }

 egress {
 from_port = 0
 to_port = 0
 protocol = "-1"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

data "aws_vpc" "default" {
 default = true
}

variable "instance_type" {
 type = string # default가 없으면 required이다.
}

variable "environment" {
 type = string
 default = "dev" # default가 있으면 optional하다.
}

그 뒤, 이런 식으로 사용하면 된다:

1
2
3
4
5


module "myserver" {
 source = "./modules/ec2" # 디렉토리를 맞춰줘야 한다.

 instance_type = "t3.micro" # instance_type은 required이므로, 반드시 선언해야 한다.
}

모듈에는 변수를 지정해서 자리를 만들어놓고, 모듈을 사용하는 시스템에서 변수를 지정해서 사용하면 된다.

적용해보자. 모듈의 추가 또는 관련 정보를 바꿀 때에도 init이 필요하다.

1
2


terraform init
terraform apply

모듈 output 사용하기

출력 변수를 사용하여 퍼블릭 IP를 출력하게 할 수는 없을까? 물론 가능하다.
그러나, 이중으로 출력 작업이 필요하다.
모듈 정의에서 출력하고, 사용하는 루트 모듈에서 출력해야 한다.
모듈은 캡슐화되어있기 때문이다.

modules/helloserver/main.tf에 아래 스니펫을 추가하자.

1
2
3
4


output "public_ip" {
 description = "The public IP address of the EC2 instance"
 value = aws_instance.example.public_ip
}

그리고, 루트 모듈에도 정의해주자.

1
2
3


output "public_ip" {
 value = module.myserver.public_ip
}

다시 적용해보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


➜ terraform apply -auto-approve
module.myserver.data.aws_vpc.default: Reading...
module.myserver.data.aws_vpc.default: Read complete after 1s [id=vpc-063724386f9ff7382]
module.myserver.aws_security_group.example_sg: Refreshing state... [id=sg-0290d12641c27eac8]
module.myserver.aws_instance.example: Refreshing state... [id=i-09e6320eba5984532]

Changes to Outputs:
 + public_ip = "52.78.5.192"

You can apply this plan to save these new output values to the Terraform state, without changing any real infrastructure.

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

public_ip = "52.78.5.192"

➜ curl $(terraform output -raw public_ip)
<h2> Hello World! </h2>

local 변수

그러면, 모든 변수를 외부 루트 모듈에서의 사용으로부터 받아야 할까?
모듈 정의 내부에서만 편리하게 재사용할 수 있는 방법은 없을까?
이러한 문제를 해결해주는 것이 local변수이다.

아래 예시를 참고하자. 포트 번호를 local변수로 사용하고 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67


provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_instance" "example" {
 ami = "ami-08943a151bd468f4e" # Ubuntu 22.04
 instance_type = var.instance_type
 vpc_security_group_ids = [aws_security_group.example_sg.id]

 user_data = <<-EOF
 #!/bin/bash
 apt-get update -y
 apt-get install -y apache2
 echo "<h2> Hello World! </h2>" > /var/www/html/index.html
 systemctl enable apache2
 systemctl start apache2
 EOF

 user_data_replace_on_change = true

 tags = {
 "Name" = "ec2"
 "env" = var.environment
 }
}

resource "aws_security_group" "example_sg" {
 name = "myweb-sg"
 vpc_id = data.aws_vpc.default.id

 # local은 이렇게 사용할 수 있다.
 ingress {
 from_port = local.port
 to_port = local.port
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }

 egress {
 from_port = 0
 to_port = 0
 protocol = "-1"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

data "aws_vpc" "default" {
 default = true
}

# 로컬 변수 정의
locals {
 port = 80
}

variable "instance_type" {
 type = string
}

variable "environment" {
 type = string
}

output "public_ip" {
 description = "The public IP address of the EC2 instance"
 value = aws_instance.example.public_ip
}

환경 나눠보기

dev, stage, prod등의 여러 환경으로 나눌 때, 모듈은 용이하다.
아래와 같이 구성을 할 수 있겠다(예시일 뿐이다):

이렇게 구성한 뒤, 각 환경에서 모듈에 각각 상이하게 입력변수들을 넣어서 사용하면 되겠다.

global과 같은 곳에는 IAM 등을 것을 정의하면 좋겠고,
tfstate도 환경별로 원격 저장 벡엔드를 분리하면 좋을 것이다.

🏷️ 모듈 버저닝

이전에는 로컬에 버전을 참조하고 있는데, 대신 모듈을 VCS(Version Control System) 등에서 관리하도록 하면 더욱 편할 것이다.
모듈에 git tag등으로 버전 지정이 가능해지고, 모듈과 실제 환경들의 각 루트 모듈과의 분리된 저장으로 더욱 유연한 관리가 가능하다.

Terraform의 모듈은 Git, HTTPS등의 여러 모듈 리소스를 지원한다.
모듈을 별도의 레포지토리로 구성하여 이와 같이 커밋 및 푸시해주면 된다.

1
2
3
4
5
6


cd modules/ec2
git init
git add .
git commit -m "Initial commit"
git remote add origin "(URL OF REMOTE REPOSITORY)"
git push origin main

아래와 같이 git tag를 달아줄 수도 있다:

1
2


git tag -a "v0.0.1" -m "First Tag"
git push --follow-tags

이제, 리포트 레포지토리로부터 가져올 수 있다:

1
2
3
4
5


module "myserver" {
 source = "github.com/<user>/<repo>//ec2?ref=v0.0.1"
 instance_type = "t3.micro"
 environment = "prod"
}

여기서 terraform init을 하면, 다운로드를 받는 것을 알 수 있다.
로컬 모듈을 제외하고, 원격 모듈이나 외부 모듈을 사용하는 경우, 반드시 다운받는다.

이러한 방법을 사용하면, 모듈을 업데이트하고 리모트 레포지토리에 푸시된 이후, 태그만 잘 업데이트된다면, 여러 버전의 모듈들을 사용할 수 있다.

🌐 외부 모듈 사용하기

Terraform Registry에는 다양한 모듈들이 올라와 있다.
이곳에서 여러 모듈을 사용할 수 있다.

예를 들어, AWS의 VPC 모듈을 사용한다고 해보자.
두 개의 가용영역을 사용하고, 각각 퍼블릭 서브넷, 프라이빗 서브넷, DB 서브넷을 하나씩 만들어 줄 것이다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


module "vpc" {
 source = "terraform-aws-modules/vpc/aws"
 version = "6.0.1"

 name = "my-vpc"
 cidr = "10.0.0.0/16"

 azs = ["ap-northeast-2a", "ap-northeast-2c"]
 public_subnets = ["10.0.1.0/24", "10.0.2.0/24"]
 private_subnets = ["10.0.101.0/24", "10.0.102.0/24"]
 database_subnets = ["10.0.201.0/24", "10.0.202.0/24"]

 # Single NAT Gateway setup
 enable_nat_gateway = true
 single_nat_gateway = false
 one_nat_gateway_per_az = true

 tags = {
 Terraform = "true"
 Environment = "dev"
 }
}

초기화 후 적용해보자:

1
2


terraform init
terraform apply

잘 만들어진 것을 볼 수 있다!

📚 요약

Terraform은 현재 디렉토리의 모든 .tf파일들을 읽어서 하나의 구성으로 간주하는데, 이 하나의 단위를 모듈이라고 한다.
루트 모듈에서 여러 모듈들을 꺼내서 쓸 수 있다.
git, https등 여러 방법으로 모듈을 가져올 수 있고, Terraform Registry등의 외부 모듈도 사용이 가능하다
모듈을 통해 반복되는 자원 정의를 재사용할 수 있고, 특히 환경 분리에 용이하다.

Terraform: 상태 관리하기

Tue, 05 Aug 2025 00:00:22 +0900

💜 State

Terraform을 실행할 때마다, 생성된 인프라에 대한 정보가 기록된다.
실행된 곳에서 terraform.tfstate파일을 생성한다.

구성 파일의 Terraform의 리소스에서 실제 리소스 표현으로의 매핑을 기록하는 JSON이 포함되어 있다.

상태 파일은 비공개 API로, 직접 편집하면 안된다.
상태를 조작해야 하는 경우, terraform import 또는 terraform state명령을 사용해야 한다.

개인 프로젝트에서는 로컬에 terraform.tfstate를 저장하고 사용하는 것은 별 문제가 없다.
그러나, 실제 프로덕션에서 협업하는 경우, 일부 문제에 직면하게 된다.

상태 파일을 위한 공유 저장소
state는 공유된 위치에 저장되어야 한다.
상태 파일 잠금
동시성 문제가 생길 수 있다.
상태 파일 격리
또한, test, production등 환경의 격리가 필요하다.

📦 상태 파일을 위한 공유 저장소

원격 벡엔드 사용하기

공통의 저장소가 필요하지만, Git과 같은 버전 컨트롤에 맡기는 것은 좋지 않다.
다음의 문제가 있기 때문이다:

수동작업 오류
버전 제어에서 최신 변경사항을 풀다운하거나 실행한 후 버전 제어에 최신 변경 사항을 푸시하는 것을 잊어버리기 쉽다
잠금
동시적인 apply시의 잠금을 제공하지 않아 위험하다.
비밀(secret)
상태 파일의 모든 데이터는 일반 텍스트로 저장되기에, private하게 저장할 방법이 필요하다.

가장 좋은 방법은, Terraform에서 제공하는 원격 벡엔드 지원 을 사용하는 것이다.
Terraform 벡엔드는 Terraform이 상태를 저장하고 불러오는 방법을 결정한다.
기본 벡엔드는 로컬에 저장하는 로컬 벡엔드인데, 원격 벡엔드를 이용하면 상태 파일을 원격 공유 저장소에 저장할 수 있다.
위의 문제점들을 모두 해결한다.

AWS의 경우, S3와 DynamoDB를 이용하여 원격 벡엔드를 구성할 수 있다.
AWS S3는 다음의 이점이 있다:

관리형 서비스로, 매우 편리
11-nines(99.999999999%)의 가용성 보장
암호화를 지원(via KMS)
DynamoDB를 통한 잠금 지원
버전 관리 지원
저럼한 가격

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_s3_bucket" "terraform_state" {
 bucket = "YOUR_BUCKET_NAME" # 고유해야 함

 lifecycle {
 prevent_destroy = true # 중요한 리소스의 삭제 보호
 }
}

# 버저닝 활성화
resource "aws_s3_bucket_versioning" "enabled" {
 bucket = aws_s3_bucket.terraform_state.id
 versioning_configuration {
 status = "Enabled"
 }
}

#디폴트로 서버 측 암호화 활성화
resource "aws_s3_bucket_server_side_encryption_configuration" "default" {
 bucket = aws_s3_bucket.terraform_state.id
 rule {
 apply_server_side_encryption_by_default {
 sse_algorithm = "AES256"
 }
 }
}

#퍼블릭 액세스 허용
resource "aws_s3_bucket_public_access_block" "public_access" {
 bucket = aws_s3_bucket.terraform_state.id
 block_public_acls = true
 block_public_policy = true
 ignore_public_acls = true
 restrict_public_buckets = true
}


# dynamoDB 설치
resource "aws_dynamodb_table" "terraform_locks" {
 name = "terraform-locks"
 billing_mode = "PAY_PER_REQUEST"
 hash_key = "LockID"
 attribute {
 name = "LockID"
 type = "S"
 }
}

이 구조는 실제 tfstate가 S3에 저장되고, DynamoDB가 엑세스를 요청받아 상태의 lock을 관리 하도록 하고 있다.

이제, 명령을 실행하여 적용해보자.

1
2


terraform init
terraform apply

배포되면, 이제 벡엔드를 원격으로 옮기자.
main.tf의 맨 앞에 벡엔드 설정을 해주자.

1
2
3
4
5
6
7
8
9


terraform {
 backend "s3" {
 bucket = "riveroverflow-777" # 버킷 네임
 key = "global/s3/terraform.tfstate" # 저장하는 tfstate의 key
 region = "ap-northeast-2"
 dynamodb_table = "terraform-locks" # DynamoDB 테이블
 encrypt = true # 암호화 켬
 }
}

다시 초기화하면, 벡엔드가 이제 S3에 저장된다.

❗️ 주의 사항

이렇게 구성하면, 여러 주의 사항이 있다.

Terraform과 State 순서

구성할 때에는 아래와 같이 사용해야 한다:

Terraform 코드를 작성하여 S3버킷과 DynamoDB 테이블 생성 후, 로컬 벡엔드 잠시 사용
새로 생성된 S3버킷 및 DynamoDB를 쓰도록 구성 추가 후 상태를 S3에 복사

삭제할 때에는 다음과 같다:

Terraform 코드로 이동하여 벡엔드 구성 제거 후, 다시 init하여 복사
terraform destroy로 실행하여 자원 정리

약간 어색한 구조일 수 있으나, 처음에만 잘 구성해놓으면 유용하다.

변수나 참조

벡엔드 블록에서는 변수나 참조의 사용이 불가능 하다.
즉, 아래처럼 사용할 수 없다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# This will NOT work. Variables aren't allowed in a backend configuration.
terraform {
 backend "s3" {
 bucket = var.bucket
 region = var.region
 dynamodb_table = var.dynamodb_table
 key = "example/terraform.tfstate"
 encrypt = true
 }
}

이러면, 값을 할당할 때, 반복적인 작업이 생길 수 있는데, 이를 줄이려면, 부분 구성을 하면 된다.
예를 들어, bucket, region등의 인수를 backend.hcl에 추출할 수 있다.

1
2
3
4
5


# backend.hcl
bucket = "terraform-state-ID"
region = "ap-northeast-2"
dynamodb_table = "terraform-locks"
encrypt = true

벡엔드 구성은 아래처럼 간단해진다:

1
2
3
4
5


terraform {
 backend "s3" {
 key = "example/terraform.tfstate"
 }
}

그 뒤, 이렇게 초기화하면 된다:

1

terraform init -backend-config=backend.hcl

그러나, 여전히 모든 모듈에서 고유 키 값을 수동으로 설정해야 하는 점은 있다.

또 다른 방법은, Terragrunt를 사용하는 방법이 있으나, 지금 다루지는 않는다.

🎭 상태 파일 환경 격리

개발, 스테이징, 프로덕션 등의 환경을 격리할 필요가 있다.
방법에는 두 가지가 있다:

작업 공간을 통한 격리
파일 레이아웃을 통한 격리

🛠️ Workspace를 통한 격리

workspace를 이용하면 별도의 이름이 지정된 여러 작업공간에 저장가능하다.
Terraform은 default라는 기본 작업 공간에서 시작한다.

인스턴스를 하나 띄워보자. 아래와 같이 간단하게 띄워보자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


terraform {
 backend "s3" {
 bucket = "YOUR_BUCKET_NAME"
 key = "workspace-example/terraform.tfstate"
 region = "ap-northeast-2"
 dynamodb_table = "terraform-locks"
 encrypt = true
 }
}

provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_instance" "example" {
 ami = "ami-08943a151bd468f4e"
 instance_type = "t3.micro"
}

적용까지 해주자.

1
2


terraform init
terraform apply

현재 workspace를 확인해보자.

1
2


➜ terraform workspace show
default

새로 구성해보자.

1
2
3
4
5
6


➜ terraform workspace new example1
Created and switched to workspace "example1"!

You're now on a new, empty workspace. Workspaces isolate their state,
so if you run "terraform plan" Terraform will not see any existing state
for this configuration.

다시 적용해보자. 새로 생긴다는 것을 알 수 있다.

1

terraform apply

이제, AWS 콘솔에서 확인해보자.

env:/안으로 들어오니, workspace 이름이 있는 것을 확인할 수 있다.

계속해서 안으로 들어가서, tfstate를 확인할 수 있다.

그러나, workspace를 쓰는 건 다음의 단점들이 존재한다:

모든 상태 파일이 동일한 벡엔드를 사용
동일한 인증 및 엑세스 제어를 이용한다는 뜻
CLI에서 네임스페이스의 표시가 잘 되지 않음
혼동 가능성 있음 물론, 아래와 같이 일부 표시되는 경우도 있다. 아래는 spaceship prompt라는 zsh 테마를 설정한 기준이다.

그래서, 실제로는 파일 레이아웃 기반의 분리가 더 잘 쓰인다.

이제 위 자원 및 워크스페이스는 정리하자..

1
2
3
4


terraform destroy -auto-approve # example1 자원정리
terraform workspace select default # 다시 디폴트로 복귀
terraform workspace delete example1 # 워크스페이스 제거
terraform destroy -auto-approve # default 자원정리

다시 S3 버킷을 확인하면, example1의 tfstate가 삭제된걸 볼 수 있다.

📂 파일 레이아웃을 통한 격리

각 환경의 구성 파일을 별도의 폴더에 저장하는 방식이다.
그 뒤, 서로 인증 메커니즘과 액세스 제어를 사용하여 각 환경별로 서로 다른 벡엔드를 구성할 수 있다.
배포환경이 훨씬 명확해지고, 별도의 인증 메커니과 함께 별도의 상태 파일을 사용하면 한 환경에서 문제가 발생할 가능성이 훨씬 줄어든다.
실제로, 격리 개념을 “구성 요소”수준까지 가져갈 수 있다.
예를 들어, 네트워크 관련 설정은 자주 바뀌지 않는데 같이 관리되다가 손상될 수 있다.
각 환경과 해당 환경 내의 각 구성 요소에 대해 별도의 Terraform 폴더를 사용하는 것이 좋다.

일반적인 환경은 다음과 같다:

stage: 사전 프로덕션 워크로드를 위한 환경(테스트)
prod: 프로덕션 워크로드를 위한 환경(사용자 대상 애플리케이션)
mgmt: DevOps도구 환경(Bastion host, CI 서버)
global: 모든 환경에서 사용되는 리소스를 보관

각 환경 내의 구성 요소는 다음과 같다:

vpc: 네트워크 토폴로지
services: 앱 또는 마이크로서비스
data-storage: 데이터베이스 등등..

각 구성요소 내에는 다음 구칙에 따라 구성되는 실제 Terraform 구성파일이 있다:

variables.tf: 입력 변수
outputs.tf: 출력 변수
main.tf: 리소스 및 데이터 소스

추가로, 다음의 것들이 필요할 수 있다:

dependencies.tf
- 의존하는 외부 항목을 더 쉽게 확인할 수 있도록
providers.tf
- 코드가 어떤 공급자와 통신하는지, 어떤 인증을 제공해야 하는지
main-xxx.tf
- main.tf 파일에 많은 리소스가 포함되어 너무 길어지면 파일을 논리적인 방식으로 리소스를 그룹화하는 작은 파일로

이런 환경에서는 다음과 같은 장점 이 있다:

명확한 코드 / 환경 레이아웃
직관적으로 자원의 구성 파일들이 환경변로 분리되어 있다.
격리
만약 문제가 발생할 경우, 피해를 최소화 시킬 수 있다.

그러나, 단점 역시 존재한다:

여러 폴더 작업
각각을 apply해야 하는 불편함이 있다.
그러나, Terragrunt나 다른 솔루션이 일부 존재한다.
중복되는 내용
많은 복사-붙여넣기가 이루어질 수 있다.
자원 의존성
코드를 나누다 보면, 리소스 종속성을 사용하기 더 어려워진다.
다른 디렉토리에 정의된 리소스간의 데이터 참조가 어려워진다.

🔗 terraform_remote_state

terraform_remote_state는 파일 레이아웃 기반의 분리에서의 자원 의존성 참조의 어려움을 해결해준다.

웹 서버와 데이터베이스 서버를 별도의 폴더로 관리되는데, 연결을 어떻게 구성해야 할까?

우선, 스테이징 상황을 가정하자. 아래와 같이 구성한다:

1
2


mkdir -p stage/services/web-server-cluster
mkdir -p stage/data-stores/mysql

stage/services/web-server-cluster/main.tf에 ASG + ALB를 아래와 같이 정의하자:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159


provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_lb" "example" {
 name = "terraform-asg-example"
 load_balancer_type = "application"
 subnets = data.aws_subnets.default.ids
 security_groups = [aws_security_group.alb.id]
}

resource "aws_lb_listener" "http" {
 load_balancer_arn = aws_lb.example.arn
 port = 80
 protocol = "HTTP"

 default_action {
 type = "fixed-response"
 fixed_response {
 content_type = "text/plain"
 message_body = "404: Page Not Found"
 status_code = 404
 }
 }
}

resource "aws_lb_target_group" "asg" {
 name = "terraform-asg-example"
 port = var.server_port
 protocol = "HTTP"
 vpc_id = data.aws_vpc.default.id

 # health check
 health_check {
 path = "/" # 헬스체크 요청 경로
 protocol = "HTTP"
 matcher = "200" # 기대하는 응답 코
 interval = 15 # 체크 간격
 timeout = 3 # 요청 타임아웃(초)
 healthy_threshold = 2 # 몇 번 연속 성공적인 응답이어야 healthy한지
 unhealthy_threshold = 2 # 몇 번 연속 실패해야 unhealthy한지
 }
}

resource "aws_lb_listener_rule" "asg" {
 listener_arn = aws_lb_listener.http.arn
 priority = 100

 condition {
 path_pattern {
 values = ["*"]
 }
 }

 action {
 type = "forward"
 target_group_arn = aws_lb_target_group.asg.arn
 }
}

resource "aws_launch_template" "example" {
 name_prefix = "example-lt"

 image_id = "ami-08943a151bd468f4e" # Ubuntu 22.04
 instance_type = "t3.micro"
 vpc_security_group_ids = [aws_security_group.example_sg.id]

 user_data = base64encode(templatefile("server-init.sh", {
 server_port = var.server_port
 }))

 tags = {
 Name = "terraform-example"
 }
}

resource "aws_autoscaling_group" "example" {
 # 시작 탬플릿 선언
 launch_template {
 id = aws_launch_template.example.id
 version = "$Latest"
 }

 # 디폴트 서브넷들 참조하기
 vpc_zone_identifier = data.aws_subnets.default.ids

 # 이 ASG와 target group 바인딩
 target_group_arns = [aws_lb_target_group.asg.arn]
 # 타겟 그룹 단위로 헬스체크.
 health_check_type = "ELB"

 # 최소 ~ 최대 인스턴스 수 선언
 min_size = 2
 max_size = 10

 # 인스턴스에 할당할 tag지정.
 tag {
 key = "Name"
 value = "terraform-asg-example"
 propagate_at_launch = true
 }

 # 먼저 생성 후 제거하여 리소스 교체를 안전하게 진행
 lifecycle {
 create_before_destroy = true
 }
}

resource "aws_security_group" "alb" {
 name = "terraform-example-alb"

 # HTTP 요청 허용
 ingress {
 from_port = 80
 to_port = 80
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }

 # 서버로 트래픽 전달
 egress {
 from_port = 0 # 모든 포트
 to_port = 0
 protocol = "-1" # 와일드카드: 모든 프로토콜 허용
 cidr_blocks = ["0.0.0.0/0"]
 }
}

resource "aws_security_group" "example_sg" {
 name = "terraform-example-sg"

 ingress {
 from_port = var.server_port
 to_port = var.server_port
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

data "aws_vpc" "default" {
 default = true
}

data "aws_subnets" "default" {
 filter {
 name = "vpc-id"
 values = [data.aws_vpc.default.id]
 }
}

variable "server_port" {
 type = number
 default = 8080
}

output "alb_dns_name" {
 value = aws_lb.example.dns_name
 description = "The domain name of the load balander"
}

stage/data-stores/mysql/main.tf에는 아래와 같이 구성하자:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


# 다른 버킷에 구성하는 등, 벡엔드 분리를 할 수도 있다.
terraform {
 backend "s3" {
 bucket = "YOUR_BUCKET_NAME"
 key = "stage/data-stores/mysql/terraform.tfstate"
 region = "ap-northeast-2"
 dynamodb_table = "terraform-locks"
 encrypt = true
 }
}

provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_db_instance" "example" {
 identifier_prefix = "terraform-mysql"
 engine = "mysql"
 allocated_storage = 10
 instance_class = "db.t3.micro"
 skip_final_snapshot = true
 db_name = "example_database"

 username = var.db_username
 password = var.db_password
}

# 실험 환경이므로 기본값을 넣었다. 실제로는 더 안전한 방법을 쓰자.
variable "db_username" {
 description = "The username for the database"
 type = string
 sensitive = true
 default = "testuser"
}

variable "db_password" {
 description = "The password for the database"
 type = string
 sensitive = true
 default = "testpass"
}

# 출력 변수 지정
output "address" {
 value = aws_db_instance.example.address
 description = "db ip addr"
}

output "port" {
 value = aws_db_instance.example.port
 description = "db service port"
}

데이터베이스부터 적용하자.
RDS 서비스는 오래 걸리니, 조금 기다리자.

1
2
3


# stage/data-stores/mysql
terraform init
terraform apply

결과에 출력이 나올 건데, 이 출력 변수는 S3벡엔드의 tfstate에도 존재한다.

웹 서버 클러스터에서 해당 tfstate로부터 출력변수를 가져올 수 있는 것이다!

아래 스니펫을 stage/services/web-server-cluster/main.tf에 추가한다:

1
2
3
4
5
6
7
8


data "terraform_remote_state" "db" {
 backend = "s3"
 config = {
 bucket = "YOUR_BUCKET_NAME"
 key = "stage/data-stores/mysql/terraform.tfstate"
 region = "ap-northeast-2"
 }
}

참조는 data.terraform_remote_state.<NAME>.outputs.<ATTR>로 하면 된다.

web-server-cluster의 server-init.sh의 내용을 아래와 같이 구성한다:

1
2
3
4
5


#!/bin/bash
echo "<h2>Hello, World</h2>" > index.html
echo "<p>DB Address: ${db_address}</p>" >> index.html
echo "<p>DB Port: ${db_port}</p>" >> index.html
nohup busybox httpd -f -p ${server_port} &

그 뒤, Launch Template에서 아래와 같이 수정한다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


resource "aws_launch_template" "example" {
 name_prefix = "example-lt"

 image_id = "ami-08943a151bd468f4e" # Ubuntu 22.04
 instance_type = "t3.micro"
 vpc_security_group_ids = [aws_security_group.example_sg.id]

 user_data = base64encode(templatefile("server-init.sh", {
 server_port = var.server_port
 # 추가
 db_address = data.terraform_remote_state.db.outputs.address
 db_port = data.terraform_remote_state.db.outputs.port
 }))

 tags = {
 Name = "terraform-example"
 }
}

이제, 웹 서비스도 apply해보자.
그리고 ALB 엔드포인트로 접속해보자.

1

terrform apply

📚 요약

tfstate는 구성 파일을 기반으로 만든 리소스에 대한 정보가 들어 있는 중요한 파일이다.
평문으로 저장되어 있으므로, 안전한 관리가 필요하고, 협업 시 동기화 문제가 필요하다.
환경을 분리하는 데에는 workspace 기반과 파일 레이아웃(프로젝트 디렉토리)기반 관리가 있다.
- 파일 레이아웃 기반은 벡엔드 분리가 가능하고 실수를 줄이며, 실수 시의 피해도 최소화한다.
- 그러나, 분리된 구성 파일들 간의 데이터 참조 문제가 있다.
terraform_remote_state는 분리된 구성 파일들 간의 데이터 참조 문제를 해결해준다.

Terraform: ASG(Auto Scaling Group)과 Elb(Elastic Load Balancer)

Mon, 04 Aug 2025 22:02:09 +0900

💼 웹 서버 클러스터 배포하기

단일 서버는 간단하지만, 단일 장애점(Single Point of Failure) 의 위험이 있다.
해당 서버가 종료되거나, 너무 많은 트래픽으로 과부하가 발생하는 경우, 사용자는 접속할 수 없다.

이에 대한 해결책은, 서버 클러스터를 실행하고, 트래픽에 따라 클러스터의 크기를 조정하면 된다.
이를 수동으로 하면 번거롭지만, ASG(Auto Scaling Group) 을 이용하면, AWS가 이를 처리하도록 도울 수 있다.
ASG는 EC2 클러스터 시작, 각 인스턴스 상태 모니터링, 실패한 인스턴스 교체, 로드에 따른 클러스터 크기 조정 등 많은 작업을 처리한다.

시작 탬플릿 생성

현재 이러한 웹 서버를 가진다고 하자:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_instance" "example" {
 ami = "ami-08943a151bd468f4e"
 instance_type = "t3.micro"
 vpc_security_group_ids = [aws_security_group.example_sg.id]

 user_data = <<-EOF
 #!/bin/bash
 echo "Hello World!" > index.html
 nohup busybox httpd -f -p ${var.server_port} &
 EOF

 user_data_replace_on_change = true

 tags = {
 Name = "terraform-example"
 }
}

resource "aws_security_group" "example_sg" {
 name = "terraform-example-sg"

 ingress {
 from_port = var.server_port
 to_port = var.server_port
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

variable "server_port" {
 type = number
}

output "public_ip" {
 value = aws_instance.example.public_ip
 description = "THe public IP address of the web server"
}

aws_instance대신, 아래처럼 시작 탬플릿의 리소스를 선언하자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


resource "aws_launch_template" "example" {
 name_prefix = "example-lt"

 image_id = "ami-08943a151bd468f4e" # Ubuntu 22.04
 instance_type = "t3.micro"
 vpc_security_group_ids = [aws_security_group.example_sg.id]

 # aws_instance와는 다르게, base64encode를 진행해야 한다.
 user_data = base64encode(templatefile("server-init.sh", {
 server_port = var.server_port
 }))

 tags = {
 Name = "terraform-example"
 }
}

server-init.sh는 아래와 같이 구성한다:

1
2
3


#!/bin/bash
echo "Hello, World" > index.html
nohup busybox httpd -f -p ${server_port} &

ASG(Auto Scaling Group) 생성

이제, aws_autoscaling_group으로 ASG를 생성할 수 있다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


resource "aws_autoscaling_group" "example" {
 # 시작 탬플릿 선택
 launch_template {
 id = aws_launch_template.example.id
 version = "$Latest"
 }

 # 최소 ~ 최대 인스턴스 수 선언
 min_size = 2
 max_size = 10

 # 인스턴스에 할당할 tag지정.
 tag {
 key = "Name"
 value = "terraform-asg-example"
 propagate_at_launch = true
 }

 # 먼저 생성 후 제거하여 리소스 교체를 안전하게 진행
 lifecycle {
 create_before_destroy = true
 }
}

lifecycle의 create_before_destroy 옵션을 true로 하여, 안정된 교체가 가능하다.
비활성화 된 경우, 먼저 지우고 새 인스턴스로 교체하지 못하고, 기존 상태의 인스턴스가 부활되어 교체하지 못하고 교착에 걸리게 된다.

서브넷 구성

ASG가 동작하려면, 서브넷을 추가해줘야 한다.
data는 Terraform을 실행할 때 마다 Provider가 가져오는 Read-Only 정보를 가져온다.
이는 동적이고, 유연하게 리소스의 정보를 가져올 수 있도록 한다.

Terraform 구성 파일에 data를 추가해도, 새로운 리소스가 생기진 않는다.
각 Provider는 다양한 data를 제공한다.

1
2
3


data "<PROVIDER>_<TYPE>" "<NAME>" {
 [CONFIG...]
}

PROVIDER: Provider 이름
TYPE: 데이터 소스 유형
CONFIG: 관련된 args

아래는 기본 VPC를 조회한다:

1
2
3


data "aws_vpc" "default" {
 default = true
}

데이터를 가져오려면, 아래와 같이 참조하면 된다:

1

data.<PROVIDER>_<TYPE>.<NAME>.<ATTR>

aws_subnets와 결합하여, vpc내의 서브넷을 조회할 수 있다. 아래는 기본 vpc의 서브넷들을 참조한다.

1
2
3
4
5
6


data "aws_subnets" "default" {
 filter {
 name = "vpc-id"
 values = [data.aws_vpc.default.id]
 }
}

아래처럼 ASG를 수정하자:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27



resource "aws_autoscaling_group" "example" {
 # 시작 탬플릿 선언
 launch_template {
 id = aws_launch_template.example.id
 version = "$Latest"
 }

 # 디폴트 서브넷들 참조하기
 vpc_zone_identifier = data.aws_subnets.default.ids

 # 최소 ~ 최대 인스턴스 수 선언
 min_size = 2
 max_size = 10

 # 인스턴스에 할당할 tag지정.
 tag {
 key = "Name"
 value = "terraform-asg-example"
 propagate_at_launch = true
 }

 # 먼저 생성 후 제거하여 리소스 교체를 안전하게 진행
 lifecycle {
 create_before_destroy = true
 }
}

설명과 코드가 뒤죽박죽이니, 현재까지의 정리본을 한번 정리하고자 한다.
시작 탬플릿과 ASG의 구성은 아래와 같다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73


provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_launch_template" "example" {
 name_prefix = "example-lt"

 image_id = "ami-08943a151bd468f4e" # Ubuntu 22.04
 instance_type = "t3.micro"
 vpc_security_group_ids = [aws_security_group.example_sg.id]

 user_data = base64encode(templatefile("server-init.sh", {
 server_port = var.server_port
 }))

 tags = {
 Name = "terraform-example"
 }
}

resource "aws_autoscaling_group" "example" {
 # 시작 탬플릿 선언
 launch_template {
 id = aws_launch_template.example.id
 version = "$Latest"
 }

 # 디폴트 서브넷들 참조하기
 vpc_zone_identifier = data.aws_subnets.default.ids

 # 최소 ~ 최대 인스턴스 수 선언
 min_size = 2
 max_size = 10

 # 인스턴스에 할당할 tag지정.
 tag {
 key = "Name"
 value = "terraform-asg-example"
 propagate_at_launch = true
 }

 # 먼저 생성 후 제거하여 리소스 교체를 안전하게 진행
 lifecycle {
 create_before_destroy = true
 }
}

resource "aws_security_group" "example_sg" {
 name = "terraform-example-sg"

 ingress {
 from_port = var.server_port
 to_port = var.server_port
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

data "aws_vpc" "default" {
 default = true
}

data "aws_subnets" "default" {
 filter {
 name = "vpc-id"
 values = [data.aws_vpc.default.id]
 }
}

variable "server_port" {
 type = number
 default = 8080
}

⚖️ 로드밸런서(ALB 배포하기)

이제 여러 서버가 있지만, 사용자에게는 단일의 엔드포인트만을 제공하는 것이 좋다.
로드 밸런서를 이용하여 트래픽을 ASG를 대상으로 보내고, 사용자에게는 하나의 엔드포인트만을 제공할 수 있다.

AWS에는 세 가지의 로드밸런서가 있다:

ALB(Application Load Balancer) HTTP 및 HTTPS 트래픽의 로드밸런싱을 제공하며, L7 라우팅을 제공한다.
NLB(Network Load Balancer) TCP, UDP, TLS수준의 로드밸런싱을 제공, ALB보다 더 빠르게 응답하며, 확장 및 축소할 수 있다. 성능이 더 좋다.
CLB(Classic Load Balancer) 레거시 로드 밸런서로, L7, L4 모두 지원하지만, 기능이 적고 잘 쓰이지 않는다.

여기서는 ALB를 쓸 것이다.
ALB는 세 가지의 구성 요소로 구성된다:

Listener 특정 포트 및 프로토콜을 수신한다.
Rules 리스너로 들어오는 요청을 받아 특정 경로 또는 호스트 이름과 일치하는 요청을 특정 대상 그룹에 보낸다.
Target Group 라우팅 대상이 되는 하나 이상의 서버. 주기적으로 헬스체크를 진행하며, 건강한 노드에만 라우팅한다.

ALB 및 리스너 생성

아래는 ALB 생성의 예시이다:

1
2
3
4
5


resource "aws_lb" "example" {
 name = "terraform-asg-example"
 load_balancer_type = "application" # ALB로 생성
 subnets = data.aws_subnets.default.ids
}

subnets 파라미터는 aws_subnets 데이터를 사용하여 기본 VPC의 모든 서브넷을 사용하도록 로드 밸런서를 구성한다.
AWS ALB는 VPC에 종속되어 선택한 서브넷들에 따른 AZ들에 걸쳐 자동으로 확장 및 축소하여, 확정성과 고가용성을 제공한다.
이것이 추상화 되어있고, 두 개 이상의 서로 다른 AZ의 퍼블릭 서브넷에 걸쳐야 한다.
기본적으로 디폴트 VPC는 모두 퍼블릭 서브넷이다.

ALB를 만들었으면, 이제 리스너를 정의하자.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


resource "aws_lb_listener" "http" {
 load_balancer_arn = aws_lb.example.arn
 port = 80
 protocol = "HTTP"

 default_action {
 type = "fixed-response"
 fixed_response {
 content_type = "text/plain"
 message_body = "404: Page Not Found"
 status_code = 404
 }
 }
}

이 리스너는 포트 80에서 수신을 대기하고, HTTP 프로토콜을 사용, 리스너 규칙과 일치하지 않는 요청에 대한 기본 응답으로 간단한 404 페이지를 보내도록 구성되어있다.

보안 그룹 생성

이제, ALB를 위한 보안 그룹이 필요하다.
보안 그룹은 stateful해서, 인바운드 트래픽이 허용되어있다면, 그의 아웃바운드 트래픽도 자동으로 허용되어 별 상관 없지만, 로드 밸런서의 경우, 트래픽이 서버로 가야 하기에, 아웃바운드 트래픽을 허용해주어야 한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


resource "aws_security_group" "alb" {
 name = "terraform-example-alb"

 # HTTP 요청 허용
 ingress {
 from_port = 80
 to_port = 80
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }

 # 서버로 트래픽 전달
 egress {
 from_port = 0 # 모든 포트
 to_port = 0
 protocol = "-1" # 와일드카드: 모든 프로토콜 허용
 cidr_blocks = ["0.0.0.0/0"]
 }
}

이제, 보안 그룹을 사용하도록 alb에 할당하자.

1
2
3
4
5
6


resource "aws_lb" "example" {
 name = "terraform-asg-example"
 load_balancer_type = "application"
 subnets = data.aws_subnets.default.ids
 security_groups = [aws_security_group.alb.id]
}

Target Group 생성

다음으로, aws_lb_target_group을 생성하여, ASG에 대한 타겟 그룹을 생성해야 한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


resource "aws_lb_target_group" "asg" {
 name = "terraform-asg-example"
 port = var.server_port
 protocol = "HTTP"
 vpc_id = data.aws_vpc.default.id

 # health check
 health_check {
 path = "/" # 헬스체크 요청 경로
 protocol = "HTTP"
 matcher = "200" # 기대하는 응답 코
 interval = 15 # 체크 간격
 timeout = 3 # 요청 타임아웃(초)
 healthy_threshold = 2 # 몇 번 연속 성공적인 응답이어야 healthy한지
 unhealthy_threshold = 2 # 몇 번 연속 실패해야 unhealthy한지
 }
}

타겟 그룹은 aws_lb_target_group_attachment로 인스턴스의 정적 리스트를 가지킬 수 있지만,
aws_autoscaling_group에서 target_group_arns가 새 target_group으로 가리키게 하면 된다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


resource "aws_autoscaling_group" "example" {
 # 시작 탬플릿 선언
 launch_template {
 id = aws_launch_template.example.id
 version = "$Latest"
 }

 # 디폴트 서브넷들 참조하기
 vpc_zone_identifier = data.aws_subnets.default.ids

 # 이 ASG와 target group 바인딩
 target_group_arns = [aws_lb_target_group.asg.arn]
 # 타겟 그룹 단위로 헬스체크.
 health_check_type = "ELB"

 # 최소 ~ 최대 인스턴스 수 선언
 min_size = 2
 max_size = 10

 # 인스턴스에 할당할 tag지정.
 tag {
 key = "Name"
 value = "terraform-asg-example"
 propagate_at_launch = true
 }

 # 먼제 생성 후 제거하여 리소스 교체를 안전하게 진행
 lifecycle {
 create_before_destroy = true
 }
}

마지막으로, aws_lb_listener_rule리소스를 사용하여 묶어주면 된다.
ASG가 포함된 타겟 그룹에 대한 경로와 일치하는 요청을 보내는 리스너 규칙을 추가한다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


resource "aws_lb_listener_rule" "asg" {
 listener_arn = aws_lb_listener.http.arn
 priority = 100

 condition {
 path_pattern {
 values = ["*"]
 }
 }

 action {
 type = "forward"
 target_group_arn = aws_lb_target_group.asg.arn
 }
}

출력 변수 지정

마지막으로, 출력 변수가 나오도록 설정해주자.

1
2
3
4


output "alb_dns_name" {
 value = aws_lb.example.dns_name
 description = "The domain name of the load balander"
}

🚀 전체 코드 및 테스트

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159


`provider "aws" {
 region = "ap-northeast-2"
}

resource "aws_lb" "example" {
 name = "terraform-asg-example"
 load_balancer_type = "application"
 subnets = data.aws_subnets.default.ids
 security_groups = [aws_security_group.alb.id]
}

resource "aws_lb_listener" "http" {
 load_balancer_arn = aws_lb.example.arn
 port = 80
 protocol = "HTTP"

 default_action {
 type = "fixed-response"
 fixed_response {
 content_type = "text/plain"
 message_body = "404: Page Not Found"
 status_code = 404
 }
 }
}

resource "aws_lb_target_group" "asg" {
 name = "terraform-asg-example"
 port = var.server_port
 protocol = "HTTP"
 vpc_id = data.aws_vpc.default.id

 # health check
 health_check {
 path = "/" # 헬스체크 요청 경로
 protocol = "HTTP"
 matcher = "200" # 기대하는 응답 코
 interval = 15 # 체크 간격
 timeout = 3 # 요청 타임아웃(초)
 healthy_threshold = 2 # 몇 번 연속 성공적인 응답이어야 healthy한지
 unhealthy_threshold = 2 # 몇 번 연속 실패해야 unhealthy한지
 }
}

resource "aws_lb_listener_rule" "asg" {
 listener_arn = aws_lb_listener.http.arn
 priority = 100

 condition {
 path_pattern {
 values = ["*"]
 }
 }

 action {
 type = "forward"
 target_group_arn = aws_lb_target_group.asg.arn
 }
}

resource "aws_launch_template" "example" {
 name_prefix = "example-lt"

 image_id = "ami-08943a151bd468f4e" # Ubuntu 22.04
 instance_type = "t3.micro"
 vpc_security_group_ids = [aws_security_group.example_sg.id]

 user_data = base64encode(templatefile("server-init.sh", {
 server_port = var.server_port
 }))

 tags = {
 Name = "terraform-example"
 }
}

resource "aws_autoscaling_group" "example" {
 # 시작 탬플릿 선언
 launch_template {
 id = aws_launch_template.example.id
 version = "$Latest"
 }

 # 디폴트 서브넷들 참조하기
 vpc_zone_identifier = data.aws_subnets.default.ids

 # 이 ASG와 target group 바인딩
 target_group_arns = [aws_lb_target_group.asg.arn]
 # 타겟 그룹 단위로 헬스체크.
 health_check_type = "ELB"

 # 최소 ~ 최대 인스턴스 수 선언
 min_size = 2
 max_size = 10

 # 인스턴스에 할당할 tag지정.
 tag {
 key = "Name"
 value = "terraform-asg-example"
 propagate_at_launch = true
 }

 # 먼저 생성 후 제거하여 리소스 교체를 안전하게 진행
 lifecycle {
 create_before_destroy = true
 }
}

resource "aws_security_group" "alb" {
 name = "terraform-example-alb"

 # HTTP 요청 허용
 ingress {
 from_port = 80
 to_port = 80
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }

 # 서버로 트래픽 전달
 egress {
 from_port = 0 # 모든 포트
 to_port = 0
 protocol = "-1" # 와일드카드: 모든 프로토콜 허용
 cidr_blocks = ["0.0.0.0/0"]
 }
}

resource "aws_security_group" "example_sg" {
 name = "terraform-example-sg"

 ingress {
 from_port = var.server_port
 to_port = var.server_port
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

data "aws_vpc" "default" {
 default = true
}

data "aws_subnets" "default" {
 filter {
 name = "vpc-id"
 values = [data.aws_vpc.default.id]
 }
}

variable "server_port" {
 type = number
 default = 8080
}

output "alb_dns_name" {
 value = aws_lb.example.dns_name
 description = "The domain name of the load balander"
}

이제, 테스트해보자.

1
2


curl $(terraform output -raw alb_dns_name)
Hello, World

📚 요약

ASG + LB를 구성하면, 자동으로 확장되면서도 단일 엔드포인트를 제공하는 서비스를 만들 수 있다.

자원의 의존 관계는 다음과 같다(A -> B: A자원리 B자원을 필요로 함):

ALB -> VPC, Security Group for ALB
ALB Listener -> ALB
ALB Target Group -> VPC
Listener Rule -> Listener, Target Group
Launch Template -> Security Group for EC2s
ASG -> Launch Template, Target Group, Subnets