donghyeon.kang/project-infra
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

refactor: 폴더 구조 변경

Browse Source
This commit is contained in:
donghyeon-ka
2026-08-02 00:22:19 +09:00
parent f9c463f87a
commit be2f8e4863
1869 changed files with 4565 additions and 295591 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/troubleshooting.md
+40 -36
View File
@@ -1,19 +1,23 @@
# 운영 중 만난 함정 9건 — 사건 카탈로그
K3s 기반 로컬 클러스터에서 Project-Infra 를 부트스트랩 / 운영하면서 실제로 만났던 사건들의 narrative 정리.
운영자 절차서 톤은 [`guide.md`](../guide.md) 의 15장 (`15.1` ~ `15.11`) 에 있고, 이 문서는 사건 단위로 "무엇을 보고 / 왜 그랬고 / 어떻게 풀었는지" 를 짧게 쓰기 위한 자료다.
> 이 문서는 과거 `dev` 단일-aggregate 시기의 incident 기록이다. node 이름,
> host, 인증서, 수동 apply 명령은 당시 상태를 설명하며 현재 실행 runbook이
> 아니다. 현재 배포와 복구는 `docs/operations.md`와 staged bootstrap을 따른다.
| # | 사건 | guide.md cross-ref |
|---|---|---|
| 1 | Registry image pull 실패 (`ImagePullBackOff`) | (별건 — guide.md 15.1 은 ContainerCreating 사건) |
| 2 | `vault-0` 가 `0/1 Running` 에서 멈춤 | [15.10](../guide.md#1510-vault-0-이-01-running-에서-멈춤) |
| 3 | `helm upgrade` 가 `has no deployed releases` 로 실패 | [15.11](../guide.md#1511-helm-upgrade-가-has-no-deployed-releases-로-실패) |
| 4 | VSO 가 기존 K8s Secret 을 덮어쓰지 않음 | [15.8](../guide.md#158-기존-k8s-secret-이-남아있을-때) |
| 5 | ForwardAuth 로그인 E2E 검증 실패 | (현장 검증 사건) |
| 6 | namespace 가 `Terminating` 에 걸림 | [15.9](../guide.md#159-namespace-가-terminating-에-걸림) |
| 7 | PodSecurity 위반 경고 (admission) | [15.7](../guide.md#157-podsecurity-위반-경고) |
| 8 | VSO 가 Vault 로그인 실패 | [15.2](../guide.md#152-vso-가-vault-에-로그인-실패) |
| 9 | Registry 는 살아났지만 auth-server 새 이미지 pull 이 끝나지 않음 | (해결됨 — registries.yaml 제거 + hosts.toml 직접 작성) |
K3s 기반 로컬 클러스터에서 Project-Infra 를 부트스트랩 / 운영하면서 실제로
만났던 사건을 "무엇을 보고 / 왜 그랬고 / 어떻게 풀었는지" 순서로 기록한다.
| # | 사건 |
| --- | --- |
| 1 | Registry image pull 실패 (`ImagePullBackOff`) |
| 2 | `vault-0` 가 `0/1 Running` 에서 멈춤 |
| 3 | `helm upgrade` 가 `has no deployed releases` 로 실패 |
| 4 | VSO 가 기존 K8s Secret 을 덮어쓰지 않음 |
| 5 | ForwardAuth 로그인 E2E 검증 실패 |
| 6 | namespace 가 `Terminating` 에 걸림 |
| 7 | PodSecurity 위반 경고 (admission) |
| 8 | VSO 가 Vault 로그인 실패 |
| 9 | Registry 는 살아났지만 auth-server 새 이미지 pull 이 끝나지 않음 |
---
@@ -133,8 +137,8 @@ Git/Kustomize 원천 파일을 수정했다.
변경 파일:
- `k8s/base/plugins/docker-registry/configmap.yaml`
- `k8s/overlays/dev/registry/networkpolicy.yaml`
- `gitops/platform/registry/base/configmap.yaml`
- `gitops/platform/registry/overlays/lab/networkpolicy.yaml`
변경 내용:
@@ -156,8 +160,8 @@ ports:
적용:
```bash
kubectl diff -k k8s/overlays/dev/registry
kubectl apply -k k8s/overlays/dev/registry
kubectl diff -k gitops/platform/registry/overlays/lab
kubectl apply -k gitops/platform/registry/overlays/lab
kubectl -n mnt rollout restart deployment/docker-registry
kubectl -n mnt rollout status deployment/docker-registry --timeout=180s
```
@@ -340,8 +344,8 @@ server = "http://registry.project.com"
skip_verify = true
[host."http://registry.project.com".auth]
username = "testuser"
password = "abcd6845"
username = "<registry-username>"
password = "<registry-password>"
EOF
# 3) 적용
@@ -360,7 +364,7 @@ sudo systemctl restart k3s # control-plane
```bash
# 노드의 registry 연결 직접 검증
sudo /usr/local/bin/k3s ctr -a /run/k3s/containerd/containerd.sock \
images pull --plain-http --user 'testuser:abcd6845' \
images pull --plain-http --user '<registry-username>:<registry-password>' \
registry.project.com/auth-platform/auth-server:manual-20260512071751
# Pod 가 새 이미지로 정상 Running 되는지
@@ -425,7 +429,7 @@ vault-0 0/1 Running 0 5m
### 해결
```bash
REPO_ROOT="$(pwd)" ENV_NAME=dev bash k8s/scripts/tasks/vault-init.sh
REPO_ROOT="$(pwd)" ENV_NAME=lab bash scripts/tasks/vault-init.sh
```
이 스크립트는 idempotent — 다음을 차례로 처리한다.
@@ -526,7 +530,7 @@ Vault KV 에 새 값을 넣었는데 K8s Secret 은 옛날 값을 유지. `Vault
bootstrap 스크립트에 명시적 opt-in 환경변수를 둠.
```bash
RESET_STALE_SECRETS=yes bash k8s/scripts/bin/bootstrap.sh dev
RESET_STALE_SECRETS=yes bash scripts/bin/bootstrap.sh lab
```
이 옵션이 있을 때만 VSO-managed K8s Secret 후보들을 선제 삭제 → VSO 가 새로 생성.
@@ -640,7 +644,7 @@ unknown TLS options: kube-system-modern-tls@kubernetescrd
Traefik packaged manifest 를 직접 수정하지 않고, Git source-of-truth 인 overlay 를 적용했다.
```bash
kubectl apply -k k8s/overlays/dev/platform/traefik
kubectl apply -k gitops/platform/traefik/overlays/lab
```
적용된 리소스:
@@ -680,17 +684,17 @@ dev 전용 `ClusterIssuer/dev-selfsigned` 를 추가하고, dev TLS `Certificate
변경 파일:
- `k8s/overlays/dev/platform/cert-manager-issuers/dev-selfsigned-clusterissuer.yaml`
- `k8s/overlays/dev/platform/cert-manager-issuers/kustomization.yaml`
- `k8s/overlays/dev/tls/project-com-certificate.yaml`
- `k8s/overlays/dev/tls/keycloak-dev-certificate.yaml`
- `k8s/overlays/dev/tls/registry-project-com-certificate.yaml`
- `gitops/platform/cert-manager/overlays/lab/issuers/dev-selfsigned-clusterissuer.yaml`
- `gitops/platform/cert-manager/overlays/lab/issuers/kustomization.yaml`
- `gitops/platform/cert-manager/overlays/lab/certificates/project-com-certificate.yaml`
- `gitops/platform/cert-manager/overlays/lab/certificates/keycloak-dev-certificate.yaml`
- `gitops/platform/cert-manager/overlays/lab/certificates/registry-project-com-certificate.yaml`
적용:
```bash
kubectl apply -k k8s/overlays/dev/platform/cert-manager-issuers
kubectl apply -k k8s/overlays/dev/tls
kubectl apply -k gitops/platform/cert-manager/overlays/lab/issuers
kubectl apply -k gitops/platform/cert-manager/overlays/lab/certificates
kubectl -n mnt wait --for=condition=Ready certificate/project-com --timeout=120s
kubectl -n mnt wait --for=condition=Ready certificate/keycloak-dev-example-com --timeout=120s
```
@@ -846,7 +850,7 @@ set_authorization_header = true
변경 파일:
- `k8s/components/forward-auth/oauth2-proxy-config.yaml`
- `gitops/platform/forward-auth/component/oauth2-proxy-config.yaml`
반영 후 oauth2-proxy 를 재시작했다.
@@ -1071,15 +1075,15 @@ spec:
type: RuntimeDefault
```
이 패턴은 [`docs/security-hardening.md`](./security-hardening.md) 의 체크리스트에 정리되어 있고, [`k8s/scripts/ci/validate.sh`](../k8s/scripts/ci/validate.sh) 가 `kube-linter` 로 회귀를 막는다.
이 패턴은 [`docs/security-hardening.md`](./security-hardening.md) 의 체크리스트에 정리되어 있고, [`scripts/ci/validate.sh`](../scripts/ci/validate.sh) 가 `kube-linter` 로 회귀를 막는다.
### 검증
```bash
bash k8s/scripts/ci/validate.sh
bash scripts/ci/validate.sh
# build=ok schema=ok lint=ok
kubectl apply -k k8s/overlays/dev
bash scripts/bin/bootstrap.sh lab
# Warning 없음
```
@@ -1123,10 +1127,10 @@ K8s 인증의 의존 그래프는 두 단:
```bash
# 1. ClusterRoleBinding 적용
kubectl apply -k k8s/overlays/<env>/vault/
kubectl apply -k gitops/platform/vault/overlays/<env>/
# 2. vault auth/kubernetes/config 설정 (idempotent)
REPO_ROOT="$(pwd)" ENV_NAME=<env> bash k8s/scripts/tasks/vault-init.sh
REPO_ROOT="$(pwd)" ENV_NAME=<env> bash scripts/tasks/vault-init.sh
```
`vault-init.sh` 는 다음을 자동으로 한다: