tutorial

How to connect to your EKS cluster with kubectl

How to connect to your EKS cluster using kubectl
type: tutorialinstallation_guide: aws

Qovery makes it easy to create an EKS cluster on your AWS account and manage the deployment of applications on it. But you still might want to execute operations on it via kubectl like you would on any other Kubernetes cluster.

Goal

This tutorial will show you how to access a Qovery managed cluster on AWS with kubectl and shell into a running application container.

  1. Install and configure your toolchain

    kubectl

    To interact with your cluster, you will need kubectl installed. https://kubernetes.io/docs/tasks/tools/

    AWS CLI

    The AWS CLI must be installed and configured on your machine. https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html

    Qovery CLI

    The Qovery CLI is required to get the kubeconfig file of your cluster: https://hub.qovery.com/docs/using-qovery/interface/cli/

  2. IAM user permissions

    Since kubectl will use IAM to authenticate, you need to have one of those things: 1. Add your IAM user (the one the AWS CLI is authenticated with) to the Admins group you created when setting up Qovery 2. Have the permissions to access the EKS cluster via SSO (see cluster advanced settings for it)

    AWS console - add admin user

  3. Download the Kubeconfig file

    To get the kubeconfig file of your cluster, run the following command to list your clusters and get the desired cluster ID:

    $ qovery cluster list
    Id                                   | Name                 | Type    | Status   | Last Update
    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx | Qovery Prod          | cluster | DEPLOYED | 2024-10-11 07:40:33.562523 +0000 UTC

    Then run the following command to get the kubeconfig file (replace with your cluster ID):

    $ qovery cluster kubeconfig --cluster-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    INFO[2024-11-01T11:42:49+01:00] Kubeconfig file created in the current directory. 
    INFO[2024-11-01T11:42:49+01:00] Execute `export KUBECONFIG=/Users/user/kubeconfig-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.yaml` to use it.

    The path of your kubeconfig file will be displayed in the output. You can now use it to set the context for kubectl.

  4. Set the context for kubectl

    To set the context for kubectl, run the following command:

    export KUBECONFIG=<path to the kubeconfig file you downloaded>

    You can check that it works with a kubectl command. For example:

    kubectl get nodes

    You are good to go if you see an output like the following:

    NAME              STATUS   ROLES    AGE   VERSION
    zb81b1cd4-ub667   Ready    <none>   14d   v1.19.15
    zb81b1cd4-ujkm8   Ready    <none>   24d   v1.19.15
    zb81b1cd4-ujkmc   Ready    <none>   24d   v1.19.15

  5. Get your application namespace

    When you deploy an application, Qovery will create a separate namespace for each environment on your Kubernetes cluster.

    You can get the list of the namespaces on your cluster using the following command:

    kubectl get namespaces

    You will get an output similar to this one:

    NAME                  STATUS        AGE
    cert-manager          Active        44d
    default               Active        44d
    kube-node-lease       Active        44d
    kube-public           Active        44d
    kube-system           Active        44d
    logging               Active        44d
    nginx-ingress         Active        44d
    prometheus            Active        44d
    qovery                Active        44d
    z0121531e-zb2daee81   Active        35d
    z016bd165-zeb51c37e   Active        31d

    The Qovery application namespaces are the ones begining with z.

    In case you have several environments running, to identify the right one:

    • Go to the Qovery console
    • Go to the right environment

    In your URL bar you'll have something like:

    https://console.qovery.com/platform/organization/<organisation id>/projects/<project id>/environments/<environment id>/applications

    Qovery console - environment

    The environment namespace is defined the following way: z<project short ID>-z<environment short ID>.

    The short ID is the first section of the ID. For example, given the following ID: e0aabc0d-99cb-4867-ad39-332d6162c32c, the short ID will be e0aabc0d.

    The following environment URL: https://console.qovery.com/platform/organization/<organisation ID>/projects/e0aabc0d-99cb-4867-ad39-332d6162c32c/environments/b91d2eb8-a850-49b5-8626-ade7afc4a28b/applications would translate to the following namespace: ze0aabc0d-zb91d2eb8.

  6. Identify the right application pod(s)

    To list the pods running in your environment namespace, run the following command:

    kubectl get pods --namespace <your namespace>

    The output should be similar to this one:

    NAME                             READY   STATUS    RESTARTS   AGE
    app-z2fc29b74-5db6745975-nrw8v   1/1     Running   0          29h
    app-zabbcf976-74f969f848-kzp87   1/1     Running   0          29h

    The same principle goes for finding the right application pod. Go to the application page on the Qovery console.

    You'll get an URL looking like this:

    https://console.qovery.com/platform/organization/<organisation ID>/projects/<project ID>/environments/<environment ID>/applications/abbcf976-27a1-4531-9cdd-e4d15d7b2c27/summary

    Get the short ID of our application, in our case abbcf976 which means the application pod name will start with app-zabbcf976.

    In case you setup your app to run multiple replicas, it is possible that you see several pods begining with the same string. You can pick any of them.

    In our case the right pod corresponding to our application would be app-zabbcf976-74f969f848-kzp87.

  7. Shell into the container

    To get a shell access to the container running inside the application pod, all you have to do is:

    kubectl exec -ti --namespace <your namespace> <your pod name> -- sh

    This will open a shell inside of your application container. You can now execute any command you need.

Conclusion

Qovery helps you manage your Kubernetes cluster and deploy your applications on it while still giving you the power of a full access to your cluster.