platform-core/bootstrap/manual/phase3-admin-surfaces.md

# Phase 3 비공개 관리 UI 적용 절차

상세 설계와 실행 원장은 /home/donghyeon/workspace/docs/platform에서 관리합니다.
이 문서는 실제 적용 순서와 입력 문자열만 요약합니다.

## 현재 완료 경계

2026-07-24 기준 선언형 YAML, 고정 차트 검증, dry-run 스크립트는 구현·검증했습니다.
pgAdmin bootstrap password는 다음 경로에 `0600`으로 생성했습니다.

- /home/donghyeon/.secrets/pgadmin/bootstrap-password

private DNS, Gitea CoreDNS 전환, 공유기 DNS와 Tailscale split DNS 등록,
Cloudflare DNS-01 관리 인증서, Keycloak 관리 OIDC, AIStor Console OIDC
profile, pgAdmin, Host Nginx cutover와 자동 수용 시험을 실제 적용하고
검증했습니다.

현재 AIStor는 `green`, pgAdmin Deployment는 `1/1`, PVC는 2Gi SSD Local PV에
`Bound`입니다. 인증서 갱신 dry-run과 S3 bucket/object CRUD도 통과했습니다.
남은 단계는 브라우저 OIDC 수동 시험뿐입니다.

- /home/donghyeon/.secrets/certbot/cloudflare.ini

공유기 DHCP DNS와 Tailscale 관리 화면도 서버에서 자동 변경하지 않습니다.

## 1. 정적 렌더

    cd /home/donghyeon/workspace/platform
    PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm \
      bash scripts/validate/render-admin-services.sh

pgAdmin Chart archive와 OCI digest, AIStor ObjectStore Chart archive를 검증한 뒤
Secret 리소스가 없는 manifest만 렌더합니다.

## 2. Keycloak 외부망 시간 초과 대조

실패 단말에서 시각을 기록하고 다음을 실행합니다.

    date --iso-8601=seconds
    dig @1.1.1.1 A id.learn.hyeonworks.com
    dig @1.1.1.1 AAAA id.learn.hyeonworks.com
    curl -4 -vkI --connect-timeout 10 https://id.learn.hyeonworks.com/
    curl -4 -vk --connect-timeout 10 \
      https://id.learn.hyeonworks.com/realms/hyeonworks/.well-known/openid-configuration

같은 시간대 Host Nginx access log에 요청이 없으면 서버 설정이 아니라 실패
단말의 VPN·보안 필터·통신사 경로 문제로 판정합니다.

## 3. private DNS

상태: 2026-07-24 실제 적용 완료. Gitea live `hostAliases` 제거도 완료.

먼저 dry-run을 실행한 뒤 실제 적용합니다.

    bash scripts/bootstrap/apply-private-dns.sh
    bash scripts/bootstrap/apply-private-dns.sh --execute

확인 문자열은 APPLY default입니다. 이후 공유기 DHCP DNS를 192.168.0.107,
Tailscale의 learn.hyeonworks.com 제한 nameserver를 100.92.240.34로 등록합니다.
공개 DNS에는 두 admin 도메인을 만들지 않습니다.

서버의 공유기는 TP-Link 계열로 식별됐습니다. 정확한 TP-Link·Tailscale 메뉴와
검증 방법은 infrastructure/networking/private-dns/host/README.md를 따릅니다.

CoreDNS 전환 뒤 Gitea OIDC profile을 다시 적용하면 기존 Pod의 임시
hostAliases도 제거됩니다.

    PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm \
      bash scripts/bootstrap/apply-gitea-oidc.sh --execute

## 4. 운영자 Secret 파일

Cloudflare Dashboard의 `My Profile > API Tokens > Create Token`에서
`Edit Zone DNS` 템플릿을 선택합니다. 권한은 `Zone:DNS:Edit`, Zone resource는
`Include > Specific zone > hyeonworks.com`으로 제한합니다.

공식 절차:
https://developers.cloudflare.com/fundamentals/api/get-started/create-token/

파일 내용은 `dns_cloudflare_api_token = ...` 한 줄이며 저장소에 만들지 않습니다.

    sudo install -d -o root -g root -m 0700 /home/donghyeon/.secrets/certbot
    sudoedit /home/donghyeon/.secrets/certbot/cloudflare.ini
    sudo chown root:root /home/donghyeon/.secrets/certbot/cloudflare.ini
    sudo chmod 0600 /home/donghyeon/.secrets/certbot/cloudflare.ini

