인터페이스

Version : 1.1 / Update : 2025.08.16

1. 개요

K8S Resource Security 는 K8S에서 제공하는 인터페이스를 이용하여 서비스를 구성한다. K8S는 그 내용을 Using a KMS provider for data encryption이라는 이름으로 공식 문서를 통해 배포하고 있다. 공식 문서는 다음에서 확인 가능하다. 아래의 내용은 공식 문서에서 필요한 내용을 발췌하였다.

공식 사이트 주소: https://kubernetes.io/docs/tasks/administer-cluster/kms-provider/

1-1. KMS Version

KMS provider는 다음의 2가지 버전을 제공한다. 이 또한 공식 문서에서 동일하게 표기하고 있다.

KMS v1: Kubernetes v1.28 [deprecated]
- Kubernetes version 1.10.0 or later is required
- For version 1.29 and later, the v1 implementation of KMS is disabled by default. To enable the feature, set --feature-gates=KMSv1=true to configure a KMS v1 provider.
- Your cluster must use etcd v3 or later
KMS v2: Kubernetes v1.29 [stable]
- Your cluster must use etcd v3 or later

1-2. KMS provider 구성

API 서버에서 KMS 공급자를 구성하려면 암호화 구성 파일의 공급자 배열에 kms 유형의 공급자를 포함하고 다음 속성을 설정해야 한다.

KMS v1
- apiVersion: API Version for KMS provider. Leave the value empty or set it to v1.
- name: Display name of the KMS plugin. Cannot be changed once set.
- endpoint: Listen address of the gRPC server (KMS plugin). The endpoint is a UNIX domain socket.
- cachesize: Number of data encryption keys (DEKs) to be cached in the clear. When cached, DEKs can be used without another call to the KMS; whereas DEKs that are not cached require a call to the KMS to unwrap.
- timeout: How long should kube-apiserver wait for kms-plugin to respond before returning an error (default is 3 seconds).
KMS v2
- apiVersion: API Version for KMS provider. Set this to v2.
- name: Display name of the KMS plugin. Cannot be changed once set.
- endpoint: Listen address of the gRPC server (KMS plugin). The endpoing is a UNIX domain socket.
- timeout: How long should kube-apiserver wait for kms-plugin to respond before returning an error (default is 3 seconds).

1-3. KMS plugin 구현

KMS plugin은 다음의 방법으로 구현할 수 있다. KMS plugin은 Kubernetes control plane에 배포되어야 한다.

Cloud Provider에서 제공하는 방법으로 사용하기
gRPC Server로 KMS plugin을 개발하기

Key4C K8S Resource Security는 gRPC Server로 개발된 KMS plugin 이다. 따라서 Cloud Provider에 따라 사용이 불가능 할 수도 있다.

2. 인터페이스

각 버전별로 인터페이스 정의를 K8S 공식 문서에 존재한다. 각 버전별 인터페이스는 다음주소에서 확인 가능하다.

KMS v1
- Golang: https://github.com/kubernetes/kms/blob/release-1.33/apis/v1beta1/api.pb.go
- Other Languages: https://github.com/kubernetes/kms/blob/release-1.33/apis/v1beta1/api.proto
KMS v2
- Golang: https://github.com/kubernetes/kms/blob/release-1.33/apis/v2/api.pb.go
- Other Languages: https://github.com/kubernetes/kms/blob/release-1.33/apis/v2/api.proto

3. 구현 확인

다음 링크를 통해 구현을 확인 할 수 있다.

4. Key4C K8S Resource Security 적용 방법

Key4C K8S Resource Security(이하 Key4C K8S App) 는 K8S의 KMS plugin의 두가지 버전을 모두 지원한다. Key4C K8S App을 적용하기 위해 다음의 단계를 따라 확인한다.

4-1. 사전 확인

웹 콘솔에서 사용하기 위한 Key4C K8S App에서 사용하기 위하여 다음의 두가지 내용을 확인한다.

KMS_USER_ID: 서비스 신청을 하면 생성되는 토큰의 ID 값
KMS_KEY_ID: 암복호화를 위해 생성한 키의 ID 값

4-2. Key4C K8S App 준비 및 실행

(!) important

Key4C K8S App을 실행하기전 다음의 사항을 반드시 숙지해야 한다.

Key4C K8S App은 Control plane과 같은 Host에 존재해야 한다.
K8S의 API Server가 실행되기전에 KMS plugin의 존재를 알아야 한다. 따라서 반드시 static pod로 생성해야 한다.
단일 pod로 생성해야 한다.

아래 예시를 보고 K8S의 yaml파일을 적용한다.

key4c-container-image은 다운로드 페이지에서 다운 받을 수 있다.

# key4c-kms-plugin-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: key4c-kms-plugin
  namespace: kube-system # api-server와 같은 namespace에 있어야 함.
spec:
  containers:
  - name: key4c-kms-plugin-encryption-provider
    image: {{key4c-container-image}}
    securityContext:
      privileged: true
    env:
    - name: KMS_USER_ID
      value: {{KMS_USER_ID}}
    - name: KMS_KEY_ID
      value: {{KMS_KEY_ID}}
    volumeMounts:
    - name: kms-plugin-socket
      mountPath: /tmp # K8S와 통신을 위한 Unix Domain 소켓의 위치
    volumes:
    - name: kms-plugin-socket
      hostPath:
        type: DirectoryOrCreate
        path: /tmp

