엔지니어 다이어리

[ArgoCD] ArgoCD Upgrade

EndiYou — Sat, 25 Apr 2026 18:45:57 +0900

사전 확인 사항

릴리즈 노드 및 마이그레이션 가이드 확인
작업 전 Application Sync 상태 확인
롤백 계획 수립

버전 업그레이드 작업 절차

ArgoCD 데이터 백업

# backup command
argocd admin export --namespace argocd - > argocd-backup-260424.yaml

ArgoCD 설치 파일 다운로드 및 설정

설치파일 다운로드:

Air-Gap 환경인 경우 Air-Gap 환경에서 ArgoCD 설치 정보 참고하여 설치파일 수정 필요

wget https://raw.githubusercontent.com/argoproj/argo-cd/v3.3.0/manifests/install.yaml

ArgoCD Server 서비스 타입 변경(필요시):

# NOTE:: 대상 파일: install.yaml
apiVersion: v1
kind: Service
metadata:
  annotations:
  labels:
    app.kubernetes.io/component: server
    app.kubernetes.io/name: argocd-server
    app.kubernetes.io/part-of: argocd
  name: argocd-server
spec:
  type: LoadBalancer										# 추가
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: 8080
  - name: https
    port: 443
    protocol: TCP
    targetPort: 8080
  selector:
    app.kubernetes.io/name: argocd-server

ArgoCD 업그레이드

kubectl apply -n argocd --server-side --force-conflicts -f install.yaml

업그레이드 후 검증:

# Verify version
argocd version

# Check pod status
kubectl get pods -n argocd

# Verify applications are healthy
argocd app list

# Check for any stuck applications
argocd app list --output json | jq '.[] | select(.status.health.status != "Healthy")'

롤백

# NOTE:: argocd-install-v2.14.yaml 
kubectl apply -n argocd --server-side --force-conflicts -f argocd-install-v2.14.yaml

# 필요시
argocd admin import - < argocd-backup-260424.yaml

[ArgoCD] ArgoCD Backup / Restore

EndiYou — Sat, 25 Apr 2026 18:31:32 +0900

ArgoCD 백업 및 복구 개요

백업/복구 도구 종류:

도구	설명
kubectl	Application, AppProject 단위 백업 및 복원
ArgoCD CLI	ArgoCD 전체 설정 백업 및 복원

백업 도구 비교:

항목	kubectl	ArgoCD CLI
Application	o	o
AppProjects	o	o
Repositories / Clusters	x	o
ArgoCD 설정 (ConfigMap, RBAC)	x	o
uid / resourceVersion 제거	x	o
타 클러스터 복원	불안정	안정적 지원
주요 용도	단순 백업 / 복원	마이그레이션, 재해복구 시나리오

유즈케이스별 권장 도구:

유즈케이스	권장 도구
실수로 삭제한 특정 App/Project 복원	kubectl
동일 클러스터 내 전체 복원	kubectl
ArgoCD 버전 업그레이드를 위한 백업/복원	ArgoCD CLI
다른 클러스터로 마이그레이션	ArgoCD CLI
ArgoCD 완전 삭제 후 재설치 (재해복구)	ArgoCD CLI
Repoisitory / Cluster 접속 정보까지 전체 복원이 필요한 경우	ArgoCD CLI

백업 방법

kubectl:

# Application 백업
kubectl get applications.argoproj.io -A -o yaml > argocd-applications-backup.yaml

# Project 백업
kubectl get appprojects.argoproj.io -A -o yaml > argocd-appprojects-backup.yaml

ArgoCD CLI:

# ArgoCD 전체 설정 백업 (App, Project, Repo, Cluster, ConfigMap 포함)                                                                             
argocd admin export --namespace argocd > argocd-full-backup.yaml

정기 백업 설정

백업 정책 기준(샘플):

백업 주기: 1일 1회 (매일 02:00AM)
보관 주기: 30일
보관 장소: NAS
백업 방식: Crond / CronJob 이용 백업 스크립트 수행

백업 스크립트:

#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)                                                                                                                       
BACKUP_DIR_APP="/mnt/netapp/argo_backup/app"
BACKUP_DIR_PROJ="/mnt/netapp/argo_backup/proj"                                                                                                          
BACKUP_DIR_FULL="/mnt/netapp/argo_backup/full"
LOG="/mnt/netapp/argo_backup/backup.log"

# NAS 마운트 확인
if ! mountpoint -q /mnt/netapp; then
  echo "[$DATE] ERROR: NAS not mounted" >> /var/log/argocd_backup.log
  exit 1
fi

# 1. App/Project 단위 백업                                                                                                                   
kubectl get applications.argoproj.io -A -o yaml > "$BACKUP_DIR_APP/argocd-applications-backup_$DATE.yaml"
kubectl get appprojects.argoproj.io -A -o yaml > "$BACKUP_DIR_PROJ/argocd-appprojects-backup_$DATE.yaml"                                          
                
# 2. 전체 설정 백업 (Repo/Cluster/ConfigMap 포함)                                                                                            
argocd admin export --namespace argocd > "$BACKUP_DIR_FULL/argocd-full-backup_$DATE.yaml"

# 3. 백업 파일 용량 0 체크
for f in "$BACKUP_DIR_APP/argocd-applications-backup_$DATE.yaml" \                                                                                
          "$BACKUP_DIR_PROJ/argocd-appprojects-backup_$DATE.yaml" \                                                                               
          "$BACKUP_DIR_FULL/argocd-full-backup_$DATE.yaml"; do
  if [ ! -s "$f" ]; then                                                                                                                          
    echo "[$DATE] ERROR: $f is empty" >> "$LOG"
    exit 1                                                                                                                                        
  fi            
done     

# 30일 초과 파일 삭제
find "$BACKUP_DIR_APP"  -type f -mtime +30 -delete                                                                                                
find "$BACKUP_DIR_PROJ" -type f -mtime +30 -delete                                                                                                
find "$BACKUP_DIR_FULL" -type f -mtime +30 -delete
echo "[$DATE] SUCCESS" >> "$LOG"

Crontab 등록:

# crontab -e
0 2 * * * /root/argo_backup/backup_argocd.sh

복구 방법

Case1. Application 복원 시

# NOTE:: 복구 파일: Application 파일
# NOTE:: 사전 작업: 복구할 대상 Application만 YAML 파일에서 추출 후 수행
kubectl apply -f argocd-applications-backup.yaml

# NOTE:: 복구 후 대상 Application 상태 확인
kubectl get applications.argoproj.io -n <namespace> <app-name>                                                                                    
kubectl get applications.argoproj.io -A

Case2. Project 복원 시

# NOTE:: 복구 파일: Application / AppProject 파일
# NOTE:: 프로젝트 파일 먼저 복구 후 애플리케이션 복구
kubectl apply -f argocd-appprojects-backup.yaml
kubectl apply -f argocd-applications-backup.yaml

# NOTE:: 복구 후 대상 Project / Application 상태 확인
kubectl get appprojects.argoproj.io -A
kubectl get applications.argoproj.io -A

Casse3. ArgoCD 설정 정보까지 전체 복원 시

# NOTE:: 복구 파일: ArgoCD 설치 파일 및 전체 설정 백업 파일
# NOTE:: ArgoCD 재설치 후 설정 백업 파일 이용 복구 
kubectl apply -f argocd-install.yaml
argocd admin import --namespace argocd < argocd-full-backup.yaml

# NOTE:: ArgoCD 전체 복구 후 상태 확인
# 1. ArgoCD Pod 상태 확인                                                                                                                         
kubectl get pods -n argocd

# 2. Project / App 개수 확인                                                                                                                      
kubectl get appprojects.argoproj.io -A
kubectl get applications.argoproj.io -A                                                                                                           
                
# 3. Repo 접속 정보 복원 확인                                                                                                                     
kubectl get secrets -n argocd -l argocd.argoproj.io/secret-type=repository
                                                                                                                                                  
# 4. Cluster 등록 정보 복원 확인                                                                                                                  
kubectl get secrets -n argocd -l argocd.argoproj.io/secret-type=cluster
                                                                                                                                                  
# 5. App Sync 상태 확인 (전체가 Synced/Healthy인지)                                                                                               
kubectl get applications.argoproj.io -A \
  -o custom-columns="NAME:.metadata.name,SYNC:.status.sync.status,HEALTH:.status.health.status"

[ArgoCD] Air-Gap 환경에서 ArgoCD 설치

EndiYou — Sat, 25 Apr 2026 18:07:19 +0900

인터넷 접근이 제한되는 네트워크에서 ArgoCD를 설치하기 위한 방법 정리

Step 1. ArgoCD 설치 파일 다운로드

인터넷 접근 가능한 환경에서 ArgoCD 설치 파일을 다운로드 받은 후 수정해야 한다.

curl -o argocd-install.yaml https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Step 2. ArgoCD 이미지 수집

사설 레지스트리로 이미지 업로드:

# docker pull -> tag -> push
ghcr.io/dexidp/dex:v2.43.0
public.ecr.aws/docker/library/redis:8.2.3-alpine
quay.io/argoproj/argocd:v3.3.0

직접 연결이 제한되어 이미지 파일 수동 전송이 필요한 경우:

# docker pull -> save -> 전달 -> load -> push
docker pull ghcr.io/dexidp/dex:v2.43.0
docker pull public.ecr.aws/docker/library/redis:8.2.3-alpine
docker pull quay.io/argoproj/argocd:v3.3.0

# docker save (create tar) -> 사내 전달
docker save ghcr.io/dexidp/dex:v2.43.0 -o dex.tar
docker save public.ecr.aws/docker/library/redis:8.2.3-alpine -o redis.tar
docker save quay.io/argoproj/argocd:v3.3.0 -o argocd.tar

# docker load -> tag -> push
docker load -i dex.tar
docker load -i redis.tar
docker load -i argocd.tar
docker tag ghcr.io/dexidp/dex:v2.43.0 <REGISTRY_URL>/<PROJECT>/dexidp/dex:v2.43.0
docker tag public.ecr.aws/docker/library/redis:8.2.3-alpine <REGISTRY_URL>/<PROJECT>/redis:8.2.3-alpine
docker tag quay.io/argoproj/argocd:v3.3.0 <REGISTRY_URL>/<PROJECT>/argoproj/argocd:v3.3.0
docker push <REGISTRY_URL>/<PROJECT>/dexidp/dex:v2.43.0
docker push <REGISTRY_URL>/<PROJECT>/redis:8.2.3-alpine
docker push <REGISTRY_URL>/<PROJECT>/argoproj/argocd:v3.3.0

Step3. 설치 파일 수정

사설 레지스트리 정보로 업데이트:

sed -i 's|ghcr.io/dexidp/dex|<REGISTRY_URL>/<PROJECT>/dex|g' argocd-install.yaml
sed -i 's|public.ecr.aws/docker/library/redis|<REGISTRY_URL>/<PROJECT>/redis|g' argocd-install.yaml
sed -i 's|quay.io/argoproj/argocd|<REGISTRY_URL>/<PROJECT>/argocd|g' argocd-install.yaml

imagePullSecret 설정(필요시):

# 인증정보 설정
REGISTRY_URL="<REGISTRY_URL>"
KEY="<ACCESS_KEY>:<SECRET_KEY>"
KEY_ENCODING=$(echo -n $KEY | base64 -w 0)
CONFIG_ENCODING=$(echo -n '{"auths": {"'$REGISTRY_URL'": {"auth": "'$KEY_ENCODING'"}}}' | base64 -w 0)

# Secret 리소스 파일 생성
echo '---
apiVersion: v1
kind: Secret
metadata:
  name: auth-secret
  namespace: argocd
data:
  .dockerconfigjson: '$CONFIG_ENCODING'
type: kubernetes.io/dockerconfigjson' > auth-secret.yaml

# NOTE:: 대상 파일: argocd-install.yaml
# NOTE:: ServiceAccount 7개 리소스에 imagePullSecrets 정보 추가
# NOTE:: ServiceAccount List: argocd-application-controller, argocd-applicationset-controller, argocd-dex-server, argocd-notifications-controller, argocd-redis, argocd-repo-server, argocd-server
apiVersion: v1
kind: ServiceAccount
metadata:
  labels:
    app.kubernetes.io/component: application-controller
    app.kubernetes.io/name: argocd-application-controller
    app.kubernetes.io/part-of: argocd
  name: argocd-application-controller
imagePullSecrets:				# imagePullSecrets 추가
  - name: argocd-scr-secret
... 나머지 6개 리소스에도 동일하게 반영

ArgoCD Server 서비스 타입 변경(필요시):

# NOTE:: 대상 파일: argocd-install.yaml
apiVersion: v1
kind: Service
metadata:
  labels:
    app.kubernetes.io/component: server
    app.kubernetes.io/name: argocd-server
    app.kubernetes.io/part-of: argocd
  name: argocd-server
spec:
  type: LoadBalancer	# 타입 정보 추가
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: 8080
  - name: https
    port: 443
    protocol: TCP
    targetPort: 8080
  selector:
    app.kubernetes.io/name: argocd-server
...

Repo Server 정보 추가(필요시):

# NOTE:: 대상파일: argocd-install.yaml
# NOTE:: 내부에 도메인 서버가 없는 경우 추가 필요
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/component: repo-server
    app.kubernetes.io/name: argocd-repo-server
    app.kubernetes.io/part-of: argocd
  name: argocd-repo-server
spec:
  selector:
  ...
  template:
    metadata: 
    ...
    spec:
      hostAliases:					# hostAliases 내용 추가
	  - ip: "<GITHUB_IP>"
		hostnames:
		  - "<GITHUB_URL>"
      affinity:
        podAntiAffinity:
        ...
...

TSL 처리 비활성화(필요시):

# NOTE:: 대상파일: argocd-install.yaml
# NOTE:: LB type 리소스로 접근할 경우 불필요
# NOTE:: Ingress 이용 접근할 경우 SSL Termination 설정 희망 시 필요
apiVersion: v1
kind: ConfigMap
metadata:
  labels:
    app.kubernetes.io/name: argocd-cmd-params-cm
    app.kubernetes.io/part-of: argocd
  name: argocd-cmd-params-cm
data:
  server.insecure: "true"		# Ingress SSL Termination 사용 시 활성화
...

Step4. ArgoCD 배포

ArgoCD 배포:

kubectl create namespace argocd
kubectl apply -f argocd-registry-secret.yaml                                                                                
kubectl apply -f argocd-install.yaml

초기 패스워드 확인:

kubectl secret -n argocd argocd-initial-admin-secret -o=jsonpath='(.data.password}' | base64 -d

[AWS] EKS 개요

EndiYou — Thu, 19 Mar 2026 00:21:50 +0900

EKS란?

AWS가 Kubernetes 컨트롤 플레인을 대신 관리해주는 EKS의 구조를 이해하고, Ubuntu 24.04 환경에서 실습 환경을 직접 구성해본다.

배경

Kubernetes는 컨테이너 오케스트레이션의 사실상 표준이지만, 컨트롤 플레인을 직접 구성·운영하는 일은 생각보다 손이 많이 간다. API 서버 이중화, etcd 백업, 버전 업그레이드, 가용 영역 분산 배치... 이 작업들을 모두 직접 하려면 운영 부담이 상당하다.
Amazon EKS(Elastic Kubernetes Service)는 컨트롤 플레인 운영을 AWS가 대신 맡아주는 완전 관리형 Kubernetes 서비스다. 클러스터를 만들면 API 서버와 etcd는 AWS가 관리하고, 개발자는 워크로드 배포에만 집중할 수 있다.

주요 개념

1. EKS 클러스터 구조

EKS 클러스터를 생성하면 내부적으로 VPC 두 개가 관여한다.

AWS 관리형 VPC: Kubernetes 컨트롤 플레인(API 서버, etcd)이 위치한다. 고객 계정에서는 보이지 않는다.
고객 관리형 VPC: 실제 워크로드(파드)가 실행되는 워커 노드가 위치한다.

두 VPC 사이 통신은 교차 계정 ENI(Elastic Network Interface, 탄력적 네트워크 인터페이스)를 통해 이루어진다. 노드가 시작되면 kubelet이 클러스터 엔드포인트에 연결해 컨트롤 플레인에 등록된다.

2. 클러스터 엔드포인트 접근 방식

EKS 클러스터에 접근하는 방식은 세 가지 모드로 구성할 수 있다. kubectl이나 kubelet이 API 서버와 통신하는 경로가 달라진다.

※ 운영 환경에서는 보안을 위해 Public + Private 또는 Private 모드를 권장한다.

2.1 Public 모드 (기본값)

API 서버 엔드포인트가 인터넷에 공개된다. kubectl과 노드의 kubelet 모두 퍼블릭 엔드포인트를 통해 컨트롤 플레인과 통신한다.

kubectl → 퍼블릭 엔드포인트(NLB) → API 서버
kubelet  → 퍼블릭 엔드포인트(NLB) → API 서버

2.2 Public + Private 모드

퍼블릭 엔드포인트는 유지하되, VPC 내부에서도 프라이빗 경로로 접근할 수 있다. kubelet은 VPC 내부 경로를 사용하므로 노드 → API 서버 트래픽이 인터넷을 거치지 않는다.

kubectl  → 퍼블릭 엔드포인트(NLB)      → API 서버
kubelet  → EKS owned ENI (VPC 내부)  → API 서버

2.3 Private 모드

API 서버 엔드포인트가 VPC 내부에서만 접근 가능하다. kubectl도 VPN, Direct Connect, 또는 VPC 내 배스천 호스트를 통해야 한다. Route 53 Private Hosted Zone을 통해 내부 DNS를 처리한다.

kubectl  → (VPN/배스천) → EKS owned ENI → API 서버
kubelet  → EKS owned ENI (VPC 내부)    → API 서버

EKS owned ENI: AWS가 고객 VPC에 직접 생성하는 네트워크 인터페이스다. 컨트롤 플레인과 워커 노드 간 트래픽을 VPC 내부에서 처리하는 데 사용된다.

3. 컨트롤 플레인

