Managing an Oracle Container Engine for Kubernetes (OKE) cluster requires a correctly configured command-line client. The primary tool for this purpose is kubectl — the Kubernetes command-line interface. Before kubectl can issue commands against a specific cluster, it must know how to locate and authenticate to that cluster. This is accomplished through a configuration file known as the kubeconfig file.

This guide covers the kubeconfig file in detail, authentication mechanisms including multi-factor authentication (MFA) and service account tokens, and the end-to-end setup process for both Cloud Shell and local terminal access.

2.  kubectl — The Kubernetes CLI

kubectl is the primary command-line tool for interacting with a Kubernetes cluster. On OKE, operators have two options for where to run kubectl:

•       Cloud Shell: A browser-based terminal available directly in the OCI Console. kubectl is pre-installed and requires no local setup.

•       Local Terminal: kubectl installed on a developer or administrator’s machine, connecting to the cluster over the network.

Tip Both options are fully supported. Cloud Shell is the faster path to getting started since kubectl and the OCI CLI come pre-configured. Local terminal access provides more flexibility for automation, scripting, and integration with local development toolchains.

3.  Understanding the kubeconfig File

The kubeconfig file is the configuration file that kubectl reads to determine which cluster to connect to and how to authenticate. By default, this file is named config and is stored at:

~/.kube/config

3.1  File Structure

A kubeconfig file is organized into three primary sections — clusters, users, and contexts — along with a current-context pointer that tells kubectl which context is active:

Figure 1 — kubeconfig File: Key Fields & Purposes

kubeconfig Field	Purpose
clusters	List of cluster definitions (server URL, CA certificate).
users	List of user credentials / auth mechanisms.
contexts	Named mappings pairing a cluster with a user.
current-context	The active context kubectl acts against.
OCI CLI command	Dynamically generates a short-lived auth token at runtime.

3.2  Multiple Clusters & Contexts

A single kubeconfig file can hold configuration for multiple clusters, each represented as a named context. Switching between clusters is as simple as changing the current-context value. This makes the kubeconfig file a powerful tool for operators who manage multiple OKE clusters across different environments or tenancies.

3.3  Dynamic Authentication Token Generation

OKE’s kubeconfig file includes an embedded OCI CLI command that runs automatically each time kubectl executes a request. This command dynamically generates a short-lived authentication token and injects it into the request:

Figure 2 — Authentication Token Lifecycle

kubectl command issued

→

OCI CLI command runs in kubeconfig

→

Short-lived token generated

→

Token injected & request authenticated

Important — Tokens Are Not Shareable Authentication tokens generated by the OCI CLI command are short-lived, cluster-specific, and tied to the individual user’s OCI credentials. kubeconfig files must not be shared between users. Each operator must generate and maintain their own kubeconfig file.

4.  Working with Multiple OCI CLI Profiles

If your OCI CLI configuration file defines multiple profiles — for example, to manage access across different tenancies — you can control which profile is used when generating authentication tokens. There are two methods:

4.1  Inline Profile Specification

Modify the kubeconfig file to include the target profile name directly in the OCI CLI command arguments:

–profile <profile-name>

4.2  Environment Variable

Alternatively, set the OCI_CLI_PROFILE environment variable before running any kubectl commands. This avoids modifying the kubeconfig file and is particularly convenient for scripting:

export OCI_CLI_PROFILE=<profile-name>

In both cases, replace <profile-name> with the exact name of the profile as defined in your OCI CLI configuration file.

5.  Multi-Factor Authentication (MFA) Configuration

Some OCI environments enforce IAM policies that require users to have completed multi-factor authentication before accessing cluster resources. Attempting to access such a cluster without MFA verification will result in an Unauthorized error. The kubeconfig file must be updated to accommodate MFA-gated access.

5.1  Required kubeconfig Modifications

Add the following arguments to the args section of the OCI CLI command entry in your kubeconfig file:

Figure 3 — kubeconfig Arguments Required for MFA Access

kubeconfig Argument	Purpose
–profile <profile-name>	Specifies the OCI CLI profile of the MFA-verified user.
–auth security_token	Instructs the OCI CLI to use the security (MFA) token for authentication.

5.2  Setting the Profile Environment Variable for MFA

As with standard multi-profile usage, you can set the environment variable to point to the MFA-verified user’s profile:

export OCI_CLI_PROFILE=<mfa-verified-profile-name>

Prerequisite Before attempting to connect, ensure that the user account is currently MFA-verified in OCI. An unverified session — even with the correct profile and flags — will result in an Unauthorized response from the cluster.

5.3  CI/CD and Automated Tool Access

The OCI CLI-based authentication token mechanism is designed for human operators using kubectl interactively. For automated processes — such as CI/CD pipelines, deployment tools, or monitoring agents — this approach is not appropriate.

In such cases, create a dedicated Kubernetes service account and embed its long-lived authentication token directly in the kubeconfig file used by the automated toolchain. Service account tokens are not subject to the short-lived token rotation behavior of user-scoped OCI credentials.

