API 서버의 요청 처리 흐름: Authentication부터 Admission Control까지

API 서버의 요청 처리 흐름: Authentication부터 Admission Control까지

쿠버네티스 API 서버(kube-apiserver)는 클러스터의 관문으로서 모든 외부 및 내부의 요청을 처리하는 핵심 컴포넌트입니다. 사용자가 kubectl 명령어를 실행하거나 파드 내부의 애플리케이션이 클러스터 자원에 접근하려고 할 때, 이 모든 RESTful HTTP 요청은 API 서버를 거쳐야만 합니다. API 서버는 단순히 요청을 etcd에 전달하는 단순한 프록시가 아닙니다. 클러스터의 보안과 무결성을 유지하고 다중 테넌트 환경에서의 자원 충돌을 방지하기 위해 고도로 정교한 다단계 파이프라인을 통과시킵니다. 이 파이프라인은 크게 인증(Authentication), 인가(Authorization), 그리고 어드미션 컨트롤(Admission Control)의 세 가지 핵심 단계로 나뉘며, 각 단계마다 수많은 플러그인이 유기적으로 상호작용합니다.

1. HTTP 요청 수신 및 병목 제어

API 서버로 향하는 모든 통신은 기본적으로 TLS를 통해 암호화됩니다. API 서버가 클라이언트의 요청을 수신하면 가장 먼저 TLS 터미네이션(TLS Termination)을 수행하여 암호화된 트래픽을 해독합니다. 이후 HTTP 헤더와 URI 경로를 분석하여 요청 리소스(예: Pods, Services)와 HTTP 동사(GET, POST, PUT, PATCH, DELETE)를 식별합니다.

이 초기 단계에서는 클러스터의 보호를 위한 'API Priority and Fairness (APF)' 메커니즘이 작동합니다. API 서버의 과부하를 막기 위해 유입되는 트래픽의 우선순위를 평가하고 대기열(Queue)에 할당합니다. 일반 사용자의 대규모 조회 요청보다 시스템 내부 컨트롤러의 상태 업데이트 요청이 우선 처리되도록 트래픽 셰이핑(Traffic Shaping)을 수행하여, 요청 폭주 상황에서도 클러스터의 코어 기능이 마비되지 않도록 방어합니다.

2. 인증 (Authentication): 접근 주체의 식별

요청이 유효한 형태를 갖추고 API 서버의 수용 한도 내에 있다면, 첫 번째 보안 관문인 '인증' 페이즈로 진입합니다. 인증의 유일한 목적은 "이 요청을 보낸 주체가 누구인가?"를 명확하게 식별하는 것입니다. 쿠버네티스는 내부에 별도의 사용자 데이터베이스를 관리하지 않으며, 여러 개의 인증 플러그인을 체인 형태로 구성하여 순서대로 신원 확인을 시도합니다.

• X.509 클라이언트 인증서: 쿠버네티스 컨트롤 플레인 컴포넌트 간의 통신이나 클러스터 최고 관리자(admin) 계정에서 가장 널리 사용되는 강력한 방식입니다. 클라이언트가 제시한 인증서가 클러스터의 최상위 인증기관(Root CA)에 의해 서명되었는지 수학적으로 검증합니다. 검증이 완료되면 인증서의 'Subject' 필드에 명시된 Common Name(CN)을 사용자 이름으로, Organization(O)을 그룹으로 추출합니다.
• 서비스 어카운트 베어러 토큰 (Service Account Bearer Token): 쿠버네티스 내부에서 동작하는 파드(Pod)가 API 서버와 시스템적으로 통신할 때 사용하는 방식입니다. JWT(JSON Web Token) 포맷을 사용하며, API 서버는 해당 토큰의 암호학적 서명을 확인하여 위조 여부를 판단하고 이 토큰이 어느 네임스페이스의 어떤 서비스 어카운트에 매핑되는지 식별합니다.
• OpenID Connect (OIDC): 실제 조직 내의 사람(Human User)에 대한 접근을 통제하기 위해 외부의 신원 제공자(Google Workspace, Okta, Active Directory 등)와 연동하는 메커니즘입니다. 클라이언트가 외부 IdP에서 발급받은 ID 토큰을 제시하면, API 서버는 해당 IdP의 공개 키를 통해 토큰을 검증하고 사용자 이메일이나 소속 그룹 클레임(Claim)을 매핑합니다.