EKS는 기본적으로 컨트롤 플레인을 3개의 가용 영역에 분산 배치한다. 하나가 불안정해지면 자동으로 다른 가용 영역의 인스턴스로 대체된다.

API 서버 (kube-apiserver): 클러스터 내외부 요청 진입점. kubectl이 여기와 통신한다
etcd: 클러스터 상태를 저장하는 키-값 스토어. 접근 불가 시 상태 변경 자체가 멈춘다
스케줄러 (kube-scheduler): 어느 노드에 파드를 배치할지 결정
컨트롤러 관리자 (kube-controller-manager): 클러스터의 현재 상태와 원하는 상태의 차이를 지속적으로 감지·조정
Cloud Controller Manager: 로드 밸런서(service controller), 네트워크 경로(route controller), 노드 수명 주기(node lifecycle controller) 등 AWS 리소스 연동 처리

4. 데이터 플레인

컨트롤 플레인은 EKS가 관리하지만, 워커 노드(데이터 플레인)는 선택지가 다양하다.

노드 유형	특징	적합한 경우
EKS Auto Mode	데이터 플레인까지 AWS가 관리. Karpenter·EBS CSI·로드 밸런서 컨트롤러 내장	운영 오버헤드 최소화가 우선일 때
Fargate	노드 개념 없이 파드 단위로 컴퓨팅 할당. 서버리스	인프라 관리 없이 컨테이너 배포만 할 때
Karpenter	워크로드 요구에 맞춰 적절한 인스턴스를 실시간 프로비저닝하는 오토스케일러	비용 최적화와 유연한 스케일링이 필요할 때
관리형 노드 그룹	EC2 인스턴스 관리 자동화(패치·업데이트·스케일링). 커스텀 kubelet 인수 지원	자동화와 커스터마이징을 함께 원할 때
자체 관리형 노드	EC2를 직접 운영. 완전한 제어권	인프라를 세밀하게 통제해야 할 때
EKS Hybrid Nodes	온프레미스 서버를 EKS 노드로 연결	클라우드·온프레미스 혼용 환경

5. 워크로드

Kubernetes에서 배포의 가장 작은 단위는 파드(Pod) 다. 파드는 하나 이상의 컨테이너를 묶어 동일한 네트워크 환경을 공유한다.

Deployment: 상태 비저장(stateless) 앱. 웹 서버처럼 여러 복제본을 띄울 때
StatefulSet: 상태 저장(stateful) 앱. 각 인스턴스의 정체성과 순서가 중요한 경우 (DB 등)
DaemonSet: 모든 노드에서 하나씩 실행해야 하는 에이전트 (모니터링, 로그 수집 등)
Job / CronJob: 특정 작업을 완료하면 종료되는 배치성 워크로드

클러스터 외부 트래픽은 Ingress(수신 컨트롤러)를 통해 내부 Service로 라우팅된다.

실습

1. 사전 패키지 설치

sudo apt update && sudo apt install -y \
  curl wget unzip jq tree git \
  bridge-utils net-tools ca-certificates

jq: JSON 출력을 보기 좋게 파싱·필터링할 때 쓴다. AWS CLI 출력 확인에 자주 활용
tree: 디렉터리 구조를 트리 형태로 출력. Terraform 모듈 구조 파악 등에 유용

2. AWS CLI 설치 및 자격증명 설정

ARM 계열(예: AWS Gravition EC2)을 사용하는 경우 URL에서 x86_64를 aarch64로 변경

# AWS CLI v2 다운로드 (Linux x86_64)
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"

unzip awscliv2.zip
sudo ./aws/install

aws --version
# aws-cli/2.x.x Python/3.x.x Linux/... ...

rm -rf awscliv2.zip aws/

# AWS 인증 설정
aws configure
# AWS Access Key ID     : <액세스 키>
# AWS Secret Access Key : <시크릿 키>
# Default region name   : ap-northeast-2
# Default output format : json

설정 파일은 ~/.aws/credentials와 ~/.aws/config에 저장된다.

# 자격증명 확인 — 현재 인증된 IAM 주체 정보를 반환한다
aws sts get-caller-identity
# {
#   "UserId": "AIDA...",
#   "Account": "123456789012",
#   "Arn": "arn:aws:iam::123456789012:user/myuser"
# }

get-caller-identity는 자격증명이 제대로 설정됐는지 확인할 때 가장 먼저 쓰는 명령어다. 오류 없이 계정 정보가 나오면 설정 완료다.

3. EC2 Key Pair 생성 (선택)

워커 노드에 SSH로 직접 접속하려면 키 페어가 필요하다.

aws ec2 create-key-pair \
  --key-name my-keypair \
  --query 'KeyMaterial' \
  --output text \
  > ~/.ssh/my-keypair.pem

chmod 400 ~/.ssh/my-keypair.pem

aws ec2 describe-key-pairs --key-names my-keypair

4. kubectl 설치

kubectl은 Kubernetes API 서버와 통신하는 CLI 도구다. 파드 조회, 배포, 로그 확인 등 대부분의 클러스터 작업에 사용한다.

ARM 계열 사용 시 URL에서 amd64를 arm64 로 변경

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

chmod +x kubectl
sudo mv ./kubectl /usr/local/bin/kubectl

kubectl version --client=true

# 자동완성 설정 (bash)
source <(kubectl completion bash)
echo 'source <(kubectl completion bash)' >> ~/.bashrc

# k를 kubectl 단축 명령어로 등록하고 자동완성도 연결
echo 'alias k=kubectl' >> ~/.bashrc
echo 'complete -o default -F __start_kubectl k' >> ~/.bashrc

source ~/.bashrc

주요 옵션:

-n <namespace>: 특정 네임스페이스를 지정 (-n kube-system)
-A: 모든 네임스페이스를 대상으로 조회
-o wide: 노드 IP, 할당된 노드 등 확장 정보 출력
-o yaml: 리소스 전체 스펙을 YAML 형식으로 출력
-v=6: API 호출 상세 로그 출력 (인증 흐름 확인 시 유용)

5. Helm 설치

Helm은 Kubernetes 애플리케이션을 패키지(차트) 단위로 설치·관리하는 도구다. 공개 차트를 활용하거나 직접 차트를 만들어 반복 배포에 활용한다.

curl -s https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | bash

helm version

6. Terraform 설치

# HashiCorp GPG 키 등록
wget -O- https://apt.releases.hashicorp.com/gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

# HashiCorp apt 저장소 추가
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] \
  https://apt.releases.hashicorp.com $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/hashicorp.list

sudo apt update && sudo apt install -y terraform

terraform version

# 자동완성 설정
terraform -install-autocomplete
source ~/.bashrc

7. EKS 클러스터 배포

실습 코드를 클론한 뒤 Terraform으로 VPC와 EKS 클러스터를 배포한다.

git clone https://github.com/gasida/aews.git
cd aews/1w

# 현재 계정에 등록된 EC2 Key Pair 이름 확인
aws ec2 describe-key-pairs --query "KeyPairs[].KeyName" --output text

# TF_VAR_ 접두사를 붙이면 terraform이 자동으로 변수로 인식
export TF_VAR_KeyName=$(aws ec2 describe-key-pairs --query "KeyPairs[].KeyName" --output text)

# 현재 공인 IP 확인 후 SSH 허용 CIDR로 설정 (/32 = 단일 IP)
export TF_VAR_ssh_access_cidr=$(curl -s ipinfo.io/ip)/32

echo "KeyName: $TF_VAR_KeyName"
echo "SSH CIDR: $TF_VAR_ssh_access_cidr"

# 초기화 — provider와 모듈 다운로드
terraform init

# 실행 계획 미리 보기
terraform plan

# 배포 (약 12분 소요) — nohup으로 터미널 끊김에 대비
nohup sh -c "terraform apply -auto-approve" > create.log 2>&1 &

tail -f create.log

# 배포 완료 후 kubeconfig 등록
aws eks update-kubeconfig --region ap-northeast-2 --name myeks

# 컨텍스트 이름 변경
CURRENT_CTX=$(kubectl config current-context)
kubectl config rename-context $CURRENT_CTX myeks

kubectl config current-context
# myeks

8. 클러스터 상태 확인

8.1 컨트롤 플레인 엔드포인트

CLUSTER_NAME=myeks

kubectl cluster-info
# Kubernetes control plane is running at https://<hash>.gr7.ap-northeast-2.eks.amazonaws.com

# 상세 정보 조회
aws eks describe-cluster --name $CLUSTER_NAME | jq

# 엔드포인트 URL만 추출
aws eks describe-cluster --name $CLUSTER_NAME | jq -r .cluster.endpoint

# 엔드포인트 DNS → IP 조회 (조회된 IP는 AWS 소유)
APIDNS=$(aws eks describe-cluster --name $CLUSTER_NAME | jq -r .cluster.endpoint | cut -d '/' -f 3)
dig +short $APIDNS

8.2 노드 확인

kubectl get node

kubectl get node -o wide

# 인스턴스 타입, 용량 타입, 가용 영역을 컬럼으로 표시
kubectl get node --label-columns=node.kubernetes.io/instance-type,eks.amazonaws.com/capacityType,topology.kubernetes.io/zone

# API 호출 과정 상세 로그 출력 (kubeconfig 경로, 엔드포인트, HTTP 응답 코드 확인)
kubectl get node -v=6

8.3 노드 그룹 확인

aws eks describe-nodegroup \
  --cluster-name $CLUSTER_NAME \
  --nodegroup-name $CLUSTER_NAME-node-group | jq

8.4 시스템 파드 확인

kubectl get pod -n kube-system -o wide

kubectl get pod -A

kubectl get deploy,ds,pod,cm,secret,svc,ep,sa,role,rolebinding -n kube-system

# 모든 파드의 컨테이너 이미지 목록
kubectl get pods --all-namespaces \
  -o jsonpath="{.items[*].spec.containers[*].image}" \
  | tr -s '[[:space:]]' '\n' | sort | uniq -c

EKS는 컨테이너 이미지를 Docker Hub 대신 AWS ECR(Elastic Container Registry)에서 가져온다. 이미지 주소에 dkr.ecr.ap-northeast-2.amazonaws.com 형태가 붙는다.

8.5 Add-on 확인

EKS 클러스터에는 기본적으로 세 가지 Add-on이 설치된다.

Add-on	구성 요소	역할
vpc-cni	`aws-node` DaemonSet	파드에 VPC IP 주소를 직접 할당. 파드가 VPC 내에서 네이티브 IP를 가짐
kube-proxy	`kube-proxy` DaemonSet	노드의 iptables/ipvs 규칙을 관리. Service → 파드 트래픽 라우팅 처리
coredns	`coredns` Deployment	클러스터 내부 DNS 서버. `svc-name.namespace.svc.cluster.local` 형식으로 서비스 조회 가능

aws eks list-addons --cluster-name $CLUSTER_NAME | jq
# {
#   "addons": ["coredns", "kube-proxy", "vpc-cni"]
# }

# 특정 Add-on 상세 정보 (버전, 상태, IAM 역할 등)
aws eks describe-addon --cluster-name $CLUSTER_NAME --addon-name vpc-cni | jq

# Add-on이 배포한 리소스 직접 확인
kubectl get ds -n kube-system      # aws-node, kube-proxy (DaemonSet)
kubectl get deploy -n kube-system  # coredns (Deployment)

# vpc-cni 파라미터 확인
kubectl describe ds aws-node -n kube-system

9. 워커 노드 직접 확인

9.1 SSH 접속

# 실행 중인 EC2 인스턴스 목록
aws ec2 describe-instances \
  --query "Reservations[*].Instances[*].{Name:Tags[?Key=='Name']|[0].Value,PublicIP:PublicIpAddress,PrivateIP:PrivateIpAddress,Status:State.Name}" \
  --filters Name=instance-state-name,Values=running \
  --output table

NODE1=<노드1_공인IP>
NODE2=<노드2_공인IP>

ping -c 1 $NODE1

ssh -i ~/.ssh/my-keypair.pem -o StrictHostKeyChecking=no ec2-user@$NODE1

9.2 노드 기본 정보

sudo su -

# 호스트 정보 확인 (OS, 커널, 하드웨어)
hostnamectl

# Swap 비활성화 확인 — Kubernetes는 Swap이 비활성화되어야 정상 동작
free -h
# Swap: 0 이어야 함

# cgroup 버전 확인 — 현재 EKS는 cgroup v2 사용
stat -fc %T /sys/fs/cgroup/
# cgroup2fs

# overlay 커널 모듈 로드 확인 — 컨테이너 레이어드 파일시스템에 필요
lsmod | grep overlay

# Kubernetes 필수 커널 파라미터 확인
cat /etc/sysctl.d/99-kubernetes-cri.conf
# net.bridge.bridge-nf-call-iptables  = 1
# net.ipv4.ip_forward                 = 1

9.3 kubelet 설정

# kubelet 설정 파일 확인
cat /etc/kubernetes/kubelet/config.json

주요 설정값:

maxPods: 노드에서 실행 가능한 최대 파드 수. 인스턴스 타입과 ENI 수에 따라 결정됨
evictionHard: 리소스 부족 시 파드를 강제 종료하는 임계값 (메모리, 디스크 등)
featureGates: Kubernetes 실험적 기능 활성화 여부
clusterDNS: CoreDNS 서비스 IP (파드가 사용하는 DNS 서버 주소)

systemctl status kubelet --no-pager -l

# kubelet이 API 서버에 인증하는 kubeconfig 확인
# aws eks get-token 명령어로 토큰을 동적으로 발급받는다
cat /var/lib/kubelet/kubeconfig

9.4 컨테이너 런타임

systemctl status containerd --no-pager -l

# nerdctl — containerd용 Docker 호환 CLI
nerdctl ps

nerdctl images

cat /etc/containerd/config.toml

9.5 CNI 설정

# AWS VPC CNI 설정 파일 확인
# 파드의 IP 할당 방식, MTU, 로그 레벨 등을 확인할 수 있다
cat /etc/cni/net.d/10-aws.conflist

AWS VPC CNI는 파드에 VPC의 실제 IP를 할당한다. 파드 IP가 곧 VPC IP이므로 RDS, ElastiCache 등 다른 VPC 리소스와 추가 NAT 없이 직접 통신할 수 있다.

# cgroup 계층 구조 확인
# kubepods.slice 아래에 파드별 cgroup이 생성된다
systemd-cgls | grep -A 3 kubepods

배포 방식 비교

AWS Management Console: 클릭 기반. 학습·테스트 환경에 적합
eksctl: EKS 공식 CLI. 내부적으로 CloudFormation 스택을 생성·관리
Terraform: 선언적 IaC. 대규모 인프라나 멀티 클러스터 환경에 유리
CDK / CloudFormation: AWS 네이티브 IaC 도구

eksctl은 단순하고 빠르게 클러스터를 올릴 때 유용하다. eksctl create cluster 명령 하나로 VPC, 서브넷, IAM 역할, 노드 그룹까지 자동 생성된다. 내부적으로는 CloudFormation 스택을 생성해 리소스를 관리한다.

Provisioned Control Plane

컨트롤 플레인 용량을 사전 예약해 예측 가능한 성능을 보장하는 방식이다. 기존 Standard Mode(온디맨드 자동 스케일링)와 달리, 트래픽 급증에도 일관된 API 응답 속도를 유지할 수 있다.

Standard: 기본값. 온디맨드 자동 스케일링. 소규모~중규모 클러스터에 적합
Provisioned: 용량 사전 예약. API 동시 요청 최대 6,800개 처리. 대규모·고가용성 워크로드에 적합

참고 자료

[Nginx] Nginx 컴파일 설치 방식으로 버전 업그레이드

EndiYou — Fri, 26 Dec 2025 23:34:23 +0900

업그레이드 전 준비

1. 필수 패키지 설치

# 필수 빌드 도구 및 라이브러리 설치
sudo apt-get update
sudo apt-get install -y \
  build-essential \
  libpcre3 \
  libpcre3-dev \
  zlib1g \
  zlib1g-dev \
  libssl-dev \
  libgd-dev \
  libgeoip-dev \
  libxslt1-dev

2. Nginx 컴파일 소스 파일 다운로드

# 작업 디렉토리 생성
mkdir -p /tmp/nginx_upgrade
cd /tmp/nginx_upgrade

# Nginx 1.28.0 소스 다운로드
wget https://nginx.org/download/nginx-1.28.0.tar.gz

# 압축 해제
tar -xzf nginx-1.28.0.tar.gz
cd nginx-1.28.0

3. 현재 설정 정보 확인

컴파일 옵션을 확인하고 신규 버전 설치 시 제외하거나 추가해야할 옵션들을 정리한다. nginx-1.18.0 같은 버전이 명시되어 있거나 업그레이드 하는 버전에서 지원하지 않는 옵션은 확인 후 제거한다.

# 1. 현재 Nginx 버전 및 컴파일 옵션 확인
$ nginx -V
nginx version: nginx/1.18.0 (Ubuntu)
built with OpenSSL 3.0.2 15 Mar 2022
TLS SNI support enabled
configure arguments: -- with-cc-opt='-g -02 -ffile-prefix-map=/build/nginx-zctdR4/
nginx-1.18.0 =. -flto=auto -ffat-lto-objects -flto=auto -ffat-lto-objects
-fstack-protector-strong -Wformat -Werror=format-security -fPIC -Wdate-time
-D_FORTIFY_SOURCE=2' -- with-ld-opt='-wl,-Bsymbolic-functions -flto=auto
-ffat-lto-objects -flto=auto -wl,-z,relro -Wl,-z,now -fPIC' -- prefix=/usr/share/nginx
-- conf-path=/etc/nginx/nginx.conf -- http-log-path=/var/log/nginx/access.log
-- error-log-path=/var/log/nginx/error. log -- lock-path=/var/lock/nginx.lock -- pid-path=/
run/nginx.pid -- modules-path=/usr/lib/nginx/modules -- http-client-body-temp-path=/var/
lib/nginx/body -- http-fastcgi-temp-path=/var/lib/nginx/fastcgi -- http-proxy-temp-path=/
var/lib/nginx/proxy -- http-scgi-temp-path=/var/lib/nginx/scgi -- http-uwsgi-temp-path=/
var/lib/nginx/uwsgi -- with-compat -- with-debug -- with-pcre-jit -- with-http_ssl_module
-- with-http_stub_status_module -- with-http_realip_module
-- with-http_auth_request_module -- with-http_v2_module -- with-http_dav_module
-- with-http_slice_module -- with-threads -- add-dynamic-module=/build/nginx-zctdR4/
nginx-1.18.0/debian/modules/http-geoip2 -- with-http_addition_module
-- with-http gunzip module -- with-http gzip static module -- with-http sub module

