---
title: "Kubernetes Ingress를 활용한 클러스터 서비스 외부 접근 관리의 모든 것"
description: "Kubernetes Ingress를 사용해 ClusterIP 서비스 앞에 외부 HTTP(S) 라우팅 규칙을 설정하고, 단일 도메인·경로로 여러 서비스를 노출할 수 있다. 네임스페이스, ConfigMap, Deployment, Service, Ingress 리소스를 순차적으로 배포하고, Traefik이나 NGINX 등 Ingress Controller와 /etc/hosts 매핑을 통해 로컬 테스트한다. Ingress는 트래픽 라우팅, 도메인 매핑, 확장성을 제공해 효율적인 서비스 외부 접근을 가능하게 한다."
date: "2025-10-29"
last_modified: "2026-08-20T01:28:00.000Z"
type: "Post"
tags:
  - "kubernetes"
  - "networking"
  - "load balancing"
categories:
  - "🤖 Computer Science"
series:
  - "k8s"
canonical_url: "https://blog.pieroot.xyz/k8s-ingress-access"
markdown_url: "https://blog.pieroot.xyz/k8s-ingress-access.md"
---

# Kubernetes Ingress를 활용한 클러스터 서비스 외부 접근 관리의 모든 것

Kubernetes Ingress를 사용해 ClusterIP 서비스 앞에 외부 HTTP(S) 라우팅 규칙을 설정하고, 단일 도메인·경로로 여러 서비스를 노출할 수 있다. 네임스페이스, ConfigMap, Deployment, Service, Ingress 리소스를 순차적으로 배포하고, Traefik이나 NGINX 등 Ingress Controller와 /etc/hosts 매핑을 통해 로컬 테스트한다. Ingress는 트래픽 라우팅, 도메인 매핑, 확장성을 제공해 효율적인 서비스 외부 접근을 가능하게 한다.

## Kubernetes Ingress를 활용한 외부 접근 제어

Ingress는 클러스터 내부 Service에 대한 외부 접근을 HTTP(S) 라우팅 규칙으로 제어하는 리소스입니다. `ClusterIP` 타입 서비스 앞단에 위치하여 하나의 엔드포인트(도메인, 경로)로 여러 서비스를 노출할 수 있습니다.

![image](https://blog.pieroot.xyz/api/image-proxy?id=5bc568d5-4ee2-494f-8c0d-401cd1982a2b&kind=s3&pageId=2e4067c0-15d0-80cb-acc2-e56f55e4c5a3&source=block&blockId=2e4067c0-15d0-8088-8e77-e877e448805d)

### 구성 요소

이번 실습에서는 다음과 같은 리소스들을 구성합니다:

- **Namespace**: `file-server` 네임스페이스 생성 (`namespace.yaml`)

- **ConfigMap & Deployment**: 간단한 파일 업로드 서버 배포 (`deployment.yaml`)

- **Service**: 백엔드 서비스를 `ClusterIP`로 노출 (`service.yaml`)

- **Ingress**: `file.test.com` 도메인으로 서비스 라우팅 (`ingress.yaml`)

### 사전 준비

- K3s 기본 Ingress Controller(traefik) 또는 별도의 Ingress Controller가 설치되어 있어야 합니다.

- 로컬 테스트 시 `/etc/hosts` 에 마스터 노드 IP와 `file.test.com`을 매핑합니다.

```bash
sudo sh -c 'echo "<MASTER_NODE_IP> file.test.com" >> /etc/hosts'
```

### Ingress 리소스 정의

Ingress 리소스는 외부 트래픽을 내부 서비스로 라우팅하는 규칙을 정의합니다:

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: simple-file-server-ingress
  namespace: file-server
  annotations:
    # NGINX Ingress Controller 기준: 기본 백엔드로 80 사용
    # nginx.ingress.kubernetes.io/ssl-redirect: "false"   # HTTPS 강제 리다이렉트 비활성화 (HTTP만 사용)
    traefik.ingress.kubernetes.io/router.tls: "false"
spec:
  # ingressClassName: nginx   # 설치한 Ingress Controller의 클래스명. NGINX를 쓴다면 일반적으로 "nginx"
  ingressClassName: traefik
  rules:
    - host: file.test.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: simple-file-server-svc
                port:
                  number: 80
```

### ConfigMap 및 Deployment 구성

애플리케이션 설정과 배포 정의를 포함합니다:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: simple-file-server-config
  namespace: file-server
data:
  PORT: "3001"
  LOG_PATH: "/var/log/app.log"
  UPLOAD_DIR: "/var/uploads"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: simple-file-server
  namespace: file-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: simple-file-server
  template:
    metadata:
      labels:
        app: simple-file-server
    spec:
      nodeSelector:
        kubernetes.io/hostname: "worker-1"
      containers:
        - name: simple-file-server
          image: ghcr.io/jung-geun/simple-file-server:latest
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 3001
          env:
            - name: PORT
              valueFrom:
                configMapKeyRef:
                  name: simple-file-server-config
                  key: PORT
            - name: LOG_PATH
              valueFrom:
                configMapKeyRef:
                  name: simple-file-server-config
                  key: LOG_PATH
            - name: UPLOAD_DIR
              valueFrom:
                configMapKeyRef:
                  name: simple-file-server-config
                  key: UPLOAD_DIR
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "250m"
              memory: "256Mi"
```

### Service 리소스 정의

백엔드 파드를 ClusterIP 타입으로 노출합니다:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: simple-file-server-svc
  namespace: file-server
spec:
  selector:
    app: simple-file-server
  ports:
    - protocol: TCP
      port: 80
      targetPort: 3001
  type: ClusterIP
```

### 배포 순서

다음 순서대로 리소스를 배포합니다:

```bash
# 네임스페이스 생성
kubectl apply -f namespace.yaml

# 애플리케이션 및 서비스 배포
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

# Ingress 생성
kubectl apply -f ingress.yaml
```

### 확인 방법

배포된 리소스 상태를 확인하고 접근 테스트를 수행합니다:

```bash
# 리소스 상태 확인
kubectl get all -n file-server
kubectl describe ingress simple-file-server-ingress -n file-server

# 브라우저 또는 curl로 접근
curl http://file.test.com/
```

### 정리

이 문서에서는 Kubernetes Ingress를 사용하여 클러스터 내부 서비스를 외부에 노출하는 방법을 알아보았습니다. Ingress는 HTTP(S) 레벨에서 트래픽을 라우팅하여 효율적인 서비스 노출이 가능합니다.

- Ingress 규칙은 기본적으로 HTTP/HTTPS 트래픽을 라우팅합니다.

- `ingress.yaml`의 `ingressClassName`을 사용 중인 컨트롤러에 맞게 조정할 수 있습니다.

- 여러 경로 또는 호스트를 추가하여 단일 엔드포인트로 여러 서비스를 노출할 수 있습니다.

### 핵심 정리

✅ **Ingress 역할**: ClusterIP 서비스 앞단에서 HTTP(S) 라우팅 규칙으로 외부 접근 제어

✅ **구성 요소**: Namespace, ConfigMap, Deployment, Service, Ingress 리소스로 구성

✅ **Ingress Controller**: K3s의 기본 Traefik 또는 NGINX 등 다양한 컨트롤러 사용 가능

✅ **도메인 라우팅**: 단일 엔드포인트(도메인)로 여러 서비스 노출 가능

✅ **로컬 테스트**: /etc/hosts 파일 수정으로 도메인 매핑 후 curl 또는 브라우저로 접근 확인

✅ **확장성**: 여러 경로(path)와 호스트(host) 규칙을 추가하여 복잡한 라우팅 구현 가능