Oracle Cloud Infrastructure Documentation

Downloading a kubeconfig File to Enable Cluster Access

When you create a cluster, you need to download a Kubernetes configuration file (commonly known as a 'kubeconfig' file) for the cluster. The kubeconfig file (by default named config and stored in the $HOME/.kube directory) provides the necessary details to access the cluster using kubectl and the Kubernetes Dashboard.

You have to follow a number of steps to download the kubeconfig file. Having completed the steps, you can start using kubectl and the Kubernetes Dashboard to manage the cluster.

To download the kubeconfig file:

Step 1: Generate an API signing key pair
Step 2: Upload the public key of the API signing key pair
Step 3: Install and configure the Oracle Cloud Infrastructure CLI
Step 4: Download the kubeconfig file
Step 5: Verify that kubectl is available

Notes about kubeconfig Files

Note the following about kubeconfig files:

  • A single kubeconfig file can include the details for multiple clusters, as multiple contexts. The cluster on which operations will be performed is specified by the current-context: element in the kubeconfig file.
  • A kubeconfig file includes an Oracle Cloud Infrastructure CLI command that dynamically generates an authentication token and inserts it when you run a kubectl command. The Oracle Cloud Infrastructure CLI must be available on your shell's executable path (for example, $PATH on Linux).
  • The tokens generated by the Oracle Cloud Infrastructure CLI command in the kubeconfig file are short-lived, cluster-scoped, and specific to individual users. As a result, you cannot share kubeconfig files between users to access Kubernetes clusters.
  • The Oracle Cloud Infrastructure CLI command in the kubeconfig file uses your current CLI profile when generating an authentication token. If you have defined multiple profiles in different tenancies in the CLI configuration file (for example, in ~/.oci/config), specify which profile to use when generating the authentication token as follows. In both cases, <profile-name> is the name of the profile defined in the CLI configuration file:

    • Add --profile to the args: section of the kubeconfig file as follows:

      user:
        exec:
          apiVersion: client.authentication.k8s.io/v1beta1
          args:
          - ce
          - cluster
          - generate-token
          - --cluster-id
          - <cluster ocid>
          - --profile
          - <profile-name>
          command: oci
          env: []
    • Set the OCI_CLI_PROFILE environment variable to the name of the profile defined in the CLI configuration file before running kubectl commands. For example:

      $ export OCI_CLI_PROFILE=<profile-name>
      $ kubectl get nodes
      

Upgrading kubeconfig files from Version 1.0.0 to Version 2.0.0

Container Engine for Kubernetes currently supports two versions of kubeconfig file:
  • version 1.0.0
  • version 2.0.0

Enhancements in kubeconfig version 2.0.0 files provide security improvements for your Kubernetes environment, including short-lived cluster-scoped tokens with automated refreshing, and support for instance principals to access Kubernetes clusters. Additionally, authentication tokens are generated on-demand for each cluster, so kubeconfig version 2.0.0 files cannot be shared between users to access Kubernetes clusters (unlike kubeconfig version 1.0.0 files).

Note that support for kubeconfig version 1.0.0 files will be discontinued on November 15, 2019. Prior to that date, you must upgrade any kubeconfig version 1.0.0 files to version 2.0.0. Follow the instructions below to determine the current version of kubeconfig files, and how to upgrade them to version 2.0.0.

Determine the kubeconfig file version

To determine the version of a cluster's kubeconfig file:

1. In a terminal window, enter the following command to see the format of the kubeconfig file currently pointed at by the KUBECONFIG environment variable:

$ kubectl config view

2. If the kubeconfig file is version 1.0.0, you see a response in the following format:

users:
- name: <username>
  user:
    token: <token-value>

If you see a response in the above format, you have to upgrade the kubeconfig file. See Upgrade a kubeconfig version 1.0.0 file to version 2.0.0.

3. If the kubeconfig file is version 2.0.0, you see a response in the following format:

user:
  exec:
    apiVersion: client.authentication.k8s.io/v1beta1
    args:
    - ce
    - cluster
    - generate-token
    - --cluster-id
    - <cluster ocid>
    command: oci
    env: []

If you see a response in the above format, no further action is required.

Upgrade a kubeconfig version 1.0.0 file to version 2.0.0

To upgrade a kubeconfig version 1.0.0 file:

  1. Confirm the Oracle Cloud Infrastructure CLI version 2.6.4 (or later) is installed by entering:

    oci -version
  2. If the Oracle Cloud Infrastructure CLI version is earlier than version 2.6.4, upgrade the CLI to a later version. See Upgrading the CLI.

  3. Follow the instructions to download the kubeconfig file (see Step 4: Download the kubeconfig file). Running the oci ce cluster create-kubeconfig command shown in the How to Access Kubeconfig dialog box upgrades the existing kubeconfig version 1.0.0 file. If you change the name or location of the kubeconfig file, set the KUBECONFIG environment variable to point to the new name and location of the file.

  4. Confirm the kubeconfig file is now version 2.0.0:
    1. In a terminal window, enter:

      $ kubectl config view
    2. Confirm that that the response is in the following format:

      user:
        exec:
          apiVersion: client.authentication.k8s.io/v1beta1
          args:
          - ce
          - cluster
          - generate-token
          - --cluster-id
          - <cluster ocid>
          command: oci
          env: []