코더 텔레포트 WebSocket 부트스트랩

증상

다음 중 하나가 발생하는 경우 이 가이드를 사용하세요.

• Coder UI가 로드되지만 /api/v2/notifications/inbox/watch와 같은 WebSocket 지원 엔드포인트는 403를 반환합니다.
• 새 작업 공간이 Agent state is timeout에 멈췄습니다.

현재 저장소가 Coder에게 기대하는 것

Coder 차트 값은 여전히 https://coder.lumie-infra.com를 통한 공용 액세스를 가정하고 클러스터 내 역방향 프록시에서 전달된 헤더를 신뢰합니다.

- name: CODER_ACCESS_URL
  value: "https://coder.lumie-infra.com"
- name: CODER_PROXY_TRUSTED_HEADERS
  value: "X-Forwarded-For,X-Forwarded-Proto,X-Forwarded-Host"
- name: CODER_PROXY_TRUSTED_ORIGINS
  value: "10.42.0.0/16"

출처: lumie-infra/applications/coder/helm-values.yaml

또한 작업 영역 템플릿은 기본 에이전트 부트스트랩을 대체하므로 작업 영역 포드는 Teleport 전면 공개 URL 대신 클러스터 내 Coder 서비스를 통해 다운로드하고 연결됩니다.

command = ["sh", "-c", <<-EOT
  ...
  if curl -fsSL --compressed "$CODER_AGENT_URL/bin/coder-linux-arm64" -o coder; then
    break
  fi
  ...
  exec ./coder agent
EOT
]

env {
  name  = "CODER_AGENT_URL"
  value = "http://coder.coder.svc.cluster.local"
}

출처: lumie-infra/applications/coder/template/main.tf

이 실패 모드가 발생한 이유

커밋	변경	해결된 사항
47d3465b	Coder의 신뢰할 수 있는 X-Forwarded-Host 및 pod-CIDR 출처	동일 출처 확인에서 브라우저 Origin를 잘못된 업스트림 Host와 비교했습니다.
557a073e	텔레포트 측 Host: coder.lumie-infra.com 재작성 추가	WebSocket 요청에는 브라우저 원본과 일치하기 위해 전달된 Host가 필요했습니다.
76673143	기본 에이전트 부트스트랩을 클러스터 내 다운로드 경로로 대체	Workspace Pod는 Coder 에이전트 바이너리를 가져오기 위해 Teleport SSO를 전달할 수 없습니다.

진단 경로

WebSocket이 요청하면 403를 반환합니다.

kubectl logs -n coder deploy/coder --tail=200
kubectl get configmap,secret -n coder

일반적인 네트워크 오류보다는 원본 확인 실패를 찾으십시오. 역사적 실패는 손상된 TCP 경로가 아니라 엄격한 동일 출처 거부였습니다.

작업 공간이 Agent state is timeout에 유지되는 경우

작업공간 템플릿이 여전히 클러스터 내 부트스트랩을 사용하는지 확인합니다.

rg -n "CODER_AGENT_URL|coder-linux-arm64|exec \\./coder agent" \
  applications/coder/template/main.tf

해당 줄이 누락된 경우 작업 공간이 CODER_ACCESS_URL에서 다운로드되어 Teleport 로그인 벽에 도달하는 기본 Coder 초기화 스크립트로 대체되었을 수 있습니다.

Coder를 비난하기 전에 확인해야 할 현재 드리프트

2026년 4월 11일 WebSocket 수정 순서는 security/teleport/agent/helm-values.yaml의 호스트 재작성을 사용하여 coder에 대한 Teleport 앱 등록에 따라 달라졌습니다. 현재 검사된 파일에는 더 이상 coder 앱 항목이 전혀 포함되어 있지 않습니다.

이는 현재 저장소가 다음과 같은 경우에도 이전 Teleport 측 수정 사항이 여전히 Git에 선언되어 있음을 완전히 증명하지 못한다는 것을 의미합니다.

• applications/coder/helm-values.yaml는 여전히 https://coder.lumie-infra.com를 가리킵니다.
• 커밋 557a073e에 텔레포트 호스트 재작성이 추가되었습니다.
• 기존 Teleport 참조 페이지에는 여전히 coder가 앱으로 나열되어 있습니다.

