Files
DongHyeonka de600a0bb1 feat(priority): attach PriorityClasses to Keycloak, Gitea, Loki, Tempo
The PriorityClasses exist in the repository but no pod uses them, so
every platform pod still evicts at priority 0.

Attach platform-critical to Keycloak (CR spec.scheduling) and Gitea
(chart priorityClassName), and platform-low to Loki (singleBinary) and
Tempo. The Keycloak CR also gets spec.image at the running 26.7.0
digest with startOptimized: false: with spec.image the operator
otherwise assumes a pre-built optimized image, and this is the stock
one. Grafana and pgAdmin have no top-level priorityClassName in their
charts and are left for later; platform-postgres is W1's file and
tech-log belongs to its deploy/ directory.

Risk: applying restarts Keycloak, Gitea, Loki and Tempo once, so it
belongs in the k3s restart window, after the PriorityClasses exist (a
pod that names a missing class is rejected). The accepted-drift list
holds these objects until 2026-11-30.

Verification (desktop): render-phase1/2 and render-observability-core
pass with the four priorityClassName values; kubectl diff (server
dry-run) against live shows only these fields.
2026-11-12 01:25:24 +09:00
..

Gitea 서비스

Gitea는 같은 공식 Helm Chart와 공통 values를 사용하는 두 Kustomize 빌드 루트로 관리한다. 업스트림 Chart 템플릿은 복제하거나 수정하지 않는다.

용도 빌드 루트 검증 산출물 적용 진입점
신규 설치 baseline services/gitea gitea.yaml apply-phase1-gitea.sh
OIDC·브랜딩 목표 상태 services/gitea/profiles/oidc gitea-oidc.yaml apply-gitea-oidc.sh

baseline 루트는 OIDC Secret, id host alias, Keycloak 전용 egress와 브랜딩을 포함하지 않는다. OIDC profile만 공통 기반에 이 네 요소를 추가한다.

상태(2026-07-23): Host Nginx public discovery 전환과 OIDC-enabled Gitea rollout을 완료했다. 적용 manifest SHA-256은 d25a757...a157이며, 활성 keycloak OAuth2 source, 외부 인증 전용 가입 정책, authorization-code redirect와 아래 선언형 브랜딩의 자동 검증을 모두 통과했다. 실제 realm 사용자의 브라우저 login/callback/logout, 비상 관리자 실제 로그인과 Pod 재시작 뒤 설정 지속성은 별도 수용 시험으로 남아 있다.

상태(2026-11-07): Actions와 Package Registry를 켠 values(커밋 87dee1f)를 같은 진입점 apply-gitea-oidc.sh --execute로 적용했다. 적용 manifest SHA-256은 f082cba5ca22b97ed5a463414404b852a4cfd452a0dd40c6e3b4b5f3afd4abbc이고 스크립트의 rollout·OAuth2 source·로그인 흐름·브랜딩 검사를 모두 통과했다. 적용 전후 health, 웹, Git HTTPS, OIDC discovery, 사용자 repository 24개와 PR이 같았다.

고정된 업스트림 릴리스

항목 값
Chart 저장소 https://dl.gitea.com/charts/
Chart gitea
Chart 버전 12.7.0
Chart 패키지 SHA-256 5881ef9c59400bee2d5547e77c4cd0efb925143c2f5d93fb4f38446db76b0167
Gitea 이미지 docker.gitea.com/gitea:1.27.0-rootless

Chart는 렌더링할 때 저장소 공통 .gitignore에서 제외한 profiles/oidc/.helm/charts에 내려받는다. baseline 루트와 OIDC profile이 이 고정 SHA 검증 캐시 하나를 각자의 chartHome으로 참조한다. values와 Patch는 모두 services/gitea 아래에 있으므로 Kustomize의 기본 RootOnly 로드 제한을 유지한다.

baseline과 OIDC 로그인 정책

두 프로필이 공유하는 profiles/oidc/values/baseline.yaml은 다음 정책을 선언한다.

  • 자체 가입을 닫고(DISABLE_REGISTRATION=true) 외부 인증 전용 가입도 끈다.
  • 가입 버튼을 숨기고 기존 gitea-admin 로컬 비상 로그인을 유지한다.
  • PostgreSQL, PVC, probe, resource와 restricted securityContext를 공통으로 둔다.

profiles/oidc/values/oidc.yaml은 baseline 위에 다음 항목만 덮어쓴다.

  • APP_NAME=Hyeonworks Git으로 브라우저 제목과 애플리케이션 이름을 고정한다.
  • DISABLE_REGISTRATION=false와 ALLOW_ONLY_EXTERNAL_REGISTRATION=true를 함께 사용해 Keycloak 같은 외부 인증을 통한 신규 사용자 생성만 허용한다.
  • SHOW_REGISTRATION_BUTTON=false로 Gitea 자체 공개 가입 버튼을 숨긴다.
  • oauth2_client.ENABLE_AUTO_REGISTRATION=true, USERNAME=preferred_username, OPENID_CONNECT_SCOPES="profile email"로 OIDC 최초 로그인 계정을 생성한다.
  • baseline의 ENABLE_PASSWORD_SIGNIN_FORM=true를 유지해 Keycloak 장애 시에도 로컬 비상 관리자가 로그인할 수 있게 한다.

ACCOUNT_LINKING=login은 이메일이 같은 기존 계정을 자동 병합하지 않는다. 사용자가 기존 Gitea 자격 증명으로 한 번 더 확인해야 연결되므로, 이메일 일치만으로 계정을 탈취하는 위험을 줄인다.

의존성과 트래픽

  • gitea와 platform-data namespace를 먼저 적용한다.
  • 이 서비스를 적용하기 전에 /srv/k3s/ssd/gitea를 준비하고 gitea-local-pv 기반 구성을 적용한다. gitea-data Claim은 ssd-local-gitea-retain을 통해 해당 PV에 바인딩되며 50Gi를 요청한다.
  • 외부 Database endpoint는 platform-postgres-rw.platform-data.svc.cluster.local:5432다.
  • Host Nginx에서 공개 TLS를 종료한다. Traefik은 HTTP를 받아 gitea-http:3000으로 전달하며, 이 Ingress에는 의도적으로 TLS 섹션이 없다.
  • OIDC profile의 Gitea 서버가 discovery와 token endpoint에 접근할 때도 공개 issuer https://id.learn.hyeonworks.com/realms/hyeonworks를 사용한다. 홈 라우터의 NAT loopback에 의존하지 않도록 Pod의 hostAliases는 이 이름만 노드 192.168.0.107로 해석하고, 전용 NetworkPolicy가 해당 /32의 TCP 443만 허용한다. 연결은 Host Nginx TLS와 Traefik을 그대로 통과한다.
  • Gitea SSH와 Git LFS는 비활성화한다. Chart 12.7.0은 항상 SSH Service를 렌더링하므로 baseline 루트는 inline patch, OIDC profile은 patches/delete-ssh-service.yaml로 Helm 렌더링 뒤 gitea-ssh를 삭제한다.
  • Actions와 Package Registry는 첫 배포에서 껐다가 2026-11-07 소유자 결정으로 서버에서 켰다([actions] ENABLED=true, [packages] ENABLED=true, DISABLED_REPO_UNITS=""). 꺼져 있을 때 만든 repository에는 두 unit이 없으므로 기존 repository는 모두 has_actions=false, has_packages=false로 남고, 소유자가 repository 설정에서 켜야 workflow가 돌거나 repository에 패키지 탭이 생긴다. 새로 만드는 repository는 Gitea 기본값(DEFAULT_REPO_UNITS)에 따라 두 unit이 켜진 채 만들어진다. 아래 「Actions와 Package Registry」를 따른다.
  • 공통 egress는 클러스터 DNS, 플랫폼 PostgreSQL Pod 및 공개 IPv4 HTTPS 대상으로 제한한다. OIDC profile만 Host Nginx 노드 /32의 TCP 443을 추가한다. 내부 HTTPS, SMTP, SSH remote 및 사설 네트워크 webhook을 사용하려면 향후 NetworkPolicy를 명시적으로 변경해야 한다. Actions runner와 Maven 클라이언트는 기존 Host Nginx → Traefik HTTPS 경로로 Gitea에 들어오기만 하므로 egress는 바꾸지 않는다.

