권한(RBAC)을 제대로 이해하려면, Kubernetes API가 어떻게 “그룹/버전/리소스/동사(verb)”로 구성되는지부터 잡아야 합니다. Kubernetes에서 우리가 kubectl로 하는 거의 모든 작업은 결국 kube-apiserver가 제공하는 HTTP API를 호출하는 형태입니다.

1) Kubernetes API란?

Kubernetes API는 클러스터 상태를 조회/변경하기 위한 표준 인터페이스입니다.

  • kubectl get pods → 사실상 API 서버의 “Pod 리소스 목록 조회” 호출
  • YAML로 kubectl apply -f ... → API 서버에 “리소스 생성/갱신” 호출

API 서버는 기본적으로(클러스터 구성에 따라 다르지만) 6443 포트에서 HTTPS로 동작합니다.

2) API 엔드포인트 구조: /version, /api, /apis

API 서버는 크게 다음 경로로 “무슨 API가 있는지”를 드러냅니다(Discovery).

대표적인 엔드포인트

  • 클러스터 버전
curl -k https://<APISERVER>:6443/version
  • Core API 그룹(= legacy/core group) 디스커버리
curl -k https://<APISERVER>:6443/api
  • Named API 그룹(= group이 있는 API들) 디스커버리
curl -k https://<APISERVER>:6443/apis
  • (환경에 따라) 루트 /에서도 그룹 요약이 보일 수 있습니다.
curl -k https://<APISERVER>:6443/

포인트:

  • Core 그룹 리소스는 /api/<version> 아래
  • Named 그룹 리소스는 /apis/<group>/<version> 아래

3) “목적별 API”와 “클러스터 기능 API”

질문에 나온 것처럼 Kubernetes API는 목적에 따라 여러 범주로 이야기될 수 있습니다.

  • 클러스터 기능(Workloads/Network/Auth 등)을 담당하는 API: 우리가 보통 말하는 “Kubernetes API 그룹”
  • 상태/메트릭/로그 관련 API: 구성에 따라 별도 API(또는 Aggregated API)로 제공될 수 있음
    • 예: metrics.k8s.io (metrics-server 설치 시)

이 글에서는 권한(RBAC)과 직접 맞닿는 “클러스터 기능 API” 중심으로 봅니다.

4) Core API 그룹 (group="")

Core 그룹은 Kubernetes의 가장 핵심 리소스가 모여 있는 영역입니다.

  • 그룹 이름이 비어있다(empty string) → YAML에서 apiVersion: v1 처럼 “그룹 없이 버전만” 보임
  • 경로는 /api/v1

Core 그룹의 대표 리소스

  • Namespace, Pod, Service, ConfigMap, Secret, Node, Event, Endpoint
  • PV/PVC 등 스토리지 기본 리소스

예를 들어, Pod 목록 조회는:

curl -k https://<APISERVER>:6443/api/v1/pods
curl -k https://<APISERVER>:6443/api/v1/namespaces/default/pods

5) Named API 그룹 (예: apps, networking.k8s.io, rbac.authorization.k8s.io)

최신 기능들은 대부분 Named API 그룹으로 제공됩니다. 여기에는 “기능별로 정리된 그룹”이 있고, 각 그룹 안에 여러 버전과 리소스가 있습니다.

  • 경로: /apis/<group>/<version>
  • YAML: apiVersion: <group>/<version>

대표 그룹 예시

  • apps/v1
    • Deployment, ReplicaSet, StatefulSet, DaemonSet
  • batch/v1
    • Job, CronJob
  • networking.k8s.io/v1
    • NetworkPolicy, Ingress
  • rbac.authorization.k8s.io/v1
    • Role, ClusterRole, RoleBinding, ClusterRoleBinding
  • storage.k8s.io/v1
    • StorageClass, CSIDriver 등
  • certificates.k8s.io/v1
    • CertificateSigningRequest(CSR)

예: Deployment 목록 조회는 Core가 아니라 apps 그룹입니다.

curl -k https://<APISERVER>:6443/apis/apps/v1/deployments
curl -k https://<APISERVER>:6443/apis/apps/v1/namespaces/default/deployments

그리고 YAML도 이렇게 나타납니다:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web

6) 리소스(Resource)와 동사(Verb): “무엇을” + “어떤 작업을”

각 API 그룹에는 여러 리소스(resource) 가 있고, 각 리소스는 수행 가능한 동사(verb) 들을 갖습니다.

리소스에 대해 할 수 있는 대표 동사(개념적으로)

  • list: 목록 조회
  • get: 단건 조회
  • create: 생성
  • update/patch: 갱신
  • delete: 삭제
  • watch: 변경 감시

이것들은 HTTP 레벨에서 대략 이렇게 매핑됩니다:

  • GET (list/get/watch)
  • POST (create)
  • PUT/PATCH (update/patch)
  • DELETE (delete)

