diff options
Diffstat (limited to 'doc/user/project/clusters')
| -rw-r--r-- | doc/user/project/clusters/add_eks_clusters.md | 33 | ||||
| -rw-r--r-- | doc/user/project/clusters/add_gke_clusters.md | 4 | ||||
| -rw-r--r-- | doc/user/project/clusters/add_remove_clusters.md | 8 | ||||
| -rw-r--r-- | doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_10.png | bin | 14897 -> 0 bytes | |||
| -rw-r--r-- | doc/user/project/clusters/index.md | 8 | ||||
| -rw-r--r-- | doc/user/project/clusters/kubernetes_pod_logs.md | 90 | ||||
| -rw-r--r-- | doc/user/project/clusters/runbooks/index.md | 2 | ||||
| -rw-r--r-- | doc/user/project/clusters/securing.md | 21 | ||||
| -rw-r--r-- | doc/user/project/clusters/serverless/aws.md | 2 |
9 files changed, 89 insertions, 79 deletions
diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index b11483a7446..d5713f20257 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -56,12 +56,17 @@ Generate an access key for the IAM user, and configure GitLab with the credentia To create and add a new Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes**, for an instance-level cluster. + - Project's **Operations > Kubernetes** page, for a project-level cluster. + - Group's **Kubernetes** page, for a group-level cluster. + - **Admin Area > Kubernetes**, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an `Account ID` and `External ID` to use in the next step. +1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an EKS management IAM role. + To do so, follow the [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) instructions + to create a IAM role suitable for managing the AWS EKS cluster's resources on your behalf. + In addition to the policies that guide suggests, you must also include the `AmazonEKSClusterPolicy` + policy for this role in order for GitLab to manage the EKS cluster correctly. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: 1. From the left panel, select **Roles**. 1. Click **Create role**. @@ -135,11 +140,17 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Click **Authenticate with AWS**. 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. - - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster. - **Kubernetes version** - The Kubernetes version to use. Currently the only version supported is 1.14. - - **Role name** - Select the [IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) - to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. This IAM role is separate - to the IAM role created above, you will need to create it if it does not yet exist. + - **Service role** - Select the **EKS IAM role** you created earlier to allow Amazon EKS + and the Kubernetes control plane to manage AWS resources on your behalf. + + NOTE: **Note:** + This IAM role is _not_ the IAM role you created in the previous step. It should be + the one you created much earlier by following the + [Amazon EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) + guide. + - **Region** - The [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) in which the cluster will be created. - **Key pair name** - Select the [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) @@ -194,10 +205,10 @@ If the `Cluster` resource failed with the error the role specified in **Role name** is not configured correctly. NOTE: **Note:** -This role should not be the same as the one created above. If you don't have an -existing -[EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html), -you must create one. +This role should be the role you created by following the +[EKS cluster IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) guide. +In addition to the policies that guide suggests, you must also include the +`AmazonEKSClusterPolicy` policy for this role in order for GitLab to manage the EKS cluster correctly. ## Existing EKS cluster diff --git a/doc/user/project/clusters/add_gke_clusters.md b/doc/user/project/clusters/add_gke_clusters.md index 2746076befe..720f9bdf253 100644 --- a/doc/user/project/clusters/add_gke_clusters.md +++ b/doc/user/project/clusters/add_gke_clusters.md @@ -48,14 +48,14 @@ To create and add a new Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Under the **Create new cluster** tab, click **Google GKE**. 1. Connect your Google account if you haven't done already by clicking the **Sign in with Google** button. 1. Choose your cluster's settings: - **Kubernetes cluster name** - The name you wish to give the cluster. - - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope) to this cluster. - **Google Cloud Platform project** - Choose the project you created in your GCP console that will host the Kubernetes cluster. Learn more about [Google Cloud Platform projects](https://cloud.google.com/resource-manager/docs/creating-managing-projects). diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 65f1c59f4ca..e4a750084c9 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -142,7 +142,7 @@ Amazon Elastic Kubernetes Service (EKS) at the project, group, or instance level 1. Navigate to your: - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Click the **Create new cluster** tab. 1. Click either **Amazon EKS** or **Google GKE**, and follow the instructions for your desired service: @@ -164,12 +164,12 @@ To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: 1. Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. 1. Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - 1. **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + 1. **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. 1. Click the **Add existing cluster** tab and fill in the details: 1. **Kubernetes cluster name** (required) - The name you wish to give the cluster. 1. **Environment scope** (required) - The - [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. + [associated environment](index.md#setting-the-environment-scope) to this cluster. 1. **API URL** (required) - It's the URL that GitLab uses to access the Kubernetes API. Kubernetes exposes several APIs, we want the "base" URL that is common to all of them. @@ -331,7 +331,7 @@ a new cluster or added an existing one. To disable Kubernetes cluster integratio 1. Navigate to your: - Project's **{cloud-gear}** **Operations > Kubernetes** page, for a project-level cluster. - Group's **{cloud-gear}** **Kubernetes** page, for a group-level cluster. - - **{admin}** **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. + - **Admin Area >** **{cloud-gear}** **Kubernetes** page, for an instance-level cluster. 1. Click on the name of the cluster. 1. Click the **GitLab Integration** toggle. 1. Click **Save changes**. diff --git a/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_10.png b/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_10.png Binary files differdeleted file mode 100644 index ee37970d867..00000000000 --- a/doc/user/project/clusters/img/sidebar_menu_pod_logs_v12_10.png +++ /dev/null diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index ddcfd376d89..98078854050 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -67,17 +67,17 @@ to: ### Multiple Kubernetes clusters > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3 -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab core in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/35094) to GitLab Core in 13.2. You can associate more than one Kubernetes cluster to your project. That way you can have different clusters for different environments, like dev, staging, production, and so on. Simply add another cluster, like you did the first time, and make sure to -[set an environment scope](#setting-the-environment-scope-premium) that will +[set an environment scope](#setting-the-environment-scope) that will differentiate the new cluster with the rest. -#### Setting the environment scope **(PREMIUM)** +#### Setting the environment scope When adding more than one Kubernetes cluster to your project, you need to differentiate them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments/index.md) similar to how the @@ -368,7 +368,7 @@ Automatically detect and monitor Kubernetes metrics. Automatic monitoring of ### Visualizing cluster health > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6. -> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab core in 13.2. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Core in 13.2. When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index ee642dc18cf..afb6d016f45 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -1,6 +1,6 @@ --- -stage: Configure -group: Configure +stage: Monitor +group: APM 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 --- @@ -9,56 +9,54 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/26383) to [GitLab Core](https://about.gitlab.com/pricing/) 12.9. -GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). -By displaying the logs directly in GitLab in the **Log Explorer**, developers can avoid -managing console tools or jumping to a different interface. - -NOTE: **Note:** -[Learn more about Kubernetes + GitLab](https://about.gitlab.com/solutions/kubernetes/). -Everything you need to build, test, deploy, and run your application at scale. - -## Overview - -[Kubernetes](https://kubernetes.io) logs can be viewed directly within GitLab with -the **Log Explorer**. +GitLab makes it easy to view the logs of running pods or managed applications in +[connected Kubernetes clusters](index.md). By displaying the logs directly in GitLab +in the **Log Explorer**, developers can avoid managing console tools or jumping +to a different interface. The **Log Explorer** interface provides a set of filters +above the log file data, depending on your configuration:  +- **Namespace** - Select the environment to display. Users with Maintainer or + greater [permissions](../../permissions.md) can also select Managed Apps. +- **Search** - Only available if the Elastic Stack managed application is installed. +- **Select time range** - Select the range of time to display. Only available if the + Elastic Stack managed application is installed. +- **Scroll to bottom** **{scroll_down}** - Scroll to the end of the displayed logs. +- **Refresh** **{retry}** - Reload the displayed logs. + <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -To learn more, see [APM - Log Explorer](https://www.youtube.com/watch?v=hWclZHA7Dgw). +To learn more about the Log Explorer, see [APM - Log Explorer](https://www.youtube.com/watch?v=hWclZHA7Dgw). + +NOTE: **Note:** +[Learn more about Kubernetes + GitLab](https://about.gitlab.com/solutions/kubernetes/). +Everything you need to build, test, deploy, and run your application at scale. ## Requirements [Deploying to a Kubernetes environment](../deploy_boards.md#enabling-deploy-boards) is required to use Logs. -## Usage - -To access logs, you must have the right [permissions](../../permissions.md#project-members-permissions). - -You can access them in two ways. - -### From the project sidebar +## Accessing the log explorer -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 12.5. +To access the **Log explorer**, click the **More actions** **{ellipsis_v}** menu on +a [metrics dashboard](../../../operations/metrics/index.md) and select **View logs**, or: -Go to **{cloud-gear}** **Operations > Pod logs** on the sidebar menu to display -the **Log Explorer**. +1. Sign in as a user with the _View pod logs_ + [permissions](../../permissions.md#project-members-permissions) in the project. +1. *To navigate to the **Log Explorer** from the sidebar menu,* go to + **{cloud-gear}** **Operations > Pod logs**. + ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22011) in GitLab 12.5.) +1. *To navigate to the **Log Explorer** from a specific pod on a [Deploy Board](../deploy_boards.md):* - - -### From Deploy Boards - -Logs can be displayed by clicking on a specific pod from [Deploy Boards](../deploy_boards.md): - -1. Go to **{cloud-gear}** **Operations > Environments** and find the environment - which contains the desired pod, like `production`. -1. On the **Environments** page, you should see the status of the environment's - pods with [Deploy Boards](../deploy_boards.md). -1. When mousing over the list of pods, a tooltip will appear with the exact pod name - and status. -  -1. Click on the desired pod to display the **Log Explorer**. + 1. Go to **{cloud-gear}** **Operations > Environments** and find the environment + which contains the desired pod, like `production`. + 1. On the **Environments** page, you should see the status of the environment's + pods with [Deploy Boards](../deploy_boards.md). + 1. When mousing over the list of pods, GitLab displays a tooltip with the exact pod name + and status. +  + 1. Click on the desired pod to display the **Log Explorer**. ### Logs view @@ -69,6 +67,7 @@ The **Log Explorer** lets you filter the logs by: - [From GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21656), [full text search](#full-text-search). - [From GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/issues/197879), dates. +- [From GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/208790), managed apps. Loading more than 500 log lines is possible from [GitLab 12.9](https://gitlab.com/gitlab-org/gitlab/-/issues/198050) onward. @@ -93,17 +92,16 @@ Click **Show last** in the **Log Explorer** to see the available options. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21656) in GitLab 12.7. When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) on your cluster, -you can search the content of your logs through a search bar. - -The search is passed on to Elasticsearch using the +you can search the content of your logs through a search bar. The search is passed +to Elasticsearch using the [simple_query_string](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html) Elasticsearch function, which supports the following operators: -| Operator | Description | -|----------------------------|------------------------------------------------------------| -| `\|` | An OR operation. | +| Operator | Description | +|----------------------------|-------------------------------------------------------------| +| `\|` | An `OR` operation. | | `-` | Negates a single token. | -| `+` | An AND operation. | +| `+` | An `AND` operation. | | `"` | Wraps a number of tokens to signify a phrase for searching. | | `*` (at the end of a term) | A prefix query. | | `(` and `)` | Precedence. | diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index a592d59f964..360b02efb69 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -129,7 +129,7 @@ the components outlined above and the pre-loaded demo runbook. %env DB_NAME={project.variables.get('DB_NAME').value} ``` - 1. Navigate to **{settings}** **Settings >> CI/CD >> Variables** to create + 1. Navigate to **Settings > CI/CD > Variables** to create the variables in your project.  diff --git a/doc/user/project/clusters/securing.md b/doc/user/project/clusters/securing.md index b4c20cb8dbc..5b9f776080b 100644 --- a/doc/user/project/clusters/securing.md +++ b/doc/user/project/clusters/securing.md @@ -9,7 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w GitLab makes it easy to secure applications deployed in [connected Kubernetes clusters](index.md). You can benefit from the protection of a [Web Application Firewall](../../../topics/web_application_firewall/quick_start_guide.md), [Network Policies](../../../topics/autodevops/stages.md#network-policy), -or even [Container Host Security](../../clusters/applications.md#install-falco-using-gitlab-cicd). +and [Container Host Security](../../clusters/applications.md#install-falco-using-gitlab-cicd). This page contains full end-to-end steps and instructions to connect your cluster to GitLab and install these features, whether or not your applications are deployed through GitLab CI/CD. If you @@ -25,7 +25,7 @@ At a high level, the required steps include the following: - Connect the cluster to GitLab. - Set up one or more runners. - Set up a cluster management project. -- Install a Web Application Firewall, Network Policies, and/or Container Host +- Install a Web Application Firewall, and/or Network Policies, and/or Container Host Security. - Install Prometheus to get statistics and metrics in the [threat monitoring](../../application_security/threat_monitoring/) @@ -40,6 +40,10 @@ Minimum requirements (depending on the GitLab Manage Application you want to ins ### Understanding how GitLab Managed Apps are installed +NOTE: **Note:** +These diagrams use the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm +Tiller daemon running in a pod in the cluster. + You install GitLab Managed Apps from the GitLab web interface with a one-click setup process. GitLab uses Sidekiq (a background processing service) to facilitate this. @@ -52,12 +56,8 @@ uses Sidekiq (a background processing service) to facilitate this. Sidekiq-->>-GitLab: Refresh UI ``` -NOTE: **Note:** -This diagram uses the term _Kubernetes_ for simplicity. In practice, Sidekiq connects to a Helm -Tiller daemon running in a pod in the cluster. - Although this installation method is easier because it's a point-and-click action in the user -interface, it's inflexible and hard to debug. When something goes wrong, you can't see the +interface, it's inflexible and harder to debug. If something goes wrong, you can't see the deployment logs. The Web Application Firewall feature uses this installation method. However, the next generation of GitLab Managed Apps V2 ([CI/CD-based GitLab Managed Apps](https://gitlab.com/groups/gitlab-org/-/epics/2103)) @@ -75,10 +75,10 @@ sequenceDiagram ``` Debugging is easier because you have access to the raw logs of these jobs (the Helm Tiller output is -available as an artifact in case of failure) and the flexibility is much better. Since these +available as an artifact in case of failure), and the flexibility is much better. Since these deployments are only triggered when a pipeline is running (most likely when there's a new commit in the cluster management repository), every action has a paper trail and follows the classic merge -request workflow (approvals, merge, deploy). The Network Policy (Cilium) Managed App and Container +request workflow (approvals, merge, deploy). The Network Policy (Cilium) Managed App, and Container Host Security (Falco) are deployed with this model. ## Connect the cluster to GitLab @@ -151,4 +151,5 @@ falco: installed: true ``` -[Read more] about configuring Container Host Security. +[Read more](../../clusters/applications.md#install-falco-using-gitlab-cicd) +about configuring Container Host Security. diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 595d8fb3895..543ffdbce8f 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -373,7 +373,7 @@ variables. To set these: -1. Navigate to the project's **{settings}** **Settings > CI / CD**. +1. Navigate to the project's **Settings > CI / CD**. 1. Expand the **Variables** section and create entries for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. 1. Mask the credentials so they do not show in logs using the **Masked** toggle. |
