From 85101c0c7a053832537695d4b7776f7f54680662 Mon Sep 17 00:00:00 2001 From: Carrano Date: Wed, 14 May 2025 16:50:40 +0200 Subject: [PATCH] Cherry-picked changes to EKS kubectl connection guides from 3c75f10 --- ...onnect-to-your-eks-cluster-with-kubectl.md | 86 +++++++++---------- ...ct-to-your-eks-cluster-with-kubectl.md.erb | 82 ++++++++---------- 2 files changed, 78 insertions(+), 90 deletions(-) diff --git a/website/guides/tutorial/how-to-connect-to-your-eks-cluster-with-kubectl.md b/website/guides/tutorial/how-to-connect-to-your-eks-cluster-with-kubectl.md index 1e4f51172f..1813bb0dab 100644 --- a/website/guides/tutorial/how-to-connect-to-your-eks-cluster-with-kubectl.md +++ b/website/guides/tutorial/how-to-connect-to-your-eks-cluster-with-kubectl.md @@ -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 --- @@ -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. -* 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 @@ -41,6 +40,17 @@ This tutorial will show you how to access a Qovery managed cluster on AWS with ` +## 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/) + +
  1. @@ -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** @@ -66,20 +77,7 @@ The Qovery CLI is required to get the kubeconfig file of your cluster:
  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](/docs/using-qovery/configuration/cluster-advanced-settings/#awsiamenable_sso)) - -

    - AWS console - add admin user -

    -
    3. - -
  3. - -#### 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: @@ -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`. - - -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. - - -
  4. #### 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= @@ -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`. @@ -175,16 +167,12 @@ In your URL bar you'll have something like: `https://console.qovery.com/platform/organization//projects//environments//applications` -

    - Qovery console - environment -

    - -The environment namespace is defined the following way: `z-z`. +The environment namespace is defined the following way: `z-`. 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//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//projects/e0aabc0d-99cb-4867-ad39-332d6162c32c/environments/b91d2eb8-a850-49b5-8626-ade7afc4a28b/applications` +would translate to the following namespace: `zb91d2eb8-production-site`.
  5. @@ -200,9 +188,9 @@ kubectl get pods --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. @@ -211,17 +199,23 @@ You'll get an URL looking like this: `https://console.qovery.com/platform/organization//projects//environments//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`.
  6. #### Shell into the container + + +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. + + + + To get a shell access to the container running inside the application pod, all you have to do is: ```bash @@ -243,4 +237,4 @@ Qovery helps you manage your Kubernetes cluster and deploy your applications on - +[docs.using-qovery.interface.cli#shell]: /docs/using-qovery/interface/cli/#shell diff --git a/website/guides/tutorial/how-to-connect-to-your-eks-cluster-with-kubectl.md.erb b/website/guides/tutorial/how-to-connect-to-your-eks-cluster-with-kubectl.md.erb index 0f7e538626..65bab06677 100644 --- a/website/guides/tutorial/how-to-connect-to-your-eks-cluster-with-kubectl.md.erb +++ b/website/guides/tutorial/how-to-connect-to-your-eks-cluster-with-kubectl.md.erb @@ -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. -* 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 @@ -29,6 +28,17 @@ This tutorial will show you how to access a Qovery managed cluster on AWS with ` +## 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/) + +
    1. @@ -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** @@ -54,20 +65,7 @@ The Qovery CLI is required to get the kubeconfig file of your cluster:
    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](/docs/using-qovery/configuration/cluster-advanced-settings/#awsiamenable_sso)) - -

      - AWS console - add admin user -

      -
      3. - -
    3. - -#### 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: @@ -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`. - - -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. - - -
    4. #### 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= @@ -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`. @@ -163,16 +155,12 @@ In your URL bar you'll have something like: `https://console.qovery.com/platform/organization//projects//environments//applications` -

      - Qovery console - environment -

      - -The environment namespace is defined the following way: `z-z`. +The environment namespace is defined the following way: `z-`. 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//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//projects/e0aabc0d-99cb-4867-ad39-332d6162c32c/environments/b91d2eb8-a850-49b5-8626-ade7afc4a28b/applications` +would translate to the following namespace: `zb91d2eb8-production-site`.
    5. @@ -188,9 +176,9 @@ kubectl get pods --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. @@ -199,17 +187,23 @@ You'll get an URL looking like this: `https://console.qovery.com/platform/organization//projects//environments//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`.
    6. #### Shell into the container + + +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. + + + + To get a shell access to the container running inside the application pod, all you have to do is: ```bash