From 6ce82deda34e8af9d07cf7dfff0057f33b9e6187 Mon Sep 17 00:00:00 2001 From: GitLab Bot Date: Wed, 23 Dec 2020 15:00:18 +0000 Subject: Add latest changes from gitlab-org/gitlab@13-7-stable-ee --- doc/.vale/gitlab/spelling-exceptions.txt | 2 + doc/development/rake_tasks.md | 7 +- .../group/roadmap/img/roadmap_filters_v13_7.png | Bin 0 -> 21615 bytes doc/user/group/roadmap/index.md | 54 +++++++++- doc/user/project/clusters/add_eks_clusters.md | 113 +++++++++++++++++++-- .../project/clusters/img/aws_iam_role_trust.png | Bin 0 -> 56783 bytes 6 files changed, 160 insertions(+), 16 deletions(-) create mode 100644 doc/user/group/roadmap/img/roadmap_filters_v13_7.png create mode 100644 doc/user/project/clusters/img/aws_iam_role_trust.png (limited to 'doc') diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt index fd3aff63bce..3d8e9b1ef72 100644 --- a/doc/.vale/gitlab/spelling-exceptions.txt +++ b/doc/.vale/gitlab/spelling-exceptions.txt @@ -404,6 +404,8 @@ reusability reverified reverifies reverify +roadmap +roadmaps rollout rollouts rsync diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index 09e8f780fe1..226d21b2ecd 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -88,13 +88,14 @@ bundle exec rake 'gitlab:seed:development_metrics[your_project_id]' ### Automation If you're very sure that you want to **wipe the current database** and refill -seeds, you could: +seeds, you can set the `FORCE` environment variable to `yes`: ```shell -echo 'yes' | bundle exec rake setup +FORCE=yes bundle exec rake setup ``` -To save you from answering `yes` manually. +This will skip the action confirmation/safety check, saving you from answering +`yes` manually. ### Discard `stdout` diff --git a/doc/user/group/roadmap/img/roadmap_filters_v13_7.png b/doc/user/group/roadmap/img/roadmap_filters_v13_7.png new file mode 100644 index 00000000000..00505a7f34f Binary files /dev/null and b/doc/user/group/roadmap/img/roadmap_filters_v13_7.png differ diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 32abc676352..6dfa7641dbb 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -15,7 +15,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/214375) and later, the Roadmap also shows milestones in projects in a group. > - In [GitLab 13.2](https://gitlab.com/gitlab-org/gitlab/-/issues/212494) and later, milestone bars can be collapsed and expanded. -Epics and milestones within a group containing a start date or due date can be visualized in a form +Epics and milestones in a group containing a start date or due date can be visualized in a form of a timeline (that is, a Gantt chart). The Roadmap page shows the epics and milestones in a group, one of its subgroups, or a project in one of the groups. @@ -24,14 +24,31 @@ When you hover over an epic bar, a popover appears with the epic's title, start weight completed. You can expand epics that contain child epics to show their child epics in the roadmap. -You can click the chevron (**{chevron-down}**) next to the epic title to expand and collapse the child epics. +You can click the chevron (**{chevron-down}**) next to the epic title to expand and collapse the +child epics. -On top of the milestone bars, you can see their title. When you hover a milestone bar or title, a popover appears with its title, start date and due date. -You can also click the chevron (**{chevron-down}**) next to the **Milestones** heading to toggle the list of the milestone bars. +On top of the milestone bars, you can see their title. +When you hover over a milestone bar or title, a popover appears with its title, start date, and due +date. You can also click the chevron (**{chevron-down}**) next to the **Milestones** heading to +toggle the list of the milestone bars. ![roadmap view](img/roadmap_view_v13_2.png) -A dropdown menu allows you to show only open or closed epics. By default, all epics are shown. +## Sort and filter the Roadmap + +> - Filtering roadmaps by milestone [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218621) in GitLab 13.7. +> - Filtering roadmaps by milestone is [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - Filtering roadmaps by milestone is enabled on GitLab.com. +> - Filtering roadmaps by milestone is recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-filtering-roadmaps-by-milestone). **(PREMIUM ONLY)** + +WARNING: +Filtering roadmaps by milestone might not be available to you. Check the **version history** note above for details. + +When you want to explore a roadmap, there are several ways to make it easier by sorting epics or +filtering them by what's important for you. + +A dropdown menu lets you show only open or closed epics. By default, all epics are shown. ![epics state dropdown](img/epics_state_dropdown_v12_10.png) @@ -45,8 +62,35 @@ You can sort epics in the Roadmap view by: Each option contains a button that toggles the sort order between **ascending** and **descending**. The sort option and order persist when browsing Epics, including the [epics list view](../epics/index.md). +You can also filter epics in the Roadmap view by: + +- Author +- Label +- Milestone + +![roadmap date range in weeks](img/roadmap_filters_v13_7.png) + Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). +### Enable or disable filtering roadmaps by milestone **(PREMIUM ONLY)** + +Filtering roadmaps by milestone is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can opt to disable it. + +To enable it: + +```ruby +Feature.enable(:async_filtering) +``` + +To disable it: + +```ruby +Feature.disable(:async_filtering) +``` + ## Timeline duration > - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. diff --git a/doc/user/project/clusters/add_eks_clusters.md b/doc/user/project/clusters/add_eks_clusters.md index 07aa02db2b5..4fae10c58eb 100644 --- a/doc/user/project/clusters/add_eks_clusters.md +++ b/doc/user/project/clusters/add_eks_clusters.md @@ -41,14 +41,32 @@ For example, the following policy document allows assuming a role whose name sta } ``` +### Administration settings + Generate an access key for the IAM user, and configure GitLab with the credentials: 1. Navigate to **Admin Area > Settings > General** and expand the **Amazon EKS** section. 1. Check **Enable Amazon EKS integration**. -1. Enter the account ID and access key credentials into the respective - `Account ID`, `Access key ID` and `Secret access key` fields. +1. Enter your **Account ID**. +1. Depending on your configuration, enter your access key and ID: + + - _GitLab 13.7 and later, and using an instance profile_: You may leave + **Access key ID** and **Secret access key** blank. + Read [Instance profiles](#instance-profiles) for more information. + - _All GitLab versions_: Enter your access key credentials into + **Access key ID** and **Secret access key**. + 1. Click **Save changes**. +#### Instance profiles + +> Introduced in [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/291015). + +You may leave `Access key ID` and `Secret access key` fields blank if +you are using an instance profile +[to pass an IAM role to an EC2 instance](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html). +Instance profiles dynamically retrieve temporary credentials from AWS when needed. + ## New EKS cluster > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22392) in GitLab 12.5. @@ -175,17 +193,96 @@ You must add your AWS external ID to the [IAM Role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html#cli-configure-role-xaccount) to manage your cluster using `kubectl`. +### Cluster creation flow + +The following sequence illustrates how GitLab works with AWS to create an EKS cluster: + +```mermaid +sequenceDiagram + autonumber + participant G as GitLab + participant A as AWS + participant E as EKS cluster + alt static credentials + G->>G: Load AWS Access and secret key + end + alt IAM instance profile + G->>A: Fetch temporary credentials + A->>G: Temporary access credentials + end + G->>A: AssumeRole: EKS Provision Role + A->>A: Check account, external IDs + A->>A: Check permissions + A->>G: New access credentials + note over G: user selects EKS cluster options + note over G,A: Use Service Role credentials + G->>A: CreateStack (CloudFormation) + A->>G: Received + G->>G: Wait 5 minutes + loop Poll for cluster creation + G->>A: DescribeStacks + A->>G: CREATE_IN_PROGRESS + end + note over G,E: EKS Cluster Created + G->>A: DescribeStacks + A->>G: CREATE_COMPLETE + G->>E: kubectl create role (service account) + E->>G: OK +``` + +First, GitLab must obtain an initial set of credentials to communicate with the AWS API. +These credentials can be retrieved in one of two ways: + +- Statically through the [Administration settings](#administration-settings). +- Dynamically via an IAM instance profile ([introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/291015) in GitLab 13.7). + +After GitLab retrieves the AWS credentials, it makes an +[AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) +API call to obtain credentials for the Provision Role. AWS confirms +the request has the correct account ID, external ID, and permissions. + +If the request is valid, AWS returns a new set of temporary credentials GitLab +uses to load the **Create cluster** options page. + +On the **Create cluster** page, the user must select a **Service Role**, which is +the IAM role that is actually used to create the cluster, and other options +such as the Kubernetes cluster name, Kubernetes version, and region. +After the user clicks the **Create Kubernetes cluster** button, GitLab +submits a CloudFormation API request to create an EKS cluster with the given parameters +from the user. GitLab waits 5 minutes before checking whether the cluster was created, +and polls once a minute for up to 30 minutes. + +After GitLab receives a `CREATE_COMPLETE` message from AWS, GitLab talks +to the EKS cluster to create a Kubernetes service account with `cluster-admin` +privileges, and updates its internal database to reflect the newly-created +Kubernetes cluster. From this point forward, GitLab uses this service account to +interact with the cluster. + ### Troubleshooting creating a new cluster The following errors are commonly encountered when creating a new cluster. -#### Error: Request failed with status code 422 +#### Validation failed: Role ARN must be a valid Amazon Resource Name + +Check that the `Provision Role ARN` is correct. An example of a valid ARN: + +```plaintext +arn:aws:iam::123456789012:role/gitlab-eks-provision' +``` + +#### Access denied: User `arn:aws:iam::x` is not authorized to perform: `sts:AssumeRole` on resource: `arn:aws:iam::y` + +This error occurs when the credentials defined in the +[Administration settings](#administration-settings) cannot assume the role defined by the +Provision Role ARN. Check that: + +1. The initial set of AWS credentials [has the AssumeRole policy](#additional-requirements-for-self-managed-instances). +1. The Provision Role has access to create clusters in the given region. +1. The account ID and + [external ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) + match the value defined in the **Trust relationships** tab in AWS: -When submitting the initial authentication form, GitLab returns a status code 422 -error when it can't determine the role or region you've provided. Make sure you've -correctly configured your role with the **Account ID** and **External ID** -provided by GitLab. In GitLab, make sure to enter the correct **Role ARN**. -Make sure you also have access to the chosen region. + ![AWS IAM Trust relationships](img/aws_iam_role_trust.png) #### Could not load Security Groups for this VPC diff --git a/doc/user/project/clusters/img/aws_iam_role_trust.png b/doc/user/project/clusters/img/aws_iam_role_trust.png new file mode 100644 index 00000000000..a2263b174b5 Binary files /dev/null and b/doc/user/project/clusters/img/aws_iam_role_trust.png differ -- cgit v1.2.3