Configure GitLab Dedicated

GitLab Dedicated is a single-tenant SaaS solution, fully managed and hosted by GitLab. For more information about this offering, see the subscription page.

The instructions on this page guide you through:

  1. Onboarding and initial setup of your GitLab Dedicated instance.
  2. Configuring your GitLab Dedicated instance including enabling and updating the settings for available functionality.

Any functionality in the GitLab application that is not controlled by the SaaS environment can be configured by using the Admin Panel.

Examples of SaaS environment settings include gitlab.rb configurations and access to shell, Rails console, and PostgreSQL console. These environment settings cannot be changed by tenants. GitLab Dedicated Engineers also don’t have direct access to tenant environments, except for break glass situations.

Onboarding

To request the creation of a new GitLab Dedicated environment for your organization, you must provide the following information to your account team:

  • Expected number of users.
  • Desired primary region: Primary AWS region in which your data is stored (take note of unavailable AWS regions).
  • Desired secondary region: Secondary AWS region in which your data is stored. This region is used to recover your GitLab Dedicated instance in case of a disaster.
  • Desired backup region: An AWS region where the primary backups of your data are replicated. This can be the same as the primary or secondary region or different.
  • Desired instance subdomain: The main domain for GitLab Dedicated instances is gitlab-dedicated.com. You get to choose the subdomain name where your instance is accessible from (for example, customer_name.gitlab-dedicated.com).
  • Initial storage: Initial storage size for your repositories in GB.
  • Availability Zone IDs for PrivateLink: If you plan to later add a PrivateLink connection (either inbound or outbound) to your environment, and you require the connections to be available in specific Availability Zones, you must provide up to two Availability Zone IDs during onboarding. If not specified, GitLab selects two random Availability Zone IDs where the connections are available.
  • KMS keys for encrypted AWS services (if you are using that functionality).

Maintenance window

When onboarding, you must also specify your preference for the weekly four-hour time slot that GitLab uses to perform routine maintenance and upgrade operations on all tenant instances.

Available scheduled maintenance windows, performed outside standard working hours:

  • APAC: Wednesday 1 PM - 5 PM UTC
  • EU: Tuesday 1 AM - 5 AM UTC
  • AMER Option 1: Tuesday 7 AM - 11 AM UTC
  • AMER Option 2: Sunday 9 PM - Monday 1 AM UTC

Consider the following notes:

  • The Dedicated instance is not expected to be down the entire duration of the maintenance window. Occasionally, a small period of downtime (on the order of a few tens of seconds) can occur while compute resources restart after they are upgraded. If it occurs, this small period of downtime typically happens during the first half of the maintenance window. Long-running connections may be interrupted during this period. To mitigate this, clients should implement strategies like automatic recovery and retry. Longer periods of downtime during the maintenance window are rare, and GitLab provides notice if longer downtime is anticipated.
  • In case of a performance degradation or downtime during the scheduled maintenance window, the impact to the system SLA is not counted.
  • The weekly scheduled maintenance window can be postponed into another window within the same week. This option needs to be agreed with the assigned Customer Success Manager at least one week in advance.
  • The scheduled weekly maintenance window is different from emergency maintenance.

Emergency maintenance

In an event of a platform outage, degradation or a security event requiring urgent action, emergency maintenance will be carried out per the emergency change processes.

The emergency maintenance is initiated urgently when urgent actions need to be executed by GitLab on a Dedicated tenant instance. Communication with the customer will be provided on best effort basis prior to commencing the maintenance, and full communication will follow after the immediate action is carried out.

For example, when a critical security process is initiated to address an S1 vulnerability in GitLab, emergency maintenance is carried out to upgrade GitLab to the non-vulnerable version and that can occur outside of a scheduled maintenance window. Postponing emergency maintenance is not possible, because the same process must be applied to all existing Dedicated customers, and the primary concern is to ensure safety and availability of Dedicated tenant instances.

Configuration changes

To change or update the configuration for your GitLab Dedicated instance, open a support ticket with your request. You can request configuration changes for the options originally specified during onboarding, or for any of the optional features below.

The turnaround time for processing configuration change requests is documented in the GitLab handbook.

Encrypted Data At Rest (BYOK)

note
To enable BYOK, you must do it during onboarding.

You can opt to encrypt your GitLab data at rest with AWS KMS keys, which must be made accessible to GitLab Dedicated infrastructure. GitLab Dedicated only supports keys with AWS-managed key material (the AWS_KMS origin type).

For instructions on how to create and manage KMS keys, see the AWS KMS documentation.

In GitLab Dedicated, you can use KMS keys in two ways:

  • One KMS key for all services
  • Per-service KMS keys (Backup, EBS, RDS, S3)
    • Keys do not need to be unique to each service.
    • All services must be encrypted at rest.
    • Selective enablement of this feature is not supported.
    • Keys do not need to be unique to each service.

Make sure the AWS KMS keys are replicated to your desired primary, secondary, and backup region specified during onboarding.

Create KMS keys in AWS

To enable BYOK, indicate on your onboarding ticket that you’d like to use this functionality. GitLab will provide you with your AWS account ID which is necessary to enable BYOK.

After you have received the AWS account ID, create your KMS keys using the AWS Console:

  1. In Configure key, select:
    1. Key type: Symmetrical
    2. Key usage: Encrypt and decrypt
    3. Advanced options:
      1. Key material origin: KMS
      2. Regionality: Multi-Region key
  2. Enter your values for key alias, description, and tags.
  3. Select key administrators.
  4. Optional. Allow or prevent key administrators from deleting the key.
  5. On the Define key usage permissions page, under Other AWS accounts, add the GitLab AWS account.

The last page asks you to confirm the KMS key policy. It should look similar to the following example, populated with your account IDs and usernames:

{
    "Version": "2012-10-17",
    "Id": "byok-key-policy",
    "Statement": [
        {
            "Sid": "Enable IAM User Permissions",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<CUSTOMER-ACCOUNT-ID>:root"
            },
            "Action": "kms:*",
            "Resource": "*"
        },
        {
            "Sid": "Allow access for Key Administrators",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::<CUSTOMER-ACCOUNT-ID>:user/<CUSTOMER-USER>"
                ]
            },
            "Action": [
                "kms:Create*",
                "kms:Describe*",
                "kms:Enable*",
                "kms:List*",
                "kms:Put*",
                "kms:Update*",
                "kms:Revoke*",
                "kms:Disable*",
                "kms:Get*",
                "kms:Delete*",
                "kms:TagResource",
                "kms:UntagResource",
                "kms:ScheduleKeyDeletion",
                "kms:CancelKeyDeletion",
                "kms:ReplicateKey",
                "kms:UpdatePrimaryRegion"
            ],
            "Resource": "*"
        },
        {
            "Sid": "Allow use of the key",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::<GITLAB-ACCOUNT-ID>:root"
                ]
            },
            "Action": [
                "kms:Encrypt",
                "kms:Decrypt",
                "kms:ReEncrypt*",
                "kms:GenerateDataKey*",
                "kms:DescribeKey"
            ],
            "Resource": "*"
        },
        {
            "Sid": "Allow attachment of persistent resources",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    "arn:aws:iam::<GITLAB-ACCOUNT-ID>:root"
                ]
            },
            "Action": [
                "kms:CreateGrant",
                "kms:ListGrants",
                "kms:RevokeGrant"
            ],
            "Resource": "*"
        }
    ]
}

Make sure the AWS KMS keys are replicated to your desired primary, secondary and backup region specified during onboarding. After you have created the keys, send GitLab the corresponding ARNs of each key so that GitLab can use to encrypt the data stored in your Dedicated instance.

AWS Private Link allows users and applications in your VPC on AWS to securely connect to the GitLab Dedicated endpoint without network traffic going over the public internet.

