The page has been translated by Gen AI.

Access the cluster

kubectl installation and usage guide

After creating a Kubernetes Engine service, you can use the Kubernetes command-line tool kubectl to execute commands on a Kubernetes cluster. You can deploy applications using kubectl, inspect and manage cluster resources, and view logs. You can see how to install and use kubectl in the official Kubernetes documentation as follows.

Category	Reference URL
kubectl installation (Linux)	https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/
kubectl installation (Windows)	https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/
Introduction to kubectl	https://kubernetes.io/docs/reference/kubectl/
kubectl quick reference	https://kubernetes.io/docs/reference/kubectl/quick-reference/
kubectl command reference	https://kubernetes.io/docs/reference/kubectl/kubectl/

Table. kubectl reference documentation

Reference

You must use a kubectl version that is within the cluster’s minor version difference. For example, if the cluster version is 1.30, you can use kubectl versions 1.29, 1.30, or 1.31.

Refer to the following document for the kubectl version skew policy. * https://kubernetes.io/releases/version-skew-policy/#kubectl

To access a Kubernetes cluster with kubectl, you need a kubeconfig file that contains the Kubernetes server address and authentication information.

Reference

For detailed information on Kubernetes authentication and authorization, see 인증 및 인가.

Kubernetes Engine supports authentication via admin certificate kubeconfig and user authentication key kubeconfig.

admin certificate kubeconfig

This kubeconfig uses the admin certificate as the authentication method when accessing the Kubernetes API.

Download admin kubeconfig

Kubernetes Engine > Cluster List > Cluster Details > Admin kubeconfig Download Click the button to download the kubeconfig file.

Caution

Downloading the admin kubeconfig is only allowed for Admin.
There are separate private endpoint and public endpoint versions, and each can be downloaded only once.

Use admin kubeconfig

Reference

By default, kubectl looks for a file named config in the $HOME/.kube directory. * Or set the KUBECONFIG environment variable, or specify the kubeconfig flag to use a different kubeconfig file.
Private endpoints are, by default, only accessible from the nodes of the respective cluster. * For resources in the same account and the same region, you can allow access by adding them to the private endpoint access control settings.
If you need to access the cluster from the external internet, setting public endpoint access to enabled allows you to access using the public endpoint kubeconfig.

User authentication key kubeconfig

This kubeconfig uses the user’s Open API authentication key as the credential when accessing the Kubernetes API.

User kubeconfig download

Kubernetes Engine > Cluster List > Cluster Details > User kubeconfig download Click the button to download the kubeconfig file.

Caution

Downloading a user’s kubeconfig is only permitted for users with cluster view permissions.
Separate private and public endpoint versions are available.
Since the downloaded kubeconfig file does not contain the authentication key token, you must add the authentication key token information before using it. * (see the next paragraph)

Add authentication key token to user kubeconfig file

Below is an example of a user kubeconfig file. To use a kubeconfig file, you must add the authentication key token (AUTHKEY_TOKEN) information to the token field inside the file.

Color mode

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> Writing required

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> Writing required

Code block. Example of a user kubeconfig file

AUTHKEY_TOKEN can be generated by concatenating the ACCESS_KEY and SECRET_KEY of the authentication key with a colon (:) and then Base64 encoding it. The following is an example of creating AUTHKEY_TOKEN in a Linux environment.

Color mode

$ ACCESS_KEY=5df418813aed051548a72f4a814cf09e
$ SECRET_KEY=6ba7b810-9dad-11d1-80b4-00c04fd430c8
$ AUTHKEY_TOKEN=$(echo -n "$ACCESS_KEY:$SECRET_KEY" | base64 -w0)
$ echo $AUTHKEY_TOKEN
NWRmNDE4ODEzYWVkMDUxNTQ4YTcyZjRhODE0Y2YwOWU6NmJhN2I4MTAtOWRhZC0xMWQxLTgwYjQtMDBmMDRmZDQzMGM4r

$ ACCESS_KEY=5df418813aed051548a72f4a814cf09e
$ SECRET_KEY=6ba7b810-9dad-11d1-80b4-00c04fd430c8
$ AUTHKEY_TOKEN=$(echo -n "$ACCESS_KEY:$SECRET_KEY" | base64 -w0)
$ echo $AUTHKEY_TOKEN
NWRmNDE4ODEzYWVkMDUxNTQ4YTcyZjRhODE0Y2YwOWU6NmJhN2I4MTAtOWRhZC0xMWQxLTgwYjQtMDBmMDRmZDQzMGM4r

Code block. Example of generating AUTHKEY_TOKEN value

Reference

For detailed information on authentication key creation, refer to Samsung Cloud Platform Open API Call Procedure.

User kubeconfig execution example

You can see an example of running the user kubeconfig.

When access is blocked by access control or a firewall

Color mode

$ 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

Code block. Example execution when access is blocked by access control or firewall.

When AUTHKEY_TOKEN does not match and authentication fails

Color mode

$ 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)

Code block. Example execution when authentication fails because the AUTHKEY_TOKEN does not match.

When AUTHKEY_TOKEN authentication succeeds

Color mode

$ 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

code block. Example execution when AUTHKEY_TOKEN authentication succeeds

When AUTHKEY_TOKEN authentication succeeds but there is no permission

Color mode

$ 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

Code block. Execution example when AUTHKEY_TOKEN authentication succeeds but lacks permission.

Reference

When AUTHKEY_TOKEN authentication succeeds but the user lacks permission, it indicates that the authentication process completed successfully, yet the authority to perform the requested operation was not granted (authorized). For detailed information about authorization, refer to Authentication and Authorization.

Kubernetes Engine Usage Guide

Authentication and Authorization