diff options
Diffstat (limited to 'doc/user/project/clusters/index.md')
| -rw-r--r-- | doc/user/project/clusters/index.md | 118 |
1 files changed, 65 insertions, 53 deletions
diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 65cdece8d3d..b25b09f7b1f 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -7,9 +7,10 @@ cluster in a few steps. ## Overview -With a Kubernetes cluster associated to your project, you can use +With one or more Kubernetes clusters associated to your project, you can use [Review Apps](../../../ci/review_apps/index.md), deploy your applications, run -your pipelines, and much more, in an easy way. +your pipelines, use it with [Auto DevOps](../../../topics/autodevops/index.md), +and much more, all from within GitLab. 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 @@ -18,59 +19,65 @@ or provide the credentials to an [existing Kubernetes cluster](#adding-an-existi ## Adding and creating a new GKE cluster via GitLab +TIP: **Tip:** +Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial), +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://goo.gl/AaJzRW) and apply for credit. + NOTE: **Note:** -You need Master [permissions] and above to access the Kubernetes page. - -Before proceeding, make sure the following requirements are met: - -- 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. -- 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) - must be set up and that you have to have permissions to access it. -- You must have Master [permissions] in order to be able to access the - **Kubernetes** page. -- You must have [Cloud Billing API](https://cloud.google.com/billing/) enabled -- You must have [Resource Manager - API](https://cloud.google.com/resource-manager/) +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. + +### 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 is enabled. Follow the steps as outlined in the + ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). + +### Creating the cluster If all of the above requirements are met, you can proceed to create and add a -new Kubernetes cluster that will be hosted on GKE to your project: +new Kubernetes cluster to your project: + +1. Navigate to your project's **Operations > Kubernetes** page. + + NOTE: **Note:** + You need Maintainer [permissions] and above to access the Kubernetes page. -1. Navigate to your project's **CI/CD > Kubernetes** page. 1. Click on **Add Kubernetes cluster**. -1. Click on **Create with GKE**. +1. Click on **Create with Google Kubernetes Engine**. 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/) +1. From there on, choose your cluster's settings: + - **Kubernetes cluster name** - The name you wish to give the cluster. + - **Environment scope** - The [associated environment](#setting-the-environment-scope) to this cluster. + - **Google Cloud Platform project** - Choose the project you created in your GCP + console that will host the Kubernetes cluster. Learn more about + [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). + - **Zone** - Choose the [region 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. + - **Number of nodes** - Enter 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. - - **Environment scope** - The [associated environment](#setting-the-environment-scope) to this cluster. 1. Finally, click the **Create Kubernetes cluster** button. -After a few moments, your cluster should be created. If something goes wrong, -you will be notified. - -You can now proceed to install some pre-defined applications and then -enable the Cluster integration. +After a couple of minutes, your cluster will be ready to go. You can now proceed +to install some [pre-defined applications](#installing-applications). ## Adding an existing Kubernetes cluster -NOTE: **Note:** -You need Master [permissions] and above to access the Kubernetes page. - To add an existing Kubernetes cluster to your project: -1. Navigate to your project's **CI/CD > Kubernetes** page. +1. Navigate to your project's **Operations > Kubernetes** page. + + NOTE: **Note:** + You need Maintainer [permissions] and above to access the Kubernetes page. + 1. Click on **Add Kubernetes cluster**. 1. Click on **Add an existing Kubernetes cluster** and fill in the details: - **Kubernetes cluster name** (required) - The name you wish to give the cluster. @@ -91,9 +98,8 @@ To add an existing Kubernetes cluster to your project: 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. + - **Project namespace** (optional) - You don't have to fill it in; by leaving + it blank, GitLab will create one for you. Also: - 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`. @@ -103,11 +109,8 @@ To add an existing Kubernetes cluster to your project: be the same. 1. Finally, click the **Create Kubernetes cluster** button. -After a few moments, your cluster should be created. If something goes wrong, -you will be notified. - -You can now proceed to install some pre-defined applications and then -enable the Kubernetes cluster integration. +After a couple of minutes, your cluster will be ready to go. You can now proceed +to install some [pre-defined applications](#installing-applications). ## Security implications @@ -152,11 +155,11 @@ added directly to your configured cluster. Those applications are needed for | Application | GitLab version | Description | | ----------- | :------------: | ----------- | -| [Helm Tiller](https://docs.helm.sh/) | 10.2+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It will be automatically installed as a dependency when you try to install a different app. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. | +| [Helm Tiller](https://docs.helm.sh/) | 10.2+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. | | [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] 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 | +| [Prometheus](https://prometheus.io/docs/introduction/overview/) | 10.4+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications. | | [GitLab Runner](https://docs.gitlab.com/runner/) | 10.6+ | GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with [GitLab CI/CD](https://about.gitlab.com/features/gitlab-ci-cd/), the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in **privileged mode** by default. Make sure you read the [security implications](#security-implications) before doing so. | -| [JupyterHub](http://jupyter.org/) | 11.0+ | The Jupyter Notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations and narrative text. | +| [JupyterHub](http://jupyter.org/) | 11.0+ | [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. **Note**: Authentication will be enabled for any user of the GitLab server via OAuth2. HTTPS will be supported in a future release. | ## Getting the external IP address @@ -201,6 +204,11 @@ Otherwise, you can list the IP addresses of all load balancers: kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' ``` +> **Note**: Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: +> ```bash +> kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}"`. +> ``` + The output is the external IP address of your cluster. This information can then be used to set up DNS entries and forwarding rules that allow external access to your deployed applications. @@ -233,7 +241,7 @@ When adding more than one Kubernetes clusters to your project, 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) +[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-variables) work. The default environment scope is `*`, which means all jobs, regardless of their @@ -325,7 +333,7 @@ To disable the Kubernetes cluster integration, follow the same procedure. ## Removing the Kubernetes cluster integration NOTE: **Note:** -You need Master [permissions] and above to remove a Kubernetes cluster integration. +You need Maintainer [permissions] and above to remove a Kubernetes cluster integration. NOTE: **Note:** When you remove a cluster, you only remove its relation to GitLab, not the @@ -382,7 +390,7 @@ you will need the Kubernetes project integration enabled. ### Web terminals NOTE: **Note:** -Introduced in GitLab 8.15. You must be the project owner or have `master` permissions +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. @@ -393,6 +401,10 @@ 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! +## Read more + +- [Connecting and deploying to an Amazon EKS cluster](eks_and_gitlab/index.md) + [permissions]: ../../permissions.md -[ee]: https://about.gitlab.com/products/ +[ee]: https://about.gitlab.com/pricing/ [Auto DevOps]: ../../../topics/autodevops/index.md |