쿠버네티스 첫걸음 6편 — 네임스페이스와 Git으로 팀과 협업하기: context 규칙, Kustomize, 권한까지

들어가며 — 혼자일 때는 없던 문제들

크게 보기

1~5편은 내 노트북의 클러스터에서 혼자 실습했습니다. 무엇을 지워도, 무엇을 망가뜨려도 괜찮았습니다. 그런데 팀이 같은 클러스터를 쓰기 시작하면 이런 일이 생깁니다.

1. 먼저, 이미 아는 것에서 출발 — compose와 쿠버네티스

도커 첫걸음 5편에서 팀과 협업하는 compose.yaml을 만들었습니다. 쿠버네티스 협업도 같은 원칙(파일을 공유하고, 비밀은 분리하고, 같은 명령으로 띄운다) 위에 있습니다. compose.yaml의 각 줄을 눌러 쿠버네티스에서 무엇이 되는지 확인해 보세요. 대부분 이름만 바뀐 같은 개념입니다.

2. 네임스페이스 — 한 클러스터를 여러 칸으로

크게 보기

네임스페이스는 클러스터 안의 폴더입니다. 같은 이름의 리소스도 네임스페이스가 다르면 공존할 수 있고, 권한과 자원 한도를 네임스페이스 단위로 줄 수 있습니다. 지금까지 우리가 쓴 곳은 default 네임스페이스였습니다.

kubectl get namespaces
kubectl create namespace dev-kim
kubectl apply -f k8s/ -n dev-kim
kubectl get pods -n dev-kim

매번 -n을 붙이기 귀찮다면 현재 context의 기본 네임스페이스를 바꿉니다(5편의 kubens dev-kim과 같음).

kubectl config set-context --current --namespace=dev-kim

다른 네임스페이스의 서비스는 서비스이름.네임스페이스로 부릅니다. dev-kim의 앱이 shared 네임스페이스의 DB에 접속하려면 db.shared 또는 db.shared.svc.cluster.local입니다.

3. context 규칙 — "지금 어디지?"를 없애기

2편에서 kubeconfig와 context를 봤습니다. 팀에서는 로컬 클러스터 외에 개발·운영 클러스터의 context가 추가됩니다. 사고의 대부분은 엉뚱한 context에서 명령을 치는 것입니다.

4. Git이 원본이다 — 매니페스트 저장소 규칙

도커 5편의 원칙 "컨테이너 안에서 손으로 설치한 것은 없는 것"이 쿠버네티스에서는 이렇게 바뀝니다. 클러스터에서 손으로 바꾼 것은 없는 것. 원하는 상태의 원본은 Git의 YAML이고, 클러스터는 그 YAML을 반영한 결과일 뿐입니다.

GitOps는 이 원칙을 끝까지 밀어붙인 방식입니다. 사람이 apply 하지 않고, Argo CD나 Flux 같은 도구가 Git 저장소를 지켜보다가 바뀌면 자동으로 클러스터에 반영하고, 누가 손으로 바꾸면 되돌립니다. 팀이 커지면 자연스럽게 가는 다음 단계입니다.

5. Kustomize — 개발과 운영의 차이를 한 저장소에서

개발에서는 파드 1개·로컬 이미지, 운영에서는 파드 3개·레지스트리 이미지처럼 환경마다 조금씩 다른 값이 필요합니다. YAML을 환경마다 통째로 복사하면 금방 서로 어긋납니다. Kustomize는 공통 YAML(base) 위에 환경별 차이(overlay)만 덧씌웁니다. kubectl에 내장되어 있어 따로 설치할 필요가 없습니다.

4편의 k8s/ 폴더를 이렇게 정리합니다.

• k8s/base/ — 공통 부품
  • deployment.yaml · service.yaml (4편의 것 그대로)
  • kustomization.yaml
• k8s/overlays/dev/kustomization.yaml — 개발 환경의 차이
• k8s/overlays/prod/kustomization.yaml — 운영 환경의 차이

mkdir -p k8s/base k8s/overlays/dev k8s/overlays/prod
mv k8s/deployment.yaml k8s/service.yaml k8s/base/

k8s/base/kustomization.yaml — 공통 부품 목록입니다.

resources:
  - deployment.yaml
  - service.yaml

k8s/overlays/dev/kustomization.yaml — 개발 환경의 차이만 적습니다.

namespace: dev
resources:
  - ../../base
images:
  - name: hello-api
    newTag: "0.3"
replicas:
  - name: hello-api
    count: 1

k8s/overlays/prod/kustomization.yaml — 운영은 레지스트리 이미지와 3개.

namespace: prod
resources:
  - ../../base
images:
  - name: hello-api
    newName: ghcr.io/myteam/hello-api
    newTag: "0.3"
replicas:
  - name: hello-api
    count: 3

결과 YAML을 미리 보고, 차이를 확인하고, 적용합니다. -f 대신 -k(Kustomize)를 씁니다.

