Commit d0a74585 authored by Marcel Amirault's avatar Marcel Amirault

Merge branch 'eread/improve-add-cluster-docs' into 'master'

Improve add cluster documentation

Closes #30575

See merge request gitlab-org/gitlab!21806
parents 6553776f 7e160590
......@@ -11,6 +11,6 @@
'role-arn' => @aws_role.role_arn,
'instance-types' => @instance_types,
'kubernetes-integration-help-path' => help_page_path('user/project/clusters/index'),
'account-and-external-ids-help-path' => help_page_path('user/project/clusters/add_remove_clusters.md', anchor: 'eks-cluster'),
'create-role-arn-help-path' => help_page_path('user/project/clusters/add_remove_clusters.md', anchor: 'eks-cluster'),
'account-and-external-ids-help-path' => help_page_path('user/project/clusters/add_remove_clusters.md', anchor: 'new-eks-cluster'),
'create-role-arn-help-path' => help_page_path('user/project/clusters/add_remove_clusters.md', anchor: 'new-eks-cluster'),
'external-link-icon' => icon('external-link') } }
......@@ -27,6 +27,7 @@ The Admin Area is made up of the following sections:
| Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. |
| Abuse Reports | Manage [abuse reports](abuse_reports.md) submitted by your users. |
| License **(STARTER ONLY)** | Upload, display, and remove [licenses](license.md). |
| Kubernetes | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md). |
| Push Rules **(STARTER)** | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. |
| Geo **(PREMIUM ONLY)** | Configure and maintain [Geo nodes](geo_nodes.md). |
| Deploy Keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). |
......
......@@ -53,8 +53,8 @@ differentiate the new cluster from the rest.
## GitLab-managed clusters
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 11.5.
> Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26565) in GitLab 11.11.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 11.5.
> - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26565) in GitLab 11.11.
You can choose to allow GitLab to manage your cluster for you. If your cluster is
managed by GitLab, resources for your projects will be automatically created. See the
......@@ -170,6 +170,11 @@ For important information about securely configuring GitLab Runners, see
Runners](../../project/clusters/add_remove_clusters.md#security-of-gitlab-runners)
documentation for project-level clusters.
## More information
For information on integrating GitLab and Kubernetes, see
[Kubernetes clusters](../../project/clusters/index.md).
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
......
......@@ -12,11 +12,12 @@ projects.
## Cluster precedence
GitLab will try match to clusters in the following order:
GitLab will try [to match](../../../ci/environments.md#scoping-environments-with-specs) clusters in
the following order:
- Project-level clusters
- Group-level clusters
- Instance level
- Project-level clusters.
- Group-level clusters.
- Instance-level clusters.
To be selected, the cluster must be enabled and
match the [environment selector](../../../ci/environments.md#scoping-environments-with-specs).
......@@ -26,3 +27,8 @@ match the [environment selector](../../../ci/environments.md#scoping-environment
For a consolidated view of which CI [environments](../../../ci/environments.md)
are deployed to the Kubernetes cluster, see the documentation for
[cluster environments](../../clusters/environments.md).
## More information
For information on integrating GitLab and Kubernetes, see
[Kubernetes clusters](../../project/clusters/index.md).
......@@ -10,6 +10,74 @@ Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign
and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's
Google Kubernetes Engine Integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) and apply for credit.
## Before you begin
Before [adding a Kubernetes cluster](#add-new-cluster) using GitLab, you need:
- GitLab itself. Either:
- A GitLab.com [account](https://about.gitlab.com/pricing/#gitlab-com).
- A [self-managed installation](https://about.gitlab.com/pricing/#self-managed) with GitLab version
12.5 or later. This will ensure the GitLab UI can be used for cluster creation.
- The following GitLab access:
- [Maintainer access to a project](../../permissions.md#project-members-permissions) for a
project-level cluster.
- [Maintainer access to a group](../../permissions.md#group-members-permissions) for a
group-level cluster.
- [Admin Area access](../../admin_area/index.md) for a self-managed instance-level
cluster. **(CORE ONLY)**
### GKE requirements
Before creating your first cluster on Google GKE with GitLab's integration, make sure the following
requirements are met:
- A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account)
set up with access.
- The Kubernetes Engine API and related service are enabled. It should work immediately but may
take up to 10 minutes after you create a project. For more information see the
["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin).
### EKS requirements
Before creating your first cluster on Amazon EKS with GitLab's integration, make sure the following
requirements are met:
- An [Amazon Web Services](https://aws.amazon.com/) account is set up and you are able to log in.
- You have permissions to manage IAM resources.
- If you want to use an [existing EKS cluster](#existing-eks-cluster):
- An Amazon EKS cluster with worker nodes properly configured.
- `kubectl` [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl)
for access to the EKS cluster.
#### Additional requirements for self-managed instances **(CORE ONLY)**
If you are using a self-managed GitLab instance, GitLab must first be configured with a set of
Amazon credentials. These credentials will be used to assume an Amazon IAM role provided by the user
creating the cluster. Create an IAM user and ensure it has permissions to assume the role(s) that
your users will use to create EKS clusters.
For example, the following policy document allows assuming a role whose name starts with
`gitlab-eks-` in account `123456789012`:
```json
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::123456789012:role/gitlab-eks-*"
}
}
```
Generate an access key for the IAM user, and configure GitLab with the credentials:
1. Navigate to **Admin Area > Settings > Integrations** and expand the **Amazon EKS** section.
1. Check **Enable Amazon EKS integration**.
1. Enter the account ID and access key credentials into the respective
`Account ID`, `Access key ID` and `Secret access key` fields.
1. Click **Save changes**.
## Access controls
When creating a cluster in GitLab, you will be asked if you would like to create either:
......@@ -116,57 +184,39 @@ New clusters can be added using GitLab for:
- Google Kubernetes Engine.
- Amazon Elastic Kubernetes Service.
### GKE cluster
### New GKE cluster
GitLab supports:
Starting from [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/25925), all the GKE clusters
provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips).
- Creating a new GKE cluster using the GitLab UI.
- Providing credentials to add an [existing Kubernetes cluster](#add-existing-cluster).
#### Important notes
Starting from [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/25925), all the GKE clusters provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips).
NOTE: **Note:**
The [Google authentication integration](../../../integration/google.md) must
be enabled in GitLab at the instance level. If that's not the case, ask your
GitLab administrator to enable it. On GitLab.com, this is enabled.
#### GKE Requirements
Before creating your first cluster on Google Kubernetes Engine with GitLab's
integration, make sure the following requirements are met:
- A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account)
is set up and you have permissions to access it.
- The Kubernetes Engine API and related service are enabled. It should work immediately but may take up to 10 minutes after you create a project. For more information see the
["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin).
Also note the following:
Note the following:
- The [Google authentication integration](../../../integration/google.md) must be enabled in GitLab
at the instance level. If that's not the case, ask your GitLab administrator to enable it. On
GitLab.com, this is enabled.
- Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/issues/55902), all GKE clusters
created by GitLab are RBAC-enabled. Take a look at the [RBAC section](#rbac-cluster-resources) for
more information.
- Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/merge_requests/18341), the
cluster's pod address IP range will be set to /16 instead of the regular /14. /16 is a CIDR
notation.
NOTE: **Note:**
GitLab requires basic authentication enabled and a client certificate issued for the cluster in
order to setup an [initial service account](#access-controls). Starting from [GitLab
11.10](https://gitlab.com/gitlab-org/gitlab-foss/issues/58208), the cluster creation process will
explicitly request that basic authentication and client certificate is enabled.
- GitLab requires basic authentication enabled and a client certificate issued for the cluster to
set up an [initial service account](#access-controls). Starting from [GitLab
11.10](https://gitlab.com/gitlab-org/gitlab-foss/issues/58208), the cluster creation process will
explicitly request that basic authentication and client certificate is enabled.
#### Creating the cluster on GKE
If all of the above requirements are met, you can proceed to create and add a
new Kubernetes cluster to your project:
1. Navigate to your project's **Operations > Kubernetes** page.
NOTE: **Note:**
You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page.
To create and add a new Kubernetes cluster to your project, group, or instance:
1. Navigate to your:
- Project's **Operations > Kubernetes** page, for a project-level cluster.
- Group's **Kubernetes** page, for a group-level cluster.
- **Admin Area > Kubernetes** page, for an instance-level cluster.
1. Click **Add Kubernetes cluster**.
1. Click **Create with Google Kubernetes Engine**.
1. Under the **Create new cluster** tab, click **Google GKE**.
1. Connect your Google account if you haven't done already by clicking the
**Sign in with Google** button.
1. Choose your cluster's settings:
......@@ -198,64 +248,19 @@ separately after the cluster has been created. This means that Cloud Run
(Knative), Istio, and HTTP Load Balancing will be enabled on the cluster at
create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately.
### EKS Cluster
GitLab supports:
- Creating a new EKS cluster using the GitLab UI
([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22392) in GitLab 12.5).
- Providing credentials to add an [existing Kubernetes cluster](#add-existing-cluster).
#### EKS Requirements
Before creating your first cluster on Amazon EKS with GitLab's integration,
make sure the following requirements are met:
- An [Amazon Web Services](https://aws.amazon.com/) account is set up and you are able to log in.
- You have permissions to manage IAM resources.
##### Additional requirements for self-managed instances
If you are using a self-managed GitLab instance, GitLab must first
be configured with a set of Amazon credentials. These credentials
will be used to assume an Amazon IAM role provided by the user
creating the cluster. Create an IAM user and ensure it has permissions
to assume the role(s) that your users will use to create EKS clusters.
For example, the following policy document allows assuming a role whose name starts with
`gitlab-eks-` in account `123456789012`:
```json
{
"Version": "2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::123456789012:role/gitlab-eks-*"
}
}
```
Generate an access key for the IAM user, and configure GitLab with the credentials:
1. Navigate to **Admin Area > Settings > Integrations** and expand the **Amazon EKS** section.
1. Check **Enable Amazon EKS integration**.
1. Enter the account ID and access key credentials into the respective
`Account ID`, `Access key ID` and `Secret access key` fields.
1. Click **Save changes**.
#### Creating the cluster on EKS
### New EKS cluster
If all of the above requirements are met, you can proceed to create and add a
new Kubernetes cluster to your project:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22392) in GitLab 12.5.
1. Navigate to your project's **Operations > Kubernetes** page.
NOTE: **Note:**
You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page.
To create and add a new Kubernetes cluster to your project, group, or instance:
1. Navigate to your:
- Project's **Operations > Kubernetes** page, for a project-level cluster.
- Group's **Kubernetes** page, for a group-level cluster.
- **Admin Area > Kubernetes** page, for an instance-level cluster.
1. Click **Add Kubernetes cluster**.
1. Click **Amazon EKS**. You will be provided with an `Account ID` and `External ID` to use in the next step.
1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an
`Account ID` and `External ID` to use in the next step.
1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role:
1. From the left panel, select **Roles**.
1. Click **Create role**.
......@@ -356,24 +361,23 @@ to install some [pre-defined applications](index.md#installing-applications).
If you have either of the following types of clusters already, you can add them to a project:
- [Google Kubernetes Engine cluster](#add-existing-gke-cluster).
- [Amazon Elastic Kubernetes Service](#add-existing-eks-cluster).
- [Google Kubernetes Engine cluster](#existing-gke-cluster).
- [Amazon Elastic Kubernetes Service](#existing-eks-cluster).
NOTE: **Note:**
Kubernetes integration is not supported for arm64 clusters. See the issue
[Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/issues/64044) for details.
### Add existing GKE cluster
To add an existing Kubernetes cluster to your project:
### Existing GKE cluster
1. Navigate to your project's **Operations > Kubernetes** page.
NOTE: **Note:**
You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page.
To add an existing GKE cluster to your project, group, or instance:
1. Navigate to your:
- Project's **Operations > Kubernetes** page, for a project-level cluster.
- Group's **Kubernetes** page, for a group-level cluster.
- **Admin Area > Kubernetes** page, for an instance-level cluster.
1. Click **Add Kubernetes cluster**.
1. Click **Add an existing Kubernetes cluster** and fill in the details:
1. Click the **Add existing cluster** tab and fill in the details:
- **Kubernetes cluster name** (required) - The name you wish to give the cluster.
- **Environment scope** (required) - The
[associated environment](index.md#setting-the-environment-scope-premium) to this cluster.
......@@ -389,7 +393,7 @@ To add an existing Kubernetes cluster to your project:
```
- **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default.
- List the secrets with `kubectl get secrets`, and one should named similar to
- List the secrets with `kubectl get secrets`, and one should be named similar to
`default-token-xxxxx`. Copy that token name for use below.
- Get the certificate by running this command:
......@@ -508,45 +512,27 @@ To add an existing Kubernetes cluster to your project:
After a couple of minutes, your cluster will be ready to go. You can now proceed
to install some [pre-defined applications](index.md#installing-applications).
### Add existing EKS cluster
In this section, we will show how to integrate an [Amazon EKS](https://aws.amazon.com/eks/) cluster with GitLab and begin
deploying applications.
#### Requirements
To integrate with with EKS, you will need:
### Existing EKS cluster
- An account on GitLab, like [GitLab.com](https://gitlab.com).
- An Amazon EKS cluster (with worker nodes properly configured).
- `kubectl` [installed and configured for access to the EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl).
To add an existing EKS cluster to your project, group, or instance:
If you don't have an Amazon EKS cluster, one can be created by following the
[EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html).
#### Configuring and connecting the EKS cluster
From the left side bar, hover over **Operations > Kubernetes > Add Kubernetes cluster**,
then click **Add an existing Kubernetes cluster**.
A few details from the EKS cluster will be required to connect it to GitLab:
1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to
authenticate to the EKS cluster. We will use the certificate created by default.
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:
- List the secrets with `kubectl get secrets`, and one should named similar to
1. List the secrets with `kubectl get secrets`, and one should named similar to
`default-token-xxxxx`. Copy that token name for use below.
- Get the certificate with:
1. Get the certificate with:
```sh
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 auth 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 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:
......@@ -560,13 +546,8 @@ A few details from the EKS cluster will be required to connect it to GitLab:
1. Apply the service account to your cluster:
```bash
kubectl apply -f eks-admin-service-account.yaml
```
Output:
```bash
```shell
$ kubectl apply -f eks-admin-service-account.yaml
serviceaccount "eks-admin" created
```
......@@ -589,13 +570,8 @@ A few details from the EKS cluster will be required to connect it to GitLab:
1. Apply the cluster role binding to your cluster:
```bash
kubectl apply -f eks-admin-cluster-role-binding.yaml
```
Output:
```bash
```shell
$ kubectl apply -f eks-admin-cluster-role-binding.yaml
clusterrolebinding "eks-admin" created
```
......@@ -623,21 +599,23 @@ A few details from the EKS cluster will be required to connect it to GitLab:
token: <authentication_token>
```
1. The API server endpoint is also required, so GitLab can connect to the cluster.
This is displayed on the AWS EKS console, when viewing the EKS cluster details.
You now have all the information needed to connect the EKS cluster:
- Kubernetes cluster name: Provide 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: Paste in the API server endpoint retrieved above.
- CA Certificate: Paste the certificate data from the earlier step, as-is.
- Paste the admin token value.
- Project namespace: This can be left blank to accept the default namespace, based on the project name.
![Add Cluster](img/add_cluster.png)
1. Locate the 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 **Operations > Kubernetes** page, for a project-level cluster.
- Group's **Kubernetes** page, for a group-level cluster.
- **Admin Area > 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.
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.
......
---
redirect_to: '../add_remove_clusters.md#add-existing-eks-cluster'
redirect_to: '../add_remove_clusters.md#existing-eks-cluster'
---
This document was moved to [another location](../add_remove_clusters.md#add-existing-eks-cluster).
This document was moved to [another location](../add_remove_clusters.md#existing-eks-cluster).
......@@ -30,9 +30,6 @@ Using the GitLab project Kubernetes integration, you can:
- View [Pod logs](#pod-logs-ultimate). **(ULTIMATE)**
- Run serverless workloads on [Kubernetes with Knative](serverless/index.md).
See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how to
set up integrations.
### Deploy Boards **(PREMIUM)**
GitLab's Deploy Boards offer a consolidated view of the current health and
......@@ -79,10 +76,7 @@ Kubernetes clusters can be used without Auto DevOps.
### Web terminals
NOTE: **Note:**
Introduced in GitLab 8.15. You must be the project owner or have `maintainer` permissions
to use terminals. Support is limited to the first container in the
first pod of your environment.
> Introduced in GitLab 8.15.
When enabled, the Kubernetes service adds [web terminal](../../../ci/environments.md#web-terminals)
support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in
......@@ -97,6 +91,14 @@ pods are annotated with:
`$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of
the CI variables.
You must be the project owner or have `maintainer` permissions to use terminals. Support is limited
to the first container in the first pod of your environment.
## Adding and removing clusters
See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how to
set up integrations with Google Cloud Platform (GCP) and Amazon Elastic Kubernetes Service (EKS).
## Cluster configuration
After [adding a Kubernetes cluster](add_remove_clusters.md) to GitLab, read this section that covers
......@@ -115,8 +117,8 @@ applications running on the cluster.
### GitLab-managed clusters
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 11.5.
> Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26565) in GitLab 11.11.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 11.5.
> - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26565) in GitLab 11.11.
You can choose to allow GitLab to manage your cluster for you. If your cluster is
managed by GitLab, resources for your projects will be automatically created. See the
......
......@@ -43,7 +43,7 @@ To run Knative on GitLab, you will need:
clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get
started.
1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative.
The simplest way to get started is to add a cluster using [GitLab's GKE integration](../add_remove_clusters.md#gke-cluster).
The simplest way to get started is to add a cluster using GitLab's [GKE integration](../add_remove_clusters.md).
The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory.
1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install
Knative.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment