From 3d18d37c6c221c2f674003cec03cfc1e2bc98f39 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 12 Jan 2018 17:23:10 +0100 Subject: [PATCH] Port the cluster docs from EE to CE --- doc/user/project/clusters/index.md | 167 ++++++++++++++++++++++------- 1 file changed, 129 insertions(+), 38 deletions(-) diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 130f7897b1a..f2289fcb3d1 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -1,26 +1,27 @@ # Connecting GitLab with a Kubernetes cluster -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in 10.1. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/35954) in GitLab 10.1. + +NOTE: **Note:** +The Cluster integration will eventually supersede the +[Kubernetes integration](../integrations/kubernetes.md). With a cluster associated to your project, you can use Review Apps, deploy your applications, run your pipelines, and much more, in an easy way. -Connect your project to Google Kubernetes Engine (GKE) or your own Kubernetes +Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster in a few steps. -NOTE: **Note:** -The Cluster integration will eventually supersede the -[Kubernetes integration](../integrations/kubernetes.md). For the moment, -you can create only one cluster. - ## Prerequisites -In order to be able to manage your GKE cluster through GitLab, the following -prerequisites must be met: +In order to be able to manage your Kubernetes cluster through GitLab, the +following prerequisites must be met. + +**For a cluster hosted on GKE:** - The [Google authentication integration](../../../integration/google.md) must be enabled in GitLab at the instance level. If that's not the case, ask your - administrator to enable it. + GitLab administrator to enable it. - Your associated Google account must have the right privileges to manage clusters on GKE. That would mean that a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) @@ -31,41 +32,63 @@ prerequisites must be met: - You must have [Resource Manager API](https://cloud.google.com/resource-manager/) -If all of the above requirements are met, you can proceed to add a new GKE +**For an existing Kubernetes cluster:** + +- Since the cluster is already created, there are no prerequisites. + +--- + +If all of the above requirements are met, you can proceed to add a new Kubernetes cluster. -## Adding a cluster +## Adding a Kubernetes cluster NOTE: **Note:** -You need Master [permissions] and above to add a cluster. +You need Master [permissions] and above to access the Clusters page. -There are two options when adding a new cluster; either use Google Kubernetes -Engine (GKE) or provide the credentials to your own Kubernetes cluster. +There are two options when adding a new cluster to your project; either associate +your account with Google Kubernetes Engine (GKE) so that you can create new +clusters from within GitLab, or provide the credentials to an existing +Kubernetes cluster. -To add a new cluster: +Before proceeding to either method, make sure all [prerequisites](#prerequisites) +are met. -1. Navigate to your project's **CI/CD > Cluster** page -1. If you want to let GitLab create a cluster on GKE for you, go through the - following steps, otherwise skip to the next one. - 1. Click on **Create with GKE** - 1. Connect your Google account if you haven't done already by clicking the - **Sign in with Google** button - 1. Fill in the requested values: - - **Cluster name** (required) - The name you wish to give the cluster. - - **GCP project ID** (required) - The ID of the project you created in your GCP - console that will host the Kubernetes cluster. This must **not** be confused - with the project name. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). - - **Zone** - The [zone](https://cloud.google.com/compute/docs/regions-zones/) - under which the cluster will be created. - - **Number of nodes** - The number of nodes you wish the cluster to have. - - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) - of the Virtual Machine instance that the cluster will be based on. - - **Project namespace** - The unique namespace for this project. By default you - don't have to fill it in; by leaving it blank, GitLab will create one for you. -1. If you want to use your own existing Kubernetes cluster, click on - **Add an existing cluster** and fill in the details as described in the - [Kubernetes integration](../integrations/kubernetes.md) documentation. -1. Finally, click the **Create cluster** button +**To add a new cluster hosted on GKE to your project:** + +1. Navigate to your project's **CI/CD > Clusters** page. +1. Click on **Add cluster**. +1. Click on **Create with GKE**. +1. Connect your Google account if you haven't done already by clicking the + **Sign in with Google** button. +1. Fill in the requested values: + - **Cluster name** (required) - The name you wish to give the cluster. + - **GCP project ID** (required) - The ID of the project you created in your GCP + console that will host the Kubernetes cluster. This must **not** be confused + with the project name. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). + - **Zone** - The [zone](https://cloud.google.com/compute/docs/regions-zones/) + under which the cluster will be created. + - **Number of nodes** - The number of nodes you wish the cluster to have. + - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) + of the Virtual Machine instance that the cluster will be based on. + - **Project namespace** - The unique namespace for this project. By default you + don't have to fill it in; by leaving it blank, GitLab will create one for you. + - **Environment scope** - The [associated environment](#setting-the-environment-scope) to this cluster. +1. Finally, click the **Create cluster** button. + +--- + +**To add an existing cluster to your project:** + +1. Navigate to your project's **CI/CD > Clusters** page. +1. Click on **Add cluster**. +1. Click on **Add an existing cluster** and fill in the details as described + in the [Kubernetes integration](../integrations/kubernetes.md#configuration) + documentation. +1. Select the [environment scope](#setting-the-environment-scope). +1. Finally, click the **Create cluster** button. + +--- After a few moments, your cluster should be created. If something goes wrong, you will be notified. @@ -111,4 +134,72 @@ To remove the Cluster integration from your project, simply click on the **Remove integration** button. You will then be able to follow the procedure and [add a cluster](#adding-a-cluster) again. +## Multiple Kubernetes clusters + +> Introduced in [GitLab Enterprise Edition Premium][ee] 10.3. + +With GitLab EEP, you can associate more than one Kubernetes clusters to your +project. That way you can have different clusters for different environments, +like dev, staging, production, etc. + +To add another cluster, follow the same steps as described in [adding a +Kubernetes cluster](#adding-a-kubernetes-cluster) and make sure to +[set an environment scope](#setting-the-environment-scope) that will +differentiate the new cluster with the rest. + +## Setting the environment scope + +When adding more than one clusters, you need to differentiate them with an +environment scope. The environment scope associates clusters and +[environments](../../../ci/environments.md) in an 1:1 relationship similar to how the +[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-secret-variables) +work. + +The default environment scope is `*`, which means all jobs, regardless of their +environment, will use that cluster. Each scope can only be used by a single +cluster in a project, and a validation error will occur if otherwise. + +--- + +For example, let's say the following clusters exist in a project: + +| Cluster | Environment scope | +| ---------- | ------------------- | +| Development| `*` | +| Staging | `staging/*` | +| Production | `production/*` | + +And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md): + +```yaml +stages: +- test +- deploy + +test: + stage: test + script: sh test + +deploy to staging: + stage: deploy + script: make deploy + environment: + name: staging/$CI_COMMIT_REF_NAME + url: https://staging.example.com/ + +deploy to production: + stage: deploy + script: make deploy + environment: + name: production/$CI_COMMIT_REF_NAME + url: https://example.com/ +``` + +The result will then be: + +- The development cluster will be used for the "test" job. +- The staging cluster will be used for the "deploy to staging" job. +- The production cluster will be used for the "deploy to production" job. + [permissions]: ../../permissions.md +[ee]: https://about.gitlab.com/gitlab-ee/