Accessing a Cluster
You can access your clusters using the standard kubectl
tool, or any other console or GUI tool compatible with it.
Accessing a Cluster Using OKS CLI
Before you begin: Install OKS CLI and kubectl. For more information, see Installing and Configuring OKS CLI. |
Using kubectl
You can use OKS CLI to execute any kubectl
command directly on your cluster.
To do so, use the cluster kubectl command, followed by your OKS CLI parameters and a kubectl
command.
OKS CLI will connect to the desired cluster, retrieve its configuration file, decrypt it, and launch the requested command:
$ oks-cli cluster kubectl \
--project-name NAME_OF_PROJECT \
--cluster-name NAME_OF_CLUSTER \
get nodes
This command contains the following options that you need to specify:
-
cluster-name
: The name of the cluster, with a maximum length of 40 alphanumeric characters and dashes (-). This name must not start or end with a dash, and it must be unique within the project. -
(optional)
project-name
: The name of the project where the cluster will be created.
Using kubeconfig Files
You can work with cluster authentication certificates using Kubernetes configuration files, also called kubeconfig files. OKS CLI downloads and caches locally the kubeconfig files of your clusters.
Getting kubeconfig Files
The cluster kubeconfig command prints the current kubeconfig file.
$ oks-cli cluster kubeconfig \
--project-name NAME_OF_PROJECT \
--cluster-name NAME_OF_CLUSTER
This command contains the following options that you need to specify:
-
cluster-name
: The name of the cluster, with a maximum length of 40 alphanumeric characters and dashes (-). This name must not start or end with a dash, and it must be unique within the project. -
(optional)
project-name
: The name of the project where the cluster will be created.
Setting the KUBECONFIG Environment Variable
To allow kubectl to authenticate and configure the cluster, you need to export the path to the kubeconfig file as an environment variable.
-
Find the path to the kubeconfig file for your cluster.
Request sample$ oks-cli cluster kubeconfig \ --project-name NAME_OF_PROJECT \ --cluster-name NAME_OF_CLUSTER \ --print-path
The file path is returned in the response.
-
Insert the file path in the export KUBECONFIG= command to set the environment variable.
Request sample$ export KUBECONFIG='PATH/TO/FILE'
Modifying kubeconfig Files
Configuring a Certificate TTL
The default certificate validity period is 7 days. You can modify this validity period by specifying a different Time To Live (TTL). To do so, use the following synthax:
$ oks-cli cluster kubeconfig \
--project-name NAME_OF_PROJECT \
--cluster-name NAME_OF_CLUSTER \
--print-path \
--ttl 2h
Refreshing a Certificate
You can replace a certificate by refreshing it, which will download a newly generated certificate to the same location in your local cache.
To refresh your certificate, add the --refresh
option to a cluster kubeconfig command following this syntax:
$ oks-cli cluster kubeconfig \
--project-name NAME_OF_PROJECT \
--cluster-name NAME_OF_CLUSTER \
--print-path \
--refresh
2025-01-01 15:00:00 WARNING cluster.py:cluster_kubeconfig_command extracting kubeconfig by api
/home/USER/.oks_cli/cache/ee46b46c-c20a-4c56-a791-74e523ec17ae-6f226690-76a0-4bd0-acc3-7ae078a31bf3/default/default/kubeconfig
Working With Kubeconfig File Encryption
OKS uses PyNaCl (Python binding to the Networking and Cryptography library) to encrypt kubeconfig files. For more information about PyNaCl, see the Python Package Index website. The file is encrypted from its generation on the cluster to its reception on your computer. Only you can access your kubeconfig file.
For additional protection, you can generate the encryption key on your local workstation rather than on the API side.
To do so, add the --nacl
option to your command:
$ oks-cli cluster kubeconfig \
--project-name NAME_OF_PROJECT \
--cluster-name NAME_OF_CLUSTER \
--print-path \
--refresh \
--nacl
At reception, the kubeconfig file will be automatically decrypted and stored in the ~/.oks_cli/cache
directory so it can be used to access your cluster.
Your kubeconfig file is only encrypted during the transfer to your computer. Once received, it is stored locally as plaintext, and it is your responsability to store the kubeconfig file in a secure way. |
Working With the Cache
Listing Cached Kubeconfig Files
All requested kubeconfig files are stored locally in the $HOME/.oks_cli/cache/
folder. After downloading and writing the kubeconfig file, OKS CLI applies the 600
umask to it.
To list the kubeconfigs available in your local cache for a cluster, use the cache kubeconfigs command following this syntax:
$ oks-cli cache kubeconfigs \
--project-name NAME_OF_PROJECT \
--cluster-name NAME_OF_CLUSTER
The RoleBinding cannot be returned in the response, as this information is not available locally and may be edited in the cluster at any time. |
+---------+---------+---------------------+
| user | group | expiration date |
+---------+---------+---------------------+
| default | default | 2025-01-01 01:01:10 |
+---------+---------+---------------------+
Processing Kubeconfig Retrieval Warnings
Some warnings may appear during the kubeconfig retrieval process. You can dismiss the following warnings using the 2>/dev/null command on Linux and MacOS, and the 2>$null command on Windows.
2025-01-01 10:00:00 WARNING utils.py:get_cache cache item ee46b46c-c20a kubeconfig not found
The kubeconfig not found
warning message indicates that the kubeconfig file for the cluster was not found in local cache, which is the expected behavior for newly created clusters.
2025-01-01 10:00:00 WARNING cluster.py:cluster_kubeconfig_command extracting kubeconfig by api
The extracting kubeconfig by api warning message indicates that OKS CLI is requesting the file from OKS.
Related Pages