Actions와 Package Registry

Actions

runner는 Gitea Pod가 아니라 desktop 호스트의 Docker 컨테이너다. 이미지, 설정, 등록과 되돌리기는 Gitea Actions runner에 있다. 서버 쪽 설정은 Gitea 기본값을 쓴다. job log와 artifact는 /data 아래 (actions_log, actions_artifacts)에 저장되고 log는 365일, artifact는 90일 보관한다.

저장 위치와 용량

항목 값
패키지 blob APP_DATA_PATH(/data) 아래 /data/packages
chunked upload 임시 위치 /data/tmp/package-upload
호스트 경로 gitea-local-pv의 /srv/k3s/ssd/gitea (root SSD)
PVC 요청 50Gi

Local PV는 PVC 크기를 강제하지 않는다. 실제 상한은 root SSD의 남은 공간이고, 이 공간을 desktop 호스트, Actions runner의 Docker 볼륨과 함께 쓴다(2026-11-07 기준 228G 중 여유 33G, Gitea /data 사용량 약 267M). 소유자별 상한 (LIMIT_TOTAL_OWNER_SIZE)과 형식별 상한(LIMIT_SIZE_MAVEN)은 Gitea 기본값인 무제한(-1)이다. Host Nginx의 git.learn.hyeonworks.com 요청 본문 상한은 512m이라 이보다 큰 파일은 올라가지 않는다.

정리

  • 같은 파일은 blob 하나로 저장된다. 패키지를 지우면 참조만 지워지고, 참조가 없는 blob은 cron cleanup_packages(기본: 매일 자정, OLDER_THAN=24h)가 지운다.
  • 오래된 버전은 패키지 소유자(사용자·조직)가 설정 → Packages → Cleanup rules에서 지운다. Maven SNAPSHOT은 형식 maven, 「Remove versions matching」에 .+-SNAPSHOT, 「Keep the most recent」에 남길 개수를 두는 규칙을 권한다. 규칙을 켜기 전에 preview로 지워질 버전을 확인한다. 2026-11-07 현재 규칙은 없다.
  • 같은 이름·버전의 Maven 패키지는 다시 올릴 수 없다. 먼저 그 버전을 지워야 한다.

Maven 배포와 조회 권한

  • 저장소 URL: https://git.learn.hyeonworks.com/api/packages/{owner}/maven
  • 조회: 사용자 소유 패키지는 그 사용자가 public이면 공개이고, 아니면 그 사용자만 읽는다. donghyeon.kang은 public이고 REQUIRE_SIGNIN_VIEW를 켜지 않았으므로 이 사용자의 패키지는 인증 없이 받을 수 있다. 조직 패키지는 조직이 public이면 공개, 아니면 조직 member만 읽는다.
  • 배포: 사용자 패키지는 소유자만, 조직 패키지는 packages 쓰기 권한이 있는 team member만 올린다. Maven·Gradle은 personal access token을 Authorization: token <token> header로 보낸다. token 권한은 package Read & Write(write:package)가 필요하고, 비공개 패키지를 받기만 할 때는 Read(read:package)면 된다.
  • Actions job 안에서 배포할 때는 token을 repository나 사용자 Actions secret으로 넘긴다. workflow 파일과 log에 token을 쓰지 않는다.

