diff options
Diffstat (limited to 'doc/user/project/clusters')
| -rw-r--r-- | doc/user/project/clusters/index.md | 227 |
1 files changed, 164 insertions, 63 deletions
diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index f2289fcb3d1..e87b4403854 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -2,15 +2,16 @@ > [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). +Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes +cluster in a few steps. 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 an existing Kubernetes -cluster in a few steps. +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](#adding-and-creating-a-new-gke-cluster-via-gitlab) from within GitLab, +or provide the credentials to an [existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster). ## Prerequisites @@ -41,20 +42,13 @@ following prerequisites must be met. If all of the above requirements are met, you can proceed to add a new Kubernetes cluster. -## Adding a Kubernetes cluster +## Adding and creating a new GKE cluster via GitLab NOTE: **Note:** You need Master [permissions] and above to access the Clusters page. -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. - -Before proceeding to either method, make sure all [prerequisites](#prerequisites) -are met. - -**To add a new cluster hosted on GKE to your project:** +Before proceeding, make sure all [prerequisites](#prerequisites) are met. +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**. @@ -71,24 +65,56 @@ are met. - **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. ---- +After a few moments, your cluster should be created. If something goes wrong, +you will be notified. -**To add an existing cluster to your project:** +You can now proceed to install some pre-defined applications and then +enable the Cluster integration. + +## Adding an existing Kubernetes cluster + +NOTE: **Note:** +You need Master [permissions] and above to access the Clusters page. + +To add an existing Kubernetes 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. Click on **Add an existing cluster** and fill in the details: + - **Cluster name** (required) - The name you wish to give the cluster. + - **Environment scope** (required)- The + [associated environment](#setting-the-environment-scope) to this cluster. + - **API URL** (required) - + It's the URL that GitLab uses to access the Kubernetes API. Kubernetes + exposes several APIs, we want the "base" URL that is common to all of them, + e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. + - **CA certificate** (optional) - + If the API is using a self-signed TLS certificate, you'll also need to include + the `ca.crt` contents here. + - **Token** - + GitLab authenticates against Kubernetes using service tokens, which are + scoped to a particular `namespace`. If you don't have a service token yet, + you can follow the + [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) + to create one. You can also view or create service tokens in the + [Kubernetes dashboard](https://kubernetes.io/docs/tasks/access-application-cluster/web-ui-dashboard/#config) + (under **Config > Secrets**). + - **Project namespace** (optional) - The following apply: + - By default you don't have to fill it in; by leaving it blank, GitLab will + create one for you. + - Each project should have a unique namespace. + - The project namespace is not necessarily the namespace of the secret, if + you're using a secret with broader permissions, like the secret from `default`. + - You should **not** use `default` as the project namespace. + - If you or someone created a secret specifically for the project, usually + with limited permissions, the secret's namespace and project namespace may + be the same. 1. Finally, click the **Create cluster** button. ---- +The Kubernetes service takes the following parameters: After a few moments, your cluster should be created. If something goes wrong, you will be notified. @@ -108,45 +134,6 @@ added directly to your configured cluster. Those applications are needed for | [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) | 10.2+ | Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use [Auto DevOps](../../../topics/autodevops/index.md) or deploy your own web apps. | | [Prometheus](https://prometheus.io/docs/introduction/overview/) | 10.4+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications | -## Enabling or disabling the Cluster integration - -After you have successfully added your cluster information, you can enable the -Cluster integration: - -1. Click the "Enabled/Disabled" switch -1. Hit **Save** for the changes to take effect - -You can now start using your Kubernetes cluster for your deployments. - -To disable the Cluster integration, follow the same procedure. - -## Removing the Cluster integration - -NOTE: **Note:** -You need Master [permissions] and above to remove a cluster integration. - -NOTE: **Note:** -When you remove a cluster, you only remove its relation to GitLab, not the -cluster itself. To remove the cluster, you can do so by visiting the GKE -dashboard or using `kubectl`. - -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 @@ -201,5 +188,119 @@ The result will then be: - The staging cluster will be used for the "deploy to staging" job. - The production cluster will be used for the "deploy to production" job. +## 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. + +## Deployment variables + +The Kubernetes cluster integration exposes the following +[deployment variables](../../../ci/variables/README.md#deployment-variables) in the +GitLab CI/CD build environment: + +- `KUBE_URL` - Equal to the API URL. +- `KUBE_TOKEN` - The Kubernetes token. +- `KUBE_NAMESPACE` - The Kubernetes namespace is auto-generated if not specified. + The default value is `<project_name>-<project_id>`. You can overwrite it to + use different one if needed, otherwise the `KUBE_NAMESPACE` variable will + receive the default value. +- `KUBE_CA_PEM_FILE` - Only present if a custom CA bundle was specified. Path + to a file containing PEM data. +- `KUBE_CA_PEM` (deprecated) - Only if a custom CA bundle was specified. Raw PEM data. +- `KUBECONFIG` - Path to a file containing `kubeconfig` for this deployment. + CA bundle would be embedded if specified. + +## Enabling or disabling the Cluster integration + +After you have successfully added your cluster information, you can enable the +Cluster integration: + +1. Click the "Enabled/Disabled" switch +1. Hit **Save** for the changes to take effect + +You can now start using your Kubernetes cluster for your deployments. + +To disable the Cluster integration, follow the same procedure. + +## Removing the Cluster integration + +NOTE: **Note:** +You need Master [permissions] and above to remove a cluster integration. + +NOTE: **Note:** +When you remove a cluster, you only remove its relation to GitLab, not the +cluster itself. To remove the cluster, you can do so by visiting the GKE +dashboard or using `kubectl`. + +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. + +## What you can get with the Kubernetes integration + +Here's what you can do with GitLab if you enable the Kubernetes integration. + +### Deploy Boards (EEP) + +> Available in [GitLab Enterprise Edition Premium][ee]. + +GitLab's Deploy Boards offer a consolidated view of the current health and +status of each CI [environment](../../../ci/environments.md) running on Kubernetes, +displaying the status of the pods in the deployment. Developers and other +teammates can view the progress and status of a rollout, pod by pod, in the +workflow they already use without any need to access Kubernetes. + +[> Read more about Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) + +### Canary Deployments (EEP) + +> Available in [GitLab Enterprise Edition Premium][ee]. + +Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments) +and visualize your canary deployments right inside the Deploy Board, without +the need to leave GitLab. + +[> Read more about Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) + +### Kubernetes monitoring + +Automatically detect and monitor Kubernetes metrics. Automatic monitoring of +[NGINX ingress](../integrations/prometheus_library/nginx.md) is also supported. + +[> Read more about Kubernetes monitoring](../integrations/prometheus_library/kubernetes.md) + +### Auto DevOps + +Auto DevOps automatically detects, builds, tests, deploys, and monitors your +applications. + +To make full use of Auto DevOps(Auto Deploy, Auto Review Apps, and Auto Monitoring) +you will need the Kubernetes project integration enabled. + +[> Read more about Auto DevOps](../../../topics/autodevops/index.md) + +### Web terminals + +NOTE: **Note:** +Introduced in GitLab 8.15. You must be the project owner or have `master` permissions +to use terminals. Support is limited to the first container in the +first pod of your environment. + +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 +Docker and Kubernetes, so you get a new shell session within your existing +containers. To use this integration, you should deploy to Kubernetes using +the deployment variables above, ensuring any pods you create are labelled with +`app=$CI_ENVIRONMENT_SLUG`. GitLab will do the rest! + [permissions]: ../../permissions.md [ee]: https://about.gitlab.com/gitlab-ee/ |