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:

Request sample
$ 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.

Request sample
$ 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.

  1. 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.

  2. 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:

Request sample
$ 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:

Request sample
$ oks-cli cluster kubeconfig \
    --project-name NAME_OF_PROJECT \
    --cluster-name NAME_OF_CLUSTER \
    --print-path \
    --refresh
Response sample
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:

Request sample
$ 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:

Request sample
$ 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.
Result sample
+---------+---------+---------------------+
|   user  |  group  |   expiration date   |
+---------+---------+---------------------+
| default | default | 2025-01-01 01:01:10 |
+---------+---------+---------------------+

Clearing the Cache

You can clear the cache at any time using the cache clear command.

Using this command will clear the cache for all of your projects and clusters. This action cannot be undone.
Request sample
$ oks-cli cache clear

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.

Response sample
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.

Response sample
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

Export to PDF