# How to Connect to a DigitalOcean Kubernetes Cluster DigitalOcean Kubernetes (DOKS) is a Kubernetes service with a fully managed control plane, high availability, and autoscaling. DOKS integrates with standard Kubernetes toolchains and DigitalOcean’s load balancers, volumes, CPU and GPU Droplets, 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`](https://kubernetes.io/docs/reference/kubectl/overview/), the official Kubernetes command-line tool, to connect to and interact with the cluster. The Kubernetes project provides [installation instructions for `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) on a variety of platforms. Use `kubectl version` to verify that your installation is working and [within one minor version of your cluster](https://kubernetes.io/docs/tasks/tools/install-kubectl/#before-you-begin). 2. `doctl`, the official DigitalOcean command-line tool, to manage config files and set context. The [`doctl` GitHub repo](https://github.com/digitalocean/doctl) 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. ```shell 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](#version-requirements-for-obtaining-tokens), you’ll obtain an OAuth token. You can view and revoke this token in the [**Applications & API** section](https://cloud.digitalocean.com/account/api/tokens) 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](https://docs.digitalocean.com/products/kubernetes/how-to/upgrade-cluster/index.html.md) 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](https://cloud.digitalocean.com). 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 `-kubeconfig.yaml`. Put this file in your `~/.kube` directory, and pass it to `kubectl` with the `--kubeconfig` flag. For example: ```shell kubectl --kubeconfig=~/.kube/-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](#version-requirements-for-obtaining-tokens), you’ll obtain an OAuth token. You can view and revoke this token in the [**Applications & API** section](https://cloud.digitalocean.com/account/api/tokens) 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](https://docs.digitalocean.com/products/kubernetes/how-to/upgrade-cluster/index.html.md) 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](https://kubernetes.io/docs/reference/kubectl/overview/) to learn more about its commands and options. From here, you can also [add DigitalOcean Load Balancers](https://docs.digitalocean.com/products/kubernetes/how-to/add-load-balancers/index.html.md) and [add volumes](https://docs.digitalocean.com/products/kubernetes/how-to/add-volumes/index.html.md) to your cluster. ### Contexts In Kubernetes, a [context](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#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: Example context configuration stanza ```yaml 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: ```shell 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: ```shell 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: ```shell kubectl config use-context do-sfo2-example-cluster-01 ``` ### Namespaces In Kubernetes, [namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/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](https://kubernetes.io/docs/tasks/administer-cluster/namespaces-walkthrough/).