To enable the Inbound Private Link:

  1. In the body of your support ticket, include the IAM Principal for the AWS user or role in your own AWS Organization that’s establishing the VPC endpoint in your AWS account. GitLab Dedicated uses this IAM Principal for access-control. This IAM principal is the only one able to set up an endpoint to the service.
  2. After your IAM Principal has been allowlisted, GitLab creates the Endpoint Service and communicates the Service Endpoint Name on the support ticket. The service name is generated by AWS upon creation of the service endpoint.
    • GitLab handles the domain verification for the Private DNS name, so that DNS resolution of the tenant instance domain name in your VPC resolves to the PrivateLink endpoint.
    • GitLab makes the Endpoint Service available in the Availability Zones you specified during the initial onboarding. If you did not specify any Availability Zones, GitLab randomly selects the Availability Zones IDs.
  3. In your own AWS account, create an Endpoint Interface in your VPC, with the following settings:
    • Service Endpoint Name: use the name provided by GitLab on the support ticket.
    • Private DNS names enabled: yes.
    • Subnets: choose all matching subnets.
  4. After you create the endpoint, use the instance URL provided to you during onboarding to securely connect to your GitLab Dedicated instance from your VPC, without the traffic going over the public internet.

Consider the following when using Outbound Private Links:

  • Outbound Private Links allow the GitLab Dedicated instance to securely communicate with services running in your VPC on AWS. This type of connection can execute webhooks where the targeted services are running in your VPC, import or mirror projects and repositories, or use any other GitLab functionality to access private services.
  • You can only establish Private Links between VPCs in the same region. Therefore, you can only establish a connection in the regions you selected for your Dedicated instance.
  • The Network Load Balancer (NLB) that backs the Endpoint Service at your end must be enabled in at least one of the Availability Zones to which your Dedicated tenant was deployed. This is not the user-facing name such as us-east-1a, but the underlying Availability Zone ID. If you did not specify these during onboarding to Dedicated, you must either:
    • Ask for the Availability Zone IDs in the ticket you raise to enable the link and ensure the NLB is enabled in those AZs, or
    • Ensure the NLB has is enabled in every Availability Zone in the region.

To enable an Outbound Private Link:

  1. Create the Endpoint service through which your internal service will be available to GitLab Dedicated. Provide the associated Service Endpoint Name on a new support ticket.
  2. In your support ticket, GitLab will provide you with the ARN of an IAM role that will be initiating the connection to your endpoint service. You must ensure this ARN is included, or otherwise covered by other entries, in the list of “Allowed Principals” on the Endpoint Service, as described by the AWS documentation. Though it’s optional, you should you add it explicitly, allowing you to set Acceptance required to No so that Dedicated can connect in a single operation. If you leave Acceptance required as Yes, then you must manually accept the connection after Dedicated has initiated it.
  3. To connect to services using the Endpoint, the Dedicated services require a DNS name. Private Link automatically creates an internal name, but it is machine-generated and not generally directly useful. There are two options available:
    • In your Endpoint Service, enable Private DNS name, perform the required validation, and let GitLab know in the support ticket that you are using this option. If Acceptance Required is set to Yes on your Endpoint Service, also note this on the support ticket because Dedicated will need to initiate the connection without Private DNS, wait for you to confirm it has been accepted, and then update the connection to enable the use of Private DNS.
    • Dedicated can manage a Private Hosted Zone (PHZ) within the Dedicated AWS Account and alias any arbitrary DNS names to the Endpoint, directing requests for those names to your Endpoint Service. This may be useful if you have multiple DNS names/aliases that will be accessed using a single Endpoint (for example, if you are running a reverse proxy to connect to more than one service in your environment), or if the domain you want to use is not public and cannot be validated for use by Private DNS. Let GitLab know on the support ticket if you are using this option and provide a list of DNS names that should resolve to the Private Link Endpoint. This list can be updated as needed in future.

GitLab then configures the tenant instance to create the necessary Endpoint Interfaces based on the service names you provided. Any matching outbound connections made from the tenant GitLab instance are directed through the PrivateLink into your VPC.

Custom certificates

In some cases, the GitLab Dedicated instance can’t reach an internal service you own because it exposes a certificate that can’t be validated using a public Certification Authority (CA). In these cases, custom certificates are required.

To request that GitLab add custom certificates when communicating with your services over PrivateLink, attach the custom public certificate files to your support ticket.

GitLab Dedicated limits the number of reverse PrivateLink connections to 10.

IP allowlist

GitLab Dedicated allows you to control which IP addresses can access your instance through an IP allowlist.

Specify a comma separated list of IP addresses that can access your GitLab Dedicated instance in your support ticket. After the configuration has been applied, when an IP not on the allowlist tries to access your instance, the connection is refused.

SAML

note
GitLab Dedicated supports a limited number of SAML parameters. Parameters not shown in the configuration below are unavailable for GitLab Dedicated tenant instances.

Prerequisites:

  • You must configure the identity provider before sending the required data to GitLab.

To activate SAML for your GitLab Dedicated instance:

  1. To make the necessary changes, include the desired SAML configuration block for your GitLab application in your support ticket. At a minimum, GitLab needs the following information to enable SAML for your instance:
    • IDP SSO Target URL
    • Certificate fingerprint or certificate
    • NameID format
    • SSO login button description
    "saml": {
  "attribute_statements": {
      //optional
  },
  "enabled": true,
  "groups_attribute": "",
  "admin_groups": [
    // optional
  ],
  "idp_cert_fingerprint": "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
  "idp_sso_target_url": "https://login.example.com/idp",
  "label": "IDP Name",
  "name_identifier_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
  "security": {
    // optional
  },
  "auditor_groups": [
    // optional
  ],
  "external_groups": [
    // optional
  ],
  "required_groups": [
    // optional
  ],
}
  2. After GitLab deploys the SAML configuration to your instance, you are notified on your support ticket.
  3. To verify the SAML configuration is successful:
    • Check that the SSO login button description is displayed on your instance’s login page.
    • Go to the metadata URL of your instance (https://INSTANCE-URL/users/auth/saml/metadata). This page can be used to simplify much of the configuration of the identity provider, as well as manually validate the settings.

Request signing

If SAML request signing is desired, a certificate must be obtained. This certificate can be self-signed which has the advantage of not having to prove ownership of an arbitrary Common Name (CN) to a public Certificate Authority (CA)). If you choose to enable SAML request signing, the manual steps below will need to be completed before you are able to use SAML, since it requires certificate signing to happen. To enable SAML request signing, indicate on your SAML support ticket that you want request signing enabled. GitLab works with you on sending the Certificate Signing Request (CSR) for you to sign. Alternatively, the CSR can be signed with a public CA. After the certificate is signed, GitLab adds the certificate and its associated private key to the security section of the SAML configuration. Authentication requests from GitLab to your identity provider can then be signed.

SAML groups

With SAML groups you can configure GitLab users based on SAML group membership.

To enable SAML groups, add the required elements to the SAML configuration block you provide in your support ticket.

Group sync

With group sync, you can sync users across identity provider groups to mapped groups in GitLab.

To enable group sync:

  1. Add the required elements to the SAML configuration block you provide in your support ticket.
  2. Configure the Group Links.

Access to application logs

GitLab application logs are delivered to an S3 bucket in the GitLab tenant account, which can be shared with you. Logs stored in the S3 bucket are retained indefinitely, until the 1 year retention policy is fully enforced. GitLab team members can view more information in this confidential issue: https://gitlab.com/gitlab-com/gl-infra/gitlab-dedicated/team/-/issues/483.

To gain read only access to this bucket:

  1. Open a support ticket with the title “Customer Log Access”. In the body of the ticket, include a list of IAM Principal ARNs (users or roles) that are fetching the logs from S3.
  2. GitLab then informs you of the name of the S3 bucket. Your nominated users/roles can then able to list and get all objects in the S3 bucket.