kubectl kustomize k8s/overlays/dev
kubectl create namespace dev
kubectl diff -k k8s/overlays/dev
kubectl apply -k k8s/overlays/dev

이미지 태그를 올리는 배포는 이제 overlay 파일의 newTag 한 줄을 바꾸는 PR입니다. 리뷰어는 "무엇이, 어느 환경에서 바뀌는지"를 정확히 볼 수 있습니다. CI가 kubectl apply -k를 대신 실행하게 하면(또는 GitOps 도구가 지켜보면) 사람이 운영 클러스터에 직접 명령을 칠 일이 거의 사라집니다.

6. 권한 — 필요한 만큼만 (RBAC)

모두가 클러스터 관리자 권한을 가지면 실수 하나가 전체 장애가 됩니다. 쿠버네티스의 RBAC(역할 기반 접근 제어)은 "누가, 어느 네임스페이스에서, 무엇을 할 수 있나"를 정합니다. 처음부터 역할을 직접 설계할 필요는 없습니다. 쿠버네티스가 기본 역할을 제공합니다.

역할을 사람(또는 그룹)에게 연결하는 것이 RoleBinding입니다. QA 팀에 dev 네임스페이스 읽기 권한만 주는 예입니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: qa-view
  namespace: dev
subjects:
  - kind: Group
    name: qa-team
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: view
  apiGroup: rbac.authorization.k8s.io

권한이 의도대로인지는 auth can-i로 확인합니다. --as로 다른 사람인 척 물어볼 수 있습니다(관리자만 가능).

kubectl auth can-i delete pods -n dev --as=qa-user --as-group=qa-team
kubectl auth can-i list pods -n dev --as=qa-user --as-group=qa-team

첫 줄은 no, 둘째 줄은 yes가 나와야 합니다. 5편의 팀 공용 Headlamp도 이런 읽기 권한과 함께 쓰면, 비개발 동료가 안심하고 상태를 들여다볼 수 있습니다.

7. 라벨 규칙 — 모두가 같은 이름표를

4편에서 서비스가 라벨로 파드를 찾는 것을 봤습니다. 라벨은 검색·권한·비용 집계·대시보드 필터에도 쓰이므로, 팀 전체가 같은 규칙을 쓰면 좋습니다. 쿠버네티스가 권장하는 공통 라벨이 있습니다.

metadata:
  labels:
    app.kubernetes.io/name: hello-api
    app.kubernetes.io/version: "0.3"
    app.kubernetes.io/component: backend
    app.kubernetes.io/part-of: hello
    app.kubernetes.io/managed-by: kustomize

이렇게 해 두면 kubectl get all -l app.kubernetes.io/part-of=hello -A처럼 서비스 하나에 속한 모든 것을 한 번에 찾을 수 있고, Headlamp·k9s 같은 도구도 이 라벨로 앱을 묶어 보여 줍니다.

8. 팀 규칙 체크리스트

9. 복사해서 쓰는 README 절

## 쿠버네티스 로컬 개발

### 준비물
- 로컬 클러스터 하나 (맥: OrbStack 또는 Rancher Desktop / 윈도우: Rancher Desktop)
- kubectl, (선택) k9s · Headlamp
- 확인: `kubectl config current-context` 가 로컬 클러스터인지, `kubectl get nodes` 가 Ready 인지

### 실행
```bash
docker build -t hello-api:0.3 .
kubectl create namespace dev
kubectl apply -k k8s/overlays/dev
kubectl -n dev port-forward svc/hello-api 8080:80
```
- API: http://localhost:8080/docs

### 규칙
- 공유 클러스터(dev·prod)는 PR로만 변경한다. `kubectl edit` 금지
- apply 전에 `kubectl diff -k k8s/overlays/<환경>`
- 명령 전에 현재 context 확인. 운영은 `--context=prod` 명시

10. 시리즈를 마치며 — 전체 지도

쿠버네티스를 어렵게 만드는 것은 기능의 개수가 아니라 그림이 없는 상태에서 명령부터 외우는 것입니다. 클러스터는 회사, 노드는 현장 사무실, 파드는 책상, 디플로이먼트는 "책상 3개 유지"라는 약속, 서비스는 대표 전화번호, 네임스페이스는 층. 이 그림 위에서는 처음 보는 YAML도 "아, 이건 무엇을 몇 개, 어디에 원하는지 적은 거구나" 하고 읽힙니다. 이제 팀 저장소에 k8s/ 폴더 하나를 만드는 것으로 시작해 보세요.

참고 자료

• Kubernetes 문서, Namespaces · Configure Access to Multiple Clusters
• Kubernetes 문서, Declarative Management of Kubernetes Objects Using Kustomize · kubectl diff
• Kubernetes 문서, Using RBAC Authorization (기본 역할 view·edit·admin)
• Kubernetes 문서, Recommended Labels
• 관련 글: Argo CD로 시작하는 GitOps · 관리형 쿠버네티스 가이드 · 도커 첫걸음 5편 — Compose로 협업하기
• 시리즈: 1편 · 2편 · 3편 · 4편 · 5편