Skip to content

Cherry-picked changes to EKS kubectl connection guides from 3c75f10 #557

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Cherry-picked changes to EKS kubectl connection guides from 3c75f10 #557

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 40 additions & 46 deletions website/guides/tutorial/how-to-connect-to-your-eks-cluster-with-kubectl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
last_modified_on: "2024-11-01"
last_modified_on: "2025-03-13"
$schema: "/.meta/.schemas/guides.json"
title: How to connect to your EKS cluster with kubectl
description: How to connect to your EKS cluster using kubectl
title: How to connect to your Qovery managed cluster with kubectl
description: How to connect to your Qovery managed cluster with kubectl
author_github: https://github.com/l0ck3
tags: ["type: tutorial", "installation_guide: aws"]
tags: ["type: tutorial", "installation_guide: kubernetes"]
hide_pagination: true
---

Expand All @@ -14,12 +14,11 @@ import Alert from '@site/src/components/Alert';
import Assumptions from '@site/src/components/Assumptions';
import Jump from '@site/src/components/Jump';

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.
Qovery makes it easy to create a managed cluster on your cloud account (AWS, GCP etc..) 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.

<Assumptions name="guide">

* You have an existing EKS cluster manages by Qovery
* You have deployed an application on this cluster with Qovery
* You have an existing EKS/GKE/Kapsule cluster manages by Qovery

</Assumptions>

