클러스터 접근하기

kubectl 설치 및 사용 방법

Kubernetes Engine 서비스를 생성한 후 쿠버네티스 커맨드 라인 도구인 kubectl을 사용하면 쿠버네티스 클러스터에 대해 명령을 실행할 수 있습니다. kubectl을 사용하여 애플리케이션을 배포하고, 클러스터 리소스를 검사 및 관리하고 로그를 볼 수 있습니다. 다음과 같은 쿠버네티스 공식 문서에서 kubectl을 설치하여 사용하는 방법을 확인할 수 있습니다.

구분참고 URL
kubectl 설치 (리눅스)https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/
kubectl 설치 (윈도우)https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/
kubectl 소개https://kubernetes.io/docs/reference/kubectl/
kubectl 퀵 레퍼런스https://kubernetes.io/docs/reference/kubectl/quick-reference/
kubectl 명령어 레퍼런스https://kubernetes.io/docs/reference/kubectl/kubectl/
표. kubectl 참고 문서
참고

클러스터의 마이너(minor) 버전 차이 내에 있는 kubectl 버전을 사용해야 합니다. 예를 들어, 클러스터의 버전이 1.30이라면 kubectl 버전 1.29, 1.30, 1.31을 사용할 수 있습니다.

kubectl로 쿠버네티스 클러스터에 접근하려면, 쿠버네티스 서버 주소와 인증 정보를 담은 kubeconfig 파일이 필요합니다.

참고
쿠버네티스 인증 및 인가에 대한 상세한 내용은 인증 및 인가를 참고하세요.

Kubernetes Engine은 관리자 인증서 kubeconfig와 사용자 인증키 kubeconfig를 통한 인증 기능을 지원합니다.

관리자 인증서 kubeconfig

이 kubeconfig는 Kubernetes API에 접근할 때, 관리자 인증서를 인증 수단으로 사용합니다.

관리자 kubeconfig 다운로드

Kubernetes Engine > 클러스터 목록 > 클러스터 상세 > 관리자 kubeconfig 다운로드 버튼을 클릭하여 kubeconfig 파일을 다운로드합니다.

주의
  • 관리자 kubeconfig 다운로드는 Admin만 가능합니다.
  • 프라이빗 엔드포인트용과 퍼플릭 엔드포인트용이 따로 있으며 각각 최초 1회만 다운로드할 수 있습니다.

관리자 kubeconfig 사용

참고
  • 기본적으로 kubectl은 $HOME/.kube 디렉터리에서 config라는 이름의 파일을 찾습니다. 또는 KUBECONFIG 환경 변수를 설정하거나 kubeconfig 플래그를 지정하여 다른 kubeconfig 파일을 사용할 수 있습니다.
  • 프라이빗 엔드포인트는 기본적으로 해당 클러스터의 노드에서만 접근이 허용됩니다. 동일 Account, 동일 리전에 있는 리소스의 경우, 프라이빗 엔드포인트 접근 제어 설정에 추가하여 접근을 허용할 수 있습니다.
  • 외부 인터넷에서 클러스터에 접근이 필요한 경우, 퍼블릭 엔드포인트 액세스를 사용으로 설정하면 퍼블릭 엔드포인트 kubeconfig를 사용하여 접근할 수 있습니다.

사용자 인증키 kubeconfig

이 kubeconfig는 Kubernetes API에 접근할 때, 사용자의 Open API 인증키를 인증 수단으로 사용합니다.

사용자 kubeconfig 다운로드

Kubernetes Engine > 클러스터 목록 > 클러스터 상세 > 사용자 kubeconfig 다운로드 버튼을 클릭하여 kubeconfig 파일을 다운로드합니다.

주의
  • 사용자 kubeconfig 다운로드는 클러스터 조회 권한이 있는 사용자만 가능합니다.
  • 프라이빗 엔드포인트용과 퍼플릭 엔드포인트용이 따로 있습니다.
  • 다운로드한 kubeconfig 파일에는 인증키 토큰이 포함되어 있지 않으므로, 사용하기 전에 인증키 토큰 정보를 추가해야 합니다. (다음 문단 참고)

사용자 kubeconfig 파일에 인증키 토큰 추가

아래는 사용자 kubeconfig 파일의 예시입니다. kubeconfig 파일을 사용하기 위해서는 파일 내부의 token 란에 인증키 토큰(AUTHKEY_TOKEN) 정보를 추가해야 합니다.

배경색 변경
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...
    server: https://my-cluster-a1c3e.ske.xxx.samsungsdscloud.com:6443
  name: my-cluster-a1c3e
contexts:
- context:
    cluster: my-cluster-a1c3e
    user: jane.doe
  name: jane.doe@my-cluster-a1c3e
current-context: jane.doe@my-cluster-a1c3e
kind: Config
preferences: {}
users:
- name: jane.doe
  user:
    token: <AUTHKEY_TOKEN> #### 작성 필요
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...
    server: https://my-cluster-a1c3e.ske.xxx.samsungsdscloud.com:6443
  name: my-cluster-a1c3e