출처: Package Registry, Maven, Storage, Config cheat sheet.

선언형 브랜딩

브랜딩은 Gitea 공식 custom path와 Chart의 volume 확장 필드만 사용한다. Chart 템플릿과 Gitea 전체 페이지 템플릿은 복제하거나 수정하지 않는다.

branding/
├── public/assets/
│   ├── css/hyeonworks.css
│   └── img/
│       ├── logo.svg
│       └── favicon.svg
└── templates/custom/
    ├── header.tmpl
    └── extra_links.tmpl

branding/kustomization.yaml의 configMapGenerator가 자산과 템플릿 ConfigMap을 각각 생성하고 profiles/oidc/kustomization.yaml만 이 구성요소를 포함한다. 이름 suffix hash를 끄지 않았으므로 파일 내용이 바뀌면 이름도 바뀌고, Kustomize가 Deployment의 ConfigMap 참조를 같은 해시 이름으로 치환한다.

profiles/oidc/values/oidc.yaml은 공식 Chart 확장 지점을 다음과 같이 사용한다.

  • 자산 ConfigMap을 /data/gitea/public/assets에 마운트한다.
  • 템플릿 ConfigMap을 /data/gitea/templates/custom에 마운트한다.
  • 두 volume은 rootless Gitea 주 컨테이너에만 readOnly: true로 마운트하며, init container에는 추가하지 않는다.

header.tmpl은 같은 origin의 CSS와 모바일 브라우저 색상만 추가한다. extra_links.tmpl은 실제 Gitea 내부 경로인 /explore/organizations만 연결한다. 존재하지 않는 Learning 또는 Identity 서비스 링크는 미리 만들지 않는다. 전체 home.tmpl은 덮어쓰지 않아 Gitea 업그레이드 때 template drift 범위를 줄인다. Gitea는 custom template을 시작할 때 읽으므로 변경 적용에는 Pod 재시작이 필요하다.

SVG 원본만 저장소에서 관리한다. Gitea가 참조하는 Open Graph, Apple touch icon 및 구형 브라우저용 PNG는 검증된 변환 절차를 추가하기 전까지 업스트림 기본 자산을 사용한다.

Secret 계약

credential Secret 매니페스트나 credential 값은 이 저장소에 두지 않는다. gitea-admin과 gitea-db-credentials는 baseline Deployment 최초 시작 전에, gitea-keycloak-oidc는 OIDC-enabled Deployment rollout 전에 gitea namespace에 있어야 한다.

gitea-admin

속성 필수 값
Kubernetes 유형 kubernetes.io/basic-auth
username 최초 로컬 비상 관리자 username
password 강력한 일회용 관리자 비밀번호

Chart는 initialOnlyRequireReset을 사용하므로 최초 로그인 때 초기 비밀번호를 변경해야 하며 이후에는 조정하지 않는다.

gitea-db-credentials

속성 필수 값
Kubernetes 유형 kubernetes.io/basic-auth
username gitea
password PostgreSQL gitea Role에 할당한 비밀번호

Kubernetes에서는 namespace를 넘어 Secret을 참조할 수 없다. platform-data에 있는 같은 이름의 Secret은 CloudNativePG/bootstrap 사본이다. gitea namespace의 Secret은 동일한 Database credential을 담아야 하며 Chart가 이 사본을 참조한다.

gitea-keycloak-oidc

속성 필수 값
Kubernetes 유형 Opaque
key gitea
secret Keycloak이 생성한 confidential client secret

scripts/bootstrap/configure-keycloak-gitea-oidc.sh가 Keycloak Admin REST API로 정확한 callback URI를 가진 client를 생성하거나 갱신하고 이 Secret을 만든다. 공식 Chart의 gitea.oauth[].existingSecret이 key와 secret을 환경 변수로만 초기화 컨테이너에 전달하고, 인증 소스 이름 keycloak을 반복 실행 시 갱신한다. Secret payload는 values, 렌더 결과 또는 Git에 포함되지 않는다.