kubectl로 보면 익숙하게 연결됩니다:

  • kubectl get → list/get
  • kubectl delete → delete
  • kubectl apply → (create + patch/update)
  • kubectl watch -w 또는 kubectl get ... -w → watch

7) “이 리소스가 어느 API 그룹이지?” 확인하는 방법

(1) kubectl api-resources

리소스와 그룹을 가장 빠르게 매칭할 때 씁니다.

kubectl api-resources | head
kubectl api-resources | grep -E 'deploy|ingress|role'

출력에서 APIVERSION 컬럼이 그룹/버전입니다.

(2) kubectl api-versions

클러스터가 지원하는 그룹/버전 목록을 봅니다.

kubectl api-versions

(3) kubectl explain

리소스 스펙을 보면서, 그 리소스가 어떤 apiVersion을 쓰는지까지 흐름이 이어집니다.

kubectl explain deployment
kubectl explain deployment.spec

8) curl로 API 직접 호출 시 “인증”이 필요하다

스크립트에서 말한 것처럼, 인증 없이 curl로 접근하면 /version 같은 일부를 제외하고는 대부분 거절됩니다(401/403).

방법 A) 클라이언트 인증서로 호출 (예시)

클러스터 구성에 따라 인증서 경로는 다를 수 있지만 패턴은 같습니다.

curl --cacert /etc/kubernetes/pki/ca.crt \
     --cert   /etc/kubernetes/pki/apiserver-kubelet-client.crt \
     --key    /etc/kubernetes/pki/apiserver-kubelet-client.key \
     https://<APISERVER>:6443/api/v1/pods

방법 B) 토큰(Bearer Token)로 호출 (예시)

TOKEN="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)"
curl -k -H "Authorization: Bearer ${TOKEN}" \
     https://kubernetes.default.svc/api/v1/namespaces/default/pods

(이 방식은 보통 클러스터 내부 Pod에서 호출할 때 자연스럽습니다.)

9) kubectl proxy (kube-proxy와 다름)

kubectl proxy가 하는 일

  • 로컬에 HTTP 프록시를 띄우고(기본 8001)
  • 현재 kubeconfig의 자격증명을 사용해서
  • 요청을 API 서버로 대신 전달합니다.
kubectl proxy --port=8001
curl http://127.0.0.1:8001/api
curl http://127.0.0.1:8001/apis

이렇게 하면 curl에서 인증서/토큰을 일일이 붙이지 않아도 됩니다.

kube-proxy와의 차이(중요)

이름이 비슷해서 자주 헷갈립니다.

  • kube-proxy
    • 클러스터 노드에서 동작
    • Service 트래픽 라우팅(iptables/ipvs 등)으로 Pod/Service 간 통신을 가능하게 함
  • kubectl proxy
    • 로컬에서 동작하는 “개발/디버깅용” 프록시
    • kubectl이 가진 인증정보로 API 서버 접근을 편하게 해줌

10) RBAC와 연결: apiGroups / resources / verbs

이제 왜 API 그룹을 알아야 하냐면, RBAC에서 권한은 딱 이 3가지로 자릅니다.

  • apiGroups: 어떤 API 그룹에 대해
  • resources: 어떤 리소스에 대해
  • verbs: 어떤 동작을 허용할지

예: default 네임스페이스에서 Pod 조회만 허용하는 Role

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-reader
  namespace: default
rules:
- apiGroups: [""]          # Core 그룹은 빈 문자열
  resources: ["pods"]
  verbs: ["get", "list", "watch"]

예: Deployment는 apps 그룹이므로 이렇게 됩니다.

rules:
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get", "list"]

여기서 Core 그룹이 apiGroups: [""]로 표현된다는 점이 RBAC에서 자주 실수나는 포인트입니다.

핵심 요약

  • Kubernetes API는 kube-apiserver가 제공하는 HTTP API이며 kubectl은 이를 호출하는 클라이언트다.
  • API는 Core 그룹(/api/v1) 과 Named 그룹(/apis/<group>/<version>) 으로 크게 나뉜다.
  • 각 그룹에는 리소스가 있고, 리소스에는 verbs(list/get/create/…)가 있다.
  • API 그룹/리소스/verb 조합이 RBAC에서 권한의 기준이 된다.
  • curl로 직접 호출하려면 인증이 필요하고, 편하게 보려면 kubectl proxy를 쓸 수 있다.
  • kubectl proxy는 kube-proxy와 역할이 완전히 다르다.

'CKA' 카테고리의 다른 글

Security - ClusterRole / ClusterRoleBinding  (0) 2026.01.02
Security - Authorization(RBAC)  (0) 2026.01.01
Security - 정리(1)  (2) 2026.01.01
Security - Kubeconfig  (0) 2026.01.01
Security - CSR API  (0) 2026.01.01

티스토리툴바