# 2. 현재 Nginx 프로세스 확인
ps aux | grep nginx

# 3. 현재 포트 리스닝 확인
netstat -tlnp | grep nginx

# 4. Nginx 상태 확인
systemctl status nginx

업그레이드 작업 진행

1. 서비스 중지 및 백업

# Nginx 서비스 중지
systemctl stop nginx

# 백업 디렉토리 생성
sudo mkdir -p /backup/nginx_upgrade_20251210
cd /backup/nginx_upgrade_20251210

# 현재 시간 변수 설정
BACKUP_TIME=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/nginx_upgrade_20251210"

# Nginx 바이너리 백업
sudo mv /usr/sbin/nginx ${BACKUP_DIR}/nginx_binary.${BACKUP_TIME}

# Nginx 모듈 및 설정 파일 백업
sudo mv /usr/share/nginx/modules ${BACKUP_DIR}/nginx_modules.${BACKUP_TIME}
sudo mv /usr/share/nginx/modules-available ${BACKUP_DIR}/nginx_modules_available.${BACKUP_TIME}

# 설정 파일 전체 백업
sudo mv /etc/nginx/ ${BACKUP_DIR}/nginx_config.${BACKUP_TIME}

# 현재 버전 정보 기록
${BACKUP_DIR}/nginx_binary.${BACKUP_TIME} -V > ${BACKUP_DIR}/nginx_version_before.txt 2>&1

# systemd 서비스 파일 백업
sudo cp -p /lib/systemd/system/nginx.service ${BACKUP_DIR}/nginx_service.${BACKUP_TIME} 2>/dev/null || echo "systemd service file not found"

# 백업 파일 확인
ls -lh ${BACKUP_DIR}/

2. 컴파일 설치

# 작업 디렉토리 이동
cd /tmp/nginx_upgrade/nginx-1.28.0

# configure 실행
# module을 static하게 적용하고 있다. > /usr/share/nginx/module 폴더에 .so 파일이 생성되지 않고, nginx 기본 기능에 추가되며 활성화
# module을 dynamic 하게 적용하고자 하는 경우 모듈마다 끝에 =dynamic 값을 추가해야 한다. > .so 파일 생성 후 nginx 실행될 때 마다 해당 파일을 읽어들이며 기능 활성화
./configure \
  --with-cc-opt='-g -O2 -fstack-protector-strong -Wformat -Werror=format-security -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' \
  --with-ld-opt='-Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -fPIC' \
  --prefix=/usr/share/nginx \
  --conf-path=/etc/nginx/nginx.conf \
  --http-log-path=/var/log/nginx/access.log \
  --error-log-path=/var/log/nginx/error.log \
  --lock-path=/var/lock/nginx.lock \
  --pid-path=/run/nginx.pid \
  --modules-path=/usr/lib/nginx/modules \
  --http-client-body-temp-path=/var/lib/nginx/body \
  --http-fastcgi-temp-path=/var/lib/nginx/fastcgi \
  --http-proxy-temp-path=/var/lib/nginx/proxy \
  --http-scgi-temp-path=/var/lib/nginx/scgi \
  --http-uwsgi-temp-path=/var/lib/nginx/uwsgi \
  --with-debug \
  --with-compat \
  --with-pcre-jit \
  --with-http_ssl_module \
  --with-http_stub_status_module \
  --with-http_realip_module \
  --with-http_auth_request_module \
  --with-http_v2_module \
  --with-http_dav_module \
  --with-http_slice_module \
  --with-threads \
  --with-http_addition_module \
  --with-http_gunzip_module \
  --with-http_gzip_static_module \
  --with-http_sub_module

# 컴파일 (멀티코어 활용)
make -j$(nproc)
make install

# 컴파일 완료 확인
ls -lh objs/nginx

3. 설정 파일 복구 및 검증

# 설정 디렉토리 재생성
mkdir -p /etc/nginx/sites-available
mkdir -p /etc/nginx/sites-enabled
mkdir -p /etc/nginx/modules-available
mkdir -p /etc/nginx/modules-enabled
mkdir -p /etc/nginx/conf.d

# 백업된 설정 파일 복구
cp ${BACKUP_DIR}/nginx_config.${BACKUP_TIME}/sites-available/default /etc/nginx/sites-available/default
cp ${BACKUP_DIR}/nginx_config.${BACKUP_TIME}/nginx.conf /etc/nginx/nginx.conf
ln -s /etc/nginx/sites-available/default /etc/nginx/sites-enabled/default

# 새 바이너리로 설정 파일 테스트
sudo /tmp/nginx_upgrade/nginx-1.28.0/objs/nginx -t -c /etc/nginx/nginx.conf

# 업그레이드 성공 시 예상 출력:
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

4. Nginx 바이너리 파일 교체 및 실행

# 설치 위치 확인
ls -lh /usr/share/nginx/sbin/nginx
/usr/share/nginx/sbin/nginx -v

# 바이너리 교체 (systemd가 사용하는 위치로)
sudo cp /usr/share/nginx/sbin/nginx /usr/sbin/nginx
nginx -v

# 실행 권한 확인
sudo chmod +x /usr/sbin/nginx

# 새 버전 확인
# 출력에서 "nginx version: nginx/1.28.0" 확인
nginx -V

# Nginx 재시작
sudo systemctl start nginx

# 상태 확인
sudo systemctl status nginx

5. 서비스 동작 확인 (최종점검)

# 1. 프로세스 확인
ps aux | grep nginx

# 2. 포트 리스닝 확인
netstat -tlnp | grep nginx

# 3. 접속 테스트
curl -I localhost

# 4. 로그 확인
sudo tail -50 /var/log/nginx/error.log
sudo tail -50 /var/log/nginx/access.log

롤백 절차

다음 상황 발생 시 롤백 고려:

프로세스 시작 실패
설정 파일 syntax 오류 발생
서비스 접근 불가
심각한 에러 로그 발생

1. Nginx 중지

# 문제가 발생한 서버에서 실행
sudo systemctl stop nginx

2. 백업 바이너리 복구

# 백업 파일 확인
ls -lh /backup/nginx_upgrade_20251210/nginx_binary.${BACKUP_TIME}

# 최신 백업 파일명 확인 (예: nginx.binary.20251210_180000)
BACKUP_BINARY=$(ls -t /backup/nginx_upgrade_20251210/nginx_binary.${BACKUP_TIME} | head -1)

# 바이너리 복구
sudo cp ${BACKUP_BINARY} /usr/sbin/nginx
sudo chmod +x /usr/sbin/nginx

3. 설정 파일 복구 (필요시)

# 설정 파일 백업 확인
ls -lh /backup/nginx_upgrade_20251210/nginx_config.${BACKUP_TIME}

# 최신 백업 디렉토리 확인 (예: nginx_config.20251210)
BACKUP_CONFIG=$(ls -td /backup/nginx_upgrade_20251210/nginx_config.${BACKUP_TIME} | head -1)

# 기존 설정 임시 백업
sudo mv /etc/nginx /etc/nginx.rollback_temp

# 설정 파일 복구
sudo cp -rp ${BACKUP_CONFIG} /etc/nginx

4. Nginx 재시작 및 확인

# 버전 확인
# 예상: nginx version: nginx/1.18.0
nginx -V

# 설정 파일 테스트
sudo nginx -t

# Nginx 재시작
sudo systemctl start nginx
sudo systemctl status nginx

# 프로세스 확인
ps aux | grep nginx

# 로컬 서비스 테스트
curl -I localhost

[Terraform] Terraform Module

EndiYou — Mon, 22 Dec 2025 22:33:57 +0900

Terraform 사용법이 표준화 되면서 다른 사람들이 잘 만든 코드나 사내 공통으로 사용되는 코드를 패키징하고 재사용이 가능한 모듈 단위로 관리하는 것이 가능하다. 다수의 모듈로 Repository Structure를 구성해서 사용하는 것이 일반적이다.

Multi Module Repository Structure

root module : 최상위 디렉터리를 의미한다. 아래 예시에서는 `.` 디렉터리가 최상위 디렉터리다.
module : module collection으로 단일 모듈 구성도 가능하고 중첩된 다수의 모듈 collection 구성도 가능하다.

.
├── README.md
├── main.tf
├── variables.tf
├── outputs.tf
├── ...
├── modules/
│   ├── nestedA/
│   │   ├── README.md
│   │   ├── variables.tf
│   │   ├── main.tf
│   │   ├── outputs.tf
│   ├── nestedB/
│   ├── .../

Module 구성

vpc.tf 파일을 network 모듈로 재구성하기 위해 아래 구성으로 폴더 구성을 변경한다. modules/network 디렉터리에는 provider.tf 파일이 없다. 모듈을 구성할 때 Multi Account 구조로 서로 다른 AWS Account를 사용하는 경우가 아니라면 명시적으로 provider.tf 파일을 구성하지 않아도 상위의 provider.tf 파일 정보를 참조한다.

terraform-starter-moduling/
├── main.tf
├── backend.tf
├── versions.tf
├── provider.tf
├── modules/
│   ├── network/
│   │   ├── data_sources.tf
│   │   ├── variables.tf
│   │   ├── locals.tf
│   │   ├── outputs.tf
│   │   ├── versions.tf
│   │   ├── vpc.tf

1. 폴더 구성

$ mkdir -p terraform-starter-moduling/modules/network
$ cd terraform-starter-moduling/
$ touch {main,backend,versions,provider}.tf
$ touch ./modules/network/{data_sources,variables,locals,outputs,versions,vpc}.tf
$ aws s3 mb s3://terraform-starter-moduling-bucket --region ap-northeast-2
make_bucket: terraform-starter-moduling-bucket
$ aws dynamodb create-table \
    --table-name tf_state_moduling_table \
    --attribute-definitions AttributeName=LockID,AttributeType=S \
    --key-schema AttributeName=LockID,KeyType=HASH \
    --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5 \
    --region ap-northeast-2

2. version.tf 파일 구성

# modules/network/versions.tf
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 3.62.0"
    }
  }
  required_version = ">= 1.3.6" 
}

3. data_sources.tf 파일 구성

# module/network/data_sources.tf
data "aws_availability_zones" "available" {
    state = "available"
}

4. locals.tf 파일 구성

locals {
  subnet_new_bits = 8
}

5. output.tf 파일 구성

# module/network/output.tf
output "main_vpc_id" {
  value = aws_vpc.main.id
  description = "The Id of the main VPC"
}

6. variables.tf 파일 구성

# module/network/variables.tf
variable "vpc_cidr" {
    type = string
    description = "The CIDR block for the VPC"
    default = "10.0.0.0/16"

    validation {
        condition = can(regex("^([0-9]{1,3}\\.){3}[0-9]{1,3}($|/(16|24))$",var.vpc_cidr))
        error_message = "Please ensure a valid CIDR has been entered with range /16 or /24."
    }
}

variable default_tags {
    type = object({
        environment = string
        owner = string
        cost_centre = string
    })
    description = "Default set of tags to apply to resources"
    default = {
        environment = "development",
        owner = "r&d",
        cost_centre = "1234567890"
    }

    validation {
        condition = length(var.default_tags.cost_centre) == 10
        error_message = "Please ensure a valid 10 digit cost centre code has been entered."
    }
}

variable subnet_count {
  type = number
  default = 2
}

7. vpc.tf 파일 구성

resource "aws_vpc" "main" {
  cidr_block = var.vpc_cidr
  tags = merge(
    {
      "Name" = "Main"
    },
    var.default_tags
  )
}

resource "aws_subnet" "public" {
  count = var.subnet_count

  vpc_id     = aws_vpc.main.id
  cidr_block = cidrsubnet(var.vpc_cidr,local.subnet_new_bits,count.index)

  tags = merge(
  {
    "Name" = "Public${count.index+1}"
  },
  var.default_tags
  )
  availability_zone = element(data.aws_availability_zones.available.names,count.index)
  map_public_ip_on_launch = true
}

Main 코드 작성

1. backend.tf 파일 구성

# backend.tf
terraform {
  backend "s3" {
    bucket = "terraform-starter-moduling-bucket"
    key    = "terraform-starter-moduling/"
    region = "ap-northeast-2"
    dynamodb_table = "tf_state_moduling_table"
  }
}

2. provider.tf 파일 구성

# provider.tf
provider "aws" {
  region                  = "ap-northeast-2"
  shared_credentials_file = "~/.aws/credentials"
  profile                 = "default"
}

3. main.tf 파일 구성

모듈 구성은 Block 단위로 만들어서 사용할 수 있다. source는 실행하려는 모듈의 상대 경로를 입력하게 된다. 실행하는 모듈이 변수를 취급하고 있으면 vpc_cidr, default_tags, subnet_count처럼 모듈로 데이터를 전달할 수 있다.

# main.tf
module "vpc1" {
    source    = "./modules/network"
    vpc_cidr = "10.10.0.0/16"
    default_tags = {
        environment = "development1",
        owner = "r&d",
        cost_centre = "1234567890"
    }
    subnet_count = 2
}

배포 및 결과 확인

1. Terraform 초기화 및 실행

$ terraform init
$ terraform plan --out tfplan
$ terraform apply tfplan

2. 두 번째 모듈 선언

module "vpc1" {
    source    = "./modules/network"
    vpc_cidr = "10.10.0.0/16"
    default_tags = {
        environment = "development1",
        owner = "r&d",
        cost_centre = "1234567890"
    }
    subnet_count = 2
}

module "vpc2" {
    source    = "./modules/network"
    vpc_cidr = "10.20.0.0/16"
    default_tags = {
        environment = "development2",
        owner = "r&d",
        cost_centre = "1234567890"
    }
    subnet_count = 4
}

3. Terraform 초기화 및 실행

$ terraform init
$ terraform plan --out tfplan
$ terraform apply tfplan
module.vpc1[0].aws_subnet.public[1]: Destroying... [id=subnet-00b62c735078083ed]
module.vpc1[0].aws_subnet.public[0]: Destroying... [id=subnet-0681a4aef56086385]
module.vpc2.aws_vpc.main: Creating...
module.vpc1.aws_vpc.main: Creating...
module.vpc1[0].aws_subnet.public[0]: Destruction complete after 0s
module.vpc1[0].aws_subnet.public[1]: Destruction complete after 0s
module.vpc1[0].aws_vpc.main: Destroying... [id=vpc-0895973aa883a2647]
module.vpc1[0].aws_vpc.main: Destruction complete after 1s
module.vpc2.aws_vpc.main: Creation complete after 1s [id=vpc-0dcc985afea4250fb]
module.vpc2.aws_subnet.public[0]: Creating...
module.vpc2.aws_subnet.public[2]: Creating...
module.vpc2.aws_subnet.public[3]: Creating...
module.vpc2.aws_subnet.public[1]: Creating...
module.vpc1.aws_vpc.main: Creation complete after 1s [id=vpc-019be906133fe0b4d]
module.vpc1.aws_subnet.public[1]: Creating...
module.vpc1.aws_subnet.public[0]: Creating...
module.vpc2.aws_subnet.public[0]: Still creating... [10s elapsed]
module.vpc2.aws_subnet.public[2]: Still creating... [10s elapsed]
module.vpc2.aws_subnet.public[3]: Still creating... [10s elapsed]
module.vpc2.aws_subnet.public[1]: Still creating... [10s elapsed]
module.vpc1.aws_subnet.public[1]: Still creating... [10s elapsed]
module.vpc1.aws_subnet.public[0]: Still creating... [10s elapsed]
module.vpc2.aws_subnet.public[0]: Creation complete after 11s [id=subnet-05bee4712747c6b06]
module.vpc2.aws_subnet.public[1]: Creation complete after 11s [id=subnet-054bd5f5762734ad0]
module.vpc1.aws_subnet.public[0]: Creation complete after 11s [id=subnet-04f13fd1543150886]
module.vpc2.aws_subnet.public[3]: Creation complete after 11s [id=subnet-012d32c1ccc6ea97a]
module.vpc2.aws_subnet.public[2]: Creation complete after 11s [id=subnet-0a7e41b8ca6c0af5e]
module.vpc1.aws_subnet.public[1]: Creation complete after 11s [id=subnet-03b64331d0aa898cb]

Apply complete! Resources: 8 added, 0 changed, 3 destroyed.

[Terraform] Meta arguments

EndiYou — Mon, 22 Dec 2025 22:10:34 +0900

Meta arguments 종류

depens_on : Terraform이 자동으로 추론할 수 없는 숨겨진 리소스 또는 모듈 종속성을 처리한다.
count : resource block은 1개의 인프라 객체를 구성한다. 1개 이상의 pool을 관리하고 싶을 때 사용한다.
for_each : index 요소를 참조해야 할 경우 count 대신 사용한다.특정 요소가 목록 중간에 제거되면 해당 요소 뒤의 모든 인스턴스에서 해당 subnet_id 값이 변경되는 경우가 발생할 수 있는데 for_each를 통해서 해소할 수 있다.
provider : 공급자 메타 인수는 리소스 유형 이름을 기반으로 선택하는 Terraform의 기본 동작을 재정의하여 리소스에 사용할 공급자 구성을 지정한다.
lifecycle : create_before_destroy vs prevent_destroy와 같은 특정 리소스의 생성 및 삭제 통작을 설명한다.

Meta arguments 고려 사항

Meta arfuments를 사용하여 코드를 작성할 때 고려해야 할 몇 가지 사항이 있다. vpc.tf 파일에서 Subnet 리소스에 적용하는 과정을 기준으로 고려할 사항을 보면 세 가지다.