6.  Access Methods: Cloud Shell vs. Local Terminal

OKE supports two primary access paths for kubectl. The choice between them depends on network topology (whether the API endpoint has a public IP), tooling preferences, and automation requirements.

Figure 4 — Cloud Shell vs. Local Terminal Access: Comparison

Criterion	Cloud Shell Access	Local Shell Access
kubectl location	Pre-installed in Cloud Shell	Must be installed locally
API Endpoint	Requires public IP on API endpoint	Works with private IP (VCN peering required)
kubeconfig setup	Via OKE Console → Access Cluster dialog	Via OCI CLI command
API Signing Key	Not required (Cloud Shell auto-auth)	Must generate & upload key pair
OCI CLI	Pre-configured	Must install & configure
MFA support	Supported via profile flag	Supported via profile flag
CI/CD tool access	Use Kubernetes service account token	Use Kubernetes service account token

7.  Setting Up Cloud Shell Access

Cloud Shell is the fastest way to get started with OKE cluster management. It requires no local software installation and comes with kubectl and the OCI CLI pre-configured.

7.1  Prerequisites

•       The cluster’s Kubernetes API endpoint must have a public IP address.

•       The user must have sufficient IAM permissions to access the cluster.

7.2  Setup Steps

1.      Navigate to the OKE Console and open the target cluster’s detail page.

2.      Click the Access Cluster button. The Access Your Cluster dialog will appear, displaying the exact kubeconfig setup command for this cluster.

3.      Copy and run the provided command in Cloud Shell. This command invokes the OCI CLI to generate and write the kubeconfig file.

4.      If a kubeconfig file already exists at the target path, the new cluster’s context is appended to it. The current-context is updated to point to the new cluster.

5.      If saving the kubeconfig to a non-default location, set the KUBECONFIG environment variable accordingly:

export KUBECONFIG=<path-to-your-kubeconfig-file>

6.      Verify the connection by running:

kubectl get nodes

Expected Output A successful kubectl get nodes command returns a list of the worker nodes in your cluster, showing their names, status, roles, age, and Kubernetes version. If the command returns an error, verify that the kubeconfig path is correct and that the cluster API endpoint is reachable.

8.  Setting Up Local Terminal Access

Local terminal access is appropriate when the cluster’s API endpoint does not have a public IP address, when operators prefer to work from a local development environment, or when integrating kubectl into local automation workflows. The local machine must be on a network that is peered with the cluster’s VCN.

8.1  Step-by-Step Setup

Follow these steps in sequence to configure local kubectl access:

Figure 5 — Local Terminal Access: Setup Checklist

#	Action	Command / Note
1	Generate API Signing Key Pair	OCI Console → User Settings → API Keys → Add API Key
2	Install OCI CLI	bash -c “$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)”
3	Configure OCI CLI	oci setup config
4	Install kubectl	Match version to control plane K8s version
5	Create .kube directory	mkdir -p $HOME/.kube
6	Generate kubeconfig	oci ce cluster create-kubeconfig –cluster-id <id> –file $HOME/.kube/config
7	Verify kubectl version	kubectl version
8	Verify cluster node access	kubectl get nodes

8.2  kubectl Version Alignment

When installing kubectl locally, it is strongly recommended to use a version that closely matches the Kubernetes version running on the cluster’s control plane nodes. A significant version mismatch between kubectl and the server can cause unexpected behaviour or command failures.

To check both versions simultaneously, run:

kubectl version   # Output includes: #   Client Version: <local kubectl version> #   Server Version: <cluster control plane version>

8.3  Verification Commands

Once setup is complete, run the following two commands to confirm that local access is functioning correctly:

# 1. Verify kubectl is installed and check version alignment kubectl version   # 2. List cluster nodes to confirm authenticated connectivity kubectl get nodes

Troubleshooting If kubectl get nodes returns a connection refused or timeout error, verify: (1) the kubeconfig path is correctly set, (2) the local machine is on a network peered with the cluster VCN, (3) the OCI CLI is correctly configured with a valid API signing key, and (4) the kubeconfig was generated with the correct cluster OCID.

9.  Summary

Configuring kubectl access to an OKE cluster is a multi-step process that centres on the kubeconfig file. This file defines the cluster endpoints, authentication mechanisms, and active context that kubectl uses to route and authenticate requests. Key principles to carry forward:

•       Each user must maintain their own kubeconfig file — tokens are user-specific and short-lived.

•       Cloud Shell is the fastest path to cluster access and requires no local software installation.

•       Local terminal access requires an API signing key, OCI CLI installation, and network connectivity to the cluster VCN.

•       MFA-gated environments require additional arguments in the kubeconfig file and a verified OCI session.

•       Automated tools and CI/CD pipelines should use Kubernetes service account tokens rather than user-scoped OCI credentials.

Bottom Line Whether using Cloud Shell for quick interactive management or a local terminal for deeper integration, the kubeconfig file is the foundation of all kubectl-based cluster access. Invest time upfront in configuring it correctly — including profile, MFA, and version alignment considerations — to ensure reliable, secure cluster operations.