저장소가 여전히 전체 액세스 경로를 설명한다고 가정하기 전에 실시간 텔레포트 등록을 확인하세요.

수정

1. applications/coder/helm-values.yaml에서 Coder 측 신뢰할 수 있는 헤더 설정을 유지합니다.
2. CODER_ACCESS_URL가 아닌 http://coder.coder.svc.cluster.local에 작업 공간 에이전트 부트스트랩을 유지합니다.
3. WebSocket 403가 반환되면 Teleport가 여전히 Host: coder.lumie-infra.com 업스트림을 전달하고 있는지 확인합니다. 현재 저장소는 더 이상 해당 부분을 증명하지 않습니다.
4. 리포지토리 관리 Teleport 앱 등록이 누락된 경우 Coder 런타임 동작을 독립적으로 디버깅하기 전에 해당 계약을 복원하세요.

확인

kubectl get applications.argoproj.io -n argocd coder
kubectl logs -n coder deploy/coder --tail=200
kubectl get pods -n lumie-dev
rg -n "CODER_ACCESS_URL|CODER_PROXY_TRUSTED|CODER_AGENT_URL" \
  applications/coder/helm-values.yaml applications/coder/template/main.tf

성공은 Coder 배포가 전달된 헤더를 계속 신뢰하고, 작업 영역 포드가 클러스터 내 서비스 URL에 대해 여전히 부트스트랩하며, 라이브 액세스 경로에 더 이상 WebSocket 403 또는 에이전트 시간 초과 동작이 표시되지 않음을 의미합니다.

관련 페이지

• Teleport 운영 참조

운영 세부사항

이 실패 모드는 세 ownership boundary를 가로지릅니다. browser origin check, Teleport app forwarding, workspace pod bootstrap입니다. 한 계층만 고치면 UI는 좋아 보이지만 workspace 연결은 여전히 실패할 수 있습니다.

경계	필요한 계약	흔한 깨진 상태
Browser to Teleport	browser origin은 https://coder.lumie-infra.com입니다.	WebSocket 요청이 mismatched host로 Coder에 도달합니다.
Teleport to Coder	forwarded host와 trusted header가 public URL을 보존합니다.	Coder가 watch endpoint를 403으로 거부합니다.
Workspace pod to Coder	agent는 in-cluster service URL로 다운로드합니다.	pod가 Teleport SSO를 통해 agent를 가져오려다 timeout됩니다.

Agent state is timeout은 반증되기 전까지 bootstrap path 문제로 봅니다. 보통 Coder control plane down이 아니라 workspace pod가 agent를 가져오거나 연결하지 못하는 상태입니다.

복구 절차

1. 제보를 UI WebSocket 실패와 workspace agent timeout 중 하나로 나눕니다.
2. WebSocket 403이라면 요청 주변 Coder log를 캡처하고 Origin, forwarded host, trusted header 설정을 비교합니다.
3. agent timeout이라면 rendered workspace template에서 CODER_AGENT_URL이 service DNS name을 가리키는지 확인합니다.
4. 현재 repo가 더 이상 전체를 증명하지 못하므로 live Teleport app registration에 필요한 host rewrite가 남아 있는지 확인합니다.
5. 경로가 고쳐진 뒤 affected workspace만 다시 시작합니다. template 검증 전에는 모든 workspace를 재시작하지 않습니다.

검증 증거

다음을 기록한 뒤 사고를 닫습니다.

• Coder UI watch endpoint가 더 이상 403을 반환하지 않습니다.
• 새 workspace가 Teleport SSO를 거치지 않고 agent binary를 다운로드합니다.
• workspace가 connected agent 상태에 도달합니다.
• Coder values에 trusted forwarded header와 origin이 남아 있습니다.
• live Teleport registration이 inspected repo path 밖에서 관리된다면 follow-up note에 캡처합니다.

피해야 할 패턴

• agent download path를 증명하지 않고 workspace startup timeout만 늘리는 것.
• forwarded host 계약을 고치는 대신 Coder origin check를 제거하는 것.
• workspace pod 내부에서 CODER_AGENT_URL을 public Teleport URL로 가리키는 것.
• repo에 예전 coder registration이 없는데도 repo와 live Teleport app list가 같다고 가정하는 것.