pgAdmin 내부 비상 관리자 비밀번호는 이미 준비했습니다. 재생성이 필요한 경우에만
다음을 실행합니다. 실행하면 기존 비밀번호 파일이 교체됩니다.

    install -d -m 0700 /home/donghyeon/.secrets/pgadmin
    umask 077
    openssl rand -base64 32 | tr -d '\n' \
      > /home/donghyeon/.secrets/pgadmin/bootstrap-password
    chmod 0600 /home/donghyeon/.secrets/pgadmin/bootstrap-password

파일 값은 출력하거나 runbook에 복사하지 않습니다.

## 5. admin 인증서

상태: 2026-07-24 실제 발급 완료. 만료일 2026-10-21, 자동 갱신 등록.

서비스 적용 전에 exact SAN 두 개만 발급합니다.

    bash scripts/bootstrap/apply-host-nginx-admin.sh \
      --execute \
      --certificate-only \
      --certbot-email you@example.com

확인 문자열은 APPLY입니다. 최초 실행은 공식 Cloudflare Certbot snap plugin을
설치하고 deploy hook을 등록합니다. wildcard 인증서는 만들지 않습니다.

## 6. Keycloak client와 그룹

상태: 2026-07-24 실제 적용 완료. `donghyeon.kang` 두 관리자 그룹 배정.

먼저 dry-run으로 대상을 확인합니다. donghyeon.kang은 실제 realm 사용자명으로
바꿀 수 있습니다.

    bash scripts/bootstrap/configure-keycloak-admin-oidc.sh
    bash scripts/bootstrap/configure-keycloak-admin-oidc.sh \
      --execute \
      --object-admin donghyeon.kang \
      --db-admin donghyeon.kang

확인 문자열은 APPLY default입니다. 두 OIDC Secret의 값은 출력하지 않습니다.

## 7. 관리 서비스

상태: 2026-07-24 실제 적용 완료.

최종 검증 결과:

    object-storage/minio-aistor: green, drivesOnline=1
    platform-admin/pgadmin: 1/1
    platform-admin/pgadmin PVC: Bound, pgadmin-data-local-pv
    storage-admin Traefik HTTP: 200
    db-admin Traefik HTTP: 302

    PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm \
      bash scripts/bootstrap/apply-admin-services.sh \
        --execute \
        --pgadmin-password-file \
          /home/donghyeon/.secrets/pgadmin/bootstrap-password

확인 문자열은 APPLY default입니다. 실패 시 AIStor spec은 복원하고 pgAdmin은
0 replica로 내리지만 pgAdmin PVC/PV와 AIStor 데이터는 삭제하지 않습니다.

적용 중 pgAdmin rollout 뒤 출력이 잠시 없으면 AIStor health를 확인하는
구간입니다. 현재 스크립트는 15초마다 상태와 경과 시간을 출력합니다. 300초 뒤
실패하면 자동 rollback하므로 강제로 다시 적용하기 전에 중앙 runbook의
`pgAdmin 완료 뒤 AIStor health 대기` 항목을 확인합니다.

## 8. Nginx 최종 전환

상태: 2026-07-24 실제 적용 완료.

활성 설정 SHA-256:

    f07d558d7ebbe09bdd61f3422fe8dcdaaaa6d1160d0872c06538d2bee193908f

    bash scripts/bootstrap/apply-host-nginx-admin.sh --execute

확인 문자열은 APPLY입니다. 설정을 timestamp backup한 뒤 LAN 요청의 정상 응답,
허용 목록 밖 loopback 요청의 403, unknown SNI 거부와 인증서 갱신 dry-run을
검사합니다.

## 9. 수용 시험

상태: 2026-07-24 자동 시험 완료.

    READ-ONLY CHECK PASS
    AISTOR_S3_SMOKE_PASS
    ADMIN UI SMOKE PASS

    bash scripts/validate/admin-ui-smoke.sh --execute --run-s3

확인 문자열은 APPLY이며 S3 하위 검사에서도 APPLY를 한 번 더 입력합니다.
재검증이 필요할 때만 다시 실행합니다.

마지막으로 LAN 또는 Tailscale 연결 상태에서 브라우저로 다음을 시험합니다.

- https://storage-admin.learn.hyeonworks.com
  - `/platform-object-admins` 사용자의 Keycloak OIDC 로그인 성공
  - 해당 group이 없는 사용자의 관리 기능 접근 거부
- https://db-admin.learn.hyeonworks.com
  - `/platform-db-admins` 사용자의 Keycloak OIDC 로그인 성공
  - 해당 group이 없는 사용자의 로그인 거부

pgAdmin 내부 비상 관리자 로그인은 OIDC 장애 대응용으로만 유지합니다.