70 lines
4.1 KiB
Markdown
70 lines
4.1 KiB
Markdown
# k3s 배포
|
|
|
|
`base/`는 `jarca-ledger` namespace에 다음 리소스를 배포하는 Kustomize base다.
|
|
|
|
- 단일 `Deployment`와 `Recreate` 전략
|
|
- 동일 ARM64 이미지의 MCP·Dashboard 컨테이너
|
|
- SQLite 초기화를 담당하는 init container
|
|
- 공유 `ReadWriteOnce` PVC
|
|
- Dashboard용 내부 `ClusterIP` Service
|
|
- Dashboard port `8501` ingress만 허용하는 `NetworkPolicy`
|
|
- UID/GID `1000:1000`, `fsGroup: 1000`, read-only root filesystem
|
|
|
|
## 사전 준비
|
|
|
|
Base는 실제 Secret 값을 포함하지 않는다. 먼저 namespace를 생성한다.
|
|
|
|
```bash
|
|
kubectl apply -f deploy/k8s/base/namespace.yaml
|
|
```
|
|
|
|
그 다음 승인된 secret manager나 Git에 기록되지 않는 운영 절차로 다음 Secret을 `jarca-ledger` namespace에 생성한다.
|
|
|
|
- `jarca-ledger-registry`
|
|
- type: `kubernetes.io/dockerconfigjson`
|
|
- `gitea.jsfamily.quest`에서 image를 pull할 수 있는 credential
|
|
- `jarca-ledger-dashboard-auth`
|
|
- key `admin-id`
|
|
- key `admin-password`
|
|
- key `signing-secret` (32 byte 이상의 독립적인 무작위 값)
|
|
|
|
Registry credential을 application container에 환경변수나 volume으로 전달하지 않는다. `imagePullSecrets`로만 사용한다.
|
|
|
|
## Immutable image 지정
|
|
|
|
`base/deployment.yaml`의 release version tag는 템플릿 기본값일 뿐이며 운영 배포에 안전한 immutable 참조가 아니다. Release commit 자체에는 최종 image digest를 넣을 수 없다. Image의 revision label이 release commit을 가리키므로, 그 commit에 digest를 기록하면 commit과 image digest가 다시 바뀌는 자기참조가 발생한다.
|
|
|
|
Release가 완료된 뒤 검증된 digest를 사용하는 환경/인프라 저장소의 overlay를 생성한다. 예를 들어 `environments/production/jarca-ledger/kustomization.yaml`은 다음과 같다.
|
|
|
|
```yaml
|
|
apiVersion: kustomize.config.k8s.io/v1beta1
|
|
kind: Kustomization
|
|
resources:
|
|
- ../../../../jarca-ledger-mcp/deploy/k8s/base
|
|
images:
|
|
- name: gitea.jsfamily.quest/jsfamily/jarca-ledger-mcp
|
|
newName: gitea.jsfamily.quest/jsfamily/jarca-ledger-mcp
|
|
digest: sha256:<verified-release-digest>
|
|
```
|
|
|
|
두 application container와 init container는 반드시 같은 digest를 사용해야 한다.
|
|
|
|
## 배포
|
|
|
|
Namespace와 Secret 준비가 끝난 뒤, base가 아니라 위의 외부 digest-pinned overlay를 적용한다.
|
|
|
|
```bash
|
|
kubectl apply -k environments/production/jarca-ledger
|
|
kubectl -n jarca-ledger rollout status deployment/jarca-ledger
|
|
kubectl -n jarca-ledger get pods,svc,pvc
|
|
```
|
|
|
|
Dashboard를 외부에 공개하는 Ingress나 NodePort는 environment overlay에서 추가한다. 인증 cookie가 항상 `Secure`이고 endpoint가 ASGI HTTPS scheme을 요구하므로 공개 origin에는 TLS가 필수다. Base의 `FORWARDED_ALLOW_IPS=127.0.0.1`은 ingress forwarded header를 신뢰하지 않는 fail-closed 기본값이다. TLS를 ingress에서 종료하는 overlay는 이 값을 실제 ingress-controller source IP/CIDR allowlist로 교체해야 하며 `*` 또는 불특정 network를 사용해서는 안 된다. TLS 종료 계층은 `Host`와 `Origin`을 보존하고 `X-Forwarded-Proto: https`를 설정해야 한다. 인증 cookie의 발급·검증 자체는 Dashboard 프로세스가 수행한다. Base에는 MCP Service가 없고, `NetworkPolicy`는 workload ingress를 dashboard port `8501`로 제한하여 인증 계층이 없는 MCP port `8000` ingress를 차단한다. Cluster의 network plugin이 `NetworkPolicy`를 enforce하는지 운영 환경에서 확인한다.
|
|
|
|
## SQLite와 PVC
|
|
|
|
- PVC 전체를 `/data`에 mount한다. SQLite journal, WAL, SHM 파일이 DB 옆에 생성되므로 DB 파일 하나만 `subPath`로 mount하지 않는다.
|
|
- `replicas`는 `1`, update 전략은 `Recreate`로 유지한다. RollingUpdate는 일시적으로 두 Pod가 같은 SQLite DB를 열 수 있다.
|
|
- k3s `local-path` volume에서는 `fsGroup: 1000` 적용 여부를 기존 PVC에서도 확인한다. 권한이 맞지 않으면 rollout 전에 운영 절차로 소유권을 수정하고, 상시 privileged `chown` init container는 두지 않는다.
|
|
- 같은 PVC 안의 backup은 node 또는 disk 손실에 대한 재해 복구가 아니다. 별도 저장소로 backup을 내보낸다.
|