> For the complete documentation index, see [llms.txt](https://atomoh.gitbook.io/eks-workshop/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atomoh.gitbook.io/eks-workshop/readme.md).

# 워크샵 소개

> **Amazon EKS 기능을 실습으로 배우는 한국어 워크샵 가이드**
>
> 원본: [eksworkshop.com](https://www.eksworkshop.com/) | 마지막 업데이트: 2026-07-24

***

## 이 워크샵은?

[Amazon EKS Workshop](https://www.eksworkshop.com/)은 AWS에서 공식 제공하는 EKS 실습 가이드입니다. 이 한국어 워크샵은 upstream [aws-samples/eks-workshop-v2](https://github.com/aws-samples/eks-workshop-v2)의 `website/docs/` 전체 구조를 그대로 미러링하여, 373페이지에 달하는 원본 콘텐츠를 10개 대분류(Introduction, Fundamentals, Networking, Security, Observability, Automation, Fastpaths, AI/ML, Troubleshooting, 기타)로 빠짐없이 한국어로 제공합니다.

**특징:**

* 원본 eksworkshop.com 전체 콘텐츠를 한국어로 제공 (기존 13개 선별 모듈 → 전체 미러링으로 확장)
* 각 페이지마다 핵심 개념 설명 → 단계별 실습 → 결과 확인의 일관된 구조
* `prepare-environment` 명령으로 환경 준비(\~5분) 동안 개념을 먼저 학습하는 효율적 흐름
* 코드 블록은 그대로 복사하여 터미널에 붙여넣기 가능
* 디렉터리 구조가 upstream `website/docs/`와 1:1로 대응되어, 원본 업데이트 추적과 동기화가 용이

{% hint style="info" %}
이 워크샵은 [aws-samples/eks-workshop-v2](https://github.com/aws-samples/eks-workshop-v2) 전체를 기반으로 작성되었습니다. 원본 영문 콘텐츠는 [eksworkshop.com](https://www.eksworkshop.com/)에서 확인할 수 있습니다. 구조 전환 배경은 [ADR-001](https://github.com/Atom-oh/eks-workshop/tree/main/docs/decisions/ADR-001-mirror-upstream-structure.md)을 참고하세요.
{% endhint %}

## "컨테이너는 띄웠는데, 그 다음은?"

쿠버네티스 클러스터를 만들고 첫 번째 Pod를 배포하는 것까지는 순조롭습니다. 하지만 곧 질문이 쏟아집니다 — 노드는 어떻게 관리하지? 트래픽이 몰리면 자동으로 확장할 수 있나? 외부에서 서비스에 어떻게 접근하지? 스토리지는 어떻게 붙이지? 보안과 네트워크 정책은 어떻게 구성하지? 배포는 매번 수동으로 해야 하나? 문제가 생기면 어떻게 디버깅하지?

이 워크샵은 **Amazon EKS**의 기능을 Kubernetes 기초부터 컴퓨팅, 네트워킹, 보안, 관측성, 자동화, AI/ML, 트러블슈팅까지 순서대로 실습하며 이 질문들에 답합니다.

## 10개 섹션 구성

| 섹션                                                                     | 주제                   | 설명                                                                                                                         | upstream 페이지 |
| ---------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------ |
| [Introduction](/eks-workshop/introduction/introduction.md)             | 시작하기                 | 환경 설정, 랩 탐색법, 샘플 애플리케이션, Kubernetes 기본 개념(Pods/Namespaces/Services/Workload), Kustomize/Helm                               | 28           |
| [Fundamentals](/eks-workshop/fundamentals/fundamentals.md)             | 기초                   | 애플리케이션 노출(LB/Ingress/Gateway API), 스토리지(EBS/EFS/FSx/S3), 컴퓨팅(MNG/Karpenter/Fargate), 워크로드 오토스케일링(HPA/CPA/KEDA), 클러스터 업그레이드 | 83           |
| [Networking](/eks-workshop/networking/networking.md)                   | 네트워킹                 | VPC CNI(Network Policies/Security Groups for Pods/Custom Networking/Prefix Delegation), VPC Lattice, EKS Hybrid Nodes      | 30           |
| [Security](/eks-workshop/security/security.md)                         | 보안                   | Cluster Access Management API, IRSA, EKS Pod Identity, Secrets Management, GuardDuty, Pod Security Standards, Kyverno      | 51           |
| [Observability](/eks-workshop/observability/observability.md)          | 관측성                  | EKS 콘솔, 로깅, OpenSearch, 오픈소스 메트릭(ADOT/AMP/Grafana), Container Insights, Kubecost, 카오스 엔지니어링/HA                             | 47           |
| [Automation](/eks-workshop/automation/automation.md)                   | 자동화                  | GitOps(ArgoCD/Flux), Control Planes(ACK/Crossplane/kro), Continuous Delivery(CodePipeline), Platform Engineering           | 39           |
| [Fastpaths](/eks-workshop/fastpaths-amazon-eks-auto-mode/fastpaths.md) | Amazon EKS Auto Mode | Auto Mode 클러스터 기반 빠른 학습 경로: Developer Essentials, Operator Essentials                                                      | 52           |
| [AI/ML](/eks-workshop/ai-ml/aiml.md)                                   | AI/ML on EKS         | vLLM 챗봇, AWS Inferentia 추론, Kiro CLI 운영, AI on EKS                                                                         | 18           |
| [Troubleshooting](/eks-workshop/troubleshooting/troubleshooting.md)    | 문제 해결 시나리오           | ALB Controller, DNS Resolution, Pod Issues, Worker Nodes 트러블슈팅 실습                                                          | 19           |
| [기타](/eks-workshop/undefined-1/cloud9-access.md)                       | 기타                   | Cloud9 접근, 메이저 업그레이드, 레거시 환경 이전, [정리(Cleanup)](/eks-workshop/undefined-1/cleanup.md)                                       | 4            |

{% hint style="warning" %}
**Introduction → Fundamentals → Networking → Security → Observability → Automation → Fastpaths → AI/ML** 순서로 진행하는 것을 권장합니다. Troubleshooting과 기타 섹션은 순차적 학습 흐름이 아니라 필요할 때 참고하는 독립 자료입니다. Fastpaths는 별도의 Amazon EKS Auto Mode 클러스터를 사용하므로, 다른 섹션과 클러스터를 공유하지 않는 독립 실습 경로입니다.
{% endhint %}

## 학습 여정

```mermaid
graph LR
    A["Introduction<br/><i>환경설정 &<br/>K8s 기초</i>"] --> B["Fundamentals<br/><i>컴퓨팅 · 노출 ·<br/>스토리지 · 오토스케일링</i>"]
    B --> C["Networking<br/><i>VPC CNI · Lattice ·<br/>Hybrid Nodes</i>"]
    C --> D["Security<br/><i>IAM · Pod Identity ·<br/>Secrets · GuardDuty</i>"]
    D --> E["Observability<br/><i>로깅 · 메트릭 ·<br/>카오스 엔지니어링</i>"]
    E --> F["Automation<br/><i>GitOps · Control<br/>Planes · CD</i>"]
    F --> G["Fastpaths<br/><i>EKS Auto Mode<br/>빠른 학습</i>"]
    G --> H["AI/ML<br/><i>vLLM · Inferentia ·<br/>Kiro CLI</i>"]

    T["Troubleshooting<br/><i>필요시 참고</i>"]
    M["기타 · Cleanup<br/><i>필요시 참고</i>"]

    style A fill:#232F3E,stroke:#FF9900,color:#fff
    style B fill:#232F3E,stroke:#FF9900,color:#fff
    style C fill:#232F3E,stroke:#FF9900,color:#fff
    style D fill:#232F3E,stroke:#FF9900,color:#fff
    style E fill:#232F3E,stroke:#FF9900,color:#fff
    style F fill:#232F3E,stroke:#FF9900,color:#fff
    style G fill:#232F3E,stroke:#FF9900,color:#fff
    style H fill:#232F3E,stroke:#FF9900,color:#fff
    style T fill:#555,stroke:#999,color:#fff
    style M fill:#555,stroke:#999,color:#fff
```

## 달성할 내용

이 워크샵을 마치면 다음을 수행할 수 있습니다:

* Kubernetes 핵심 리소스(Pods, Namespaces, Services, Deployments, ConfigMaps/Secrets)와 Kustomize/Helm 이해
* EKS Managed Node Groups, Karpenter, Fargate를 활용한 컴퓨팅 관리 및 오토스케일링 전략 구성
* Load Balancer, Ingress, Gateway API를 통한 애플리케이션 노출과 EBS/EFS/FSx/S3 기반 스토리지 구성
* HPA, Cluster Proportional Autoscaler, KEDA를 활용한 워크로드 오토스케일링 구현
* VPC CNI Network Policies, Security Groups for Pods, VPC Lattice, EKS Hybrid Nodes를 활용한 네트워크 구성
* IRSA/EKS Pod Identity로 워크로드에 최소 권한 IAM 역할 연결, Secrets Manager·GuardDuty·Kyverno로 보안 강화
* CloudWatch/OpenSearch/Prometheus/Grafana/Kubecost를 활용한 로깅, 메트릭, 비용 관측성 구축과 카오스 엔지니어링 실습
* ArgoCD/Flux 기반 GitOps, ACK/Crossplane/kro 기반 Control Plane 자동화, CodePipeline 기반 CI/CD 구현
* Amazon EKS Auto Mode 환경에서 Fastpaths를 통한 빠른 실습, AI/ML 워크로드(vLLM, Inferentia) 운영
* ALB/DNS/Pod/Worker Node 관련 실제 장애 시나리오 트러블슈팅

## 사전 요구 사항

* AWS 서비스 기본 이해 (VPC, EC2, IAM, EKS)
* Kubernetes 기본 개념 (Pod, Service, Deployment, Namespace)
* YAML 문법과 kubectl CLI 기초
* Git 기본 사용법

{% hint style="info" %}
실습 환경 설정은 [환경 접근 가이드](/eks-workshop/undefined/overview.md)와 [Introduction의 설정 가이드](/eks-workshop/introduction/introduction/setup.md)를 참고하세요. AWS 호스팅 이벤트 참여 시 별도 환경이 제공되며, 개인 AWS 계정 사용 시 [자신의 AWS 계정에서 설정하기](/eks-workshop/introduction/introduction/setup/your-account.md)를 따라 진행할 수 있습니다.
{% endhint %}

## 워크샵 핵심 도구: Helm & Kustomize

이 워크샵 전반에서 Kubernetes 리소스를 배포하고 관리하기 위해 **Helm**과 **Kustomize** 두 가지 도구를 사용합니다. 자세한 개념은 [Introduction의 Kustomize](/eks-workshop/introduction/introduction/kustomize.md), [Introduction의 Helm](/eks-workshop/introduction/introduction/helm.md) 페이지에서 다루며, 여기서는 핵심만 짚습니다.

### Helm — Kubernetes 패키지 매니저

Helm은 여러 Kubernetes 리소스(Deployment, Service, ConfigMap, RBAC 등)를 하나의 **Chart**로 패키징하여 설치, 업그레이드, 삭제를 한 번에 처리하는 도구입니다. Linux의 `apt`/`yum`, Node.js의 `npm`과 유사한 역할입니다.

**이 워크샵에서의 사용 예:**

```bash
# Chart 리포지토리를 추가하고 설치
helm repo add kedacore https://kedacore.github.io/charts
helm upgrade --install keda kedacore/keda \
  --namespace keda --create-namespace \
  --set serviceAccount.annotations."eks\.amazonaws\.com/role-arn"=$KEDA_ROLE_ARN \
  --wait
```

| 사용 섹션                  | 설치 대상                        | 설명                                          |
| ---------------------- | ---------------------------- | ------------------------------------------- |
| Fundamentals/Compute   | Karpenter                    | OCI 레지스트리(`public.ecr.aws`)에서 Helm Chart 설치 |
| Fundamentals/Workloads | KEDA                         | 이벤트 기반 오토스케일러 설치                            |
| Fundamentals/Exposing  | AWS Load Balancer Controller | L4/L7 로드밸런서 컨트롤러 설치                         |
| Automation/GitOps      | ArgoCD, Flux                 | GitOps 서버 설치, Git 리포지토리 프로비저닝               |
| Observability          | ADOT, Kubecost               | 메트릭 수집 및 비용 가시성 도구 설치                       |

**핵심 개념:**

```
Chart          하나의 애플리케이션을 구성하는 Kubernetes 매니페스트 템플릿 묶음
Repository     Chart를 저장하고 공유하는 저장소 (HTTP 또는 OCI 레지스트리)
Release        Chart를 클러스터에 설치한 인스턴스 (같은 Chart를 여러 번 설치 가능)
values.yaml    Chart의 기본 설정값. --set이나 -f로 오버라이드 가능
```

{% hint style="info" %}
Helm Chart는 **템플릿 엔진**을 사용합니다. `values.yaml`의 값이 Go 템플릿(`{{ .Values.xxx }}`)에 주입되어 최종 매니페스트가 생성됩니다. `--set key=value`로 개별 값을, `-f custom-values.yaml`로 전체 설정을 오버라이드할 수 있습니다.
{% endhint %}

### Kustomize — 패치 기반 매니페스트 커스터마이징

Kustomize는 원본 YAML을 **직접 수정하지 않고** 오버레이(overlay)와 패치를 적용하여 환경별로 다른 설정을 관리하는 도구입니다. `kubectl`에 내장되어 있어 별도 설치가 필요 없습니다.

**이 워크샵에서의 사용 예:**

```bash
# kustomize로 매니페스트 적용 (-k 플래그)
kubectl apply -k ~/environment/eks-workshop/manifests/modules/fundamentals/compute/managed-node-groups/basics/affinity/

# 적용 전 미리보기
kubectl kustomize ~/environment/eks-workshop/manifests/modules/fundamentals/compute/managed-node-groups/basics/affinity/
```

| 사용 섹션                  | 적용 대상              | 설명                                             |
| ---------------------- | ------------------ | ---------------------------------------------- |
| Fundamentals/Compute   | Pod Affinity 설정    | checkout Deployment에 affinity 패치 적용            |
| Fundamentals/Compute   | Karpenter NodePool | NodePool/EC2NodeClass CRD 매니페스트 적용             |
| Fundamentals/Workloads | HPA/KEDA 설정        | HorizontalPodAutoscaler, ScaledObject 매니페스트 적용 |
| Fundamentals/Exposing  | LB/Ingress         | NLB Service, ALB Ingress 매니페스트 적용              |
| Networking/VPC CNI     | Network Policies   | NetworkPolicy 매니페스트 적용                         |

**핵심 개념:**

```
kustomization.yaml   Kustomize의 설정 파일. 어떤 리소스에 어떤 패치를 적용할지 정의
Base                 원본 매니페스트 (수정하지 않음)
Overlay              Base 위에 적용할 환경별 패치 (dev, staging, prod 등)
Patch                Base 리소스의 특정 필드만 변경하는 부분 매니페스트
```

{% hint style="info" %}
`kubectl apply -k <directory>`의 `-k` 플래그가 핵심입니다. 이 플래그는 해당 디렉토리의 `kustomization.yaml`을 읽어 Base + Patch가 합쳐진 최종 매니페스트를 생성하고 적용합니다. 적용 전에 `kubectl kustomize <directory>`로 결과를 미리 확인하는 습관을 들이세요.
{% endhint %}

### Helm vs Kustomize — 언제 무엇을 사용하나?

| 기준          | Helm                             | Kustomize                      |
| ----------- | -------------------------------- | ------------------------------ |
| **주 용도**    | 외부 패키지(Chart) 설치                 | 자체 매니페스트 환경별 관리                |
| **동작 방식**   | 템플릿 렌더링 (`{{ .Values }}`)        | 패치 병합 (strategic merge patch)  |
| **별도 설치**   | 필요 (`helm` CLI)                  | 불필요 (`kubectl`에 내장)            |
| **이 워크샵에서** | Karpenter, ArgoCD 등 **외부 도구 설치** | affinity, HPA 등 **워크로드 설정 변경** |

> 실무에서는 두 도구를 함께 사용하는 것이 일반적입니다. Helm으로 인프라 컴포넌트(Ingress Controller, 모니터링 등)를 설치하고, Kustomize로 애플리케이션 매니페스트를 환경별로 관리합니다. 이 워크샵에서도 동일한 패턴을 따릅니다.

## 대상 청중

| 역할              | 관심 포인트                                    |
| --------------- | ----------------------------------------- |
| **클라우드 엔지니어**   | EKS 노드 관리, 오토스케일링 전략                      |
| **DevOps 엔지니어** | GitOps 배포 파이프라인, CI/CD 통합                 |
| **플랫폼 엔지니어**    | 멀티 테넌트 클러스터 운영, Control Plane 자동화, 비용 최적화 |
| **솔루션 아키텍트**    | EKS 아키텍처 설계 패턴, 네트워킹/보안 설계                |
| **SRE**         | 관측성, 카오스 엔지니어링, 트러블슈팅, 배포 안정성             |
| **ML 엔지니어**     | GPU/Inferentia 기반 AI/ML 워크로드 운영           |

## 참고 자료

* [Amazon EKS Workshop (영문 원본)](https://www.eksworkshop.com/)
* [GitHub: eks-workshop-v2](https://github.com/aws-samples/eks-workshop-v2)
* [Amazon EKS 공식 문서](https://docs.aws.amazon.com/eks/)
* [Amazon EKS 모범 사례 가이드](https://aws.github.io/aws-eks-best-practices/)
* [ADR-001: 워크샵 구조를 upstream 미러로 재편](https://github.com/Atom-oh/eks-workshop/tree/main/docs/decisions/ADR-001-mirror-upstream-structure.md)
* [Upstream 커버리지 체크리스트](https://github.com/Atom-oh/eks-workshop/tree/main/docs/reference/upstream-coverage.md)