Skip to content

ELOG 011 tailscale operator remote kubectl

wcorn edited this page Jun 15, 2026 · 1 revision

ELOG-011: Tailscale operator 원격 kubectl 셋업 함정

항목 내용
분류 🔧 트러블슈팅
날짜 2026-06-15
영역 Infra
관련 이슈/PR #492
상태 해결

1. 상황 (Before)

집(NAT 뒤)의 kubeadm 클러스터를 맥에서 직접 kubectl로 다루고 싶었다. 요구사항: API 서버를 공개 노출하지 않을 것, VPN을 매번 토글하지 않을 것, 단일 사용자. → Tailscale k8s operator + API server proxy(자체 호스팅 클러스터에 설치, 데이터는 P2P·컨트롤 플레인만 Tailscale 클라우드)를 GitOps로 도입(infra/helm/tailscale-operator). 그런데 셋업 중 여러 단계에서 막혔다.

2. 원인 분석 (막혔던 지점들)

  1. operator CrashLoopBackOff — authkey 생성 403: OAuth 클라이언트 스코프가 Devices Core만 있고 Auth Keys(write)가 없어 operator가 노드 등록용 authkey를 못 만들었다.
  2. kubectl tls: internal error: tailnet의 HTTPS Certificates가 비활성이라 API server proxy가 TLS 인증서를 발급받지 못함.
  3. CI 러너/노드 접근 불가 — subnet route 미승인: subnet router(Connector)가 192.168.0.0/24를 광고했지만 tailnet에서 승인되지 않아(PrimaryRoutes: None) 경로가 동작 안 함.
  4. macOS 클라이언트: 시스템 확장(Network Extensions) 승인 + 메뉴바 로그인 필요(GUI 무한 로딩은 확장 미승인 때문).

3. 조치

  • OAuth 클라이언트 스코프를 Devices Core + Auth Keys(둘 다 write) + 태그 tag:k8s-operator로 수정(스코프는 콘솔에서 edit 가능 — 기존 client_id/secret 유지라 재-seal 불필요). ACL tagOwners에 tag:k8s-operator/tag:k8s 정의.
  • admin 콘솔 DNS → HTTPS Certificates 활성화 → proxy TLS 정상.
  • 콘솔 Machines에서 subnet route 192.168.0.0/24 수동 승인.
  • 차트(infra/helm/tailscale-operator, v1.98.4): apiServerProxyConfig.mode/allowImpersonation=true, OAuth는 SealedSecret operator-oauth, ClusterRoleBinding(dsk08208@gmail.com → cluster-admin), Connector(subnet router).
  • 맥: 시스템 설정 → 일반 → 로그인 항목 및 확장 → 네트워크 확장 승인 후 tailscale up.

4. 결과 (After)

  • 맥 컨텍스트 tailscale-operator.tail1dc81b.ts.net로 kubectl 직접 동작. kubectl auth whoami = dsk08208@gmail.com(proxy impersonation → cluster-admin).
  • API 서버 공개 노출 0(데이터 P2P), VPN 토글 불필요(상시 백그라운드 split-tunnel, 일반 트래픽 영향 없음).
  • 같은 tailnet 경로를 Ansible CI/CD가 재사용(러너 ephemeral 조인 → subnet router 경유 노드 SSH, 노드 호스트 설치 0).

5. 교훈 / 후속

  • OAuth 스코프 누락이 가장 흔한 함정 — operator는 Auth Keys write가 반드시 필요(없으면 403 크래시). 스코프는 사후 edit 가능하니 client는 재발급 안 해도 됨.
  • tailnet HTTPS Certificates는 API proxy의 전제 — 안 켜면 원인 모를 tls: internal error.
  • subnet route는 광고 ≠ 적용 — 콘솔 승인(또는 autoApprovers ACL)까지 해야 동작. 자동화하려면 ACL에 박는 게 낫다.
  • 새 사용자/접근 추가 시 RBAC ClusterRoleBinding을 차트에 추가.

참고

Clone this wiki locally