---
# reviewers:
# jbeda
title: 부트스트랩 토큰을 사용한 인증
content_type: concept
weight: 20
---

<!-- overview -->

{{< feature-state for_k8s_version="v1.18" state="stable" >}}

부트스트랩 토큰은 새 클러스터를 만들거나 새 노드를 기존 클러스터에 결합할 때
사용되는 간단한 전달자 토큰이다.
[kubeadm](/ko/docs/reference/setup-tools/kubeadm/)을 지원하도록 구축되었지만
 `kubeadm` 없이 클러스터를 시작하려는 사용자를 위해 다른 컨텍스트에서 사용할 수 있다.
또한 RBAC 정책을 통해 [Kubelet TLS 부트스트래핑](/docs/reference/access-authn-authz/kubelet-tls-bootstrapping/)
시스템과 함께 동작하도록 구축되었다.


<!-- body -->
## 부트스트랩 토큰 개요

부트스트랩 토큰은 `kube-system` 네임스페이스에 있는
특정 유형(`bootstrap.kubernetes.io/token`)의 시크릿(Secret)으로 정의된다.
API 서버의 부트스트랩 인증자가 이러한 시크릿을 읽는다.
만료된 토큰은 컨트롤러 관리자가 TokenCleaner 컨트롤러로 제거한다.
토큰은 BootstrapSigner 컨트롤러를 통해
"discovery" 프로세스에 사용되는 특정 컨피그맵(ConfigMap)에 대한
서명을 만드는 데도 사용된다.

## 토큰 형식

부트스트랩 토큰은 `abcdef.0123456789abcdef` 형식을 취한다. 더 공식적으로는
정규식 `[a-z0-9]{6}\.[a-z0-9]{16}` 와 일치해야 한다.

토큰의 첫 번째 부분은 "Token ID" 이며 공개 정보로 간주된다.
인증에 사용하는 시크릿의 일부를 노출하지 않고 토큰을 참조할 때 사용한다.
두 번째 부분은 "Token Secret"이며
신뢰할 수 있는 당사자와만 공유해야 한다.

## 부트스트랩 토큰 인증 활성화

API 서버에서 다음 플래그를 사용하여 부트스트랩 토큰 인증자를
활성화할 수 있다.

```
--enable-bootstrap-token-auth
```

활성화되면 부트스트랩 토큰을 API 서버에 대한 요청을 인증하기 위한
전달자 토큰 자격 증명으로 사용할 수 있다.

```http
Authorization: Bearer 07401b.f395accd246ae52d
```

토큰은 사용자 이름 `system:bootstrap:<token id>` 로 인증되며 `system:bootstrappers` 그룹의 구성원이다.
토큰의 시크릿에 추가 그룹을
지정할 수 있다.

만료된 토큰은 컨트롤러 관리자에서 `tokencleaner`
컨트롤러를 활성화하여 자동으로 삭제할 수 있다.

```
--controllers=*,tokencleaner
```

## 부트스트랩 토큰 시크릿 형식

각각의 유효한 토큰은 `kube-system` 네임스페이스의 시크릿에 의해 지원된다.
전체 디자인 문서는
[여기](https://git.k8s.io/design-proposals-archive/cluster-lifecycle/bootstrap-discovery.md)에서 찾을 수 있다.

시크릿은 다음과 같다.

```yaml
apiVersion: v1
kind: Secret
metadata:
  # Name MUST be of form "bootstrap-token-<token id>"
  name: bootstrap-token-07401b
  namespace: kube-system

# Type MUST be 'bootstrap.kubernetes.io/token'
type: bootstrap.kubernetes.io/token
stringData:
  # Human readable description. Optional.
  description: "The default bootstrap token generated by 'kubeadm init'."

  # Token ID and secret. Required.
  token-id: 07401b
  token-secret: f395accd246ae52d

  # Expiration. Optional.
  expiration: 2017-03-10T03:22:11Z

  # Allowed usages.
  usage-bootstrap-authentication: "true"
  usage-bootstrap-signing: "true"

  # Extra groups to authenticate the token as. Must start with "system:bootstrappers:"
  auth-extra-groups: system:bootstrappers:worker,system:bootstrappers:ingress
```

시크릿 유형은 `bootstrap.kubernetes.io/token` 이어야 하고
이름은 `bootstrap-token-<token id>`여야 한다. 반드시 `kube-system`
네임스페이스에도 존재해야 한다.

`usage-bootstrap-*` 멤버는 이 시크릿의 용도를 나타낸다.
활성화하려면 값을 `true` 로 설정해야 한다.

* `usage-bootstrap-authentication` 은 토큰을 API 서버에
베어러 토큰으로 인증하는데 사용할 수 있음을 나타낸다.
* `usage-bootstrap-signing` 은 토큰을 사용하여 아래에 설명된
`cluster-info` 컨피그맵에 서명할 수 있음을 나타낸다.

`expiration` 필드는 토큰의 만료를 제어한다. 만료된 토큰은
인증에 사용될 때 거부되고 컨피그맵서명 중에 무시된다.
만료된 값은 RFC3339를 사용하여 절대 UTC 시간으로 인코딩된다.
만료된 토큰을 자동으로 삭제하려면 `tokencleaner` 컨트롤러를 활성화한다.

## kubeadm을 사용한 토큰 관리

`kubeadm` 툴을 사용하여 실행중인 클러스터에서 토큰을 관리할 수 있다.
자세한 내용은 [kubeadm token docs](/docs/reference/setup-tools/kubeadm/kubeadm-token/) 에서 찾을 수 있다.

## 컨피그맵 서명

토큰은 인증 외에도 컨피그맵에 서명하는데 사용할 수 있다.
이것은 클라이언트가 API 서버를 신뢰하기 전에 클러스터 부트스트랩 프로세스의 초기에 사용된다.
서명된 컨피그맵은 공유 토큰으로 인증할 수 있다.

컨트롤러 관리자에서 `bootstrapsigner` 컨트롤러를 활성화하여
컨피그맵서명을 활성화 한다.

```
--controllers=*,bootstrapsigner
```

서명된 컨피그맵은 `kube-public` 네임스페이스에 있는 `cluster-info` 이다.
일반적인 흐름은 클라이언트가 인증되지 않고 TLS 오류를 무시하는 동안
컨피그맵을 읽는 것이다. 그런 다음 컨피그맵에 포함된 서명을 확인하여
컨피그맵의 페이로드를 확인한다.

컨피그맵은 다음과 같을 수 있다.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: cluster-info
  namespace: kube-public
data:
  jws-kubeconfig-07401b: eyJhbGciOiJIUzI1NiIsImtpZCI6IjA3NDAxYiJ9..tYEfbo6zDNo40MQE07aZcQX2m3EB2rO3NuXtxVMYm9U
  kubeconfig: |
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: <really long certificate data>
        server: https://10.138.0.2:6443
      name: ""
    contexts: []
    current-context: ""
    kind: Config
    preferences: {}
    users: []
```

컨피그맵의 `kubeconfig` 멤버는 클러스터 정보만 입력된 구성 파일이다.
여기서 전달되는 핵심은 `certificate-authority-data` 이다.  
이는 향후 확대될 수 있다.

서명은 "detached" 모드를 사용하는 JWS 서명이다. 서명을 검증하려면
사용자는 JWS 규칙(뒤로 오는 `=` 를 삭제하는 동안 인코딩된 base64)에 따라
`kubeconfig` 페이로드를 인코딩해야 한다. 그런 다음 인코딩된 페이로드는
두 개의 점 사이에 삽입하여 전체 JWS를 형성하는 데 사용된다.
전체 토큰(예:`07401b.f395accd246ae52d`)을 공유 시크릿으로 사용하여
`HS256` 방식(HMAC-SHA256)을 사용함으로 JWS를 확인할 수 있다.
사용자는 _반드시_ HS256이 사용되고 있는지 확인해야 한다.

{{< warning >}}
부트스트래핑 토큰을 가진 모든 당사자는 해당 토큰에 대한 유효한 서명을 만들 수 있다.
컨피그맵 서명을 사용할 때 많은 클라이언트와 동일한 토큰을 공유하는 것은 권장되지 않는다.
손상된 클라이언트는 잠재적으로 서명에 의존하여
TLS 트러스트를 부트스트랩하는 다른 클라이언트를 대신할 수 있기 때문이다.
{{< /warning >}}

자세한 내용은 [kubeadm implementation details](/docs/reference/setup-tools/kubeadm/implementation-details/)
섹션을 참조하면 된다.