doc/administration/dedicated/configure_instance/network_security.md
{{< details >}}
{{< /details >}}
You can configure a custom domain to access your GitLab Dedicated
instance instead of the default your-tenant.gitlab-dedicated.com.
When you add a custom domain:
tenant.gitlab-dedicated.com domain are no longer available.GitLab automatically manages SSL/TLS certificates for your custom domain using Let's Encrypt. Let's Encrypt uses the HTTP-01 challenge to verify domain ownership, which requires:
For instances configured with private networking (such as AWS PrivateLink), public DNS resolution ensures certificate management works properly, even when all other access is restricted to private networks.
GitLab Dedicated supports custom domains through two configuration methods:
Contact your Customer Success Manager to determine which configuration method applies to your instance.
With this configuration, your domain connects directly to your GitLab instance using a CNAME record. GitLab automatically manages SSL certificates using Let's Encrypt, which verifies domain ownership through public DNS lookups and renews certificates automatically every 90 days.
[!note] Your custom domain must be accessible from the public internet for SSL certificate management, even if you access your instance through private networks.
For instances configured with private networking (such as AWS PrivateLink), public DNS access ensures certificate management works properly, even when all other access is restricted to private networks.
Prerequisites:
To configure DNS records:
Sign in to your domain host's website.
Go to the DNS settings.
Add a CNAME record that points your custom domain to your GitLab Dedicated instance. For example:
gitlab.my-company.com. CNAME my-tenant.gitlab-dedicated.com
Optional. If your domain has an existing CAA record, update it to include
Let's Encrypt as a valid certificate authority. For example:
gitlab.my-company.com. IN CAA 0 issue "pki.goog"
gitlab.my-company.com. IN CAA 0 issue "letsencrypt.org"
The CAA record defines which certificate authorities can issue certificates for your domain.
Save your changes and wait for DNS changes to take effect.
Keep your DNS records in place as long as you use the custom domain.
Prerequisites:
To enable your custom domain:
gitlab.company.com.registry.company.com and kas.company.com.With this configuration, your domain must be delegated to GitLab using NS records, which allows traffic to be routed through Cloudflare Web Application Firewall (WAF). Cloudflare manages all DNS settings for your domain and provides enhanced security features.
[!note] This approach requires coordination with your Customer Success Manager. The configuration is applied during your instance's maintenance period.
To request a custom domain:
gitlab.company.com.registry.company.com and kas.company.com.GitLab configures your domain in Cloudflare and provides:
name1.ns.cloudflare.com and name2.ns.cloudflare.com.Configure NS records in your DNS provider to delegate your subdomain to Cloudflare.
Prerequisites:
To configure DNS records:
Sign in to your domain host's website.
Go to the DNS settings.
Create NS records using the nameservers provided by GitLab. For example:
gitlab.company.com. NS name1.ns.cloudflare.com.
gitlab.company.com. NS name2.ns.cloudflare.com.
Remove any conflicting A, AAAA, or CNAME records for the same subdomain.
FedRAMP customers only. Add a DS record using the values provided by GitLab:
gitlab.company.com. DS [Key Tag] [Algorithm] [Digest Type] [Digest]
For example:
gitlab.company.com. DS 12345 13 2 A1B2C3D4E5F6...
Save your changes. DNS changes can take up to 48 hours to take effect.
Verify your configuration:
# Verify nameserver delegation
dig +short NS gitlab.company.com
# Verify DNS resolution
dig gitlab.company.com
# Verify DNSSEC (if configured)
dig +dnssec gitlab.company.com
Notify GitLab through your support ticket that DNS configuration is complete.
GitLab then:
GitLab Dedicated validates certificates when connecting to external services over HTTPS. By default, GitLab Dedicated trusts only publicly recognized certificate authorities and rejects connections to services with certificates from untrusted certificate authorities.
If your external services use certificates from a private or internal certificate authority, you must add that certificate authority to your GitLab Dedicated instance.
You might need custom certificate authorities to:
Certificate chain blocks (multiple certificates in a single text block) are not supported. If you have multiple certificates in your chain, add each certificate separately.
To add a custom certificate:
-----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.If you cannot use Switchboard to add a custom certificate, open a support ticket and attach each custom certificate as a separate file.
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.
You can create private links only in your primary and secondary AWS regions where your GitLab Dedicated instance is deployed.
When you create a private link, you specify IAM principals that control access. Only the IAM principals you specify can create VPC endpoints to connect to your instance.
The endpoint service is available in two availability zones that are either chosen during onboarding or randomly selected.
To create the interface VPC endpoint, the IAM principal must have the following permissions:
ec2:CreateVpcEndpointec2:DescribeVpcEndpointServicesec2:DescribeVpcEndpointsec2:DescribeVpcsroute53:AssociateVPCWithHostedZoneThese permissions allow you to:
For example, attach the following IAM policy to the role or user creating the VPC endpoint:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "GitLabDedicatedInboundPrivateLink",
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpoint",
"ec2:DescribeVpcEndpointServices",
"ec2:DescribeVpcEndpoints",
"ec2:DescribeVpcs",
"route53:AssociateVPCWithHostedZone"
],
"Resource": "*"
}
]
}
Prerequisites:
arn:aws:iam::AWS_ACCOUNT_ID:role/RoleNamearn:aws:iam::AWS_ACCOUNT_ID:role/somepath/AnotherRoleNameTo create an inbound private link:
Sign in to Switchboard.
At the top of the page, select Configuration.
Expand Inbound private link.
Select Add endpoint service. This button is not available if all your available regions already have private links.
Select a region.
Add IAM principals for the AWS users or roles in your AWS organization that are establishing the VPC endpoints. The IAM principals must be IAM role principals or IAM user principals.
Select Save.
GitLab creates the endpoint service and handles domain verification for private DNS. The service endpoint name becomes available on the Configuration page.
In your AWS account, create an endpoint interface in your VPC.
Configure the endpoint interface with these settings:
Use the instance URL provided during onboarding to connect to your GitLab Dedicated instance from your VPC.
When you use Inbound Private Link to connect to your GitLab Dedicated instance, only the main instance URL has automatic DNS resolution through the private network.
To access KAS (GitLab agent for Kubernetes) and registry services through your private network, you must create an additional DNS configuration in your VPC.
Prerequisites:
To enable KAS and registry through your private network:
In your AWS console, create a private hosted zone for gitlab-dedicated.com
and associate it with the VPC that contains your private link connection.
After you create the private hosted zone, add the following DNS records (replace example with your instance name):
Create an A record for your GitLab Dedicated instance:
Configure your full instance domain (for example, example.gitlab-dedicated.com) to resolve to your VPC endpoint as an Alias.
Select the VPC endpoint that does not contain an Availability Zone reference.
Create CNAME records for both KAS and the registry to resolve to your GitLab Dedicated instance domain (example.gitlab-dedicated.com):
kas.example.gitlab-dedicated.comregistry.example.gitlab-dedicated.comTo verify connectivity, from a resource in your VPC, run these commands:
nslookup kas.example.gitlab-dedicated.com
nslookup registry.example.gitlab-dedicated.com
nslookup example.gitlab-dedicated.com
All commands should resolve to private IP addresses within your VPC.
This configuration is robust to IP address changes because it uses the VPC endpoint interface rather than specific IP addresses.
Access GitLab Pages through your private network by creating additional DNS configuration in your VPC, similar to the KAS and registry configuration.
To enable Pages through your private network:
<tenant_name>.gitlab-dedicated.site
and associate it with the VPC that contains your private link connection.A alias record for the VPC endpoint.CNAME for *.<tenant_name>.gitlab-dedicated.site that points to <tenant_name>.gitlab-dedicated.site.The tenant name is available on the Overview page in Switchboard, in the Tenant overview section.
Service name could not be verifiedYou might get an error that states Service name could not be verified when trying to create a VPC endpoint.
This issue occurs when the custom IAM role provided in the support ticket does not have the proper permissions or trust policies configured in your AWS account.
To resolve this issue:
Confirm that you can assume the custom IAM role provided to GitLab in the support ticket.
Verify the custom role has a trust policy that allows you to assume it. For example:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::CONSUMER_ACCOUNT_ID:user/user-name"
},
"Action": "sts:AssumeRole"
}
]
}
Verify the custom role has a permission policy that allows VPC endpoint and EC2 actions. For example:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "vpce:*",
"Resource": "*"
},
{
"Sid": "Statement1",
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpoint",
"ec2:DescribeVpcEndpointServices",
"ec2:DescribeVpcEndpoints"
],
"Resource": "*"
}
]
}
Using the custom role, retry creating the VPC endpoint in your AWS console or CLI.
Outbound private links allow your GitLab Dedicated instance and the hosted runners for GitLab Dedicated to securely communicate with services running in your VPC on AWS without exposing any traffic to the public internet.
This type of connection allows GitLab functionality to access private services:
For the GitLab Dedicated instance:
For hosted runners:
Consider the following:
Prerequisites:
Create the endpoint service for your internal service to be available to GitLab Dedicated.
Configure a Network Load Balancer (NLB) for the endpoint service in the Availability Zones (AZs) where your Dedicated instance is deployed. Either:
Add the ARN of the role that GitLab Dedicated uses to connect to your endpoint service to the Allowed Principals list on the Endpoint Service. You can find this ARN in Switchboard under Outbound private link IAM principal. For more information, see Manage permissions.
Recommended. Set Acceptance required to No to enable GitLab Dedicated to connect in a single operation. If set to Yes, you must manually accept the connection after it's initiated.
[!note] If you set Acceptance required to Yes, Switchboard cannot accurately determine when the link is accepted. After you manually accept the link, the status shows as Pending instead of Active until next scheduled maintenance. After maintenance, the link status refreshes and shows as connected.
Once the endpoint service is created, note the Service Name and if you have enabled Private DNS or not.
Service Endpoint Name on a new
support ticket.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.Acceptance Required is set to Yes on your
Endpoint Service, also note this on the support ticket because Dedicated will have 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.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 instance are directed through the PrivateLink into your VPC.
If you have trouble establishing a connection after the Outbound Private Link has been set up, a few things in your AWS infrastructure could be the cause of the problem. The specific things to check vary based on the unexpected behavior you're seeking to fix. Things to check include:
A private hosted zone (PHZ) creates custom DNS records (such as A, CNAME, or other record types) that resolve in your GitLab Dedicated instance's network.
Use a PHZ when you want to:
PHZs are commonly used with reverse PrivateLink to create readable domain names instead of using AWS-generated endpoint names. For example, you can use alpha.beta.tenant.gitlab-dedicated.com instead of vpce-0987654321fedcba0-k99y1abc.vpce-svc-0a123bcd4e5f678gh.eu-west-1.vpce.amazonaws.com.
In some cases, you can also use PHZs to create DNS records that resolve to publicly accessible DNS names. For example, you can create an internal DNS name that resolves to a public endpoint when you need internal systems to access a service through its private name.
[!note] Changes to private hosted zones can disrupt services that use these records for up to five minutes.
PHZ records can point to different types of targets. The most common and recommended approach is to point to DNS names for AWS VPC endpoints.
When using your GitLab Dedicated instance's domain as part of an alias with a VPC endpoint, you must include at least one subdomain before the main domain. For example:
subdomain1.<your-tenant-id>.gitlab-dedicated.com.<your-tenant-id>.gitlab-dedicated.com.For custom domains, you must provide a PHZ name and a PHZ entry in the format phz-entry.phz-name.com.
If your PHZ record points to a DNS name that is not a VPC endpoint, you must include at least two subdomains before the main domain. For example: subdomain1.subdomain2.tenant.gitlab-dedicated.com.
To add a private hosted zone:
Available or Pending Acceptance status are shown.If you are unable to use Switchboard to add a private hosted zone, you can open a support ticket and provide a list of DNS names that should resolve to the endpoint service for the outbound private link. The list can be updated as needed.
Control which IP addresses can access your instance with an IP allowlist.
When you enable the IP allowlist, IP addresses not on the allowlist are blocked
and receive an HTTP 403 Forbidden response when they try to access your instance.
Use Switchboard to configure and manage your IP allowlist, or submit a support request if Switchboard is unavailable.
To add IP addresses to the allowlist:
Sign in to Switchboard.
At the top of the page, select Configuration.
Expand IP allowlist, then select IP allowlist to go to the IP allowlist page.
To enable the IP allowlist, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then select Enabled.
Do one of the following:
192.168.1.1).192.168.1.0/24).At the top of the page, choose whether to apply the changes immediately or during the next maintenance window.
Sign in to Switchboard.
At the top of the page, select Configuration.
Expand IP allowlist, then select IP allowlist to go to the IP allowlist page.
Do one of the following:
At the top of the page, choose whether to apply the changes immediately or during the next maintenance window.
If you are unable to use Switchboard to update your IP allowlist, open a support ticket and specify a comma-separated list of IP addresses that can access your instance.
Using GitLab as an OpenID Connect identity provider requires internet access to the OpenID Connect verification endpoint.
To enable access to the OpenID Connect endpoint while maintaining your IP allowlist:
The configuration is applied during the next maintenance window.
You can use SCIM with external identity providers to automatically provision and manage users. To use SCIM, your identity provider must be able to access the instance SCIM API endpoints. By default, IP allowlisting blocks communication to these endpoints.
To enable SCIM while maintaining your IP allowlist:
The configuration is applied during the next maintenance window.