인증 플러그인 체인 중 단 하나라도 주체의 식별에 성공하면, API 서버는 사용자 이름, UID, 소속 그룹 정보가 모두 담긴 Context 객체를 메모리에 생성하여 다음 단계로 전달합니다. 모든 플러그인이 식별을 거부하면 HTTP 401(Unauthorized) 에러를 반환하고 연결을 끊습니다.

3. 인가 (Authorization): 권한의 적절성 판별

사용자가 누구인지 밝혀졌다면, 다음 단계는 '인가'입니다. 인가는 "식별된 사용자가 요청한 특정 리소스에 대해 해당 동작을 수행할 적법한 권한을 가지고 있는가?"를 판별하는 논리적 관문입니다. 쿠버네티스는 보안의 핵심인 최소 권한의 원칙(Principle of Least Privilege)을 이 단계를 통해 강제합니다.

• RBAC (Role-Based Access Control): 현대 쿠버네티스의 표준 인가 방식입니다. 사용자의 신원(User, Group)과 시스템 내에 정의된 역할(Role, ClusterRole)을 바인딩(RoleBinding, ClusterRoleBinding)하여 권한을 부여합니다. API 서버는 사용자가 요청한 리소스의 API 그룹, 네임스페이스, 동사(Verb)를 조합하여 RBAC 정책 테이블과 엄격하게 대조합니다. 예를 들어, 특정 개발 그룹이 dev 네임스페이스의 파드를 조회(get, list)할 수는 있지만 재생성(create, delete)할 권한은 없도록 세밀하게 통제합니다.
• Node Authorization: 워커 노드의 에이전트인 Kubelet을 위한 특수한 형태의 권한 제어기입니다. Kubelet이 클러스터 내의 모든 데이터에 접근하는 것을 막고, 오직 자신이 실행 중인 특정 노드에 스케줄링된 파드의 메타데이터와 연관된 시크릿, 컨피그맵만 읽고 쓸 수 있도록 격리합니다. 이를 통해 워커 노드 하나가 해킹되더라도 클러스터 전체가 붕괴하는 것을 막습니다.
• Webhook Authorization: 외부의 특화된 정책 결정 엔진(예: Open Policy Agent)에 인가 로직 일체를 위임할 때 사용합니다. 동적이고 복잡한 엔터프라이즈 맞춤형 보안 정책을 코드로 관리하고 적용할 때 핵심적인 역할을 합니다.

인가 체인 내의 모듈 중 하나라도 요청을 명시적으로 '허용(Allow)'하면 파이프라인은 계속 진행됩니다. 반면 허용 정책을 찾지 못하거나 명시적으로 거부되면 즉각 HTTP 403(Forbidden) 에러를 반환합니다.

4. 어드미션 컨트롤 (Admission Control): 페이로드 변형 및 심층 정책 검증

인증과 인가를 모두 통과했다고 해서 데이터가 곧바로 저장되는 것은 아닙니다. 마지막이자 가장 복잡한 관문인 '어드미션 컨트롤'이 기다리고 있습니다. 인가가 단순히 주체의 권한 유무를 따진다면, 어드미션 컨트롤은 '제출된 데이터(Payload)의 내용 자체가 클러스터의 전역적인 정책, 제약 조건, 무결성에 부합하는가'를 깊이 있게 해부합니다. 이 단계는 클러스터의 상태를 변경하는 요청(POST, PUT, PATCH, DELETE)에만 개입하며 조회(GET) 요청은 통과시킵니다. 어드미션 컨트롤은 순차적으로 실행되는 두 가지 페이즈(Phase)로 나뉩니다.

4.1. Mutating Admission (변형 어드미션)

이 단계에서는 사용자가 제출한 리소스의 명세를 etcd에 기록하기 전에 시스템이 개입하여 동적으로 데이터를 수정하거나 기본값을 강제로 주입합니다.

• DefaultStorageClass / LimitRanger: 사용자가 PersistentVolumeClaim을 생성할 때 스토리지 타입을 누락하면 시스템 기본값을 매니페스트에 끼워 넣습니다. 또한 파드 배포 시 CPU/메모리 제한을 명시하지 않으면 네임스페이스의 기본 Limit/Request 값을 자동으로 삽입합니다.
• MutatingAdmissionWebhook: 아키텍처 확장의 꽃이라 불리는 기능입니다. 예를 들어 서비스 메시(Service Mesh) 환경에서 사용자가 평범한 파드 배포를 요청하면, API 서버가 이 웹훅을 호출합니다. 웹훅 서버는 사용자의 매니페스트를 가로채어 트래픽 프록시 역할을 할 Envoy 사이드카 컨테이너 명세를 파드 데이터에 몰래 주입(Injection)한 뒤 API 서버로 돌려보냅니다.

4.2. Object Schema Validation (스키마 검증)

데이터의 변형 작업이 모두 끝나면, API 서버는 수정된 최종 페이로드가 해당 API 버전의 OpenAPI 스키마 구조와 완벽하게 일치하는지 기계적인 문법 검사를 수행합니다. 필드의 데이터 타입 오류나 필수 속성(Required Field)의 누락을 이 단계에서 걸러냅니다.

4.3. Validating Admission (검증 어드미션)

문법 검증을 통과한 데이터는 마지막으로 논리적인 시스템 제약 조건 위반 여부를 테스트받습니다. 이 단계에서는 데이터를 수정할 권한이 없으며 오직 '승인(Admit)' 또는 '거부(Reject)' 판정만 내립니다.

• ResourceQuota: 요청된 파드의 리소스 총량이 해당 네임스페이스에 할당된 쿼터(Quota)를 초과하지 않는지 수학적으로 계산합니다. 단 1바이트라도 초과하면 즉시 거부됩니다.
• Pod Security Admission (PSA): 컨테이너가 루트(Root) 권한으로 실행되려 하거나 호스트 시스템의 중요 디렉토리에 마운트를 시도하는 등, 클러스터 보안 표준(Pod Security Standards)을 위반하는 치명적인 보안 위협을 원천 차단합니다.
• ValidatingAdmissionWebhook: 기업의 자체적인 규정을 강제할 때 사용됩니다. 사내의 검증된 프라이빗 레지스트리에서 가져온 도커 이미지만 실행을 허용하거나, 모든 리소스 생성 시 필수 비용 처리 라벨을 강제하는 등의 복잡한 비즈니스 룰을 여기서 검증합니다.

어드미션 컨트롤 플러그인 중 단 하나라도 조건에 부합하지 않아 요청을 거부하면, 전체 트랜잭션은 롤백되고 API 서버는 실패 사유와 함께 HTTP 422(Unprocessable Entity) 또는 HTTP 403(Forbidden) 에러를 클라이언트에게 반환합니다.

5. etcd 직렬화 저장 및 Watch 이벤트 스트리밍

Authentication, Authorization, 그리고 두 단계의 Admission Control이라는 강력한 파이프라인을 모두 통과한 요청만이 시스템의 영구적인 저장소에 안착할 자격을 얻습니다.

API 서버는 최종 검증된 리소스 메모리 객체를 쿠버네티스 내부 버전(Internal Version) 포맷으로 직렬화하여 백엔드 키-값 데이터베이스인 etcd에 트랜잭션을 날립니다. 이때 낙관적 동시성 제어(Optimistic Concurrency Control)를 적용하여 여러 컨트롤러가 동시에 동일한 오브젝트를 수정하려 할 때 발생하는 데이터 덮어쓰기 충돌을 방지합니다. 데이터가 etcd의 물리 디스크에 안전하게 동기화(fsync)된 것이 최종 확인되면, API 서버는 마침내 클라이언트에게 HTTP 201(Created) 등의 성공 응답을 전송합니다.

데이터 저장과 동시에 API 서버 아키텍처의 핵심인 'Watch 메커니즘'이 발동합니다. etcd에 새로운 데이터가 기록되는 즉시 API 서버는 이를 감지하고, 해당 리소스의 상태 변화를 구독하고 있던 스케줄러(Scheduler)나 각종 컨트롤러 매니저(Controller Manager)들에게 이벤트를 푸시(Push) 스트리밍합니다. 이 실시간 알림을 기반으로 클러스터의 각 컴포넌트들이 각자의 위치에서 분산 처리 작업을 시작하며, 사용자가 선언한 상태를 실제 인프라에 구현해 나갑니다.