업스트림 Chart는 credential이 아닌 초기화 스크립트와 inline 설정이 담긴 Opaque Secret도 렌더링한다. 이 생성 리소스들은 고정된 Chart의 일부이며 위 세 credential 계약의 값은 포함하지 않는다.

렌더링과 검사

Helm은 PATH에 있어야 하지만 릴리스를 직접 설치하는 데 사용하지 않는다. 플랫폼 저장소 루트에서 고정 Chart SHA를 확인하는 검증기로 렌더링한다.

PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm \
  bash scripts/validate/render-phase1.sh

검증기는 gitea.yaml baseline과 gitea-oidc.yaml 목표 상태를 모두 렌더한다. 두 결과에는 각각 Gitea Deployment 하나, gitea-http, gitea-data, Traefik Ingress가 있어야 하고 gitea-ssh, NodePort, LoadBalancer와 내부 TLS는 없어야 한다. 두 Deployment 모두 gitea-admin, gitea-db-credentials를 참조만 하고 생성하지 않는다.

baseline은 gitea-keycloak-oidc, ID host alias, Keycloak 전용 NetworkPolicy, 브랜딩 ConfigMap과 외부 인증 전용 가입 설정이 없어야 한다. 반대로 OIDC 산출물은 gitea-keycloak-oidc를 값 노출 없이 참조하고 다음을 모두 만족해야 한다.

  • 두 브랜딩 ConfigMap 이름에 content hash가 있고 Deployment 참조와 일치한다.
  • /data/gitea/public/assets와 /data/gitea/templates/custom 마운트는 read-only다.
  • inline 설정에 외부 인증 전용 가입, OIDC 자동 계정 생성, ACCOUNT_LINKING=login, 로컬 비밀번호 로그인 유지가 모두 렌더링된다.
  • OAuth 인증 소스 이름은 callback URI의 경로와 같은 keycloak이고 discovery issuer는 https://id.learn.hyeonworks.com/realms/hyeonworks다.

Keycloak OIDC 안전 적용

Host Nginx의 Keycloak discovery가 실제 JSON issuer를 반환하고 위 세 Secret 계약이 준비된 뒤 다음 전용 진입점으로 적용한다.

  1. Host Nginx의 id.learn.hyeonworks.com 정적 hold를 Keycloak proxy 후보로 전환한다.
  2. public discovery JSON의 issuer가 https://id.learn.hyeonworks.com/realms/hyeonworks와 정확히 같은지 확인한다.
  3. 다음 전용 스크립트로 OIDC 목표 상태와 브랜딩을 함께 적용한다.
PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm \
  bash scripts/bootstrap/apply-gitea-oidc.sh --execute

스크립트는 public discovery와 Secret의 type·key 이름만 먼저 확인하고, 고정 Chart SHA 검증 결과 중 gitea-oidc.yaml 하나만 적용한다. 이후 Deployment·EndpointSlice, 활성 keycloak OAuth2 source, 외부 인증 전용 가입 정책, OIDC authorization-code redirect와 브랜딩 자산 SHA-256을 검증한다. Secret 값, bearer token과 OIDC state가 포함된 전체 Location은 출력하지 않는다.

2026-07-23 실제 적용에서는 manifest SHA-256 d25a757...a157의 rollout과 위 자동 검사를 모두 통과했다. 이 redirect 검사는 realm 사용자의 실제 브라우저 login/callback/logout 시험을 대신하지 않는다. self-registration은 비활성이므로 named 관리자와 MFA를 준비한 뒤 시험 사용자를 별도로 생성한다. 로컬 비상 관리자 실제 로그인과 Pod 재시작 뒤 OAuth source·정책·브랜딩 지속성도 별도로 확인한다.

기존 Gitea에 apply-phase1-gitea.sh를 다시 실행해 OIDC 상태를 적용하거나 복구하지 않는다.