Skip to content

Commit 3d18d37

Browse files
axilleasaxilleas
committed
Port the cluster docs from EE to CE
1 parent 6d9da73 commit 3d18d37

File tree

1 file changed

+132
-41
lines changed

1 file changed

+132
-41
lines changed

‎doc/user/project/clusters/index.md

+132-41
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,27 @@
11
# Connecting GitLab with a Kubernetes cluster
22

3-
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in 10.1.
3+
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in GitLab 10.1.
4+
5+
NOTE: **Note:**
6+
The Cluster integration will eventually supersede the
7+
[Kubernetes integration](../integrations/kubernetes.md).
48

59
With a cluster associated to your project, you can use Review Apps, deploy your
610
applications, run your pipelines, and much more, in an easy way.
711

8-
Connect your project to Google Kubernetes Engine (GKE) or your own Kubernetes
12+
Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes
913
cluster in a few steps.
1014

11-
NOTE: **Note:**
12-
The Cluster integration will eventually supersede the
13-
[Kubernetes integration](../integrations/kubernetes.md). For the moment,
14-
you can create only one cluster.
15-
1615
## Prerequisites
1716

18-
In order to be able to manage your GKE cluster through GitLab, the following
19-
prerequisites must be met:
17+
In order to be able to manage your Kubernetes cluster through GitLab, the
18+
following prerequisites must be met.
19+
20+
**For a cluster hosted on GKE:**
2021

