--- title: "IAM 인증 kubeconfig 생성" slug: "k8s-iam-auth-kubeconfig" tags: ["Ncloud Kubernetes Service 사용", "Ncloud Kubernetes Service(VPC)", "Sub Account 인증"] updated: 2026-08-20T09:03:25Z published: 2026-08-20T09:03:25Z canonical: "guide-gov.ncloud-docs.com/k8s-iam-auth-kubeconfig" --- > ## Documentation Index > Fetch the complete documentation index at: https://guide-gov.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # IAM 인증 kubeconfig 생성/업데이트 VPC 환경에서 이용 가능합니다. Ncloud Kubernetes Service는 IAM 클러스터 인증을 위해서 ncp-iam-authenticator를 사용합니다. ncp-iam-authenticator를 통해 IAM 인증이 적용된 kubeconfig를 가져와 기존 파일에 업데이트하거나 새 파일로 생성할 수 있습니다. 참고 - SubAccount의 경우 `ncp-iam-authenticator`를 통해 kubeconfig를 생성/업데이트 하려면 View/getClusterDetail 과 View/getClusterList 권한이 필요합니다. - Jenkins, Github Action와 같은 3rd-party 서비스의 사용으로 `ncp-iam-authenticator`를 사용한 인증이 어려운 경우 [클러스터 권한 제어](/docs/k8s-k8suse-clusterauth)를 참고하여 서비스 어카운트 토큰을 통한 인증을 사용할 수 있습니다. ## ncp-iam-authenticator API 인증키값 설정 `ncp-iam-authenticator`를 사용하기 위해서 먼저 API 인증키값을 설정해야 합니다. 참고 API 인증키는 네이버 클라우드 플랫폼 콘솔의 **My Account** > **계정 및 보안 관리** > **보안 관리** > **접근 관리** 메뉴에서 확인할 수 있습니다. OS 환경 변수나 configure 파일에 API 키를 설정해 주십시오. (OS 환경변수가 configure 파일보다 우선합니다.) - OS 환경 변수 설정 ``` $ export NCLOUD_ACCESS_KEY=ACCESSKEYIDACCESSKEY $ export NCLOUD_SECRET_KEY=SECRETACCESSKEYSECRETACCESSKEYSECRETACCE $ export NCLOUD_API_GW=https://ncloud.apigw.gov-ntruss.com ``` - 사용자 환경 홈 디렉터리의 .ncloud 폴더에 configure 파일 ``` $ cat ~/.ncloud/configure [DEFAULT] ncloud_access_key_id = ACCESSKEYACCESSKEYAC ncloud_secret_access_key = SECRETKEYSECRETKEYSECRETKEYSECRETKEYSECR ncloud_api_url = https://ncloud.apigw.gov-ntruss.com [project] ncloud_access_key_id = ACCESSKEYACCESSKEYAC ncloud_secret_access_key = SECRETKEYSECRETKEYSECRETKEYSECRETKEYSECR ncloud_api_url = https://ncloud.apigw.gov-ntruss.com ``` - 인증키 값을 확인하지 못할 경우, `ncp-iam-authenticator` 명령 수행 중에 API 키 입력을 요구합니다. ``` Ncloud Access Key Id []: ACCESSKEYACCESSKEYAC Ncloud Secret Access Key []: SECRETKEYSECRETKEYSECRETKEYSECRETKEYSECR Ncloud API URL []: https://ncloud.apigw.gov-ntruss.com ``` - 또한 다음과 같은 옵션을 이용하여 각 명령 시 Ncloud 인증 키 설정 및 디버그 여부를 설정할 수 있습니다. | 이름 | 설명 | 필수 여부 | 기본값 | | --- | --- | --- | --- | | credentialConfig | ncloud configure 파일 경로 | X | ~/.ncloud/configure | | profile | ncloud configure 파일 내의 profile | X | DEFAULT | | debug | debug log 출력 여부 | X | false | ## ncp-iam-authenticator update-kubeconfig 명령 사용 참고 최신 버전의 ncp-iam-authenticator가 아닐 경우 일부 명령어가 제한되므로, 최신 버전 재설치를 권장합니다. 1. `ncp-iam-authenticator`가 설치되어 있는지 확인해 주십시오. `ncp-iam-authenticator`를 설치하려면 [ncp-iam-authenticator 설치](/docs/k8s-iam-auth-ncp-iam-authenticator)를 참조해 주십시오. 2. 명령어에 사용될 옵션을 확인해주십시오. 참고 kubeconfig 파일 경로에 kubeconfig이 존재하지 않다면, 해당 경로에 새 파일을 생성합니다. clusterName 이나 userName을 설정했다면 contextName이 `userName@clusterName`으로 설정되며, 그렇지 않다면 `nks_<regionCode>_<clusterName>_<clusterUuid>`으로 설정됩니다. | 이름 | 설명 | 필수 여부 | 기본값 | | --- | --- | --- | --- | | clusterUuid | kubeconfig에 생성할 cluster의 uuid | O | | | region | kubeconfig에 생성할 cluster의 regionCode - KR, KRS | O | | | clusterName | kubeconfig에 설정될 cluster name | X | nks___ | | userName | kubeconfig에 설정될 user name | X | nks___ | | currentContext | current-context를 새로 적용될 context로 수정할지의 여부 | X | true | | overwrite | kubeconfig에 적용될 cluster name, user name, context name이 기존 파일과 중복될시 덮어쓸지의 여부 | X | false | | kubeconfig | update할 kubeconfig의 파일 경로 | X | KUBECONFIG 환경변수에 설정된 첫 번째 경로 KUBECONFIG 환경변수가 설정돼있지 않다면, ~/.kube/config | | format | 생성될 kubeconfig의 파일 형식 - yaml, json | X | yaml | 3. 위 표를 참고해, `ncp-iam-authenticator update-kubeconfig` 명령을 사용하여 기존 kubeconfig 파일에 클러스터의 config를 추가 하십시오. ``` ncp-iam-authenticator update-kubeconfig --region --clusterUuid ``` 4. 생성된 `kubeconfig` 파일로 `kubectl` 명령을 테스트해 주십시오. ``` $ kubectl get namespaces --kubeconfig kubeconfig.yaml NAME STATUS AGE default Active 1h kube-node-lease Active 1h kube-public Active 1h kube-system Active 1h kubernetes-dashboard Active 1h ``` ## ncp-iam-authenticator create-kubeconfig 명령 사용 참고 최신 버전의 ncp-iam-authenticator가 아닐 경우, 일부 명령어가 제한되므로 최신 버전 재설치를 권장드립니다. 1. `ncp-iam-authenticator`가 설치되어 있는지 확인해 주십시오. `ncp-iam-authenticator`를 설치하려면 [`ncp-iam-authenticator` 설치](/docs/k8s-iam-auth-ncp-iam-authenticator)를 참조해 주십시오. 2. 명령어에 사용될 옵션을 확인해 주십시오. 참고 clusterName 이나 userName을 설정했다면 contextName이 `userName@clusterName`으로 설정되며, 그렇지 않다면 `nks_<regionCode>_<clusterName>_<clusterUuid>`으로 설정됩니다. | 이름 | 설명 | 필수 여부 | 기본값 | | --- | --- | --- | --- | | clusterUuid | kubeconfig에 생성할 cluster의 uuid | O | | | region | kubeconfig에 생성할 cluster의 regionCode - KR, KRS | O | | | clusterName | kubeconfig에 설정될 cluster name | X | nks___ | | userName | kubeconfig에 설정될 cluster name | X | nks___ | | output | kubeconfig이 저장될 filepath (파일명 포함) | X | kubeconfig-. | | format | 생성될 kubeconfig의 파일 형식 - yaml, json | X | yaml | 3. 위 표를 참고해, `ncp-iam-authenticator create-kubeconfig` 명령을 사용하여 클러스터에 대한 kubeconfig를 생성해 주십시오. ``` ncp-iam-authenticator create-kubeconfig --region --clusterUuid --output kubeconfig.yaml ``` 4. 생성된 `kubeconfig` 파일로 `kubectl` 명령을 테스트해 주십시오. ``` $ kubectl get namespaces --kubeconfig kubeconfig.yaml NAME STATUS AGE default Active 1h kube-node-lease Active 1h kube-public Active 1h kube-system Active 1h kubernetes-dashboard Active 1h ```