How to Connect to a DigitalOcean Kubernetes Cluster

DigitalOcean Kubernetes (DOKS) is a managed Kubernetes service. Deploy Kubernetes clusters with a fully managed control plane, high availability, autoscaling, and native integration with DigitalOcean Load Balancers and volumes. DOKS clusters are compatible with standard Kubernetes toolchains and the DigitalOcean API and CLI.


DigitalOcean Kubernetes clusters are typically managed from a local machine or sometimes from a remote management server. In either case, the management machine needs two things:

  1. kubectl, the official Kubernetes command-line tool, to connect to and interact with the cluster.

    The Kubernetes project provides installation instructions for kubectl on a variety of platforms. Use kubectl version to verify that your installation is working and within one minor version of your cluster.

  2. doctl, the official DigitalOcean command-line tool, to manage config files and set context.

    The doctl GitHub repo has instructions for installing doctl.

Get an Authentication Token or Certificate

After creating a cluster, you need to add an authentication token or certificate to your kubectl configuration file to connect.

Version requirements for obtaining tokens

When connecting to these Kubernetes versions, generating credentials creates a revocable OAuth token. (If using doctl, as recommended, you must also have version 1.32.2 or higher installed to obtain an OAuth token.)

  • Any release of Kubernetes after version 1.16.
  • Kubernetes version 1.15.3-do.3 or higher
  • Kubernetes version 1.14.6-do.3 or higher
  • Kubernetes version 1.13.10-do.3 or higher

If you are not running these versions of Kubernetes, or are using a legacy version of doctl, you will be granted a certificate instead.

Generate Using doctl (Recommended)

To configure authentication from the command line, use the following command, substituting the name of your cluster.

    
        
            
doctl kubernetes cluster kubeconfig save use_your_cluster_name

        
    

This downloads the kubeconfig for the cluster, merges it with any existing configuration from ~/.kube/config, and automatically handles the authentication token or certificate.

Under the hood, this automatically generates a revocable OAuth token when using recent versions of Kubernetes and doctl, and automatically renews a certificate with legacy versions:

  • Revocable OAuth token. If you meet the version requirements listed above, you’ll obtain an OAuth token. You can view and revoke this token in the Applications & API section of the control panel.

  • Automatic certificate renewal. With legacy versions of doctl or Kubernetes, this creates a certificate that is valid for seven days, renews automatically, and cannot be revoked.

    You can upgrade Kubernetes clusters to newer patch versions and minor versions to use tokens instead.

Download from the Control Panel

There is also a cluster configuration file you can download manually from the control panel.

Click the name of the cluster to go to its Overview tab. In the Configuration section, click Download Config File to download its kubeconfig file. The file is named <clustername>-kubeconfig.yaml. Put this file in your ~/.kube directory, and pass it to kubectl with the --kubeconfig flag. For example:

kubectl --kubeconfig=~/.kube/<clustername>-kubeconfig.yaml get nodes

This generates a revocable OAuth token when using recent versions of Kubernetes and generates a certificate for legacy versions:

  • Revocable OAuth token. If you meet the version requirements listed above, you’ll obtain an OAuth token. You can view and revoke this token in the Applications & API section of the control panel.

  • Expiring certificate. With legacy versions of Kubernetes, this creates a certificate that is valid for 7 days that cannot be revoked. Download the file again every 7 days to retain access to the cluster.

    You can upgrade Kubernetes clusters to newer patch versions and minor versions to use tokens instead.

Connect to the Cluster

Once the cluster configuration file is in place, you can create, manage, and deploy clusters using kubectl. See the official kubectl documentation to learn more about its commands and options.

From here, you can also add DigitalOcean Load Balancers and add volumes to your cluster.

Contexts

In Kubernetes, a context is used to group access parameters under a convenient name. The configuration for every cluster will contain a stanza for contexts with cluster-specific values which look like this:

    
        
            
contexts:
- context:
    cluster: do-sfo2-example-cluster-01
    user: do-sfo2-example-cluster-01-admin
  name: do-sfo2-example-cluster-01
current-context: do-sfo2-example-cluster-01

        
    

When you use kubectl, the commands you run affect the default context unless you specify a different one with the --context flag (for example, kubectl get nodes --context=do-nyc1-stage).

To check the current default context, use:

    
        
            
kubectl config current-context

        
    

If you get a current-context is not set error, you need to set a default context.

To list all available contexts, use:

    
        
            
kubectl config get-contexts

        
    

The terminal returns output that looks like this:

    
        
            
CURRENT   NAME                         CLUSTER                      AUTHINFO                         NAMESPACE
*         do-sfo2-example-cluster-01   do-sfo2-example-cluster-01   do-sfo2-example-cluster-01-admin

        
    

The default context is specified with an asterisk under “CURRENT”. To set the default context to a different one, use:

    
        
            
kubectl config use-context do-sfo2-example-cluster-01

        
    

Namespaces

In Kubernetes, namespaces are a way to divide cluster resources between multiple users. They’re useful when you have many users working on the same cluster. You can create multiple namespaces in a cluster, and resources in one namespace are hidden from other namespaces.

Learn more in the Kubernetes namespaces walk-through.