tags.name: tag에 있는 "Name"의 속성 값에는 서브넷 이름에 증분 값이 포함되어야 한다.
availability_zone: 서브넷 마다 다르게 구성할 수 있어야 하는데, 인덱스 오류를 방지하도록 주의해서 코드를 작성한다.
cidr_block: 증가하고 충돌하지 않는 CIDR block을 구성해야 한다.

Meta arguments 사용 방법

원하는 Subnet 수를 입력 변수 형식으로 사용자에게 물어보는 코드가 추가되어야 한다.

1. variables.tf 내용 수정

# variables.tf
...

variable subnet_count {
  type = number
  default = 2
}

2. locals.tf 내용 수정

이 설정은 VPC CIDR로 prefix 값이 /16으로 제공된 경우 서브넷에는 CIDR 값으로 /24가 할당한다.

# locals.tf
locals {
  subnet_new_bits = 8
}

3. 충돌하지 않는 CIDR 구성 방법

Terraform function을 cidr_subnets → cidr_subnet 교체한다. 두 함수의 차이는 인수 값이 주어지는 형태가 다르다. cidr_subnet 기능은 동적인 입력에 이용 가능하지만 cidr_subnets 기능은 적합하지 않다.

3.1 cidr_subnet vs cidr_subnets format

# cidrsubnets
cidrsubnets(prefix, newbits1, newbits2...)

# cidrsubnet
cidrsubnets(prefix, newbits, netnum)

3.2 cidr_subnet 예시

cidrsubnet("10.0.0.0/16",8,0)	# "10.0.0.0/24"
cidrsubnet("10.0.0.0/16",8,1)	# "10.0.1.0/24"
cidrsubnet("10.0.0.0/16",8,2)	# "10.0.2.0/24"

4. 서브넷 Availability_Zone 구성 간 인덱스 오류 방지하는 방법

Terraform function의 element를 사용하여 인덱스 오류를 방지할 수 있다. AWS로 부터 Data source의 Attribute list를 받아온 결과 값을 element 함수를 이용해 Index 범위 안으로 둘러싸는 형태로 동작한다.

element(["eu-west-1a", "eu-west-1b", "eu-west-1c"],1)	# 출력 : "eu-west-1b"
element(["eu-west-1a", "eu-west-1b", "eu-west-1c"],5)	# 출력 : "eu-west-1c" / 인덱스 번호가 3을 초과하지만 오류가 발생하지 않는다.

5. 고유한 subnet 이름을 등록하는 방법

Terraform의 count 함수를 이용해서 인덱스 번호를 증분 할 수 있다.

# var.tf
...

tags = merge(
  {
    "Name" = "Public${count.index+1}"
  }, 
  var.default_tags
  )

...

Meta arguments 수정

1. 반영 종합본

# var.tf
resource "aws_vpc" "main" {
  cidr_block = var.vpc_cidr
  tags = merge(
    {
      "Name" = "Main"
    }, 
    var.default_tags
  )
}

resource "aws_subnet" "public" {
  count = var.subnet_count

  vpc_id     = aws_vpc.main.id
  cidr_block = cidrsubnet(var.vpc_cidr,local.subnet_new_bits,count.index)

  tags = merge(
  {
    "Name" = "Public${count.index+1}"
  }, 
  var.default_tags
  )
  availability_zone = element(data.aws_availability_zones.available.names,count.index)
  map_public_ip_on_launch = true
}

2. output 파일 수정

서브넷의 이름이 가변적이기 때문에 앞에서 state 정보를 저장하기 위해 구성했던 output 파일의 변수명도 다르게 지정해주어야 한다. output.tf 파일을 다음과 같이 수정해야 한다.

output "main_vpc_id" {
  value = aws_vpc.main.id
  description = "The Id of the main VPC"
}

output "main_subnet_id" {
  value = aws_subnet.public.*.id		// aws_subnet.public1~2.id 값을 * 표시로 처리할 수 있다.
  description = "The Id of the seubnet"
}

3. Terraform 실행 후 출력 결과 확인

$ terraform plan -var-file=environments/dev.tfvars --out tfplan
$ terraform apply tfplan
aws_vpc.main: Creating...
aws_vpc.main: Creation complete after 1s [id=vpc-06b654f4911434cce]
aws_subnet.public[1]: Creating...
aws_subnet.public[0]: Creating...
aws_subnet.public[1]: Still creating... [10s elapsed]
aws_subnet.public[0]: Still creating... [10s elapsed]
aws_subnet.public[0]: Creation complete after 11s [id=subnet-0f76fd597fe43dc3b]
aws_subnet.public[1]: Creation complete after 11s [id=subnet-0ad2624918ad45a20]

Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Outputs:

main_subnet_id = [
  "subnet-0f76fd597fe43dc3b",
  "subnet-0ad2624918ad45a20",
]
main_vpc_id = "vpc-06b654f4911434cce"

[Terraform] Data source & Terraform fucntion

EndiYou — Fri, 19 Dec 2025 20:07:17 +0900

Data source

Variable, Output을 이용해 데이터를 입력하거나 출력 되는 과정의 데이터를 변수에 담는 방식을 이용할 수 있다. 그 과정에 선언한 VPC, Subnet 생성 코드에는 하드코딩 된 데이터가 일부 있는데 재활용을 높이기 위해서는 이 부분을 최소화 해야 한다. 이 때 하드코딩 된 부분을 모두 변수로 선언해서 재활용을 높일 수도 있으나 Data source를 이용할 수 있다. Data source는 Terraform 외부 환경에 정의된 리소스의 Attribute 정보를 읽어와 코드에 변수 값을 저장하듯이 사용할 수 있다.

1. 서브넷 정보 확인

기존 구성된 vpc.tf 파일에서는 서브넷 정보를 아래와 같이 하드코딩 해두었다.

# vpc.tf
resource "aws_subnet" "public1" {
  vpc_id     = aws_vpc.main.id
  cidr_block = "10.10.1.0/24"			#개선이 필요한 부분 1

  tags = merge(
  {
    "Name" = "Public1"
  },
  var.default_tags
  )
  availability_zone = "ap-northeast-2a" #개선이 필요한 부분 2
  map_public_ip_on_launch = true
}

2. data source 설정

data_source.tf 파일을 추가하고, 아래 내용을 입력한다.

# data_source.tf
data "aws_availability_zones" "available" {
  state = "available"
}

3. 서브넷 정보 수정

하드코딩 되어 있던 서브넷 정보를 data_source 정보로 수정한다.

# vpc.tf
resource "aws_subnet" "public1" {
  vpc_id     = aws_vpc.main.id
  cidr_block = "10.10.1.0/24"

  tags = merge(
  {
    "Name" = "Public1"
  },
  var.default_tags
  )
  availability_zone = data.aws_availability_zones.available.names[0]	#내용수정
  map_public_ip_on_launch = true
}  

resource "aws_subnet" "public2" {
  vpc_id     = aws_vpc.main.id
  cidr_block = "10.10.2.0/24"

  tags = merge(
  {
    "Name" = "Public2"
  },
  var.default_tags
  )
  availability_zone = data.aws_availability_zones.available.names[1]	#내용수정    map_public_ip_on_launch = true
}

Terraform function

Terraform에 내장되어 있는 기능을 이용해 Incoding/Decoding, Input/Output, Timestamp 등의 기능을 수행할 수 있다. Terraform은 내장 함수만 지원하고 사용자 정의 함수는 지원하지 않는다. Terraform functions을 이용해서 AWS Subnet의 CIDR을 하드코딩 하지 않고 재활용성을 높일 수 있다.

1. cidrsubnets

cidrsubnets function은 특정 CIDR 접두사 내에 일련의 연속 IP 주소 범위를 계산한다. 형식은 다음과 같다.

# cidrsubnets(prefix, newbits1, newbits2...)
cidrsubnets("10.0.0.0/16", 8, 8)

prefix: 서브넷을 생성할 대상이 되는 VPC의 CIDR을 입력한다.
newbits: 추가할 서브넷의 CIDR prefix의 추가 bits 값 수를 의미한다. 복수 개의 값을 콤마(,) 단위로 구분해서 넣을 수 있다.

2. locals.tf 추가

locals.tf 파일을 생성하고, 아래의 repository structure를 구성한다.

/root/terraform-starter/
├── backend.tf
├── data_source.tf
├── environments
│   ├── dev.tfvars
│   ├── terraform.tfstate
│   └── tfplan
├── locals.tf
├── output.tf
├── provider.tf
├── tfplan
├── variables.tf
├── version.tf
└── vpc.tf

# locals.tf
locals {
    subnet_addresses = cidrsubnets(var.vpc_cidr,8,8)
}

3. 서브넷에서 사용하는 cidr block 정보 변경

# vpc.tf
resource "aws_subnet" "public1" {
  vpc_id     = aws_vpc.main.id
  cidr_block = local.subnet_addresses[0]	#내용수정

  tags = merge(
  {
    "Name" = "Public1"
  },
  var.default_tags
  )
  availability_zone = data.aws_availability_zones.available.names[0]
  map_public_ip_on_launch = true
}  