2122
- The [Google authentication integration](../../../integration/google.md) must
2223
be enabled in GitLab at the instance level. If that's not the case, ask your
23-
administrator to enable it.
24+
GitLab administrator to enable it.
2425
- Your associated Google account must have the right privileges to manage
2526
clusters on GKE. That would mean that a [billing
2627
account](https://cloud.google.com/billing/docs/how-to/manage-billing-account)
@@ -31,41 +32,63 @@ prerequisites must be met:
3132
- You must have [Resource Manager
3233
API](https://cloud.google.com/resource-manager/)
3334

34-
If all of the above requirements are met, you can proceed to add a new GKE
35+
**For an existing Kubernetes cluster:**
36+
37+
- Since the cluster is already created, there are no prerequisites.
38+
39+
---
40+
41+
If all of the above requirements are met, you can proceed to add a new Kubernetes
3542
cluster.
3643

37-
## Adding a cluster
44+
## Adding a Kubernetes cluster
3845

3946
NOTE: **Note:**
40-
You need Master [permissions] and above to add a cluster.
41-
42-
There are two options when adding a new cluster; either use Google Kubernetes
43-
Engine (GKE) or provide the credentials to your own Kubernetes cluster.
44-
45-
To add a new cluster:
46-
47-
1. Navigate to your project's **CI/CD > Cluster** page
48-
1. If you want to let GitLab create a cluster on GKE for you, go through the
49-
following steps, otherwise skip to the next one.
50-
1. Click on **Create with GKE**
51-
1. Connect your Google account if you haven't done already by clicking the
52-
**Sign in with Google** button
53-
1. Fill in the requested values:
54-
- **Cluster name** (required) - The name you wish to give the cluster.
55-
- **GCP project ID** (required) - The ID of the project you created in your GCP
56-
console that will host the Kubernetes cluster. This must **not** be confused
57-
with the project name. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
58-
- **Zone** - The [zone](https://cloud.google.com/compute/docs/regions-zones/)
59-
under which the cluster will be created.
60-
- **Number of nodes** - The number of nodes you wish the cluster to have.
61-
- **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types)
62-
of the Virtual Machine instance that the cluster will be based on.
63-
- **Project namespace** - The unique namespace for this project. By default you
64-
don't have to fill it in; by leaving it blank, GitLab will create one for you.
65-
1. If you want to use your own existing Kubernetes cluster, click on
66-
**Add an existing cluster** and fill in the details as described in the
67-
[Kubernetes integration](../integrations/kubernetes.md) documentation.
68-
1. Finally, click the **Create cluster** button
47+
You need Master [permissions] and above to access the Clusters page.
48+
49+
There are two options when adding a new cluster to your project; either associate
50+
your account with Google Kubernetes Engine (GKE) so that you can create new
51+
clusters from within GitLab, or provide the credentials to an existing
52+
Kubernetes cluster.
53+
54+
Before proceeding to either method, make sure all [prerequisites](#prerequisites)
55+
are met.
56+
57+
**To add a new cluster hosted on GKE to your project:**
58+
59+
1. Navigate to your project's **CI/CD > Clusters** page.
60+
1. Click on **Add cluster**.
61+
1. Click on **Create with GKE**.
62+
1. Connect your Google account if you haven't done already by clicking the
63+
**Sign in with Google** button.
64+
1. Fill in the requested values:
65+
- **Cluster name** (required) - The name you wish to give the cluster.
66+
- **GCP project ID** (required) - The ID of the project you created in your GCP
67+
console that will host the Kubernetes cluster. This must **not** be confused
68+
with the project name. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
69+
- **Zone** - The [zone](https://cloud.google.com/compute/docs/regions-zones/)
70+
under which the cluster will be created.
71+
- **Number of nodes** - The number of nodes you wish the cluster to have.
72+
- **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types)
73+
of the Virtual Machine instance that the cluster will be based on.
74+
- **Project namespace** - The unique namespace for this project. By default you
75+
don't have to fill it in; by leaving it blank, GitLab will create one for you.
76+
- **Environment scope** - The [associated environment](#setting-the-environment-scope) to this cluster.
77+
1. Finally, click the **Create cluster** button.
78+
79+
---
80+
81+
**To add an existing cluster to your project:**
82+
83+
1. Navigate to your project's **CI/CD > Clusters** page.
84+
1. Click on **Add cluster**.
85+
1. Click on **Add an existing cluster** and fill in the details as described
86+
in the [Kubernetes integration](../integrations/kubernetes.md#configuration)
87+
documentation.
88+
1. Select the [environment scope](#setting-the-environment-scope).
89+
1. Finally, click the **Create cluster** button.
90+
91+
---
6992

7093
After a few moments, your cluster should be created. If something goes wrong,
7194
you will be notified.
@@ -111,4 +134,72 @@ To remove the Cluster integration from your project, simply click on the
111134
**Remove integration** button. You will then be able to follow the procedure
112135
and [add a cluster](#adding-a-cluster) again.
113136

137+
## Multiple Kubernetes clusters
138+
139+
> Introduced in [GitLab Enterprise Edition Premium][ee] 10.3.
140+
141+
With GitLab EEP, you can associate more than one Kubernetes clusters to your
142+
project. That way you can have different clusters for different environments,
143+
like dev, staging, production, etc.
144+
145+
To add another cluster, follow the same steps as described in [adding a
146+
Kubernetes cluster](#adding-a-kubernetes-cluster) and make sure to
147+
[set an environment scope](#setting-the-environment-scope) that will
148+
differentiate the new cluster with the rest.
149+
150+
## Setting the environment scope
151+
152+
When adding more than one clusters, you need to differentiate them with an
153+
environment scope. The environment scope associates clusters and
154+
[environments](../../../ci/environments.md) in an 1:1 relationship similar to how the
155+
[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-secret-variables)
156+
work.
157+
158+
The default environment scope is `*`, which means all jobs, regardless of their
159+
environment, will use that cluster. Each scope can only be used by a single
160+
cluster in a project, and a validation error will occur if otherwise.
161+
162+
---
163+
164+
For example, let's say the following clusters exist in a project:
165+
166+
| Cluster | Environment scope |
167+
| ---------- | ------------------- |
168+
| Development| `*` |
169+
| Staging | `staging/*` |
170+
| Production | `production/*` |
171+
172+
And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md):
173+
174+
```yaml
175+
stages:
176+
- test
177+
- deploy
178+
179+
test:
180+
stage: test
181+
script: sh test
182+
183+
deploy to staging:
184+
stage: deploy
185+
script: make deploy
186+
environment:
187+
name: staging/$CI_COMMIT_REF_NAME
188+
url: https://staging.example.com/
189+
190+
deploy to production:
191+
stage: deploy
192+
script: make deploy
193+
environment:
194+
name: production/$CI_COMMIT_REF_NAME
195+
url: https://example.com/
196+
```
197+
198+
The result will then be:
199+
200+
- The development cluster will be used for the "test" job.
201+
- The staging cluster will be used for the "deploy to staging" job.
202+
- The production cluster will be used for the "deploy to production" job.
203+
114204
[permissions]: ../../permissions.md
205+
[ee]: https://about.gitlab.com/gitlab-ee/

0 commit comments

Comments
 (0)