contexts:
- context:
    cluster: my-cluster-a1c3e
    user: jane.doe
  name: jane.doe@my-cluster-a1c3e
current-context: jane.doe@my-cluster-a1c3e
kind: Config
preferences: {}
users:
- name: jane.doe
  user:
    token: <AUTHKEY_TOKEN> #### 작성 필요
코드 블럭. 사용자 kubeconfig 파일 예시

AUTHKEY_TOKEN은 인증키의 ACCESS_KEY와 SECRET_KEY를 콜론(:)으로 연결한 후, Base64 인코딩하여 생성할 수 있습니다. 다음은 리눅스 환경에서 AUTHKEY_TOKEN을 만드는 예시입니다.

배경색 변경
$ ACCESS_KEY=5df418813aed051548a72f4a814cf09e
$ SECRET_KEY=6ba7b810-9dad-11d1-80b4-00c04fd430c8
$ AUTHKEY_TOKEN=$(echo -n "$ACCESS_KEY:$SECRET_KEY" | base64 -w0)
$ echo $AUTHKEY_TOKEN
NWRmNDE4ODEzYWVkMDUxNTQ4YTcyZjRhODE0Y2YwOWU6NmJhN2I4MTAtOWRhZC0xMWQxLTgwYjQtMDBjMDRmZDQzMGM4r
$ ACCESS_KEY=5df418813aed051548a72f4a814cf09e
$ SECRET_KEY=6ba7b810-9dad-11d1-80b4-00c04fd430c8
$ AUTHKEY_TOKEN=$(echo -n "$ACCESS_KEY:$SECRET_KEY" | base64 -w0)
$ echo $AUTHKEY_TOKEN
NWRmNDE4ODEzYWVkMDUxNTQ4YTcyZjRhODE0Y2YwOWU6NmJhN2I4MTAtOWRhZC0xMWQxLTgwYjQtMDBjMDRmZDQzMGM4r
코드 블럭. AUTHKEY_TOKEN 값 생성 예시
참고
  • 인증키 생성에 관한 자세한 내용은 API Reference > Common > 삼성 클라우드 플랫폼 Open API 호출 절차를 참고하세요.

사용자 kubeconfig 실행 예시

사용자 kubeconfig의 실행 예시를 확인할 수 있습니다.

접근 제어나 방화벽에 의해 접근이 차단된 경우

배경색 변경
$ kubectl --kubeconfig=user-kubeconfig.yaml get namespaces
Unable to connect to the server: dial tcp 123.123.123.123:6443: i/o timeout
$ kubectl --kubeconfig=user-kubeconfig.yaml get namespaces
Unable to connect to the server: dial tcp 123.123.123.123:6443: i/o timeout
코드 블럭. 접근 제어나 방화벽에 의해 접근이 차단된 경우 실행 예시

AUTHKEY_TOKEN이 맞지 않아 인증에 실패한 경우

배경색 변경
$ kubectl --kubeconfig=user-kubeconfig.yaml get namespaces
error: You must be logged in to the server (Unauthorized)
$ kubectl --kubeconfig=user-kubeconfig.yaml get namespaces
error: You must be logged in to the server (Unauthorized)
코드 블럭. AUTHKEY_TOKEN이 맞지 않아 인증에 실패한 경우 실행 예시

AUTHKEY_TOKEN 인증에 성공한 경우

배경색 변경
$ kubectl --kubeconfig=user-kubeconfig.yaml get namespaces
...
kube-node-lease    Active 10d
kube-public        Active 10d
kube-system        Active 10d
$ kubectl --kubeconfig=user-kubeconfig.yaml get namespaces
...
kube-node-lease    Active 10d
kube-public        Active 10d
kube-system        Active 10d
코드 블럭. AUTHKEY_TOKEN 인증에 성공한 경우 실행 예시

AUTHKEY_TOKEN 인증에 성공했으나 권한이 없는 경우

배경색 변경
$ kubectl --kubeconfig=user-kubeconfig.yaml get nodes
Error from server (Forbidden): nodes is forbidden: User "jane.doe" cannot list resource "nodes" in API group "" at the cluster scope
$ kubectl --kubeconfig=user-kubeconfig.yaml get nodes
Error from server (Forbidden): nodes is forbidden: User "jane.doe" cannot list resource "nodes" in API group "" at the cluster scope
코드 블럭. AUTHKEY_TOKEN 인증에 성공했으나 권한이 없는 경우 실행 예시
참고
AUTHKEY_TOKEN 인증에 성공했으나 권한이 없는 경우, 인증 과정은 올바르게 완료되었지만 요청한 작업을 수행할 수 있는 권한이 부여(인가)되지 않았음을 의미합니다. 인가에 대한 상세한 내용은 인증 및 인가를 참고하세요.
Kubernetes Engine 활용
인증 및 인가