resource "aws_subnet" "public2" {
  vpc_id     = aws_vpc.main.id
  cidr_block = local.subnet_addresses[1]	#내용수정

  tags = merge(
  {
    "Name" = "Public2"
  },
  var.default_tags
  )
  availability_zone = data.aws_availability_zones.available.names[1]
  map_public_ip_on_launch = true
}

[Terraform] Attribute & Output

EndiYou — Fri, 19 Dec 2025 19:46:27 +0900

Attribute

provider를 통해 만들어진 리소스는 Attribute을 가지게 되는데, 이 값들은 서로 연관된 다른 리소스를 생성할 때 참조해야 할 때가 있다. 예를 들어, VPC는 vpc.id라는 Attribute을 가지고 있는데, subnet을 만들 때 vpc.id를 필수 값으로 반영해야 하기 때문에 참조할 데이터의 대상이 된다.

1. Attribute 참조 형식

# <provider_name>_<resource_type>.<resource_name>.<attribute_name>
aws_vpc.main.id

2. Attribute 적용 예시

resource "aws_vpc" "main" {
  cidr_block = var.vpc_cidr
  tags = merge(
    {
      "Name" = "Main"
    },
    var.default_tags
  )
}

resource "aws_subnet" "public1" {
  vpc_id     = aws_vpc.main.id			# Attribute 적용
  cidr_block = "10.10.1.0/24"

  tags = merge(
  {
    "Name" = "Public1"
  }, 
  var.default_tags
  )
  availability_zone = "ap-northeast-2a"
  map_public_ip_on_launch = true
}

resource "aws_subnet" "public2" {
  vpc_id     = aws_vpc.main.id			# Attribute 적용
  cidr_block = "10.10.2.0/24"

  tags = merge(
  {
    "Name" = "Public2"
  }, 
  var.default_tags
  )
  availability_zone = "ap-northeast-2b"
  map_public_ip_on_launch = true
}

Output

terraform에 데이터를 입력하여 변수에 저장할 때는 variable을 사용하고, terraform apply를 통해 출력되는 결과들을 변수에 저장할 때는 output을 사용한다. terraform을 이용해 작업하는 과정에 생성한 리소스의 Attribute 값을 확인해야 할 때가 종종 있는데, 이럴 때 별도로 저장해 두지 않으면 Provider의 Console 화면에 접속해서 확인해야 한다. Output을 이용하면 지정한 Attribute 값을 tfstate 파일에 저장해 둘 수 있다.

1. 환경구성

output.tf 파일을 생성하고, 아래의 repository structure를 구성한다.

/root/terraform-starter/
├── backend.tf
├── environments
│   ├── dev.tfvars
│   ├── terraform.tfstate
│   └── tfplan
├── outputs.tf
├── provider.tf
├── tfplan
├── variables.tf
├── version.tf
└── vpc.tf

2. output.tf 파일 구성

output "main_vpc_id" {
  value = aws_vpc.main.id
  description = "The Id of the main VPC"
}

output "main_subnet_id1" {
  value = aws_subnet.public1.id
  description = "The Id of the public1 seubnet"
}

output "main_subnet_id2" {
  value = aws_subnet.public2.id
  description = "The Id of the public2 seubnet"
}

3. terraform 실행 후 출력 결과 확인

$ terraform plan -var-file=environments/dev.tfvars --out tfplan
$ terraform apply tfplan 
aws_vpc.main: Creating...
aws_vpc.main: Creation complete after 1s [id=vpc-09aa0594e068b32e3]
aws_subnet.public1: Creating...
aws_subnet.public2: Creating...
aws_subnet.public1: Still creating... [10s elapsed]
aws_subnet.public2: Still creating... [10s elapsed]
aws_subnet.public1: Creation complete after 11s [id=subnet-0717449db12deb551]
aws_subnet.public2: Creation complete after 11s [id=subnet-0a737275d2d6186e2]

Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Outputs:

main_subnet_id1 = "subnet-0717449db12deb551"
main_subnet_id2 = "subnet-0a737275d2d6186e2"
main_vpc_id = "vpc-09aa0594e068b32e3"

4. terrafotm state 값 확인

terraform 실행 결과 정보들은 state 파일에 저장된다.
이 정보는 다른 모듈에서 접근할 수 있고, 모듈 간에 공유해야 할 데이터를 구성하는데 활용된다.

$ terraform state show aws_vpc.main 
# aws_vpc.main:
resource "aws_vpc" "main" {
    arn                              = "arn:aws:ec2:ap-northeast-2:xxxxxxxxxxxx:vpc/vpc-09aa0594e068b32e3"
    assign_generated_ipv6_cidr_block = false
    cidr_block                       = "10.10.0.0/16"
    default_network_acl_id           = "acl-0e749908dd99f3c90"
    default_route_table_id           = "rtb-07ccf3f9ca94c53e1"
    default_security_group_id        = "sg-03c7d17739cb897ac"
    dhcp_options_id                  = "dopt-069864bdefac47704"
    enable_dns_hostnames             = false
    enable_dns_support               = true
    id                               = "vpc-09aa0594e068b32e3"	#저장된 aws vpc id Attribute 값
    instance_tenancy                 = "default"
    main_route_table_id              = "rtb-07ccf3f9ca94c53e1"
    owner_id                         = "xxxxxxxxxxxx"
    tags                             = {
        "Name"        = "Main"
        "cost_centre" = "1234567890"
        "environment" = "staging"
        "owner"       = "r&d"
    }
    tags_all                         = {
        "Name"        = "Main"
        "cost_centre" = "1234567890"
        "environment" = "staging"
        "owner"       = "r&d"
    }
}

[Terraform] Variable & Validation

EndiYou — Fri, 19 Dec 2025 14:36:41 +0900

Variable & Validation 선언

변수를 사용하면 코드를 더 쉽게 재사용할 수 있고, 다른 구성 간에 코드를 공유할 수 있다.

1. variable 파일 없이 직접 입력하는 방식

# vpc.tf
resource "aws_vpc" "main" {
  cidr_block = "10.0.0.0/16"

  tags = {
	Name = "main",
    Environment = "development",
	CostCenter = "23213"
  }
}

2. variable.tf 파일을 이용해 데이터를 입력하는 방식

variable은 "vpc_cidr", "default_tags" 두 가지로 구분된다.
variable 내부는 type, description, default, validation로 구성되어 있다.

# variable.tf
variable "vpc_cidr" {
    type = string
    description = "The CIDR block for the VPC"
    default = "10.0.0.0/16"
    
    validation {
        condition = can(regex("^([0-9]{1,3}\\.){3}[0-9]{1,3}($|/(16|24))$",var.vpc_cidr))
        error_message = "Please ensure a valid CIDR has been entered with range /16 or /24."
    }
}

variable default_tags {
    type = object({
        environment = string
        owner = string
        cost_centre = string
    })
    description = "Default set of tags to apply to resources"
    default = {
        environment = "development",
        owner = "r&d",
        cost_centre = "1234567890"
    }
    
    validation {
        condition = length(var.default_tags.cost_centre) == 10
        error_message = "Please ensure a valid 10 digit cost centre code has been entered."
    }
}

type: 변수의 데이터 유형 정의 (ex: string, list, map)
description : 변수 용도 설명 (참고용)
default : 사용자의 입력이 없을 경우 사용될 기본 값 지정
validation : 입력된 변수 값 검증 규칙 설정

# vpc.tf
resource "aws_vpc" "main" {
  cidr_block = var.vpc_cidr
  tags = var.default_tags
}

3. variable.tf 파일의 변수 외에 별도 설정 값을 병합해서 사용하는 방식

cidr_block : variable.tf에 선언된 Default 값(10.0.0.0/16) 적용
tag : vpc.tf에 선언된 Name tag와 variable.tf의 Default 값이 함께 적용

resource "aws_vpc" "main" {
  cidr_block = var.vpc_cidr
  tags = merge(
    var.default_tags,
    {
      "Name" = "Main"
    }
  )
}

tfvars 파일을 이용한 환경 별 다른 변수 값 적용

variable.tf 파일은 변수의 형식을 지정하는데 사용되고, .tfvars 파일은 실제 입력할 데이터를 지정한다. 배포하는 환경 별로 다른 입력값을 사용하기 위해서 dev.tfvars, prd.tfvars 형태로 파일을 구성해서 apply 단계에서 지정해서 사용할 수 있다.

1. 환경 구성

environments 디렉터리를 추가하고, 그 하위에 dev.tfvars 파일을 생성한다.

/root/terraform-starter/
├── backend.tf
├── environments
│   └── dev.tfvars
├── provider.tf
├── terraform.tfstate
├── terraform.tfstate.backup
├── tfplan
├── variables.tf
├── version.tf
└── vpc.tf

$ mkdir environments
$ cd environments
$ touch dev.tfvars

2. 입력 데이터 값 설정

# environments/dev.tfvars
vpc_cidr = "10.10.0.0/16"
default_tags = {
  environment = "staging",
  owner = "r&d",
  cost_centre = "1234567890"
}

3. 배포 명령

$ terraform plan -var-file=environments/dev.tfvars --out tfplan
$ terraform apply tfplan