PKI 인증서와 요구 사항

PKI 인증서와 요구 사항 (PKI certificates and requirements)

쿠버네티스는 TLS를 통한 인증을 위해 PKI 인증서를 요구해요. kubeadm으로 쿠버네티스를 설치하면 클러스터에 필요한 인증서가 자동으로 생성돼요. 직접 인증서를 생성할 수도 있는데, 예를 들어 개인 키를 API 서버에 저장하지 않아 더 안전하게 보관하려는 경우가 그렇죠. 이 페이지는 클러스터에 필요한 인증서를 설명해요.

출처: 문서

본문

클러스터가 인증서를 사용하는 방법

쿠버네티스는 다음 작업에 PKI가 필요해요.

서버 인증서 (Server certificates)

API 서버 엔드포인트용 서버 인증서
etcd 서버용 서버 인증서
각 kubelet용 서버 인증서(모든 노드가 kubelet을 실행)
선택적: front-proxy용 서버 인증서

클라이언트 인증서 (Client certificates)

각 kubelet용 클라이언트 인증서로, 쿠버네티스 API의 클라이언트로서 API 서버에 인증하는 데 사용
각 API 서버용 클라이언트 인증서로, etcd에 인증하는 데 사용
controller manager가 API 서버와 안전하게 통신하기 위한 클라이언트 인증서
scheduler가 API 서버와 안전하게 통신하기 위한 클라이언트 인증서
kube-proxy가 API 서버에 인증하기 위해 노드마다 하나씩의 클라이언트 인증서
선택적: 클러스터 관리자가 API 서버에 인증하기 위한 클라이언트 인증서
선택적: front-proxy용 클라이언트 인증서

Kubelet의 서버 및 클라이언트 인증서

안전한 연결을 수립하고 kubelet에 자신을 인증하기 위해 API 서버는 클라이언트 인증서와 키 쌍이 필요해요.

이 시나리오에는 인증서 사용에 대한 두 가지 접근 방식이 있어요.

공유 인증서(Shared Certificates): kube-apiserver는 클라이언트를 인증할 때 사용하는 것과 같은 인증서와 키 쌍을 사용할 수 있어요. 즉, apiserver.crt와 apiserver.key 같은 기존 인증서를 kubelet 서버와 통신하는 데 사용할 수 있어요.
별도 인증서(Separate Certificates): 또는 kube-apiserver가 kubelet 서버와의 통신을 인증하기 위해 새 클라이언트 인증서와 키 쌍을 생성할 수 있어요. 이 경우 kubelet-client.crt라는 별도의 인증서와 그에 대응하는 개인 키인 kubelet-client.key가 만들어져요.

참고:

etcd도 클라이언트와 피어를 인증하기 위해 상호 TLS를 구현해요.

인증서가 저장되는 곳

kubeadm으로 쿠버네티스를 설치하면 대부분의 인증서가 /etc/kubernetes/pki에 저장돼요. 이 문서의 모든 경로는 kubeadm이 /etc/kubernetes에 두는 사용자 계정 인증서를 제외하고 그 디렉터리를 기준으로 해요.

인증서 수동 구성하기

kubeadm이 필요한 인증서를 생성하지 않게 하고 싶다면, 단일 루트 CA를 사용하거나 모든 인증서를 제공해 만들 수 있어요. 자신의 인증 기관을 만드는 방법의 세부 사항은 '인증서' 문서를 참고하세요. 인증서 관리에 대해 더 배우려면 'kubeadm으로 인증서 관리'를 참고하세요.

단일 루트 CA (Single root CA)

관리자가 제어하는 단일 루트 CA를 만들 수 있어요. 이 루트 CA는 여러 중간 CA를 만들 수 있고, 이후 모든 추가 생성을 쿠버네티스 자체에 위임할 수 있어요.

필요한 CA:

경로	기본 CN	설명
ca.crt,key	kubernetes-ca	쿠버네티스 일반 CA
etcd/ca.crt,key	etcd-ca	모든 etcd 관련 기능
front-proxy-ca.crt,key	kubernetes-front-proxy-ca	프런트 엔드 프록시용

위 CA 위에 더해, 서비스 계정 관리를 위한 공개/개인 키 쌍인 sa.key와 sa.pub도 필요해요. 다음 예시는 앞선 표에 표시된 CA 키와 인증서 파일을 보여 줘요.

/etc/kubernetes/pki/ca.crt
/etc/kubernetes/pki/ca.key
/etc/kubernetes/pki/etcd/ca.crt
/etc/kubernetes/pki/etcd/ca.key
/etc/kubernetes/pki/front-proxy-ca.crt
/etc/kubernetes/pki/front-proxy-ca.key

모든 인증서 (All certificates)

CA 개인 키를 클러스터에 복사하고 싶지 않다면, 모든 인증서를 직접 생성할 수 있어요.

필요한 인증서:

기본 CN	부모 CA	O (Subject에서)	kind	hosts (SAN)
kube-etcd	etcd-ca		server, client	`<hostname>`, `<Host_IP>`, `localhost`, `127.0.0.1`
kube-etcd-peer	etcd-ca		server, client	`<hostname>`, `<Host_IP>`, `localhost`, `127.0.0.1`
kube-etcd-healthcheck-client	etcd-ca		client
kube-apiserver-etcd-client	etcd-ca		client
kube-apiserver	kubernetes-ca		server	`<hostname>`, `<Host_IP>`, `<advertise_IP>` 1
kube-apiserver-kubelet-client	kubernetes-ca	system:masters	client
front-proxy-client	kubernetes-front-proxy-ca		client

참고:

여기서 kind는 x509 키 사용 하나 이상에 매핑되며, 이는 CertificateSigningRequest 유형의 .spec.usages에도 문서화되어 있어요.

kind	키 사용
server	digital signature, key encipherment, server auth
client	digital signature, key encipherment, client auth

참고:

kubeadm 사용자에게만:

개인 키 없이 CA 인증서를 클러스터에 복사하는 시나리오를 kubeadm 문서에서는 외부 CA(external CA)라고 해요.
위 목록을 kubeadm이 생성한 PKI와 비교한다면, 외부 etcd의 경우 kube-etcd, kube-etcd-peer, kube-etcd-healthcheck-client 인증서가 생성되지 않는다는 점을 인지하세요.

인증서 경로 (Certificate paths)

인증서는 (kubeadm이 사용하는) 권장 경로에 배치해야 해요. 경로는 위치와 무관하게 주어진 인자를 사용해 지정해야 해요.

기본CN	권장 키 경로	권장 인증서 경로	명령	키 인자	인증서 인자
etcd-ca	etcd/ca.key	etcd/ca.crt	kube-apiserver		--etcd-cafile
kube-apiserver-etcd-client	apiserver-etcd-client.key	apiserver-etcd-client.crt	kube-apiserver	--etcd-keyfile	--etcd-certfile
kubernetes-ca	ca.key	ca.crt	kube-apiserver		--client-ca-file
kubernetes-ca	ca.key	ca.crt	kube-controller-manager	--cluster-signing-key-file	--client-ca-file,--root-ca-file,--cluster-signing-cert-file
kube-apiserver	apiserver.key	apiserver.crt	kube-apiserver	--tls-private-key-file	--tls-cert-file
kube-apiserver-kubelet-client	apiserver-kubelet-client.key	apiserver-kubelet-client.crt	kube-apiserver	--kubelet-client-key	--kubelet-client-certificate
front-proxy-ca	front-proxy-ca.key	front-proxy-ca.crt	kube-apiserver		--requestheader-client-ca-file
front-proxy-ca	front-proxy-ca.key	front-proxy-ca.crt	kube-controller-manager		--requestheader-client-ca-file
front-proxy-client	front-proxy-client.key	front-proxy-client.crt	kube-apiserver	--proxy-client-key-file	--proxy-client-cert-file
etcd-ca	etcd/ca.key	etcd/ca.crt	etcd		--trusted-ca-file,--peer-trusted-ca-file
kube-etcd	etcd/server.key	etcd/server.crt	etcd	--key-file	--cert-file
kube-etcd-peer	etcd/peer.key	etcd/peer.crt	etcd	--peer-key-file	--peer-cert-file
etcd-ca		etcd/ca.crt	etcdctl		--cacert
kube-etcd-healthcheck-client	etcd/healthcheck-client.key	etcd/healthcheck-client.crt	etcdctl	--key	--cert

서비스 계정 키 쌍에도 같은 고려 사항이 적용돼요.

개인 키 경로	공개 키 경로	명령	인자
sa.key		kube-controller-manager	--service-account-private-key-file
	sa.pub	kube-apiserver	--service-account-key-file

다음 예시는 자신의 모든 키와 인증서를 생성할 때 제공해야 하는 앞선 표의 파일 경로를 보여 줘요.

