diff options
Diffstat (limited to 'doc/user/clusters')
-rw-r--r-- | doc/user/clusters/agent/index.md | 226 | ||||
-rw-r--r-- | doc/user/clusters/applications.md | 358 |
2 files changed, 301 insertions, 283 deletions
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 7b745577cc4..4065ee3337b 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -6,18 +6,23 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Kubernetes Agent **(PREMIUM ONLY)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223061) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.4. +> - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). -## Goals +CAUTION: **Warning:** +This feature might not be available to you. Check the **version history** note above for details. -The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) is an active in-cluster component for solving GitLab and Kubernetes integration tasks in a secure and cloud native way. +The [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) +is an active in-cluster component for solving GitLab and Kubernetes integration +tasks in a secure and cloud-native way. It enables: -Features: +- Integrating GitLab with a Kubernetes cluster behind a firewall or NAT + (network address translation). +- Pull-based GitOps deployments by leveraging the + [GitOps Engine](https://github.com/argoproj/gitops-engine). +- Real-time access to API endpoints within a cluster. -1. Makes it possible to integrate GitLab with a Kubernetes cluster behind a firewall or NAT -1. Enables pull-based GitOps deployments by leveraging the [GitOps Engine](https://github.com/argoproj/gitops-engine) -1. Allows for real-time access to API endpoints within a cluster. -1. Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). +Many more features are planned. Please [review our roadmap](https://gitlab.com/groups/gitlab-org/-/epics/3329). ## Architecture @@ -39,37 +44,45 @@ sequenceDiagram end ``` -Please refer to our [full architecture documentation in the Agent project](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture). +Please refer to our [full architecture documentation](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md#high-level-architecture) +in the Agent project. -## Getting started with GitOps using the GitLab Agent and the GitLab Cloud Native Helm chart +## Get started with GitOps and the GitLab Agent There are several components that work in concert for the Agent to accomplish GitOps deployments: -1. A Kubernetes cluster that is properly configured -1. A configuration repository that contains a `config.yaml` file. This `config.yaml` tells the Agent which repositories to synchronize with. -1. A manifest repository that contains a `manifest.yaml`. This `manifest.yaml` (which can be autogenerated) is tracked by the Agent and any changes to the file are automatically applied to the cluster. +- A properly-configured Kubernetes cluster. +- A configuration repository that contains a `config.yaml` file, which tells the + Agent which repositories to synchronize with. +- A manifest repository that contains a `manifest.yaml`, which is tracked by the + Agent and can be auto-generated. Any changes to `manifest.yaml` are applied to the cluster. -The setup process involves a few steps that, once completed, will enable GitOps deployments to work +The setup process involves a few steps to enable GitOps deployments: -1. Installing the Agent server via GitLab Helm chart -1. Defining a configuration directory -1. Creating an Agent record in GitLab -1. Generating and copying a Secret token used to connect to the Agent -1. Installing the Agent into the cluster -1. Creating a `manifest.yaml` +1. Installing the Agent server via GitLab Helm chart. +1. Defining a configuration directory. +1. Creating an Agent record in GitLab. +1. Generating and copying a Secret token used to connect to the Agent. +1. Installing the Agent into the cluster. +1. Creating a `manifest.yaml`. -### Installing the Agent server via Helm +### Install the Agent server -Currently the GitLab Kubernetes Agent can only be deployed via our [Helm chart](https://gitlab.com/gitlab-org/charts/gitlab). +The GitLab Kubernetes Agent can only be deployed through our +[Helm chart](https://gitlab.com/gitlab-org/charts/gitlab). If you don't already +have GitLab installed via Helm, please refer to our +[installation documentation](https://docs.gitlab.com/charts/installation/). -NOTE: We are working quickly to [include the Agent in Official Linux Package](https://gitlab.com/gitlab-org/gitlab/-/issues/223060). +NOTE: **Note:** +GitLab plans to include the Agent in the [official Linux Package](https://gitlab.com/gitlab-org/gitlab/-/issues/223060) and on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). -If you don't already have GitLab installed via Helm please refer to our [installation documentation](https://docs.gitlab.com/charts/installation/) - -When installing/upgrading the GitLab Helm chart please consider the following Helm 2 example (if using Helm 3 please modify): +When installing or upgrading the GitLab Helm chart, consider the following Helm 2 example. +(If you're using Helm 3, you must modify this example.) You must set `global.kas.enabled=true` +for the Agent to be properly installed and configured: ```shell -helm upgrade --force --install gitlab . \ +helm repo update +helm upgrade --force --install gitlab gitlab/gitlab \ --timeout 600 \ --set global.hosts.domain=<YOUR_DOMAIN> \ --set global.hosts.externalIP=<YOUR_IP> \ @@ -78,15 +91,14 @@ helm upgrade --force --install gitlab . \ --set global.kas.enabled=true ``` -`global.kas.enabled=true` must be set in order for the Agent to be properly installed and configured. - -### Defining a configuration repository +### Define a configuration repository -Next you will need a GitLab repository that will contain your Agent configuration. +Next, you need a GitLab repository to contain your Agent configuration. The minimal +repository layout looks like this: -The minimal repository layout looks like this: - -`.gitlab/agents/<agent-name>/config.yaml` +```plaintext +.gitlab/agents/<agent-name>/config.yaml +``` The `config.yaml` file contents should look like this: @@ -96,31 +108,24 @@ gitops: - id: "path-to/your-awesome-project" ``` -### Creating an Agent record in GitLab - -Next you will need to create an GitLab Rails Agent record so that your GitLab project so that the Agent itself can associate with a GitLab project. This process will also yield a Secret that you will use to configure the Agent in subsequent steps. +### Create an Agent record in GitLab -There are two ways to accomplish this: +Next, create an GitLab Rails Agent record so the Agent can associate itself with +a GitLab project. Creating this record also creates a Secret needed to configure +the Agent in subsequent steps. You can create an Agent record either: -1. Via the Rails console -1. Via GraphQL +- Through the Rails console, by running `rails c`: -To do this you could either run `rails c` or via GraphQL. From `rails c`: - -```ruby + ```ruby project = ::Project.find_by_full_path("path-to/your-awesome-project") agent = ::Clusters::Agent.create(name: "<agent-name>", project: project) token = ::Clusters::AgentToken.create(agent: agent) token.token # this will print out the token you need to use on the next step -``` + ``` -or using GraphQL: +- Through GraphQL: **(PREMIUM ONLY)** -with this approach, you'll need a premium license to use this feature. - -If you are new to using the GitLab GraphQL API please refer to the [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md) or check out the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer). - -```json + ```graphql mutation createAgent { createClusterAgent(input: { projectPath: "path-to/your-awesome-project", name: "<agent-name>" }) { clusterAgent { @@ -141,37 +146,77 @@ If you are new to using the GitLab GraphQL API please refer to the [Getting star errors } } -``` + ``` -Note that GraphQL will only show you the token once, after you've created it. + NOTE: **Note:** + GraphQL only displays the token once, after creating it. -### Creating the Kubernetes secret + If you are new to using the GitLab GraphQL API, refer to the + [Getting started with the GraphQL API page](../../../api/graphql/getting_started.md), + or the [GraphQL Explorer](https://gitlab.com/-/graphql-explorer). -Once the token has been generated it needs to be applied to the Kubernetes cluster. +### Create the Kubernetes secret -If you didn't previously define or create a namespace you need to do that first: +After generating the token, you must apply it to the Kubernetes cluster. -```shell -kubectl create namespace <YOUR-DESIRED-NAMESPACE> -``` +1. If you haven't previous defined or created a namespace, run the following command: + + ```shell + kubectl create namespace <YOUR-DESIRED-NAMESPACE> + ``` + +1. Run the following command to create your Secret: -Run the following command to create your Secret: + ```shell + kubectl create secret generic -n <YOUR-DESIRED-NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' + ``` + +### Install the Agent into the cluster + +Next, install the in-cluster component of the Agent. This example file contains the +Kubernetes resources required for the Agent to be installed. You can modify this +example [`resources.yml` file](#example-resourcesyml-file) in the following ways: + +- You can replace `gitlab-agent` with `<YOUR-DESIRED-NAMESPACE>`. +- For the `kas-address` (Kubernetes Agent Server), the agent can use the WebSockets + or gRPC protocols to connect to the Agent Server. Depending on your cluster + configuration and GitLab architecture, you may need to use one or the other. + For the `gitlab-kas` Helm chart, an Ingress is created for the Agent Server using + the `/-/kubernetes-agent` endpoint. This can be used for the WebSockets protocol connection. + - Specify the `grpc` scheme (such as `grpc://gitlab-kas:5005`) to use gRPC directly. + Encrypted gRPC is not supported yet. Follow the + [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) + for progress updates. + - Specify the `ws` scheme (such as `ws://gitlab-kas-ingress:80/-/kubernetes-agent`) + to use an unencrypted WebSockets connection. + - Specify the `wss` scheme (such as `wss://gitlab-kas-ingress:443/-/kubernetes-agent`) + to use an encrypted WebSockets connection. This is the recommended option if + installing the Agent into a separate cluster from your Agent Server. +- If you defined your own secret name, replace `gitlab-agent-token` with your secret name. + +To apply this file, run the following command: ```shell -kubectl create secret generic -n <YOUR-DESIRED-NAMESPACE> gitlab-agent-token --from-literal=token='YOUR_AGENT_TOKEN' +kubectl apply -n gitlab-agent -f ./resources.yml ``` -### Installing the Agent into the cluster - -Next you are now ready to install the in-cluster component of the Agent. The below is an example YAML file of the Kubernetes resources required for the Agent to be installed. +To review your configuration, run the following command: -Let's highlight a few of the details in the example below: +```shell +$ kubectl get pods --all-namespaces -1. You can replace `gitlab-agent` with <YOUR-DESIRED-NAMESPACE> -1. For the `kas-address` (Kubernetes Agent Server), you can replace `grpc://host.docker.internal:5005` with the address of the kas agent that was initialized via your Helm install. -1. If you defined your own secret name, then replace `gitlab-agent-token` with your secret name. +NAMESPACE NAME READY STATUS RESTARTS AGE +gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s +kube-system coredns-f9fd979d6-n6wcw 1/1 Running 0 14m +kube-system etcd-minikube 1/1 Running 0 14m +kube-system kube-apiserver-minikube 1/1 Running 0 14m +kube-system kube-controller-manager-minikube 1/1 Running 0 14m +kube-system kube-proxy-j6zdh 1/1 Running 0 14m +kube-system kube-scheduler-minikube 1/1 Running 0 14m +kube-system storage-provisioner 1/1 Running 0 14m +``` -`./resources.yml` +#### Example `resources.yml` file ```yaml apiVersion: v1 @@ -200,7 +245,7 @@ spec: args: - --token-file=/config/token - --kas-address - - grpc://host.docker.internal:5005 # {"$openapi":"kas-address"} + - grpc://host.docker.internal:5005 # {"$openapi":"kas-address"} volumeMounts: - name: token-volume mountPath: /config @@ -268,37 +313,31 @@ subjects: - name: gitlab-agent kind: ServiceAccount namespace: gitlab-agent - ``` -```shell -kubectl apply -n gitlab-agent -f ./resources.yml -``` +### Create a `manifest.yaml` + +In a previous step, you configured a `config.yaml` to point to the GitLab projects +the Agent should synchronize. In each of those projects, you must create a `manifest.yaml` +file for the Agent to monitor. You can auto-generate this `manifest.yaml` with a +templating engine or other means. + +Each time you commit and push a change to this file, the Agent logs the change: ```plaintext -$ kubectl get pods --all-namespaces -NAMESPACE NAME READY STATUS RESTARTS AGE -gitlab-agent gitlab-agent-77689f7dcb-5skqk 1/1 Running 0 51s -kube-system coredns-f9fd979d6-n6wcw 1/1 Running 0 14m -kube-system etcd-minikube 1/1 Running 0 14m -kube-system kube-apiserver-minikube 1/1 Running 0 14m -kube-system kube-controller-manager-minikube 1/1 Running 0 14m -kube-system kube-proxy-j6zdh 1/1 Running 0 14m -kube-system kube-scheduler-minikube 1/1 Running 0 14m -kube-system storage-provisioner 1/1 Running 0 14m +2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea ``` -### Creating a `manifest.yaml` - -In the above step, you configured a `config.yaml` to point to which GitLab projects the Agent should synchronize. Within each one of those projects, you need to create a `manifest.yaml` file which the Agent will monitor. This `manifest.yaml` can be autogenerated by a templating engine or other means. +#### Example `manifest.yaml` file -Example `manifest.yaml`: +This file creates a simple NGINX deployment. ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deployment + namespace: gitlab-agent # Can be any namespace managed by you that the agent has access to. spec: selector: matchLabels: @@ -316,14 +355,9 @@ spec: - containerPort: 80 ``` -The above file creates a simple NGINX deployment. - -Each time you commit and push a change to the `manifest.yaml` the Agent will observe the change. Example log: - -```plaintext -2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea -``` - ## Example projects -Basic GitOps example deploying NGINX: [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent), [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) +This basic GitOps example deploys NGINX: + +- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent) +- [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project) diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 2243ffa0cb1..c3b22526919 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -6,37 +6,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab Managed Apps -GitLab provides **GitLab Managed Apps**, a one-click install for various applications which can -be added directly to your configured cluster. - -These applications are needed for [Review Apps](../../ci/review_apps/index.md) -and [deployments](../../ci/environments/index.md) when using [Auto DevOps](../../topics/autodevops/index.md). - -You can install them after you -[create a cluster](../project/clusters/add_remove_clusters.md). +GitLab provides **GitLab Managed Apps**, a one-click install for various +applications which can be added directly to your configured cluster. These +applications are needed for [Review Apps](../../ci/review_apps/index.md) and +[deployments](../../ci/environments/index.md) when using [Auto DevOps](../../topics/autodevops/index.md). +You can install them after you [create a cluster](../project/clusters/add_remove_clusters.md). ## Installing applications -Applications managed by GitLab will be installed onto the `gitlab-managed-apps` namespace. - -This namespace: +Applications managed by GitLab are installed onto the `gitlab-managed-apps` +namespace. This namespace: - Is different from the namespace used for project deployments. - Is created once. - Has a non-configurable name. -To see a list of available applications to install. For a: +To view a list of available applications to install for a: - [Project-level cluster](../project/clusters/index.md), navigate to your project's **Operations > Kubernetes**. - [Group-level cluster](../group/clusters/index.md), navigate to your group's **Kubernetes** page. -NOTE: **Note:** -As of GitLab 11.6, Helm will be upgraded to the latest version supported -by GitLab before installing any of the applications. - -The following applications can be installed: +You can install the following applications: - [Helm](#helm) - [Ingress](#ingress) @@ -49,10 +41,9 @@ The following applications can be installed: - [Elastic Stack](#elastic-stack) - [Fluentd](#fluentd) -With the exception of Knative, the applications will be installed in a dedicated +With the exception of Knative, the applications are installed in a dedicated namespace called `gitlab-managed-apps`. -NOTE: **Note:** Some applications are installable only for a project-level cluster. Support for installing these applications in a group-level cluster is planned for future releases. @@ -65,6 +56,9 @@ you should be careful as GitLab cannot detect it. In this case, installing Helm via the applications will result in the cluster having it twice, which can lead to confusion during deployments. +In GitLab versions 11.6 and greater, Helm is upgraded to the latest version +supported by GitLab before installing any of the applications. + ### Helm > - Introduced in GitLab 10.2 for project-level clusters. @@ -81,7 +75,6 @@ applications. Prior to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issu GitLab used an in-cluster Tiller server in the `gitlab-managed-apps` namespace. This server can now be safely removed. -NOTE: **Note:** GitLab's Helm integration does not support installing applications behind a proxy, but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) is available. @@ -90,26 +83,25 @@ is available. > Introduced in GitLab 11.6 for project- and group-level clusters. -[cert-manager](https://cert-manager.io/docs/) is a native -Kubernetes certificate management controller that helps with issuing -certificates. Installing cert-manager on your cluster will issue a -certificate by [Let's Encrypt](https://letsencrypt.org/) and ensure that -certificates are valid and up-to-date. +[cert-manager](https://cert-manager.io/docs/) is a native Kubernetes certificate +management controller that helps with issuing certificates. Installing +cert-manager on your cluster issues a certificate by [Let's Encrypt](https://letsencrypt.org/) +and ensures that certificates are valid and up-to-date. The chart used to install this application depends on the version of GitLab used. In: -- GitLab 12.3 and newer, the [jetstack/cert-manager](https://github.com/jetstack/cert-manager) +- GitLab 12.3 and newer, the [`jetstack/cert-manager`](https://github.com/jetstack/cert-manager) chart is used with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/cert_manager/values.yaml) file. -- GitLab 12.2 and older, the [stable/cert-manager](https://github.com/helm/charts/tree/master/stable/cert-manager) +- GitLab 12.2 and older, the [`stable/cert-manager`](https://gi2wthub.com/helm/charts/tree/master/stable/cert-manager) chart was used. -If you have installed cert-manager prior to GitLab 12.3, Let's Encrypt will -[block requests from older versions of cert-manager](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753). +If you installed cert-manager prior to GitLab 12.3, Let's Encrypt +[blocks requests](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753) +from older versions of `cert-manager`. To resolve this: -To resolve this: - -1. Uninstall cert-manager (consider [backing up any additional configuration](https://cert-manager.io/docs/tutorials/backup/)). +1. [Back up any additional configuration](https://cert-manager.io/docs/tutorials/backup/). +1. Uninstall cert-manager. 1. Install cert-manager again. ### GitLab Runner @@ -117,26 +109,21 @@ To resolve this: > - Introduced in GitLab 10.6 for project-level clusters. > - Introduced in GitLab 11.10 for group-level clusters. -[GitLab Runner](https://docs.gitlab.com/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](../../ci/README.md), the open-source continuous integration -service included with GitLab that coordinates the jobs. - -If the project is on GitLab.com, shared runners are available -(the first 2000 minutes are free, you can -[buy more later](../../subscriptions/gitlab_com/index.md#purchase-additional-ci-minutes)) -and you do not have to deploy one if they are enough for your needs. If a -project-specific runner is desired, or there are no shared runners, it is easy -to deploy one. - -Note that the deployed runner will be set as **privileged**, which means it will essentially -have root access to the underlying machine. This is required to build Docker images, -so it is the default. Make sure you read the -[security implications](../project/clusters/index.md#security-implications) +[GitLab Runner](https://docs.gitlab.com/runner/) is the open source project that +is used to run your jobs and send the results back to GitLab. It's used in +conjunction with [GitLab CI/CD](../../ci/README.md), the open-source continuous +integration service included with GitLab that coordinates the jobs. + +If the project is on GitLab.com, [shared runners](../gitlab_com/index.md#shared-runners) +are available. You don't have to deploy one if they are enough for your +needs. If a project-specific runner is desired, or there are no shared runners, +you can deploy one. + +The deployed runner is set as **privileged**. Root access to the underlying +server is required to build Docker images, so it is the default. Be sure to read +the [security implications](../project/clusters/index.md#security-implications) before deploying one. -NOTE: **Note:** The [`runner/gitlab-runner`](https://gitlab.com/gitlab-org/charts/gitlab-runner) chart is used to install this application, using [a preconfigured `values.yaml`](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/blob/master/values.yaml) @@ -147,11 +134,13 @@ file. Customizing the installation by modifying this file is not supported. > - Introduced in GitLab 10.2 for project-level clusters. > - Introduced in GitLab 11.6 for group-level clusters. -[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) provides load balancing, SSL termination, and name-based virtual hosting +[Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) +provides load balancing, SSL termination, and name-based virtual hosting out of the box. 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. -The Ingress Controller installed is [Ingress-NGINX](https://kubernetes.io/docs/concepts/services-networking/ingress/), +The Ingress Controller installed is +[Ingress-NGINX](https://kubernetes.io/docs/concepts/services-networking/ingress/), which is supported by the Kubernetes community. NOTE: **Note:** @@ -159,10 +148,10 @@ With the following procedure, a load balancer must be installed in your cluster to obtain the endpoint. You can use either Ingress, or Knative's own load balancer ([Istio](https://istio.io)) if using Knative. -In order to publish your web application, you first need to find the endpoint which will be either an IP +To publish your web application, you first need to find the endpoint, which is either an IP address or a hostname associated with your load balancer. -To install it, click on the **Install** button for Ingress. GitLab will attempt +To install it, click on the **Install** button for Ingress. GitLab attempts to determine the external endpoint and it should be available within a few minutes. #### Determining the external endpoint automatically @@ -178,11 +167,15 @@ using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: -1. Check your [Kubernetes cluster on Google Kubernetes Engine](https://console.cloud.google.com/kubernetes) to ensure there are no errors on its nodes. -1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) on Google Kubernetes Engine. For more information, see [Resource Quotas](https://cloud.google.com/compute/quotas). -1. Check [Google Cloud's Status](https://status.cloud.google.com/) to ensure they are not having any disruptions. +1. [Examine your Kubernetes cluster](https://console.cloud.google.com/kubernetes) + on Google Kubernetes Engine to ensure there are no errors on its nodes. +1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) + on Google Kubernetes Engine. For more information, see + [Resource Quotas](https://cloud.google.com/compute/quotas). +1. Review [Google Cloud's Status](https://status.cloud.google.com/) for service + disruptions. -Once installed, you may see a `?` for "Ingress IP Address" depending on the +After installing, you may see a `?` for **Ingress IP Address** depending on the cloud provider. For EKS specifically, this is because the ELB is created with a DNS name, not an IP address. If GitLab is still unable to determine the endpoint of your Ingress or Knative application, you can @@ -208,58 +201,58 @@ The output of the following examples will show the external endpoint 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. -If you installed Ingress via the **Applications**, run the following command: +- If you installed Ingress using the **Applications**, run the following + command: -```shell -kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' -``` + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' + ``` -Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: +- Some Kubernetes clusters return a hostname instead, like + [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: -```shell -kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' -``` + ```shell + kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' + ``` -For Istio/Knative, the command will be different: + If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) + is also created, which will incur additional AWS costs. -```shell -kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' -``` +- For Istio/Knative, the command will be different: -Otherwise, you can list the IP addresses of all load balancers: + ```shell + kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` -```shell -kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' -``` +- Otherwise, you can list the IP addresses of all load balancers: -NOTE: **Note:** -If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) -will also be created, which will incur additional AWS costs. + ```shell + kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' + ``` -NOTE: **Note:** -You may see a trailing `%` on some Kubernetes versions, **do not include it**. +You may see a trailing `%` on some Kubernetes versions. Do not include it. -The Ingress is now available at this address and will route incoming requests to -the proper service based on the DNS name in the request. To support this, a -wildcard DNS CNAME record should be created for the desired domain name. For example, +The Ingress is now available at this address, and routes incoming requests to +the proper service based on the DNS name in the request. To support this, create +a wildcard DNS CNAME record for the desired domain name. For example, `*.myekscluster.com` would point to the Ingress hostname obtained earlier. #### Using a static IP By default, an ephemeral external IP address is associated to the cluster's load balancer. If you associate the ephemeral IP with your DNS and the IP changes, -your apps will not be able to be reached, and you'd have to change the DNS -record again. In order to avoid that, you should change it into a static -reserved IP. +your apps won't be reachable, and you'd have to change the DNS record again. +To avoid that, change it into a static reserved IP. Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). #### Pointing your DNS at the external endpoint -Once you've set up the external endpoint, you should associate it with a [wildcard DNS -record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) such as `*.example.com.` -in order to be able to reach your apps. If your external endpoint is an IP address, -use an A record. If your external endpoint is a hostname, use a CNAME record. +After you have set up the external endpoint, associate it with a +[wildcard DNS record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) (such +as `*.example.com.`) to reach your apps. If your external endpoint is an IP +address, use an A record. If your external endpoint is a hostname, use a CNAME +record. #### Web Application Firewall (ModSecurity) @@ -269,16 +262,15 @@ A Web Application Firewall (WAF) examines traffic being sent or received, and can block malicious traffic before it reaches your application. The benefits of a WAF are: -- Real-time security monitoring for your application -- Logging of all your HTTP traffic to the application -- Access control for your application -- Highly configurable logging and blocking rules +- Real-time security monitoring for your application. +- Logging of all your HTTP traffic to the application. +- Access control for your application. +- Highly configurable logging and blocking rules. -Out of the box, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/). - -ModSecurity is a toolkit for real-time web application monitoring, logging, -and access control. With GitLab's offering, the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), -which provides generic attack detection capabilities, is automatically applied. +By default, GitLab provides you with a WAF known as [`ModSecurity`](https://www.modsecurity.org/), +which is a toolkit for real-time web application monitoring, logging, and access +control. GitLab's offering applies the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), +which provides generic attack detection capabilities. This feature: @@ -299,57 +291,61 @@ There is a small performance overhead by enabling ModSecurity. If this is considered significant for your application, you can disable ModSecurity's rule engine for your deployed application in any of the following ways: -1. Setting [the deployment variable](../../topics/autodevops/index.md) -`AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off`. This will prevent ModSecurity -from processing any requests for the given application or environment. - -1. Switching its respective toggle to the disabled position and applying changes through the **Save changes** button. This will reinstall -Ingress with the recent changes. +1. Set [the deployment variable](../../topics/autodevops/index.md) + `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off` to prevent ModSecurity + from processing any requests for the given application or environment. +1. Switch its respective toggle to the disabled position, and then apply changes + by selecting **Save changes** to reinstall Ingress with the recent changes. ![Disabling WAF](../../topics/web_application_firewall/img/guide_waf_ingress_save_changes_v12_10.png) ##### Logging and blocking modes To help you tune your WAF rules, you can globally set your WAF to either -**Logging** or **Blocking** mode: +*Logging* or *Blocking* mode: -- **Logging mode** - Allows traffic matching the rule to pass, and logs the event. -- **Blocking mode** - Prevents traffic matching the rule from passing, and logs the event. +- *Logging mode*: Allows traffic matching the rule to pass, and logs the event. +- *Blocking mode*: Prevents traffic matching the rule from passing, and logs the event. To change your WAF's mode: -1. [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md) if you have not already done so. +1. If you haven't already done so, [install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). 1. Navigate to **Operations > Kubernetes**. 1. In **Applications**, scroll to **Ingress**. 1. Under **Global default**, select your desired mode. -1. Click **Save changes**. +1. Select **Save changes**. ##### WAF version updates -Enabling, disabling, or changing the logging mode for **ModSecurity** is only allowed within same version of [Ingress](#ingress) due to limitations in [Helm](https://helm.sh/) which might be overcome in future releases. +Enabling, disabling, or changing the logging mode for **ModSecurity** is only +allowed within same version of [Ingress](#ingress) due to limitations in +[Helm](https://helm.sh/) which might be overcome in future releases. -**ModSecurity** UI controls are disabled if the version deployed differs from the one available in GitLab, while actions at the [Ingress](#ingress) level, such as uninstalling, can still be performed: +**ModSecurity** user interface controls are disabled if the version deployed +differs from the one available in GitLab, while actions at the [Ingress](#ingress) +level, such as uninstalling, can still be performed: ![WAF settings disabled](../../topics/web_application_firewall/img/guide_waf_ingress_disabled_settings_v12_10.png) -Updating [Ingress](#ingress) to the most recent version enables you to take advantage of bug fixes, security fixes, and performance improvements. To update [Ingress application](#ingress), you must first uninstall it, and then re-install it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). +Update [Ingress](#ingress) to the most recent version to take advantage of bug +fixes, security fixes, and performance improvements. To update the +[Ingress application](#ingress), you must first uninstall it, and then re-install +it as described in [Install ModSecurity](../../topics/web_application_firewall/quick_start_guide.md). ##### Viewing Web Application Firewall traffic > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9. You can view Web Application Firewall traffic by navigating to your project's -**Security & Compliance > Threat Monitoring** page. - -From there, you can see tracked over time: +**Security & Compliance > Threat Monitoring** page. From there, you can see +tracked over time: - The total amount of traffic to your application. - The proportion of traffic that is considered anomalous by the Web Application Firewall's default [OWASP ruleset](https://www.modsecurity.org/CRS/Documentation/). -If a significant percentage of traffic is anomalous, it should be investigated -for potential threats, which can be done by -[examining the Web Application Firewall logs](#web-application-firewall-modsecurity). +If a significant percentage of traffic is anomalous, investigate it for potential threats +by [examining the Web Application Firewall logs](#web-application-firewall-modsecurity). ![Threat Monitoring](img/threat_monitoring_v12_9.png) @@ -358,55 +354,51 @@ for potential threats, which can be done by > - Introduced in GitLab 11.0 for project-level clusters. > - Introduced in GitLab 12.3 for group and instance-level clusters. -[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, +[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. -Authentication will be enabled only for [project -members](../project/members/index.md) for project-level clusters and group -members for group-level clusters with [Developer or -higher](../permissions.md) access to the associated project or group. +The [`jupyter/jupyterhub`](https://jupyterhub.github.io/helm-chart/) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/jupyter/values.yaml) +file. + +Authentication is enabled only for [project members](../project/members/index.md) +for project-level clusters and group members for group-level clusters with +[Developer or higher](../permissions.md) access to the associated project or group. -We use a [custom Jupyter -image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) +GitLab uses a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) that installs additional useful packages on top of the base Jupyter. You will also see ready-to-use DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix). -More information on -creating executable runbooks can be found in [our Runbooks -documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab). Note that +More information on creating executable runbooks can be found in +[our Runbooks documentation](../project/clusters/runbooks/index.md#configure-an-executable-runbook-with-gitlab). Ingress must be installed and have an IP address assigned before JupyterHub can be installed. -NOTE: **Note:** -The [`jupyter/jupyterhub`](https://jupyterhub.github.io/helm-chart/) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/jupyter/values.yaml) -file. - #### Jupyter Git Integration > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28783) in GitLab 12.0 for project-level clusters. > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/32512) in GitLab 12.3 for group and instance-level clusters. -When installing JupyterHub onto your Kubernetes cluster, [JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) -is automatically provisioned and configured using the authenticated user's: +When installing JupyterHub onto your Kubernetes cluster, +[JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) +is provisioned and configured using the authenticated user's: - Name. - Email. - Newly created access token. -JupyterLab's Git extension enables full version control of your notebooks as well as issuance of Git commands within Jupyter. -Git commands can be issued via the **Git** tab on the left panel or via Jupyter's command line prompt. +JupyterLab's Git extension enables full version control of your notebooks, and +issuance of Git commands within Jupyter. You can issue Git commands through the +**Git** tab on the left panel, or through Jupyter's command-line prompt. -NOTE: **Note:** -JupyterLab's Git extension stores the user token in the JupyterHub DB in encrypted format -and in the single user Jupyter instance as plain text. This is because [Git requires storing -credentials as plain text](https://git-scm.com/docs/git-credential-store). Potentially, if -a nefarious user finds a way to read from the file system in the single user Jupyter instance -they could retrieve the token. +JupyterLab's Git extension stores the user token in the JupyterHub DB in encrypted +format, and in the single user Jupyter instance as plain text, because +[Git requires storing credentials as plain text](https://git-scm.com/docs/git-credential-store) +Potentially, if a nefarious user finds a way to read from the file system in the +single-user Jupyter instance, they could retrieve the token. ![Jupyter's Git Extension](img/jupyter-git-extension.gif) @@ -425,18 +417,16 @@ cluster. It is used in conjunction with, and includes [Istio](https://istio.io) to provide an external IP address for all programs hosted by Knative. -You will be prompted to enter a wildcard -domain where your applications will be exposed. Configure your DNS -server to use the external IP address for that domain. For any -application created and installed, they will be accessible as -`<program_name>.<kubernetes_namespace>.<domain_name>`. This will require -your Kubernetes cluster to have [RBAC -enabled](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). - -NOTE: **Note:** The [`knative/knative`](https://storage.googleapis.com/triggermesh-charts) chart is used to install this application. +During installation, you must enter a wildcard domain where your applications +will be exposed. Configure your DNS server to use the external IP address for that +domain. Applications created and installed are accessible as +`<program_name>.<kubernetes_namespace>.<domain_name>`, which requires +your Kubernetes cluster to have +[RBAC enabled](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). + ### Prometheus > - Introduced in GitLab 10.4 for project-level clusters. @@ -451,15 +441,14 @@ GitLab is able to monitor applications automatically, using the memory metrics are automatically collected, and response metrics are retrieved from NGINX Ingress as well. -To enable monitoring, simply install Prometheus into the cluster with the -**Install** button. - -NOTE: **Note:** The [`stable/prometheus`](https://github.com/helm/charts/tree/master/stable/prometheus) chart is used to install this application with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/prometheus/values.yaml) file. +To enable monitoring, install Prometheus into the cluster with the **Install** +button. + ### Crossplane > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/34702) in GitLab 12.5 for project-level clusters. @@ -483,15 +472,14 @@ The Crossplane GitLab-managed application: PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services required by the application via the Auto DevOps pipeline. -For information on configuring Crossplane installed on the cluster, see -[Crossplane configuration](crossplane.md). - -NOTE: **Note:** [`alpha/crossplane`](https://github.com/crossplane/crossplane/tree/v0.4.1/cluster/charts/crossplane) chart v0.4.1 is used to install Crossplane using the [`values.yaml`](https://github.com/crossplane/crossplane/blob/master/cluster/charts/crossplane/values.yaml.tmpl) file. +For information about configuring Crossplane installed on the cluster, see +[Crossplane configuration](crossplane.md). + ### Elastic Stack > Introduced in GitLab 12.7 for project- and group-level clusters. @@ -500,37 +488,33 @@ file. log analysis solution which helps in deep searching, analyzing and visualizing the logs generated from different machines. -GitLab is able to gather logs from pods in your cluster automatically. -Filebeat will run as a DaemonSet on each node in your cluster, and it will ship container logs to Elasticsearch for querying. -GitLab will then connect to Elasticsearch for logs instead of the Kubernetes API, -and you will have access to more advanced querying capabilities. - -Log data is automatically deleted after 30 days using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). +GitLab can gather logs from pods in your cluster. Filebeat runs as a DaemonSet +on each node in your cluster, and ships container logs to Elasticsearch for +querying. GitLab then connects to Elasticsearch for logs, instead of the +Kubernetes API, giving you access to more advanced querying capabilities. Log +data is deleted after 30 days, using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). To enable log shipping: -1. Ensure your cluster contains at least 3 nodes of instance types larger than - `f1-micro`, `g1-small`, or `n1-standard-1`. +1. Ensure your cluster contains at least three nodes of instance types larger + than `f1-micro`, `g1-small`, or `n1-standard-1`. 1. Navigate to **Operations > Kubernetes**. 1. In **Kubernetes Cluster**, select a cluster. -1. In the **Applications** section, find **Elastic Stack** and click **Install**. +1. In the **Applications** section, find **Elastic Stack**, and then select + **Install**. -NOTE: **Note:** The [`gitlab/elastic-stack`](https://gitlab.com/gitlab-org/charts/elastic-stack) chart is used to install this application with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/elastic_stack/values.yaml) -file. +file. The chart deploys three identical Elasticsearch pods which can't be +colocated, and each requires one CPU and 2 GB of RAM, making them +incompatible with clusters containing fewer than three nodes, or consisting of +`f1-micro`, `g1-small`, `n1-standard-1`, or `*-highcpu-2` instance types. NOTE: **Note:** -The chart deploys 3 identical Elasticsearch pods which can't be colocated, and each -requires 1 CPU and 2 GB of RAM, making them incompatible with clusters containing -fewer than 3 nodes or consisting of `f1-micro`, `g1-small`, `n1-standard-1`, or -`*-highcpu-2` instance types. - -NOTE: **Note:** -The Elastic Stack cluster application is intended as a log aggregation solution and is not related to our -[Advanced Search](../search/advanced_global_search.md) functionality, which uses a separate -Elasticsearch cluster. +The Elastic Stack cluster application is intended as a log aggregation solution +and is not related to our [Advanced Search](../search/advanced_global_search.md) +functionality, which uses a separate Elasticsearch cluster. #### Optional: deploy Kibana to perform advanced queries @@ -1280,7 +1264,7 @@ You can check the default [`values.yaml`](https://gitlab.com/gitlab-org/gitlab/- You can customize the installation of Elastic Stack by defining `.gitlab/managed-apps/elastic-stack/values.yaml` file in your cluster management project. Refer to the -[chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for the +[chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for all available configuration options. NOTE: **Note:** @@ -1337,7 +1321,7 @@ You can customize the installation of Fluentd by defining `.gitlab/managed-apps/fluentd/values.yaml` file in your cluster management project. Refer to the [configuration chart for the current development release of Fluentd](https://github.com/helm/charts/tree/master/stable/fluentd#configuration) -for the available configuration options. +for all available configuration options. NOTE: **Note:** The configuration chart link points to the current development release, which @@ -1360,7 +1344,7 @@ knative: You can customize the installation of Knative by defining `.gitlab/managed-apps/knative/values.yaml` file in your cluster management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/knative) -for the available configuration options. +for all available configuration options. Here is an example configuration for Knative: |