# Connect with kubectl

Add a cluster to your kubeconfig so kubectl signs in with your {{product}} identity, with no secret stored.

Replace _my-cluster_ with your cluster's name or id.

## Prerequisites

- Permission for `eks:DescribeCluster` on the cluster (to read its endpoint and CA) and
  `eks:AccessKubernetesApi` on it (for every token).
- An access entry on the cluster for you, a group you are in, or the role you act as. See
  [Give someone access](give-access.md).
- The cluster is `active` (or `updating`). Until the first provisioning step has made the
  cluster's key material, the kubeconfig details answer `409` "The cluster is still being created";
  after that they answer, but the endpoint only responds once the control plane is up.
- The dcloud CLI installed and signed in (`dcloud auth login`), and `kubectl`.

## Add the cluster to your kubeconfig

**Console**
1. Open **Kubernetes**, then open the cluster.
2. On **Overview**, under **Connect with kubectl**, choose **Download kubeconfig**.

The file `my-cluster.kubeconfig.yaml` holds the endpoint and the CA and runs the CLI for every
token, so the CLI must be installed and signed in. The button works once the cluster is `active` or
`updating`.

**CLI**
1. Run `dcloud eks update-kubeconfig --cluster my-cluster`.
2. Check the connection:

   ```sh
   kubectl get nodes
   ```

`update-kubeconfig` adds the context `dcloud-my-cluster` and switches to it (`--alias` names the
context, `--kubeconfig` the file). Without `kubectl` installed, it writes a self-contained file in
`~/.kube/` and prints its path.

**API**
```http
GET /eks/api/clusters/my-cluster/kubeconfig
```

The answer has `server` and `certificateAuthorityData`. A token for the cluster:

```http
POST /eks/api/clusters/my-cluster/token
```

It answers an `ExecCredential`, the shape kubectl's exec plugin expects.

## Result

kubectl asks the CLI for a token on each call (`dcloud eks get-token`). A token is valid for ten
minutes and only for that cluster. Inside the cluster you are `ews:<your IAM user name>` (or
`ews:<username>` when your access entry sets a username), in the groups of your access policies;
see [Cluster access](cluster-access.md).

When the public endpoint is off, `server` is the endpoint's address in the network, so kubectl
must run on a machine in the cluster's network.

## Refusals

- `403` "You have no access entry on _my-cluster_. Ask someone with eks:CreateAccessEntry to add
  one."
- `403` without `eks:AccessKubernetesApi` on the cluster.

## Related

- [Cluster access](cluster-access.md)
- [Use break-glass credentials](use-break-glass-credentials.md)
- `eks.clusters.kubeconfig` · `eks.clusters.token`
