devops

Kubernetes v1.35: 서비스 계정 토큰을 CSI 드라이버에 전달하는 더 나은 방법

발행: (2026년 1월 8일 오전 03:30 GMT+9)
9 min read
원문: Kubernetes Blog

I’m happy to translate the article for you, but I’ll need the full text you’d like translated. Could you please paste the content (excluding the source line you already provided) here? Once I have the article, I’ll translate it into Korean while preserving the original formatting, markdown syntax, and technical terms.

기존 접근 방식 이해

CSI 드라이버가 TokenRequests 기능을 사용할 때, CSIDriver 사양의 tokenRequests 필드를 구성하여 워크로드 아이덴티티용 서비스 계정 토큰을 요청할 수 있습니다. 토큰은 현재 볼륨 속성 맵의 일부로 드라이버에 전달되며, 키는 다음과 같습니다:

csi.storage.k8s.io/serviceAccount.tokens

volume_context가 문제인 이유

  • 로그 위험 – 많은 CSI 드라이버가 사용하는 protostanitizer 도구는 volume_context를 민감한 정보로 간주하지 않으므로, gRPC 요청이 기록될 때 토큰이 로그에 남을 수 있습니다.

    • 예시: Secrets Store CSI Driver의 CVE‑2023‑2878.
    • 예시: Azure File CSI Driver의 CVE‑2024‑3744.

  • 일관성 없는 정화 – 이 문제를 피하려는 각 드라이버가 자체 정화 로직을 구현해야 하므로, 드라이버 간에 일관성이 부족합니다.

CSI 사양에서는 이미 NodePublishVolumeRequest에 secrets 필드를 정의하고 있으며, 이는 바로 이러한 민감한 정보를 위한 용도입니다. 그러나 토큰을 바로 secrets로 옮기면 volume_context에 토큰이 존재한다고 기대하는 기존 드라이버가 깨질 수 있습니다.

옵트인 메커니즘 작동 방식

Kubernetes v1.35는 CSI 드라이버가 서비스 어카운트 토큰을 받는 방식을 선택할 수 있는 옵트인 메커니즘을 도입합니다. 기존 드라이버는 그대로 동작하며, 드라이버가 준비가 되면 보다 적합한 secrets 필드로 전환할 수 있습니다.

CSIDriver 사양에 새로운 필드

# CAUTION: this is an example configuration.
# Do not use this for your own cluster!
apiVersion: storage.k8s.io/v1
kind: CSIDriver
metadata:
  name: example-csi-driver
spec:
  # ... existing fields ...
  tokenRequests:
    - audience: "example.com"
      expirationSeconds: 3600
  # New field for opting into secrets delivery
  serviceAccountTokenInSecrets: true   # defaults to false
  • serviceAccountTokenInSecrets: false (기본값) – 토큰은 현재와 같이 volumeContext 안의 키 csi.storage.k8s.io/serviceAccount.tokens에 배치됩니다.
  • serviceAccountTokenInSecrets: true – 토큰이 오직 동일한 키를 가진 secrets 필드에만 배치됩니다.

베타 릴리스에 대하여

  • CSIServiceAccountTokenSecrets 기능 게이트는 kubelet과 kube‑apiserver 모두에서 기본적으로 활성화됩니다.
  • serviceAccountTokenInSecrets가 기본값 false이므로, 기능 게이트를 활성화해도 기존 동작이 변경되지 않습니다.
  • 모든 드라이버는 명시적으로 옵트인하지 않는 한 volume_context를 통해 토큰을 계속 받습니다.
  • 이러한 하위 호환성 접근 방식 덕분에 기능을 알파가 아닌 베타 단계에서 시작할 수 있었습니다.

CSI 드라이버 작성자를 위한 가이드

서비스 계정 토큰을 사용하는 CSI 드라이버를 유지 관리하고 있다면, 새로운 메커니즘을 안전하게 채택하기 위해 다음 단계를 따르세요.

1. 폴백 로직 추가

드라이버가 토큰을 두 곳 모두 확인하도록 업데이트합니다. 이렇게 하면 기존 방식과 새로운 방식을 모두 지원하게 됩니다.