Expand All @@ -41,6 +40,17 @@ This tutorial will show you how to access a Qovery managed cluster on AWS with `

<Steps headingDepth={3}>

## Important information

In this tutorial, we will use the Kubeconfig and credentials automatically generated by Qovery via the Qovery CLI. To do this, you need to be either an Organization Admin or a Cluster Admin.

If you want to use your own set of credentials to access the Kubernetes cluster, make sure you have the right permissions to access both your cloud account and the Kubernetes cluster.

For example, on AWS, a user doesn't get access to the Kubernetes API by default. To gain access, you have two possibilities:
- EKS access entry: Via the AWS console, you can manually add users to the [EKS access entry](https://docs.aws.amazon.com/eks/latest/userguide/access-entries.html) of the cluster.
- SSO: You can automate the provisioning/deprovisioning of Kubernetes access using the [AWS SSO feature](https://aws.amazon.com/fr/blogs/containers/a-quick-path-to-amazon-eks-single-sign-on-using-aws-sso/)


<ol>

<li>
Expand All @@ -52,10 +62,11 @@ This tutorial will show you how to access a Qovery managed cluster on AWS with `
To interact with your cluster, you will need `kubectl` installed.
[https://kubernetes.io/docs/tasks/tools/](https://kubernetes.io/docs/tasks/tools/)

**AWS CLI**
**Cloud provider CLI**

Depending on your cloud provider, you might need its CLI to authenticate or retrieve the Kubeconfig.

The AWS CLI must be installed and configured on your machine.
[https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
For example, you might need the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) or [GCP CLI](https://cloud.google.com/sdk/docs/install).

**Qovery CLI**

Expand All @@ -66,20 +77,7 @@ The Qovery CLI is required to get the kubeconfig file of your cluster:

<li>

#### 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](/docs/using-qovery/configuration/cluster-advanced-settings/#awsiamenable_sso))

<p align="center">
<img src="/img/how-to-connect-to-your-eks-cluster-with-kubectl/1.png" alt="AWS console - add admin user" />
</p>
</li>

<li>

#### Download the Kubeconfig file
#### Retrieve Kubeconfig and credentials

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

Expand All @@ -99,19 +97,13 @@ INFO[2024-11-01T11:42:49+01:00] Execute `export KUBECONFIG=/Users/user/kubeconfi

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

<Alert type="warning">

On AWS you'll need to have the `AWS_PROFILE` environment variable set to the right profile to be able to download the kubeconfig file or AWS credentials set as environment variables.

</Alert>

</li>

<li>

#### Set the context for kubectl

To set the context for kubectl, run the following command:
Following the output of the previous command, to set the context for kubectl, run the following command:

```bash
export KUBECONFIG=<path to the kubeconfig file you downloaded>
Expand Down Expand Up @@ -159,8 +151,8 @@ logging Active 44d
nginx-ingress Active 44d
prometheus Active 44d
qovery Active 44d
z0121531e-zb2daee81 Active 35d
z016bd165-zeb51c37e Active 31d
z0121531e-namespac1 Active 35d
z016bd165-namespac2 Active 31d
```

The Qovery application namespaces are the ones begining with `z`.
Expand All @@ -175,16 +167,12 @@ In your URL bar you'll have something like:
`https://console.qovery.com/platform/organization/<organisation id>/projects/<project id>/environments/<environment id>/applications`


<p align="center">
<img src="/img/how-to-connect-to-your-eks-cluster-with-kubectl/3.png" alt="Qovery console - environment" />
</p>

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

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`.
The following environment "production site" with 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: `zb91d2eb8-production-site`.
</li>

<li>
Expand All @@ -200,9 +188,9 @@ kubectl get pods --namespace <your namespace>
The output should be similar to this one:

```bash
NAME READY STATUS RESTARTS AGE
app-z2fc29b74-5db6745975-nrw8v 1/1 Running 0 29h
app-zabbcf976-74f969f848-kzp87 1/1 Running 0 29h
NAME READY STATUS RESTARTS AGE
app-z2fc29b74-backend-5db6745975-nrw8v 1/1 Running 0 29h
app-zabbcf976-frontend-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.
Expand All @@ -211,17 +199,23 @@ 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`.
Get the short ID of our application and its name, in our case `abbcf976` and `backend` which means the application pod name will start with `app-zabbcf976-frontend`. The app might start with "app", "job", "cronjob", "database" depending on its type.

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`.
</li>

<li>

#### Shell into the container

<Alert type="info">

If you don't want to use kubectl, you can directly use the Qovery CLI Shell feature. Check our [documentation here][docs.using-qovery.interface.cli#shell] to know more about it.

</Alert>


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

```bash
Expand All @@ -243,4 +237,4 @@ Qovery helps you manage your Kubernetes cluster and deploy your applications on
</Alert>



[docs.using-qovery.interface.cli#shell]: /docs/using-qovery/interface/cli/#shell
82 changes: 38 additions & 44 deletions website/guides/tutorial/how-to-connect-to-your-eks-cluster-with-kubectl.md.erb
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,20 @@
---
$schema: "/.meta/.schemas/guides.json"
title: How to connect to your EKS cluster with kubectl
description: How to connect to your EKS cluster using kubectl
title: How to connect to your Qovery managed cluster with kubectl
description: How to connect to your Qovery managed cluster with kubectl
author_github: https://github.com/l0ck3
tags: ["type: tutorial", "installation_guide: aws"]
tags: ["type: tutorial", "installation_guide: kubernetes"]
hide_pagination: true
---
import Alert from '@site/src/components/Alert';
import Assumptions from '@site/src/components/Assumptions';
import Jump from '@site/src/components/Jump';

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.
Qovery makes it easy to create a managed cluster on your cloud account (AWS, GCP etc..) 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.

<Assumptions name="guide">

* You have an existing EKS cluster manages by Qovery
* You have deployed an application on this cluster with Qovery
* You have an existing EKS/GKE/Kapsule cluster manages by Qovery

</Assumptions>

Expand All @@ -29,6 +28,17 @@ This tutorial will show you how to access a Qovery managed cluster on AWS with `

<Steps headingDepth={3}>

## Important information

In this tutorial, we will use the Kubeconfig and credentials automatically generated by Qovery via the Qovery CLI. To do this, you need to be either an Organization Admin or a Cluster Admin.

If you want to use your own set of credentials to access the Kubernetes cluster, make sure you have the right permissions to access both your cloud account and the Kubernetes cluster.

For example, on AWS, a user doesn't get access to the Kubernetes API by default. To gain access, you have two possibilities:
- EKS access entry: Via the AWS console, you can manually add users to the [EKS access entry](https://docs.aws.amazon.com/eks/latest/userguide/access-entries.html) of the cluster.
- SSO: You can automate the provisioning/deprovisioning of Kubernetes access using the [AWS SSO feature](https://aws.amazon.com/fr/blogs/containers/a-quick-path-to-amazon-eks-single-sign-on-using-aws-sso/)


<ol>

<li>
Expand All @@ -40,10 +50,11 @@ This tutorial will show you how to access a Qovery managed cluster on AWS with `
To interact with your cluster, you will need `kubectl` installed.
[https://kubernetes.io/docs/tasks/tools/](https://kubernetes.io/docs/tasks/tools/)

**AWS CLI**
**Cloud provider CLI**

Depending on your cloud provider, you might need its CLI to authenticate or retrieve the Kubeconfig.

The AWS CLI must be installed and configured on your machine.
[https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
For example, you might need the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) or [GCP CLI](https://cloud.google.com/sdk/docs/install).

**Qovery CLI**

Expand All @@ -54,20 +65,7 @@ The Qovery CLI is required to get the kubeconfig file of your cluster:

<li>

#### 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](/docs/using-qovery/configuration/cluster-advanced-settings/#awsiamenable_sso))

<p align="center">
<img src="/img/how-to-connect-to-your-eks-cluster-with-kubectl/1.png" alt="AWS console - add admin user" />
</p>
</li>

<li>

#### Download the Kubeconfig file
#### Retrieve Kubeconfig and credentials

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

Expand All @@ -87,19 +85,13 @@ INFO[2024-11-01T11:42:49+01:00] Execute `export KUBECONFIG=/Users/user/kubeconfi

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

<Alert type="warning">

On AWS you'll need to have the `AWS_PROFILE` environment variable set to the right profile to be able to download the kubeconfig file or AWS credentials set as environment variables.

</Alert>

</li>

<li>

#### Set the context for kubectl

To set the context for kubectl, run the following command:
Following the output of the previous command, to set the context for kubectl, run the following command:

```bash
export KUBECONFIG=<path to the kubeconfig file you downloaded>
Expand Down Expand Up @@ -147,8 +139,8 @@ logging Active 44d
nginx-ingress Active 44d
prometheus Active 44d
qovery Active 44d
z0121531e-zb2daee81 Active 35d
z016bd165-zeb51c37e Active 31d
z0121531e-namespac1 Active 35d
z016bd165-namespac2 Active 31d
```

The Qovery application namespaces are the ones begining with `z`.
Expand All @@ -163,16 +155,12 @@ In your URL bar you'll have something like:
`https://console.qovery.com/platform/organization/<organisation id>/projects/<project id>/environments/<environment id>/applications`


<p align="center">
<img src="/img/how-to-connect-to-your-eks-cluster-with-kubectl/3.png" alt="Qovery console - environment" />
</p>

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

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`.
The following environment "production site" with 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: `zb91d2eb8-production-site`.
</li>

<li>
Expand All @@ -188,9 +176,9 @@ kubectl get pods --namespace <your namespace>
The output should be similar to this one:

```bash
NAME READY STATUS RESTARTS AGE
app-z2fc29b74-5db6745975-nrw8v 1/1 Running 0 29h
app-zabbcf976-74f969f848-kzp87 1/1 Running 0 29h
NAME READY STATUS RESTARTS AGE
app-z2fc29b74-backend-5db6745975-nrw8v 1/1 Running 0 29h
app-zabbcf976-frontend-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.
Expand All @@ -199,17 +187,23 @@ 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`.
Get the short ID of our application and its name, in our case `abbcf976` and `backend` which means the application pod name will start with `app-zabbcf976-frontend`. The app might start with "app", "job", "cronjob", "database" depending on its type.

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`.
</li>

<li>

#### Shell into the container

<Alert type="info">

If you don't want to use kubectl, you can directly use the Qovery CLI Shell feature. Check our [documentation here][docs.using-qovery.interface.cli#shell] to know more about it.

</Alert>


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

```bash
Expand Down