Kubernetes에서 hostname-backchannel-dynamic으로 Keycloak 내부·외부 접근 해결

Source: Dev.to

위에 제공된 링크에 있는 전체 글을 복사해서 여기 채팅창에 붙여 주시면, 해당 내용을 한국어로 번역해 드리겠습니다. 코드 블록이나 URL은 그대로 유지하고, 나머지 텍스트만 번역해 드릴게요.

소개

인프라 작업 시 인증 소스로 OpenID Connect (OIDC)를 사용하는 것은 보안과 유지 관리성을 크게 향상시키는 모범 사례입니다. Keycloak은 이 목적을 위해 널리 채택된 뛰어난 오픈‑소스 프로젝트입니다. PostgreSQL과 같은 다양한 스토리지 백엔드를 지원하며 공식 웹사이트에 간단한 배포 가이드가 제공됩니다.

하지만 Kubernetes에 Keycloak을 배포하면 특정 구성이 필요한 내부 서비스 통신 문제가 발생할 수 있습니다.

문제: 외부 호스트명 vs 내부 접근

Kubernetes에 Keycloak을 배포할 때 일반적으로 --hostname=https://auth.example.com 매개변수로 공개 호스트명을 지정합니다. 이는 외부 클라이언트가 인증 서비스를 이용할 때 완벽하게 동작합니다.

하지만 같은 Kubernetes 클러스터 내에서 실행되는 다른 서비스—예를 들어 컨테이너 레지스트리나 CI 서버—가 Keycloak에 인증해야 할 경우 문제가 발생합니다. 이 서비스들은 다음과 같은 discovery URL에 접근해야 합니다:

https://auth.example.com/realms/{realm-name}/.well-known/openid-configuration

Keycloak은 시작 시 제공된 호스트명을 기반으로 항상 리디렉션하고 토큰/URL을 생성합니다. 그 공개 URL이 클러스터 내부에서 해석되지 않으면, 내부 파드들은 백채널 요청(토큰 인트로스펙션, userinfo 등)을 위해 Keycloak에 접근할 수 없습니다. 비록 파드들이 내부 DNS를 통해 해당 포드에 도달할 수 있더라도 말이죠.

해결책: 동적 백채널 호스트명

Keycloak은 hostname:v2 기능이 활성화된 경우 이 문제를 해결할 수 있는 CLI 옵션을 제공합니다.

--features=hostname:v2
--hostname-backchannel-dynamic=true

이 구성을 사용하면 Keycloak은 들어오는 요청을 기반으로 백채널(내부) URL을 동적으로 결정하므로 다음과 같이 접근할 수 있습니다.

• 직접 IP 주소
• 내부 Kubernetes DNS (예: keycloak.keycloak-namespace.svc.cluster.local:8080/realms/{realm-name}/.well-known/openid-configuration)

작동 방식

--hostname-backchannel-dynamic=true가 활성화되면:

이 이중 접근 방식은 다음을 보장합니다.

• 외부 클라이언트는 인증 흐름에 적합한 공개 URL을 받습니다.
• 내부 서비스는 클러스터 내부 DNS 해석을 사용해 안정적으로 Keycloak에 도달할 수 있습니다.
• 내부 통신 전용으로 추가 네트워크 라우팅이나 인그레스 구성이 필요하지 않습니다.

프로덕션 환경 주의사항: 인그레스/리버스 프록시가 Forwarded 또는 X‑Forwarded‑* 헤더를 올바르게 전달하도록 하고, 외부와 내부 경로 모두에서 HTTPS를 활성화하는 것을 고려하십시오.

예제 구성

아래는 동적 백채널 호스트명을 활성화하는 최소한의 Kubernetes 배포 매니페스트입니다:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: keycloak
spec:
  template:
    spec:
      containers:
        - name: keycloak
          image: quay.io/keycloak/keycloak:latest
          args:
            - start
            - --features=hostname:v2           # required for dynamic backchannel
            - --hostname=https://auth.example.com
            - --hostname-backchannel-dynamic=true
            - --db=postgres
            - --proxy-headers=forwarded        # important for correct header handling behind proxy/ingress
            # ... other configuration (ports, HTTPS, DB credentials via env vars, etc.)

결론

--hostname-backchannel-dynamic=true 플래그(hostname:v2 기능과 결합)는 Kubernetes에서 내부/외부 혼합 접근 시나리오에 대해 간단하면서도 강력한 솔루션을 제공합니다. 공개 URL은 외부 클라이언트 접근에 이상적이며, 내부 서비스‑to‑서비스 통신은 동적 백채널 해상도의 유연성을 활용합니다.

Keycloak의 hostname 구성 옵션은 컨테이너화된 환경에서 인증 인프라에 견고한 선택이 됩니다.

참고 자료

• Keycloak 공식 문서
• Keycloak 서버 구성 – 호스트명