doc/administration/dedicated/configure_instance/network_security.md
{{< details >}}
{{< /details >}}
Use these settings to control how your GitLab Dedicated instance connects to the internet and to your private infrastructure. You can configure custom domains, manage certificate authorities for external services, set up private network connectivity with AWS PrivateLink, restrict access with an IP allowlist, and view the outbound IPs your instance uses.
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.
The Custom domains section displays the active domain configuration for your GitLab Dedicated instance, including:
Use this information to:
To view your custom domain details:
{{< details >}}
{{< /details >}}
If your custom domain is configured with Cloudflare Web Application Firewall (WAF), Switchboard displays additional configuration details, including Cloudflare nameservers and DNSSEC parameters for FedRAMP compliance.
The additional details include:
Use these values to configure DNS delegation and DNSSEC validation with your DNS provider.
With this configuration, your domain connects directly to your GitLab instance using a CNAME record. You configure your own DNS records and request domain activation through support.
[!note] Your custom domain must be accessible from the public internet for SSL certificate management, even if you access your instance through 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:
The container registry FQDN (Fully Qualified Domain Name) identifies the S3 bucket that stores your instance's container registry data.
Use the FQDN instead of IP addresses to configure firewall rules and network policies that reference the registry storage location. IP addresses for S3 buckets can change over time.
To view your container registry FQDN:
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 PrivateLink enables private network connectivity between your AWS infrastructure and your GitLab Dedicated instance without routing traffic over the public internet. All traffic stays within the AWS network, which reduces exposure to external threats and can help meet compliance requirements for private networking.
GitLab Dedicated supports two types of PrivateLink connections:
PrivateLink connections must be in the same AWS region as your GitLab Dedicated instance, and you can create endpoint services only in your primary and secondary AWS regions.
For more information about AWS PrivateLink, see What is AWS PrivateLink?.
Inbound PrivateLink connections allow users and applications in your VPC to connect privately to your GitLab Dedicated instance.
When you create an endpoint service, 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.
Prerequisites:
arn:aws:iam::AWS_ACCOUNT_ID:role/RoleNamearn:aws:iam::AWS_ACCOUNT_ID:role/somepath/AnotherRoleNameTo create an inbound PrivateLink connection:
Sign in to Switchboard.
At the top of the page, select Configuration.
Expand Inbound private connections.
Select Add endpoint service. This button is not available if all your available regions already have endpoint services.
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. Attach a policy with the following permissions 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": "*"
}
]
}
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.
You can use the
terraform-inbound-privatelink
Terraform module to automate the AWS VPC Endpoint setup and output the Route 53 records
required when you switch DNS.
Create additional DNS configuration in your VPC to access KAS (GitLab agent for Kubernetes) and the container registry through your private network.
Prerequisites:
To configure DNS for KAS and registry:
In your AWS console, create a private hosted zone for gitlab-dedicated.com
and associate it with the VPC that contains your inbound PrivateLink 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 uses the VPC endpoint interface rather than specific IP addresses, so it remains stable if IP addresses change.
To access GitLab Pages through your private network, create additional DNS configuration in your VPC.
To configure DNS for GitLab Pages:
<tenant_name>.gitlab-dedicated.site
and associate it with the VPC that contains your inbound PrivateLink connection.A alias record for the VPC endpoint.CNAME for *.<tenant_name>.gitlab-dedicated.site that points
to <tenant_name>.gitlab-dedicated.site.Outbound PrivateLink connections allow your GitLab Dedicated instance and hosted runners to communicate privately with services running in your VPC, without exposing traffic to the public internet.
Use outbound PrivateLink connections to send webhooks, import or mirror projects and repositories, and give hosted runners access to custom secrets managers, artifacts, job images, and deployments in your infrastructure.
You can create up to 10 outbound PrivateLink connections per region. To consolidate more
than 10 backend services behind a single connection, you can use the
terraform-outbound-proxy
Terraform module to deploy a highly available NGINX reverse proxy with TLS passthrough,
HTTP routing, and SMTP forwarding.
Prerequisites:
[!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 the next scheduled maintenance. After maintenance, the link status refreshes and shows as connected.
To add an outbound PrivateLink connection with Switchboard:
To add an outbound PrivateLink connection with a support request:
GitLab configures your instance to create the necessary endpoint interfaces based on the service names you provided. PrivateLink directs matching outbound connections into your VPC.
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 cannot use Switchboard to add a private hosted zone, open a support ticket and provide a list of DNS names that should resolve to the endpoint service for the outbound PrivateLink connection. 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 cannot 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.
NAT gateway IP addresses are the outbound IPs your instance uses when making connections to external services. These IPs typically remain consistent but can change if GitLab rebuilds your instance during disaster recovery.
Use these IP addresses to configure webhook receivers and set up allowlists for external services to accept connections from your instance.
To view your NAT gateway IP addresses:
When working with AWS PrivateLink connections, you might encounter the following issues.
Service name could not be verifiedWhen creating a VPC endpoint for an inbound PrivateLink connection,
you might get an error that states Service name could not be verified.
This issue occurs when the custom IAM role provided in the support ticket does not have the required 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.
If your outbound PrivateLink connection is not working, check the following: