diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/administration/geo/disaster_recovery/index.md | 12 | ||||
| -rw-r--r-- | doc/administration/geo/replication/troubleshooting.md | 41 | ||||
| -rw-r--r-- | doc/user/group/saml_sso/scim_setup.md | 53 | ||||
| -rw-r--r-- | doc/user/project/clusters/add_remove_clusters.md | 16 | ||||
| -rw-r--r-- | doc/user/project/clusters/index.md | 8 | ||||
| -rw-r--r-- | doc/user/project/clusters/serverless/index.md | 94 |
6 files changed, 165 insertions, 59 deletions
diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index ad5284938fa..a3014c0a21e 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -87,10 +87,14 @@ must disable the **primary** node. ### Step 3. Promoting a **secondary** node -NOTE: **Note:** -A new **secondary** should not be added at this time. If you want to add a new -**secondary**, do this after you have completed the entire process of promoting -the **secondary** to the **primary**. +Note the following when promoting a secondary: + +- A new **secondary** should not be added at this time. If you want to add a new + **secondary**, do this after you have completed the entire process of promoting + the **secondary** to the **primary**. +- If you encounter an `ActiveRecord::RecordInvalid: Validation failed: Name has already been taken` + error during this process, please read + [the troubleshooting advice](../replication/troubleshooting.md#fixing-errors-during-a-failover-or-when-promoting-a-secondary-to-a-primary-node). #### Promoting a **secondary** node running on a single machine diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index 7c36d55027a..46fd5eb7ca7 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -465,6 +465,47 @@ to start again from scratch, there are a few steps that can help you: gitlab-ctl start ``` +## Fixing errors during a failover or when promoting a secondary to a primary node + +The following are possible errors that might be encountered during failover or +when promoting a secondary to a primary node with strategies to resolve them. + +### Message: ActiveRecord::RecordInvalid: Validation failed: Name has already been taken + +When [promoting a **secondary** node](../disaster_recovery/index.md#step-3-promoting-a-secondary-node), +you might encounter the following error: + +```text +Running gitlab-rake geo:set_secondary_as_primary... + +rake aborted! +ActiveRecord::RecordInvalid: Validation failed: Name has already been taken +/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:236:in `block (3 levels) in <top (required)>' +/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:221:in `block (2 levels) in <top (required)>' +/opt/gitlab/embedded/bin/bundle:23:in `load' +/opt/gitlab/embedded/bin/bundle:23:in `<main>' +Tasks: TOP => geo:set_secondary_as_primary +(See full trace by running task with --trace) + +You successfully promoted this node! +``` + +If you encounter this message when running `gitlab-rake geo:set_secondary_as_primary` +or `gitlab-ctl promote-to-primary-node`, either: + +- Enter a Rails console and run: + + ```ruby + Rails.application.load_tasks; nil + Gitlab::Geo.expire_cache_keys!([:primary_node, :current_node]) + Rake::Task['geo:set_secondary_as_primary'].invoke + ``` + +- Upgrade to GitLab 12.6.3 or newer if it is safe to do so. For example, + if the failover was just a test. A [caching-related + bug](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22021) was + fixed. + ## Fixing Foreign Data Wrapper errors This section documents ways to fix potential Foreign Data Wrapper errors. diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index 2c8848b79df..fe64afd23f6 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -143,6 +143,19 @@ Upon the next sync, the user will be deprovisioned, which means that the user wi This section contains possible solutions for problems you might encounter. +### How do I verify my SCIM configuration is correct? + +Review the following: + +- Ensure that the SCIM value for `id` matches the SAML value for `NameId`. +- Ensure that the SCIM value for `externalId` matches the SAML value for `NameId`. + +Review the following SCIM parameters for sensible values: + +- `userName` +- `displayName` +- `emails[type eq "work"].value` + ### Testing Azure connection: invalid credentials When testing the connection, you may encounter an error: **You appear to have entered invalid credentials. Please confirm you are using the correct information for an administrative account**. If `Tenant URL` and `secret token` are correct, check whether your group path contains characters that may be considered invalid JSON primitives (such as `.`). Removing such characters from the group path typically resolves the error. @@ -159,3 +172,43 @@ As a workaround, try an alternate mapping: 1. Follow the Azure mapping instructions from above. 1. Delete the `name.formatted` target attribute entry. 1. Change the `displayName` source attribute to have `name.formatted` target attribute. + +### How do I diagnose why a user is unable to sign in + +The **Identity** (`extern_uid`) value stored by GitLab is updated by SCIM whenever `id` or `externalId` changes. Users won't be able to sign in unless the GitLab Identity (`extern_uid`) value matches the `NameId` sent by SAML. + +This value is also used by SCIM to match users on the `id`, and is updated by SCIM whenever the `id` or `externalId` values change. + +It is important that this SCIM `id` and SCIM `externalId` are configured to the same value as the SAML `NameId`. SAML responses can be traced using [debugging tools](./index.md#saml-debugging-tools), and any errors can be checked against our [SAML troubleshooting docs](./index.md#troubleshooting). + +### How do I verify user's SAML NameId matches the SCIM externalId + +Group owners can see the list of users and the `externalId` stored for each user in the group SAML SSO Settings page. + +Alternatively, the [SCIM API](../../../api/scim.md#get-a-list-of-saml-users) can be used to manually retrieve the `externalId` we have stored for users, also called the `external_uid` or `NameId`. + +For example: + +```sh +curl 'https://example.gitlab.com/api/scim/v2/groups/GROUP_NAME/Users?startIndex=1"' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +``` + +To see how this compares to the value returned as the SAML NameId, you can have the user use a [SAML Tracer](index.md#saml-debugging-tools). + +### Fix mismatched SCIM externalId and SAML NameId + +If GitLab's `externalId` doesn't match the SAML NameId, it will need to be updated in order for the user to log in. Ideally your identity provider will be configured to do such an update, but in some cases it may be unable to do so, such as when looking up a user fails due to an ID change. + +Fixing the fields your SCIM identity provider sends as `id` and `externalId` can correct this, however we use these IDs to look up users so if the identity provider is unaware of the current values for these it may try to create new duplicate users instead. + +If the `externalId` we have stored for a user has an incorrect value that doesn't match the SAML NameId, then it can be corrected with the manual use of the SCIM API. + +The [SCIM API](../../../api/scim.md#update-a-single-saml-user) can be used to manually correct the `externalId` stored for users so that it matches the SAML NameId. You'll need to know the desired value that matches the `NameId` as well as the current `externalId` to look up the user. + +It is then possible to issue a manual SCIM#update request, for example: + +```sh +curl --verbose --request PATCH 'https://gitlab.com/api/scim/v2/groups/YOUR_GROUP/Users/OLD_EXTERNAL_UID' --data '{ "Operations": [{"op":"Replace","path":"externalId","value":"NEW_EXTERNAL_UID"}] }' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json" +``` + +It is important not to update these to incorrect values, since this will cause users to be unable to sign in. It is also important not to assign a value to the wrong user, as this would cause users to get signed into the wrong account. diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index a77584c0485..7aeb4c4cf91 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -1,10 +1,12 @@ # Adding and removing Kubernetes clusters -GitLab can integrate with the following Kubernetes providers: +GitLab offers integrated cluster creation for the following Kubernetes providers: - Google Kubernetes Engine (GKE). - Amazon Elastic Kubernetes Service (EKS). +In addition, GitLab can integrate with any standard Kubernetes provider, either on-premise or hosted. + TIP: **Tip:** Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign up](https://console.cloud.google.com/freetrial), and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's @@ -360,18 +362,20 @@ to install some [pre-defined applications](index.md#installing-applications). ## Add existing cluster -If you have either of the following types of clusters already, you can add them to a project: +If you have an existing Kubernetes cluster, you can add it to a project, group, or instance. + +For more information, see information for adding an: -- [Google Kubernetes Engine cluster](#existing-gke-cluster). -- [Amazon Elastic Kubernetes Service](#existing-eks-cluster). +- [Existing Kubernetes cluster](#existing-kubernetes-cluster). +- [Existing Elastic Kubernetes Service cluster](#existing-eks-cluster). NOTE: **Note:** Kubernetes integration is not supported for arm64 clusters. See the issue [Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/issues/64044) for details. -### Existing GKE cluster +### Existing Kubernetes cluster -To add an existing GKE cluster to your project, group, or instance: +To add a Kubernetes cluster to your project, group, or instance: 1. Navigate to your: - Project's **Operations > Kubernetes** page, for a project-level cluster. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 895cc6c4b57..b78dcf615c8 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -96,8 +96,12 @@ to the first container in the first pod of your environment. ## Adding and removing clusters -See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how to -set up integrations with Google Cloud Platform (GCP) and Amazon Elastic Kubernetes Service (EKS). +See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how +to: + +- Create a cluster in Google Cloud Platform (GCP) or Amazon Elastic Kubernetes Service + (EKS) using GitLab's UI. +- Add an integration to an existing cluster from any Kubernetes platform. ## Cluster configuration diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 1dc543c3b83..9b56970db53 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -170,53 +170,6 @@ You must do the following: or [serverless applications](#deploying-serverless-applications) onto your cluster. -## Configuring logging - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33330) in GitLab 12.5. - -### Prerequisites - -- A GitLab-managed cluster. -- `kubectl` installed and working. - -Running `kubectl` commands on your cluster requires setting up access to the -cluster first. For clusters created on: - -- GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) -- Other platforms, see [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). - -### Enable request log template - -Run the following command to enable request logs: - -```shell -kubectl edit cm -n knative-serving config-observability -``` - -Copy the `logging.request-log-template` from the `data._example` field to the data field one level up in the hierarchy. - -### Enable request logs - -Run the following commands to install Elasticsearch, Kibana, and Filebeat into a `kube-logging` namespace and configure all nodes to forward logs using Filebeat: - -```shell -kubectl apply -f https://gitlab.com/gitlab-org/serverless/configurations/knative/raw/v0.7.0/kube-logging-filebeat.yaml -kubectl label nodes --all beta.kubernetes.io/filebeat-ready="true" -``` - -### Viewing request logs - -To view request logs: - -1. Run `kubectl proxy`. -1. Navigate to Kibana UI. - -Or: - -1. Open the Kibana UI. -1. Click on **Discover**, then select `filebeat-*` from the dropdown on the left. -1. Enter `kubernetes.container.name:"queue-proxy" AND message:/httpRequest/` into the search box. - ## Supported runtimes Serverless functions for GitLab can be run using: @@ -559,6 +512,53 @@ deployment. Copy and paste the domain into your browser to see the app live.  +## Configuring logging + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33330) in GitLab 12.5. + +### Prerequisites + +- A GitLab-managed cluster. +- `kubectl` installed and working. + +Running `kubectl` commands on your cluster requires setting up access to the +cluster first. For clusters created on: + +- GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl) +- Other platforms, see [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +### Enable request log template + +Run the following command to enable request logs: + +```shell +kubectl edit cm -n knative-serving config-observability +``` + +Copy the `logging.request-log-template` from the `data._example` field to the data field one level up in the hierarchy. + +### Enable request logs + +Run the following commands to install Elasticsearch, Kibana, and Filebeat into a `kube-logging` namespace and configure all nodes to forward logs using Filebeat: + +```shell +kubectl apply -f https://gitlab.com/gitlab-org/serverless/configurations/knative/raw/v0.7.0/kube-logging-filebeat.yaml +kubectl label nodes --all beta.kubernetes.io/filebeat-ready="true" +``` + +### Viewing request logs + +To view request logs: + +1. Run `kubectl proxy`. +1. Navigate to [Kibana UI](http://localhost:8001/api/v1/namespaces/kube-logging/services/kibana/proxy/app/kibana). + +Or: + +1. Open the [Kibana UI](http://localhost:8001/api/v1/namespaces/kube-logging/services/kibana/proxy/app/kibana). +1. Click on **Discover**, then select `filebeat-*` from the dropdown on the left. +1. Enter `kubernetes.container.name:"queue-proxy" AND message:/httpRequest/` into the search box. + ## Function details Go to the **Operations > Serverless** page and click on one of the function |