위 yaml파일을 static pod로 실행하기 위하여 kubernetes의 manifest 설정에 등록한다. manifest 설정에 등록을 위해서는 작성한 yaml 파일을 /etc/kubernetes/manifests/에 위치하면 된다.

cp key4c-kms-plugin-pod.yaml /etc/kubernetes/manifests

정상적으로 pod가 생성이 되면 kubectl 명령으로 pod를 확인 할 수 있습니다.

kubectl get pod -n kube-system
NAME                      READY STATUS  RESTARTS      AGE
......
key4c-kms-plugin-xxxxxx   1/1   Running 0             87s
......

Container가 정상기동이 되면 kms-plugin-socket이름으로 지정한 /tmp 디렉토리에 Unix Domain Socket이 생성된것을 확인 할수 있다.

4-3. Key4C KMS-plugin 적용

key4c-kms-plugin pod의 적용이 완료되면 K8S와 KMS-plugin이 통신을 할 수 있도록 다음과 같이 적용한다.

4-3-1. Encryption Configration File 작성

/etc/kubernetes/pki/encryption-configuration.yaml의 파일을 아래 내용으로 작성한다. K8S의 버전에 따른 작성 가이드는 다음과 같다.

Note

/etc/kubernetes/pki/encryption-configuration.yaml은 절대적인 파일의 위치는 아니다. kube-apiserver에 명시해 준다면 파일의 위치는 어디이든 상관 없다.

KMS plugin v1
- endpoint: endpoint의 경로는 key4c-kms-plugin-pod.yaml에서 기술한 kms-plugin-socket의 경로로 맞추어야 한다.
- cachesize: v1에만 존재한다. DEK 캐싱 사이즈를 지정한다.

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
  - secrets
  providers:
  - kms:
    name: key4c-kms-plugin
    endpoint: unix:///tmp/kms.sock
    cachesize: 1000
    timeout: 3s

KMS plugin v2
- apiVersion: version의 경우는 반드시 version을 지정해야 한다.
- endpoint: endpoint의 경로는 key4c-kms-plugin-pod.yaml에서 기술한 kms-plugin-socket의 경로로 맞추어야 한다.

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
- resources:
  - secrets
  providers:
  - kms:
    apiVersion: v2
    name: key4c-kms-plugin
    endpoint: unix:///tmp/kms.sock
    timeout: 3s

4-3-2. Encryption Configration File 작성

API server의 config 파일(/etc/kubernetes/manifests/kube-apiserver.yaml)의 내용에 encryption-provider를 지정한다. KMS-plugin이 생성한 socket을 API server가 접근할 수 있도록 해당 위치를 마운트 해야 한다.

Warning

kube-apiserver.yaml을 수정후 저장하면, 자동으로 API server가 재시작 되며, Control plane의 모든 pod들이 재시작 되면서 KMS plugin이 적용됩니다.

apiVersion: v1
kind: Pod
metadata:
  ...
spec:
  containers:
  - command:
    - kube-apiserver
    ...
    - --tls-private-key-file=/etc/kubernetes/pki/apiserver.key
    - --encryption-provider-config=/etc/kubernetes/pki/encryption-configuration.yaml
...
volumeMounts:
- mountPath: /tmp
  name: kms-plugin-socket
...
volumes:
- hostPath:
    path: /tmp
    type: DirectoryOrCreate
  name: kms-plugin-socket

4-3-3. KMS plugin 설치 확인

kube-apiserver, kube-controller, kube-scheduler 가 정상으로 작동하는지 확인한다.

kubectl get pod -n kube-system
NAME                            READY STATUS  RESTARTS      AGE
......
kube-apiserver-xxxxxx           1/1   Running 0             87s
kube-controller-manager-xxxxxx  1/1   Running 0             87s
kube-scheduler-xxxxxx           1/1   Running 0             87s
key4c-kms-plugin-xxxxxx         1/1   Running 0             10m
......

4-4. Key4C KMS-plugin 확인

테스트용 secret을 만든다.

kubectl create secret generic key4cSecret \
--from-literal=user=key4c \
--from-literal=pass=password

Secret을 환경변수로 받는 테스트 pod를 생성한다.

# test-nginx-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: test-nginx
  namespace: default
spec:
  containers:
  - name: test-nginx-container
    image: nginx:1.14
    env:
    - name: KEY4C_SECRET_USER
      valueFrom:
        secretKeyRef:
          name: key4cSecret
          key: user
    - name: KEY4C_SECRET_PASS
      valueFrom:
        secretKeyRef:
          name: key4cSecret
          key: pass

pod를 실행한다.

kubectl create -f test-nginx-pod.yaml

Pod 안에서 환경변수의 값이 정상인지 확인 한다.

kubectl exec -it test-nginx -- /bin/bash
env | grep KEY4C
KEY4C_SECRET_USER=key4c
KEY4C_SECRET_PASS=password