diff options
Diffstat (limited to 'doc/user/clusters')
| -rw-r--r-- | doc/user/clusters/agent/index.md | 65 | ||||
| -rw-r--r-- | doc/user/clusters/agent/repository.md | 96 | ||||
| -rw-r--r-- | doc/user/clusters/applications.md | 1271 | ||||
| -rw-r--r-- | doc/user/clusters/cost_management.md | 8 | ||||
| -rw-r--r-- | doc/user/clusters/crossplane.md | 2 | ||||
| -rw-r--r-- | doc/user/clusters/environments.md | 2 | ||||
| -rw-r--r-- | doc/user/clusters/management_project.md | 14 |
7 files changed, 785 insertions, 673 deletions
diff --git a/doc/user/clusters/agent/index.md b/doc/user/clusters/agent/index.md index 74c679d9bb9..5963485aebc 100644 --- a/doc/user/clusters/agent/index.md +++ b/doc/user/clusters/agent/index.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Kubernetes Agent **(PREMIUM ONLY)** @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [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). -CAUTION: **Warning:** +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) @@ -56,6 +56,12 @@ There are several components that work in concert for the Agent to accomplish Gi These repositories might be the same GitLab project or separate projects. +NOTE: +GitLab recommends you use the same GitLab project for the agent configuration +and manifest repositories. Our backlog contains issues for adding support for +[private manifest repositories outside of the configuration project](https://gitlab.com/gitlab-org/gitlab/-/issues/220912) and +[group level agents](https://gitlab.com/gitlab-org/gitlab/-/issues/283885). + For more details, 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. ## Get started with GitOps and the GitLab Agent @@ -82,8 +88,8 @@ Upgrade your agent installations together with GitLab upgrades. To decide which 1. Open the [GITLAB_KAS_VERSION](https://gitlab.com/gitlab-org/gitlab/-/blob/master/GITLAB_KAS_VERSION) file from the GitLab Repository, which contains the latest `agentk` version associated with the `master` branch. 1. Change the `master` branch and select the Git tag associated with your version. For instance, you could change it to GitLab [v13.5.3-ee release](https://gitlab.com/gitlab-org/gitlab/-/blob/v13.5.3-ee/GITLAB_KAS_VERSION) -The available `agentk` versions can be found in -[its container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/eyJuYW1lIjoiZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9hZ2VudGsiLCJ0YWdzX3BhdGgiOiIvZ2l0bGFiLW9yZy9jbHVzdGVyLWludGVncmF0aW9uL2dpdGxhYi1hZ2VudC9yZWdpc3RyeS9yZXBvc2l0b3J5LzEyMjMyMDUvdGFncz9mb3JtYXQ9anNvbiIsImlkIjoxMjIzMjA1LCJjbGVhbnVwX3BvbGljeV9zdGFydGVkX2F0IjpudWxsfQ==). +The available `agentk` and `kas` versions can be found in +[the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). ### Install the Kubernetes Agent Server @@ -93,7 +99,7 @@ chart](https://gitlab.com/gitlab-org/charts/gitlab). If you don't already have GitLab installed, please refer to our [installation documentation](https://docs.gitlab.com/ee/install/README.html). -NOTE: **Note:** +NOTE: GitLab plans to include the KAS on [GitLab.com](https://gitlab.com/groups/gitlab-org/-/epics/3834). #### Install with Omnibus @@ -161,23 +167,9 @@ gitops: ``` GitLab [versions 13.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) also -supports manifest projects containing multiple directories (or subdirectories) -of YAML files. To use multiple YAML files, specify a `paths` attribute: - -```yaml -gitops: - manifest_projects: - - id: "path-to/your-manifest-project-number1" - paths: - # Read all .yaml files from team1/app1 directory. - # See https://github.com/bmatcuk/doublestar#about and - # https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match for globbing rules. - - glob: '/team1/app1/*.yaml' - # Read all .yaml files from team2/apps and all subdirectories - - glob: '/team2/apps/**/*.yaml' - # If 'paths' is not specified or is an empty list, the configuration below is used - - glob: '/**/*.{yaml,yml,json}' -``` +supports manifest projects containing +multiple directories (or subdirectories) of YAML files. For more information see our +documentation on the [Kubernetes Agent configuration respository](repository.md). ### Create an Agent record in GitLab @@ -223,7 +215,7 @@ the Agent in subsequent steps. You can create an Agent record either: } ``` - NOTE: **Note:** + NOTE: GraphQL only displays the token one time after creating it. If you are new to using the GitLab GraphQL API, refer to the @@ -257,11 +249,14 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. Select the option appropriate for your cluster configuration and GitLab architecture: - The `wss` scheme (an encrypted WebSockets connection) is specified by default - after you install `gitlab-kas` sub-chart or enable `kas` for Omnibus GitLab. - In this case, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent` as + after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab. + When using the sub-chart, you must set `wss://kas.host.tld:443` as + `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation. + When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent` as `kas-address`, where `GitLab.host.tld` is your GitLab hostname. - - Specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`) + - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) to use an unencrypted WebSockets connection. + When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent`). - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. In this case, you may specify `kas-address` value as `grpc://gitlab-kas.<your-namespace>:5005`) to use gRPC directly, where `gitlab-kas` @@ -270,6 +265,10 @@ example [`resources.yml` file](#example-resourcesyml-file) in the following ways Follow the [Support TLS for gRPC communication issue](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/issues/7) for progress updates. + - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the `kas-address` for `wss` and `ws` schemes to whatever you need. + Check the [chart's KAS Ingress docs](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) + to learn more about it. + - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. - If you defined your own secret name, replace `gitlab-agent-token` with your secret name in the `secretName:` section. @@ -317,7 +316,8 @@ spec: args: - --token-file=/config/token - --kas-address - - wss://gitlab.host.tld:443/-/kubernetes-agent + - wss://kas.host.tld:443 # change this line for the one below if using Omnibus GitLab + # - wss://gitlab.host.tld:443/-/kubernetes-agent volumeMounts: - name: token-volume mountPath: /config @@ -392,9 +392,12 @@ subjects: 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. Only public projects are supported as -manifest projects. Support for private projects is planned in the issue -[Agent authorization for private manifest projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). +templating engine or other means. + +The agent is authorized to download manifests for the configuration +project, and public projects. Support for other private projects is +planned in the issue [Agent authorization for private manifest +projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). Each time you commit and push a change to this file, the Agent logs the change: @@ -548,7 +551,7 @@ issue is in progress, directly edit the deployment with the `kubectl edit deployment gitlab-kas` command, and change `--listen-websocket=true` to `--listen-websocket=false`. After running that command, you should be able to use `grpc://gitlab-kas.<YOUR-NAMESPACE>:5005`. -#### Agent logs - Decompressor is not installed for grpc-encoding +### Agent logs - Decompressor is not installed for grpc-encoding ```plaintext {"level":"warn","time":"2020-11-05T05:25:46.916Z","msg":"GetConfiguration.Recv failed","error":"rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""} diff --git a/doc/user/clusters/agent/repository.md b/doc/user/clusters/agent/repository.md new file mode 100644 index 00000000000..b71bbc29ef9 --- /dev/null +++ b/doc/user/clusters/agent/repository.md @@ -0,0 +1,96 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +--- + +# Kubernetes Agent configuration repository **(PREMIUM ONLY)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7. +> - It's disabled on GitLab.com. Rolling this feature out to GitLab.com is [planned](https://gitlab.com/groups/gitlab-org/-/epics/3834). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +The [GitLab Kubernetes Agent integration](index.md) supports hosting your configuration for +multiple GitLab Kubernetes Agents in a single repository. These agents can be running +in the same cluster or in multiple clusters, and potentially with more than one Agent per cluster. + +The Agent bootstraps with the GitLab installation URL and an authentication token, +and you provide the rest of the configuration in your repository, following +Infrastructure as Code (IaaC) best practices. + +A minimal repository layout looks like this, with `my_agent_1` as the name +of your Agent: + +```plaintext +|- .gitlab + |- agents + |- my_agent_1 + |- config.yaml +``` + +## Synchronize manifest projects + +Your `config.yaml` file contains a `gitops` section, which contains a `manifest_projects` +section. Each `id` in the `manifest_projects` section is the path to a Git repository +with Kubernetes resource definitions in YAML or JSON format. The Agent monitors +each project you declare, and when the project changes, GitLab deploys the changes +using the Agent. + +To use multiple YAML files, specify a `paths` attribute in the `gitops` section. + +By default, the Agent monitors all +[Kubernetes object types](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields). +You can exclude some types of resources from monitoring. This enables you to reduce +the permissions needed by the GitOps feature, through `resource_exclusions`. + +To enable a specific named resource, first use `resource_inclusions` to enable desired resources. +The following file excerpt includes specific `api_groups` and `kinds`. The `resource_exclusions` +which follow excludes all other `api_groups` and `kinds`: + +```yaml +gitops: + # Manifest projects are watched by the agent. Whenever a project changes, + # GitLab deploys the changes using the agent. + manifest_projects: + # No authentication mechanisms are currently supported. + # The `id` is a path to a Git repository with Kubernetes resource definitions + # in YAML or JSON format. + - id: gitlab-org/cluster-integration/gitlab-agent + # Holds the only API groups and kinds of resources that gitops will monitor. + # Inclusion rules are evaluated first, then exclusion rules. + # If there is still no match, resource is monitored. + # Resources: https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields + # Groups: https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-groups-and-versioning + resource_inclusions: + - api_groups: + - apps + kinds: + - '*' + - api_groups: + - '' + kinds: + - 'ConfigMap' + # Holds the API groups and kinds of resources to exclude from gitops watch. + # Inclusion rules are evaluated first, then exclusion rules. + # If there is still no match, resource is monitored. + resource_exclusions: + - api_groups: + - '*' + kinds: + - '*' + # Namespace to use if not set explicitly in object manifest. + default_namespace: my-ns + # Paths inside of the repository to scan for manifest files. + # Directories with names starting with a dot are ignored. + paths: + # Read all .yaml files from team1/app1 directory. + # See https://github.com/bmatcuk/doublestar#about and + # https://pkg.go.dev/github.com/bmatcuk/doublestar/v2#Match for globbing rules. + - glob: '/team1/app1/*.yaml' + # Read all .yaml files from team2/apps and all subdirectories + - glob: '/team2/apps/**/*.yaml' + # If 'paths' is not specified or is an empty list, the configuration below is used + - glob: '/**/*.{yaml,yml,json}' +``` diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 67a53fa773f..53be7e995d5 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # GitLab Managed Apps @@ -10,595 +10,16 @@ GitLab provides **GitLab Managed Apps** 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 that can installed with [one-click](#install-with-one-click) or [using CI/CD](#install-using-gitlab-cicd-alpha). +You can install them after you [create a cluster](../project/clusters/add_remove_clusters.md). +GitLab provides GitLab Managed Apps [using CI/CD](#install-using-gitlab-cicd). +GitLab Managed Apps with [one-click installations](#install-with-one-click) +have been deprecated, and are scheduled for removal in GitLab 14.0. -## Install with one click - -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 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. - -You can install the following applications with one click: - -- [Helm](#helm) -- [Ingress](#ingress) -- [cert-manager](#cert-manager) -- [Prometheus](#prometheus) -- [GitLab Runner](#gitlab-runner) -- [JupyterHub](#jupyterhub) -- [Knative](#knative) -- [Crossplane](#crossplane) -- [Elastic Stack](#elastic-stack) -- [Fluentd](#fluentd) - -With the exception of Knative, the applications are installed in a dedicated -namespace called `gitlab-managed-apps`. - -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. -For updates, see the [issue tracking progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411). - -CAUTION: **Caution:** -If you have an existing Kubernetes cluster with Helm already installed, -you should be careful as GitLab cannot detect it. In this case, installing -Helm with the applications results 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. -> - Introduced in GitLab 11.6 for group-level clusters. -> - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 and later. -> - [Uses Helm 3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46267) for clusters created with GitLab 13.6 and later. - -[Helm](https://helm.sh/docs/) is a package manager for Kubernetes and is -used to install the GitLab-managed apps. GitLab runs each `helm` command -in a pod within the `gitlab-managed-apps` namespace inside the cluster. - -- For clusters created on GitLab 13.6 and newer, GitLab uses Helm 3 to manage - applications. -- For clusters created on versions of GitLab prior to 13.6, GitLab uses - Helm 2 with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. - Prior to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), - GitLab used an in-cluster Tiller server in the `gitlab-managed-apps` - namespace. You can safely remove this server after upgrading to GitLab 13.2 - or newer. - -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. - -#### Upgrade a cluster to Helm 3 - -GitLab does not currently offer a way to migrate existing application management -on existing clusters from Helm 2 to Helm 3. To migrate a cluster to Helm 3: - -1. Uninstall all applications on your cluster. -1. [Remove the cluster integration](../project/clusters/add_remove_clusters.md#removing-integration). -1. [Re-add the cluster](../project/clusters/add_remove_clusters.md#existing-kubernetes-cluster) as - an existing cluster. - -### cert-manager - -> 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 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) - 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) - chart was used. - -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: - -1. [Back up any additional configuration](https://cert-manager.io/docs/tutorials/backup/). -1. Uninstall cert-manager. -1. Install cert-manager again. - -### GitLab Runner - -> - 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'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's the default. Be sure to read -the [security implications](../project/clusters/index.md#security-implications) -before deploying one. - -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) -file. Customizing the installation by modifying this file is not supported. This -also means you cannot modify `config.toml` file for this Runner. If you want to -have that possibility and still deploy Runner in Kubernetes, consider using the -[Cluster management project](management_project.md) or installing Runner manually -via [GitLab Runner Helm Chart](https://docs.gitlab.com/runner/install/kubernetes.html). - -### Ingress - -> - 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 -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/), -which is supported by the Kubernetes community. - -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. - -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 attempts -to determine the external endpoint and it should be available within a few minutes. - -#### Determining the external endpoint automatically - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17052) in GitLab 10.6. - -After you install Ingress, the external endpoint should be available within a few minutes. - -TIP: **Tip:** -This endpoint can be used for the -[Auto DevOps base domain](../../topics/autodevops/index.md#auto-devops-base-domain) -using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. - -If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: - -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. - -The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) -chart is used to install this application with a -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml) -file. - -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 -[determine it manually](#determining-the-external-endpoint-manually). - -#### Determining the external endpoint manually - -If the cluster is on GKE, click the **Google Kubernetes Engine** link in the -**Advanced settings**, or go directly to the -[Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) -and select the proper project and cluster. Then click **Connect** and execute -the `gcloud` command in a local terminal or using the **Cloud Shell**. - -If the cluster is not on GKE, follow the specific instructions for your -Kubernetes provider to configure `kubectl` with the right credentials. -The output of the following examples 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 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}' - ``` - -- 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}' - ``` - - If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) - is also created, which will incur additional AWS costs. - -- For Istio/Knative, the command is different: - - ```shell - kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' - ``` - -- Otherwise, you can list the IP addresses of all load balancers: - - ```shell - kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' - ``` - -You may see a trailing `%` on some Kubernetes versions. Do not include it. - -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 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 - -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) - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7. - -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. - -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: - -- Runs in "Detection-only mode" unless configured otherwise. -- Is viewable by checking your Ingress controller's `modsec` log for rule violations. - For example: - - ```shell - kubectl -n gitlab-managed-apps logs -l app=nginx-ingress,component=controller -c modsecurity-log -f - ``` - -To enable WAF, switch its respective toggle to the enabled position when installing or updating [Ingress application](#ingress). - -If this is your first time using GitLab's WAF, we recommend you follow the -[quick start guide](../../topics/web_application_firewall/quick_start_guide.md). - -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. 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. - - - -##### Logging and blocking modes - -To help you tune your WAF rules, you can globally set your WAF to either -*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. - -To change your WAF's mode: - -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. 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. - -**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: - - - -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: - -- The total amount of traffic to your application. -- The proportion of traffic that's 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, investigate it for potential threats -by [examining the Web Application Firewall logs](#web-application-firewall-modsecurity). - - - -### JupyterHub - -> - 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, -visualization, and machine learning. - -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. - -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. Ready-to-use -DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix) -are also available. - -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. - -#### 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 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, 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. - -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. - - - -You can clone repositories from the files tab in Jupyter: - - - -### Knative - -> - Introduced in GitLab 11.5 for project-level clusters. -> - Introduced in GitLab 12.3 for group- and instance-level clusters. - -[Knative](https://cloud.google.com/knative/) provides a platform to -create, deploy, and manage serverless workloads from a Kubernetes -cluster. It's used in conjunction with, and includes -[Istio](https://istio.io) to provide an external IP address for all -programs hosted by Knative. - -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. -> - Introduced in GitLab 11.11 for group-level clusters. - -[Prometheus](https://prometheus.io/docs/introduction/overview/) is an -open-source monitoring and alerting system useful to supervise your -deployed applications. - -GitLab is able to monitor applications by using the -[Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and -memory metrics are collected, and response metrics are also retrieved -from NGINX Ingress. - -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. - -[Crossplane](https://crossplane.github.io/docs/v0.9/) is a multi-cloud control plane useful for -managing applications and infrastructure across multiple clouds. It extends the -Kubernetes API using: - -- Custom resources. -- Controllers that watch those custom resources. - -Crossplane allows provisioning and lifecycle management of infrastructure components -across cloud providers in a uniform manner by abstracting cloud provider-specific -configurations. - -The Crossplane GitLab-managed application: - -- Installs Crossplane with a provider of choice on a Kubernetes cluster attached to the - project repository. -- Can then be used to provision infrastructure or managed applications such as - PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services - required by the application with the Auto DevOps pipeline. - -[`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. - -[Elastic Stack](https://www.elastic.co/elastic-stack) is a complete end-to-end -log analysis solution which helps in deep searching, analyzing and visualizing the logs -generated from different machines. - -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). - -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. - -To enable log shipping: - -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 then select - **Install**. - -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. 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. - -#### Optional: deploy Kibana to perform advanced queries - -If you are an advanced user and have direct access to your Kubernetes cluster using `kubectl` and `helm`, you can deploy Kibana manually. - -The following assumes that `helm` has been [initialized](https://v2.helm.sh/docs/helm/) with `helm init`. - -Save the following to `kibana.yml`: - -```yaml -elasticsearch: - enabled: false - -filebeat: - enabled: false - -kibana: - enabled: true - elasticsearchHosts: http://elastic-stack-elasticsearch-master.gitlab-managed-apps.svc.cluster.local:9200 -``` - -Then install it on your cluster: - -```shell -helm repo add gitlab https://charts.gitlab.io -helm install --name kibana gitlab/elastic-stack --values kibana.yml -``` - -To access Kibana, forward the port to your local machine: - -```shell -kubectl port-forward svc/kibana-kibana 5601:5601 -``` - -Then, you can visit Kibana at `http://localhost:5601`. - -### Fluentd - -> Introduced in GitLab 12.10 for project- and group-level clusters. - -[Fluentd](https://www.fluentd.org/) is an open source data collector, which enables -you to unify the data collection and consumption to better use and understand -your data. Fluentd sends logs in syslog format. - -To enable Fluentd: - -1. Navigate to **Operations > Kubernetes** and click - **Applications**. Enter a host, port, and protocol - for sending the WAF logs with syslog. -1. Provide the host domain name or URL in **SIEM Hostname**. -1. Provide the host port number in **SIEM Port**. -1. Select a **SIEM Protocol**. -1. Select at least one of the available logs (such as WAF or Cilium). -1. Click **Save changes**. - - - -### Future apps - -Interested in contributing a new GitLab managed app? Visit the -[development guidelines page](../../development/kubernetes.md#gitlab-managed-apps) -to get started. - -## Install using GitLab CI/CD (alpha) +## Install using GitLab CI/CD > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20822) in GitLab 12.6. -CAUTION: **Warning:** +WARNING: This is an _alpha_ feature, and is subject to change at any time without prior notice. @@ -664,14 +85,15 @@ applications you have configured. In case of pipeline failure, the output of the [Helm Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary is saved as a [CI job artifact](../../ci/pipelines/job_artifacts.md). +#### Usage in GitLab versions earlier than 13.5 + For GitLab versions 13.5 and below, the Ingress, Fluentd, Prometheus, -and Sentry apps are fetched from the central Helm [stable -repository](https://kubernetes-charts.storage.googleapis.com/), which -will be [deleted](https://github.com/helm/charts#deprecation-timeline) -on November 13, 2020. This will cause the installation CI/CD pipeline to +and Sentry apps are fetched from the central Helm +[stable repository](https://kubernetes-charts.storage.googleapis.com/). This repository +[was deleted](https://github.com/helm/charts#deprecation-timeline) +on November 13, 2020. This causes the installation CI/CD pipeline to fail. Upgrade to GitLab 13.6, or alternatively, you can -use the following `.gitlab-ci.yml`, which has been tested on GitLab -13.5: +use the following `.gitlab-ci.yml`, which has been tested on GitLab 13.5: ```yaml include: @@ -738,7 +160,7 @@ for the available configuration options. Support for installing the Ingress managed application is provided by the GitLab Configure group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). ### Install cert-manager using GitLab CI/CD @@ -782,7 +204,7 @@ Support for installing the Cert Manager managed application is provided by the GitLab Configure group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). ### Install Sentry using GitLab CI/CD @@ -809,7 +231,7 @@ for the available configuration options. We recommend you pay close attention to the following configuration options: - `email`. Needed to invite users to your Sentry instance and to send error emails. -- `user`. Where you can set the login credentials for the default admin user. +- `user`. Where you can set the login credentials for the default administrator user. - `postgresql`. For a PostgreSQL password that can be used when running future updates. When upgrading, it's important to provide the existing PostgreSQL password (given @@ -851,7 +273,7 @@ Support for installing the Sentry managed application is provided by the GitLab Health group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Health group](https://about.gitlab.com/handbook/product/product-categories/#health-group). +[Health group](https://about.gitlab.com/handbook/product/categories/#health-group). ### Install PostHog using GitLab CI/CD @@ -867,8 +289,8 @@ posthog: You can customize the installation of PostHog by defining `.gitlab/managed-apps/posthog/values.yaml` in your cluster management project. Refer to the -[Configuration section of the PostHog chart's README](https://github.com/PostHog/charts/tree/master/charts/posthog) -for the available configuration options. +[Configuration section](https://github.com/PostHog/charts/tree/master/charts/posthog) +of the PostHog chart's README for the available configuration options. You must provide a PostgreSQL password in `postgresql.postgresqlPassword` to avoid authentication errors. Read the @@ -922,13 +344,13 @@ prometheus: You can customize the installation of Prometheus by defining `.gitlab/managed-apps/prometheus/values.yaml` in your cluster management project. Refer to the -[Configuration section of the Prometheus chart's README](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) -for the available configuration options. +[Configuration section](https://github.com/helm/charts/tree/master/stable/prometheus#configuration) +of the Prometheus chart's README for the available configuration options. Support for installing the Prometheus managed application is provided by the GitLab APM group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group). +least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). ### Install GitLab Runner using GitLab CI/CD @@ -966,7 +388,7 @@ Support for installing the GitLab Runner managed application is provided by the GitLab Runner group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Runner group](https://about.gitlab.com/handbook/product/product-categories/#runner-group). +[Runner group](https://about.gitlab.com/handbook/product/categories/#runner-group). ### Install Cilium using GitLab CI/CD @@ -977,7 +399,8 @@ support for [NetworkPolicy](https://kubernetes.io/docs/concepts/services-network resources. For more information, see [Network Policies](../../topics/autodevops/stages.md#network-policy). <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, see the [Container Network Security Demo for GitLab 12.8](https://www.youtube.com/watch?v=pgUEdhdhoUI). +For an overview, see the +[Container Network Security Demo for GitLab 12.8](https://www.youtube.com/watch?v=pgUEdhdhoUI). Enable Cilium in the `.gitlab/managed-apps/config.yaml` file to install it: @@ -1008,14 +431,14 @@ You can check Cilium's installation status on the cluster management page: - [Group-level cluster](../group/clusters/index.md): Navigate to your group's **Kubernetes** page. -CAUTION: **Caution:** +WARNING: Installation and removal of the Cilium requires a **manual** [restart](https://docs.cilium.io/en/stable/gettingstarted/k8s-install-gke/#restart-unmanaged-pods) of all affected pods in all namespaces to ensure that they are [managed](https://docs.cilium.io/en/v1.8/operations/troubleshooting/#ensure-managed-pod) by the correct networking plugin. -NOTE: **Note:** +NOTE: Major upgrades might require additional setup steps. For more information, see the official [upgrade guide](https://docs.cilium.io/en/v1.8/operations/upgrade/). @@ -1050,9 +473,9 @@ agent: enabled: false ``` -The [Hubble](https://github.com/cilium/hubble) monitoring daemon is -enabled by default and it's set to collect per namespace flow -metrics. This metrics are accessible on the [Threat Monitoring](../application_security/threat_monitoring/index.md) +The [Hubble](https://github.com/cilium/hubble) monitoring daemon is enabled by default +and it's set to collect per namespace flow metrics. This metrics are accessible on the +[Threat Monitoring](../application_security/threat_monitoring/index.md) dashboard. You can disable Hubble by adding the following to `.gitlab/managed-apps/cilium/values.yaml`: @@ -1078,7 +501,7 @@ Support for installing the Cilium managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ### Install Falco using GitLab CI/CD @@ -1103,7 +526,7 @@ management project. Refer to the [Falco chart](https://github.com/falcosecurity/charts/tree/master/falco) for the available configuration options. -CAUTION: **Caution:** +WARNING: By default eBPF support is enabled and Falco uses an [eBPF probe](https://falco.org/docs/event-sources/drivers/#using-the-ebpf-probe) to pass system calls to user space. If your cluster doesn't support this, you can @@ -1120,8 +543,8 @@ isn't pre-compiled, you may need to manually prepare the kernel module or eBPF p [`driverkit`](https://github.com/falcosecurity/driverkit#against-a-kubernetes-cluster) and install it on each cluster node. -By default, Falco is deployed with a limited set of rules. To add more rules, add the following to -`.gitlab/managed-apps/falco/values.yaml` (you can get examples from +By default, Falco is deployed with a limited set of rules. To add more rules, add +the following to `.gitlab/managed-apps/falco/values.yaml` (you can get examples from [Cloud Native Security Hub](https://securityhub.dev/)): ```yaml @@ -1174,7 +597,7 @@ Support for installing the Falco managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ### Install Vault using GitLab CI/CD @@ -1256,12 +679,12 @@ server: } ``` -Once you have successfully installed Vault, you must +After you have successfully installed Vault, you must [initialize the Vault](https://learn.hashicorp.com/tutorials/vault/getting-started-deploy#initializing-the-vault) and obtain the initial root token. You need access to your Kubernetes cluster that Vault has been deployed into in order to do this. To initialize the Vault, get a shell to one of the Vault pods running inside Kubernetes (typically this is done -by using the `kubectl` command line tool). Once you have a shell into the pod, +by using the `kubectl` command line tool). After you have a shell into the pod, run the `vault operator init` command: ```shell @@ -1276,7 +699,7 @@ Support for installing the Vault managed application is provided by the GitLab Release Management group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Release Management group](https://about.gitlab.com/handbook/product/product-categories/#release-management-group). +[Release Management group](https://about.gitlab.com/handbook/product/categories/#release-management-group). ### Install JupyterHub using GitLab CI/CD @@ -1333,7 +756,7 @@ Support for installing the JupyterHub managed application is provided by the Git If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). ### Install Elastic Stack using GitLab CI/CD @@ -1361,7 +784,7 @@ management project. Refer to the [chart](https://gitlab.com/gitlab-org/charts/elastic-stack) for all available configuration options. -NOTE: **Note:** +NOTE: In this alpha implementation of installing Elastic Stack through CI, reading the environment logs through Elasticsearch is unsupported. This is supported if [installed with the UI](#elastic-stack). @@ -1369,7 +792,7 @@ environment logs through Elasticsearch is unsupported. This is supported if Support for installing the Elastic Stack managed application is provided by the GitLab APM group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at -least 2 people from the [APM group](https://about.gitlab.com/handbook/product/product-categories/#apm-group). +least 2 people from the [APM group](https://about.gitlab.com/handbook/product/categories/#apm-group). ### Install Crossplane using GitLab CI/CD @@ -1394,8 +817,9 @@ we set for this chart. You can customize the installation of Crossplane by defining `.gitlab/managed-apps/crossplane/values.yaml` file in your cluster management project. Refer to the -[chart](https://github.com/crossplane/crossplane/tree/master/cluster/charts/crossplane#configuration) for the -available configuration options. Note that this link points to the documentation for the current development release, which may differ from the version you have installed. +[chart](https://github.com/crossplane/crossplane/tree/master/cluster/charts/crossplane#configuration) +for the available configuration options. Note that this link points to the documentation +for the current development release, which may differ from the version you have installed. Support for the Crossplane managed application is provided by the Crossplane team. If you run into issues, @@ -1419,8 +843,8 @@ You can also review the default values set for this chart in the 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 all available configuration options. +[configuration chart](https://github.com/helm/charts/tree/master/stable/fluentd#configuration) +for the current development release of Fluentd for all available configuration options. The configuration chart link points to the current development release, which may differ from the version you have installed. To ensure compatibility, switch @@ -1430,7 +854,7 @@ Support for installing the Fluentd managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ### Install Knative using GitLab CI/CD @@ -1459,11 +883,12 @@ Support for installing the Knative managed application is provided by the GitLab Configure group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Configure group](https://about.gitlab.com/handbook/product/product-categories/#configure-group). +[Configure group](https://about.gitlab.com/handbook/product/categories/#configure-group). #### Knative Metrics -GitLab provides [Invocation Metrics](../project/clusters/serverless/index.md#invocation-metrics) for your functions. To collect these metrics, you must have: +GitLab provides [Invocation Metrics](../project/clusters/serverless/index.md#invocation-metrics) +for your functions. To collect these metrics, you must have: 1. Knative and Prometheus managed applications installed on your cluster. 1. Manually applied the custom metrics on your cluster by running the following command: @@ -1520,7 +945,8 @@ podAnnotations: ``` The only information to be changed here is the profile name which is `profile-one` -in this example. Refer to the [AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod) +in this example. Refer to the +[AppArmor tutorial](https://kubernetes.io/docs/tutorials/clusters/apparmor/#securing-a-pod) for more information on how AppArmor is integrated in Kubernetes. #### Using PodSecurityPolicy in your deployments @@ -1563,13 +989,600 @@ Support for installing the AppArmor managed application is provided by the GitLab Container Security group. If you run into unknown issues, [open a new issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new), and ping at least 2 people from the -[Container Security group](https://about.gitlab.com/handbook/product/product-categories/#container-security-group). +[Container Security group](https://about.gitlab.com/handbook/product/categories/#container-security-group). ## Browse applications logs > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/36769) in GitLab 13.2. -Logs produced by pods running **GitLab Managed Apps** can be browsed using [**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). +Logs produced by pods running **GitLab Managed Apps** can be browsed using +[**Log Explorer**](../project/clusters/kubernetes_pod_logs.md). + +## Install with one click + +WARNING: +The one click installation method is scheduled for removal in GitLab 14.0. The removal +of this feature from GitLab does not affect installed applications to avoid breaking +changes. Following GitLab 14.0, users can take ownership of already installed applications +using our documentation. + +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 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. + +You can install the following applications with one click: + +- [Helm](#helm) +- [Ingress](#ingress) +- [cert-manager](#cert-manager) +- [Prometheus](#prometheus) +- [GitLab Runner](#gitlab-runner) +- [JupyterHub](#jupyterhub) +- [Knative](#knative) +- [Crossplane](#crossplane) +- [Elastic Stack](#elastic-stack) +- [Fluentd](#fluentd) + +With the exception of Knative, the applications are installed in a dedicated +namespace called `gitlab-managed-apps`. + +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. +For updates, see the [issue tracking progress](https://gitlab.com/gitlab-org/gitlab/-/issues/24411). + +WARNING: +If you have an existing Kubernetes cluster with Helm already installed, +you should be careful as GitLab cannot detect it. In this case, installing +Helm with the applications results 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. +> - Introduced in GitLab 11.6 for group-level clusters. +> - [Uses a local Tiller](https://gitlab.com/gitlab-org/gitlab/-/issues/209736) in GitLab 13.2 and later. +> - [Uses Helm 3](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46267) for clusters created with GitLab 13.6 and later. +> - [Offers legacy Tiller removal](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/47457) in GitLab 13.7 and later. + +[Helm](https://helm.sh/docs/) is a package manager for Kubernetes and is +used to install the GitLab-managed apps. GitLab runs each `helm` command +in a pod in the `gitlab-managed-apps` namespace inside the cluster. + +- For clusters created on GitLab 13.6 and newer, GitLab uses Helm 3 to manage + applications. +- For clusters created on versions of GitLab prior to 13.6, GitLab uses Helm 2 + with a local [Tiller](https://v2.helm.sh/docs/glossary/#tiller) server. Prior + to [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/209736), GitLab + used an in-cluster Tiller server in the `gitlab-managed-apps` namespace. You + can safely uninstall the server from the GitLab application page if you have + previously installed it. This doesn't affect your other applications. + +The GitLab Helm integration does not support installing applications behind a proxy, +but a [workaround](../../topics/autodevops/index.md#install-applications-behind-a-proxy) +is available. + +#### Upgrade a cluster to Helm 3 + +GitLab does not offer a way to migrate existing application management +on existing clusters from Helm 2 to Helm 3. To migrate a cluster to Helm 3: + +1. Uninstall all applications on your cluster. +1. [Remove the cluster integration](../project/clusters/add_remove_clusters.md#removing-integration). +1. [Re-add the cluster](../project/clusters/add_remove_clusters.md#existing-kubernetes-cluster) as + an existing cluster. + +### cert-manager + +> 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 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) + 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) + chart was used. + +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: + +1. [Back up any additional configuration](https://cert-manager.io/docs/tutorials/backup/). +1. Uninstall cert-manager. +1. Install cert-manager again. + +### GitLab Runner + +> - 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'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's the default. Be sure to read +the [security implications](../project/clusters/index.md#security-implications) +before deploying one. + +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) +file. Customizing the installation by modifying this file is not supported. This +also means you cannot modify `config.toml` file for this Runner. If you want to +have that possibility and still deploy Runner in Kubernetes, consider using the +[Cluster management project](management_project.md) or installing Runner manually +via [GitLab Runner Helm Chart](https://docs.gitlab.com/runner/install/kubernetes.html). + +### Ingress + +> - 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 +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/), +which is supported by the Kubernetes community. + +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. + +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 attempts +to determine the external endpoint and it should be available in a few minutes. + +#### Determining the external endpoint automatically + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17052) in GitLab 10.6. + +After you install Ingress, the external endpoint should be available in a few minutes. + +NOTE: +This endpoint can be used for the +[Auto DevOps base domain](../../topics/autodevops/index.md#auto-devops-base-domain) +using the `KUBE_INGRESS_BASE_DOMAIN` environment variable. + +If the endpoint doesn't appear and your cluster runs on Google Kubernetes Engine: + +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. + +The [`stable/nginx-ingress`](https://github.com/helm/charts/tree/master/stable/nginx-ingress) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/ingress/values.yaml) +file. + +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 +[determine it manually](#determining-the-external-endpoint-manually). + +#### Determining the external endpoint manually + +If the cluster is on GKE, click the **Google Kubernetes Engine** link in the +**Advanced settings**, or go directly to the +[Google Kubernetes Engine dashboard](https://console.cloud.google.com/kubernetes/) +and select the proper project and cluster. Then click **Connect** and execute +the `gcloud` command in a local terminal or using the **Cloud Shell**. + +If the cluster is not on GKE, follow the specific instructions for your +Kubernetes provider to configure `kubectl` with the right credentials. +The output of the following examples 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 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}' + ``` + +- 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}' + ``` + + If EKS is used, an [Elastic Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/) + is also created, which incurs additional AWS costs. + +- For Istio/Knative, the command is different: + + ```shell + kubectl get svc --namespace=istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' + ``` + +- Otherwise, you can list the IP addresses of all load balancers: + + ```shell + kubectl get svc --all-namespaces -o jsonpath='{range.items[?(@.status.loadBalancer.ingress)]}{.status.loadBalancer.ingress[*].ip} ' + ``` + +You may see a trailing `%` on some Kubernetes versions. Do not include it. + +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 aren't 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 + +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) + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21966) in GitLab 12.7. + +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. + +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 applies the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), +which provides generic attack detection capabilities. + +This feature: + +- Runs in "Detection-only mode" unless configured otherwise. +- Is viewable by checking your Ingress controller's `modsec` log for rule violations. + For example: + + ```shell + kubectl -n gitlab-managed-apps logs -l app=nginx-ingress,component=controller -c modsecurity-log -f + ``` + +To enable WAF, switch its respective toggle to the enabled position when installing +or updating [Ingress application](#ingress). + +If this is your first time using the GitLab WAF, we recommend you follow the +[quick start guide](../../topics/web_application_firewall/quick_start_guide.md). + +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. 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. + + + +##### Logging and blocking modes + +To help you tune your WAF rules, you can globally set your WAF to either +*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. + +To change your WAF's mode: + +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. Select **Save changes**. + +##### WAF version updates + +Enabling, disabling, or changing the logging mode for **ModSecurity** is only +allowed in same version of [Ingress](#ingress) due to limitations in +[Helm](https://helm.sh/) which might be overcome in future releases. + +The **ModSecurity** user interface controls are disabled if the version deployed +differs from the one available in GitLab. However, actions at the [Ingress](#ingress) +level, such as uninstalling, can still be performed: + + + +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: + +- The total amount of traffic to your application. +- The proportion of traffic that's 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, investigate it for potential threats +by [examining the Web Application Firewall logs](#web-application-firewall-modsecurity). + + + +### JupyterHub + +> - 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, +visualization, and machine learning. + +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. + +GitLab uses a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) +that installs additional relevant packages on top of the base Jupyter. Ready-to-use +DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/Nurtch/rubix) +are also available. + +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. + +#### 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 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, and +issuance of Git commands in Jupyter. You can issue Git commands through the +**Git** tab on the left panel, or through Jupyter's command-line prompt. + +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. + + + +You can clone repositories from the files tab in Jupyter: + + + +### Knative + +> - Introduced in GitLab 11.5 for project-level clusters. +> - Introduced in GitLab 12.3 for group- and instance-level clusters. + +[Knative](https://cloud.google.com/knative/) provides a platform to +create, deploy, and manage serverless workloads from a Kubernetes +cluster. It's used in conjunction with, and includes +[Istio](https://istio.io) to provide an external IP address for all +programs hosted by Knative. + +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 +are 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. +> - Introduced in GitLab 11.11 for group-level clusters. + +[Prometheus](https://prometheus.io/docs/introduction/overview/) is an +open-source monitoring and alerting system you can use to supervise your +deployed applications. + +GitLab is able to monitor applications by using the +[Prometheus integration](../project/integrations/prometheus.md). Kubernetes container CPU and +memory metrics are collected, and response metrics are also retrieved +from NGINX Ingress. + +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. + +[Crossplane](https://crossplane.github.io/docs/v0.9/) is a multi-cloud control plane +to help you manage applications and infrastructure across multiple clouds. It extends the +Kubernetes API using: + +- Custom resources. +- Controllers that watch those custom resources. + +Crossplane allows provisioning and lifecycle management of infrastructure components +across cloud providers in a uniform manner by abstracting cloud provider-specific +configurations. + +The Crossplane GitLab-managed application: + +- Installs Crossplane with a provider of choice on a Kubernetes cluster attached to the + project repository. +- Can then be used to provision infrastructure or managed applications such as + PostgreSQL (for example, CloudSQL from GCP or RDS from AWS) and other services + required by the application with the Auto DevOps pipeline. + +[`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. + +[Elastic Stack](https://www.elastic.co/elastic-stack) is a complete end-to-end +log analysis solution which helps in deep searching, analyzing and visualizing the logs +generated from different machines. + +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). + +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. + +To enable log shipping: + +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 then select + **Install**. + +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. 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. + +#### Optional: deploy Kibana to perform advanced queries + +If you are an advanced user and have direct access to your Kubernetes cluster +using `kubectl` and `helm`, you can deploy Kibana manually. The following assumes +that `helm` has been [initialized](https://v2.helm.sh/docs/helm/) with `helm init`. + +Save the following to `kibana.yml`: + +```yaml +elasticsearch: + enabled: false + +filebeat: + enabled: false + +kibana: + enabled: true + elasticsearchHosts: http://elastic-stack-elasticsearch-master.gitlab-managed-apps.svc.cluster.local:9200 +``` + +Then install it on your cluster: + +```shell +helm repo add gitlab https://charts.gitlab.io +helm install --name kibana gitlab/elastic-stack --values kibana.yml +``` + +To access Kibana, forward the port to your local machine: + +```shell +kubectl port-forward svc/kibana-kibana 5601:5601 +``` + +Then, you can visit Kibana at `http://localhost:5601`. + +### Fluentd + +> Introduced in GitLab 12.10 for project- and group-level clusters. + +[Fluentd](https://www.fluentd.org/) is an open source data collector, which enables +you to unify the data collection and consumption to better use and understand +your data. Fluentd sends logs in syslog format. + +To enable Fluentd: + +1. Navigate to **Operations > Kubernetes** and click + **Applications**. Enter a host, port, and protocol + for sending the WAF logs with syslog. +1. Provide the host domain name or URL in **SIEM Hostname**. +1. Provide the host port number in **SIEM Port**. +1. Select a **SIEM Protocol**. +1. Select at least one of the available logs (such as WAF or Cilium). +1. Click **Save changes**. + + ## Upgrading applications diff --git a/doc/user/clusters/cost_management.md b/doc/user/clusters/cost_management.md index f13be15c6bc..d1df5642514 100644 --- a/doc/user/clusters/cost_management.md +++ b/doc/user/clusters/cost_management.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Cluster cost management **(ULTIMATE)** @@ -10,7 +10,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w Cluster cost management provides insights into cluster resource usage. GitLab provides an example [`kubecost-cost-model`](https://gitlab.com/gitlab-examples/kubecost-cost-model/) -project that uses GitLab's Prometheus integration and +project that uses the GitLab Prometheus integration and [Kubecost's `cost-model`](https://github.com/kubecost/cost-model) to provide cluster cost insights within GitLab: @@ -28,7 +28,7 @@ permissions in a project or group. need to change this value if you use a non-managed Prometheus. - Adds the necessary annotations to the deployment manifest to be scraped by GitLab-managed Prometheus. - - Changes the Google Pricing API access key to GitLab's access key. + - Changes the Google Pricing API access key to the GitLab access key. - Contains definitions for a custom GitLab Metrics dashboard to show the cost insights. 1. Connect GitLab with Prometheus, depending on your configuration: - *If Prometheus is already configured,* navigate to **Settings > Integrations > Prometheus** @@ -58,7 +58,7 @@ file or creating similar dashboard configuration files. To learn more, read abou #### Available metrics -Metrics contain both instance and node labels. The instance label will be deprecated in a future version. +Metrics contain both instance and node labels. The instance label is scheduled for deprecation in a future version. - `node_cpu_hourly_cost` - Hourly cost per vCPU on this node. - `node_gpu_hourly_cost` - Hourly cost per GPU on this node. diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index 8463917f2f3..c1ef798f5a8 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Crossplane configuration diff --git a/doc/user/clusters/environments.md b/doc/user/clusters/environments.md index 3ab20c5466e..be4ac8151e4 100644 --- a/doc/user/clusters/environments.md +++ b/doc/user/clusters/environments.md @@ -1,7 +1,7 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- # Cluster Environments **(PREMIUM)** diff --git a/doc/user/clusters/management_project.md b/doc/user/clusters/management_project.md index f7241444a6b..55f507fb318 100644 --- a/doc/user/clusters/management_project.md +++ b/doc/user/clusters/management_project.md @@ -1,12 +1,12 @@ --- stage: Configure group: Configure -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Cluster management project (alpha) +# Cluster management project -CAUTION: **Warning:** +WARNING: This is an _alpha_ feature, and it is subject to change at any time without prior notice. @@ -20,13 +20,13 @@ privileges. This can be useful for: -- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (alpha)](applications.md#install-using-gitlab-cicd-alpha) for details. +- Creating pipelines to install cluster-wide applications into your cluster, see [Install using GitLab CI/CD (alpha)](applications.md#install-using-gitlab-cicd) for details. - Any jobs that require `cluster-admin` privileges. ## Permissions -Only the management project will receive `cluster-admin` privileges. All -other projects will continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). +Only the management project receives `cluster-admin` privileges. All +other projects continue to receive [namespace scoped `edit` level privileges](../project/clusters/add_remove_clusters.md#rbac-cluster-resources). Management projects are restricted to the following: @@ -92,7 +92,7 @@ to a management project: | Production | `production` | The following environments set in -[`.gitlab-ci.yml`](../../ci/yaml/README.md) will deploy to the +[`.gitlab-ci.yml`](../../ci/yaml/README.md) deploy to the Development, Staging, and Production cluster respectively. ```yaml |