diff options
Diffstat (limited to 'doc/user/project/clusters/add_eks_clusters.md')
| -rw-r--r-- | doc/user/project/clusters/add_eks_clusters.md | 147 |
1 files changed, 39 insertions, 108 deletions
diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 712f8ea0adc..b11483a7446 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -51,7 +51,7 @@ Generate an access key for the IAM user, and configure GitLab with the credentia ## New EKS cluster -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22392) in GitLab 12.5. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. To create and add a new Kubernetes cluster to your project, group, or instance: @@ -147,7 +147,7 @@ To create and add a new Kubernetes cluster to your project, group, or instance: - **VPC** - Select a [VPC](https://docs.aws.amazon.com/vpc/latest/userguide/what-is-amazon-vpc.html) to use for your EKS Cluster resources. - **Subnets** - Choose the [subnets](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Subnets.html) - in your VPC where your worker nodes will run. + in your VPC where your worker nodes will run. You must select at least two. - **Security group** - Choose the [security group](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html) to apply to the EKS-managed Elastic Network Interfaces that are created in your worker node subnets. - **Instance type** - The [instance type](https://aws.amazon.com/ec2/instance-types/) of your worker nodes. @@ -164,114 +164,45 @@ You will need to add your AWS external ID to the [IAM Role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount) to manage your cluster using `kubectl`. +### Troubleshooting creating a new cluster + +The following errors are commonly encountered when creating a new cluster. + +#### Error: Request failed with status code 422 + +When submitting the initial authentication form, GitLab returns a status code 422 +error when it can't determine the role you've provided. Make sure you've +correctly configured your role with the **Account ID** and **External ID** +provided by GitLab. In GitLab, make sure to enter the correct **Role ARN**. + +#### Could not load Security Groups for this VPC + +When populating options in the configuration form, GitLab returns this error +because GitLab has successfully assumed your provided role, but the role has +insufficient permissions to retrieve the resources needed for the form. Make sure +you've assigned the role the correct permissions. + +#### `ROLLBACK_FAILED` during cluster creation + +The creation process halted because GitLab encountered an error when creating +one or more resources. You can inspect the associated +[CloudFormation stack](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-view-stack-data-resources.html) +to find the specific resources that failed to create. + +If the `Cluster` resource failed with the error +`The provided role doesn't have the Amazon EKS Managed Policies associated with it.`, +the role specified in **Role name** is not configured correctly. + +NOTE: **Note:** +This role should not be the same as the one created above. If you don't have an +existing +[EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html), +you must create one. + ## Existing EKS cluster -To add an existing EKS cluster to your project, group, or instance: - -1. Perform the following steps on the EKS cluster: - 1. Retrieve the certificate. A valid Kubernetes certificate is needed to authenticate to the - EKS cluster. We will use the certificate created by default. - Open a shell and use `kubectl` to retrieve it: - - 1. List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - 1. Get the certificate with: - - ```shell - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - - 1. Create admin token. A `cluster-admin` token is required to install and manage Helm Tiller. - GitLab establishes mutual SSL authentication with Helm Tiller and creates limited service - accounts for each application. To create the token we will create an admin service account as - follows: - - 1. Create a file called `eks-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: eks-admin - namespace: kube-system - ``` - - 1. Apply the service account to your cluster: - - ```shell - $ kubectl apply -f eks-admin-service-account.yaml - serviceaccount "eks-admin" created - ``` - - 1. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: - - ```yaml - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: eks-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: eks-admin - namespace: kube-system - ``` - - 1. Apply the cluster role binding to your cluster: - - ```shell - $ kubectl apply -f eks-admin-cluster-role-binding.yaml - clusterrolebinding "eks-admin" created - ``` - - 1. Retrieve the token for the `eks-admin` service account: - - ```shell - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: eks-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=eks-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - - 1. Locate the API server endpoint so GitLab can connect to the cluster. This is displayed on - the AWS EKS console, when viewing the EKS cluster details. -1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. -1. Click **Add Kubernetes cluster**. -1. Click the **Add existing cluster** tab and fill in the details: - - **Kubernetes cluster name**: A name for the cluster to identify it within GitLab. - - **Environment scope**: Leave this as `*` for now, since we are only connecting a single cluster. - - **API URL**: The API server endpoint retrieved earlier. - - **CA Certificate**: The certificate data from the earlier step, as-is. - - **Service Token**: The admin token value. - - For project-level clusters, **Project namespace prefix**: This can be left blank to accept the - default namespace, based on the project name. -1. Click on **Add Kubernetes cluster**. The cluster is now connected to GitLab. - -At this point, [Kubernetes deployment variables](index.md#deployment-variables) will -automatically be available during CI/CD jobs, making it easy to interact with the cluster. - -If you would like to utilize your own CI/CD scripts to deploy to the cluster, you can stop here. +For information on adding an existing EKS cluster, see +[Existing Kubernetes cluster](add_remove_clusters.md#existing-kubernetes-cluster). ### Create a default Storage Class |