/etc/kubernetes/pki/etcd/ca.key
/etc/kubernetes/pki/etcd/ca.crt
/etc/kubernetes/pki/apiserver-etcd-client.key
/etc/kubernetes/pki/apiserver-etcd-client.crt
/etc/kubernetes/pki/ca.key
/etc/kubernetes/pki/ca.crt
/etc/kubernetes/pki/apiserver.key
/etc/kubernetes/pki/apiserver.crt
/etc/kubernetes/pki/apiserver-kubelet-client.key
/etc/kubernetes/pki/apiserver-kubelet-client.crt
/etc/kubernetes/pki/front-proxy-ca.key
/etc/kubernetes/pki/front-proxy-ca.crt
/etc/kubernetes/pki/front-proxy-client.key
/etc/kubernetes/pki/front-proxy-client.crt
/etc/kubernetes/pki/etcd/server.key
/etc/kubernetes/pki/etcd/server.crt
/etc/kubernetes/pki/etcd/peer.key
/etc/kubernetes/pki/etcd/peer.crt
/etc/kubernetes/pki/etcd/healthcheck-client.key
/etc/kubernetes/pki/etcd/healthcheck-client.crt
/etc/kubernetes/pki/sa.key
/etc/kubernetes/pki/sa.pub

사용자 계정용 인증서 구성하기

이러한 관리자 계정과 서비스 계정은 수동으로 구성해야 해요.

파일 이름	자격 증명 이름	기본 CN	O (Subject에서)
admin.conf	default-admin	kubernetes-admin	`<admin-group>`
super-admin.conf	default-super-admin	kubernetes-super-admin	system:masters
kubelet.conf	default-auth	system:node: `<nodeName>` (참고 참조)	system:nodes
controller-manager.conf	default-controller-manager	system:kube-controller-manager
scheduler.conf	default-scheduler	system:kube-scheduler

참고:

위 예시에서 <admin-group>은 구현에 따라 다릅니다. 일부 도구는 기본 admin.conf의 인증서를 system:masters 그룹의 일부로 서명해요. system:masters는 브레이크 글래스(break-glass) 슈퍼 유저 그룹으로, RBAC 같은 쿠버네티스의 권한 부여 계층을 우회할 수 있어요. 또한 일부 도구는 이 슈퍼 유저 그룹에 바인딩된 인증서로 별도의 super-admin.conf를 생성하지 않아요.

kubeadm은 kubeconfig 파일에서 두 개의 별도 관리자 인증서를 생성해요. 하나는 admin.conf에 있으며 Subject가 O = kubeadm:cluster-admins, CN = kubernetes-admin이에요. kubeadm:cluster-admins는 cluster-admin ClusterRole에 바인딩된 커스텀 그룹이에요. 이 파일은 kubeadm이 관리하는 모든 제어 플레인 머신에서 생성돼요.

다른 하나는 super-admin.conf에 있으며 Subject가 O = system:masters, CN = kubernetes-super-admin이에요. 이 파일은 kubeadm init이 호출된 노드에서만 생성돼요.

각 구성에 대해 주어진 CN(Common Name)과 O(Organization)로 x509 인증서/키 쌍을 생성해요.
각 구성에 대해 다음과 같이 kubectl을 실행해요.

KUBECONFIG=<filename> kubectl config set-cluster default-cluster --server=https://<host ip>:6443 --certificate-authority <path-to-kubernetes-ca> --embed-certs
KUBECONFIG=<filename> kubectl config set-credentials <credential-name> --client-key <path-to-key>.pem --client-certificate <path-to-cert>.pem --embed-certs
KUBECONFIG=<filename> kubectl config set-context default-system --cluster default-cluster --user <credential-name>
KUBECONFIG=<filename> kubectl config use-context default-system

이 파일들은 다음과 같이 사용돼요.

파일 이름	명령	주석
admin.conf	kubectl	클러스터의 관리자 사용자 구성
super-admin.conf	kubectl	클러스터의 슈퍼 관리자 사용자 구성
kubelet.conf	kubelet	클러스터의 각 노드에 하나씩 필요
controller-manager.conf	kube-controller-manager	manifests/kube-controller-manager.yaml에 추가해야 함
scheduler.conf	kube-scheduler	manifests/kube-scheduler.yaml에 추가해야 함

다음 파일들은 앞선 표에 나열된 파일들의 전체 경로를 보여 줘요.

/etc/kubernetes/admin.conf
/etc/kubernetes/super-admin.conf
/etc/kubernetes/kubelet.conf
/etc/kubernetes/controller-manager.conf
/etc/kubernetes/scheduler.conf

클러스터에 접촉하는 다른 어떤 IP 또는 DNS 이름(kubeadm이 사용하는 로드 밸런서 안정 IP 및/또는 DNS 이름, kubernetes, kubernetes.default, kubernetes.default.svc, kubernetes.default.svc.cluster, kubernetes.default.svc.cluster.local) ↩︎

PKI 인증서와 요구 사항