const serviceAccountTokenKey = "csi.storage.k8s.io/serviceAccount.tokens"

func getServiceAccountTokens(req *csi.NodePublishVolumeRequest) (string, error) {
    // 새로운 동작 – 먼저 secrets 필드 확인
    if tokens, ok := req.Secrets[serviceAccountTokenKey]; ok {
        return tokens, nil
    }

    // 기존 동작 – volume context 로 폴백
    if tokens, ok := req.VolumeContext[serviceAccountTokenKey]; ok {
        return tokens, nil
    }

    return "", fmt.Errorf("service account tokens not found")
}

이 폴백 로직은 이전 버전과도 호환되며, 클러스터가 v1.35 로 업그레이드되기 전이라도 어떤 드라이버 버전에서도 안전하게 배포할 수 있습니다.

2. 롤아웃 순서

드라이버 준비 (언제든 수행 가능)

  • 폴백 로직을 추가합니다.
  • 새 드라이버 버전을 릴리스합니다(또는 유지 보수 브랜치에 백포트합니다).

클러스터 업그레이드 및 기능 활성화

  1. kube‑apiserver 를 v1.35 이상으로 업그레이드합니다.
  2. kubelet 을 v1.35 이상으로 모든 노드에서 업그레이드합니다.
  3. 폴백 로직이 포함된 CSI 드라이버 버전이 배포되어 있는지 확인합니다(아직이라면 배포).
  4. 모든 노드에 걸쳐 CSI 드라이버 DaemonSet 롤아웃을 완료합니다.
  5. CSIDriver 매니페스트를 업데이트하여 serviceAccountTokenInSecrets: true 를 설정합니다.

3. 중요한 제약 사항

  • 시점이 중요합니다. CSI 드라이버 DaemonSet과 CSIDriver 객체가 동일한 매니페스트 또는 Helm 차트에 포함되어 있다면 두 번의 별도 업데이트가 필요합니다:

    1. 새 드라이버 버전을 먼저 배포하고 DaemonSet 롤아웃이 완료될 때까지 기다립니다.
    2. 그 다음 CSIDriver 사양을 업데이트하여 serviceAccountTokenInSecrets 를 활성화합니다.

  • 모든 드라이버 파드가 롤아웃될 때까지 CSIDriver 를 업데이트하지 마세요.
    그렇지 않으면 아직 오래된 드라이버 버전을 실행 중인 노드에서는 volume_context 만 확인하기 때문에 볼륨 마운트가 실패합니다.

왜 이것이 중요한가

이 기능을 채택하면 여러 면에서 도움이 됩니다:

  • 드라이버 로그에 서비스‑계정 토큰이 실수로 기록되는 위험을 제거합니다.
  • 토큰 전달을 CSI 사양에서 의도한 민감 데이터 위치와 일치시킵니다.
  • 드라이버‑특정 정화 로직의 필요성을 줄여 생태계 전반의 일관성을 촉진합니다.

옵션을 선택하면 드라이버를 보다 안전하고 미래‑보장하게 만들면서 기존 클러스터와의 호환성을 유지할 수 있습니다.

gRPC 요청에서 볼륨 컨텍스트의 일부로서 계정 토큰

  • CSI 사양에서 지정한 민감 데이터 필드를 사용하므로 적절합니다.
  • protosanitizer 도구가 secrets 필드를 자동으로 올바르게 처리하므로 드라이버별 우회가 필요 없습니다.
  • 옵트인 방식이므로 기존 배포를 깨뜨리지 않고 원하는 속도로 마이그레이션할 수 있습니다.

행동 촉구

우리는 (Kubernetes SIG Storage) CSI 드라이버 작성자들이 이 기능을 채택하고 마이그레이션 경험에 대한 피드백을 제공해 주시길 권장합니다.

  • API 설계에 대한 의견이 있거나 채택 과정에서 문제가 발생하면 Kubernetes Slack의 #csi 채널로 연락 주세요 (초대는 방문하십시오 ).

KEP‑5538을 따라가면서 향후 Kubernetes 릴리스에서 진행 상황을 확인할 수 있습니다.

Back to Blog

관련 글

더 보기 »