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.
Each endpoint service is available in two availability zones, chosen during onboarding or randomly selected.
IAM principals are configured independently for each region. You can reuse the same principals across regions, or use different ones if your secondary region uses a separate AWS account.
Create an inbound PrivateLink connection to allow users and applications in your VPC to connect privately to your GitLab Dedicated instance.
To keep this connection available during regional failover, configure a secondary region endpoint. Without this, your instance is not privately accessible if your primary region becomes unavailable.
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.
In the left sidebar, select Configuration.
Expand Inbound PrivateLink connections.
Select Add endpoint service.
Select a region.
Under IAM principals, add the AWS users or roles that can initiate connections to the endpoint service. The IAM principals must be IAM role principals or IAM user principals.
In your AWS account, attach a policy with the following permissions to the role or user that creates the VPC endpoint:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "GitLabDedicatedInboundPrivateLink",
"Effect": "Allow",
"Action": [
"ec2:CreateVpcEndpoint",
"ec2:DescribeVpcEndpointServices",
"ec2:DescribeVpcEndpoints",
"ec2:DescribeVpcs",
"route53:AssociateVPCWithHostedZone"
],
"Resource": "*"
}
]
}
Recommended. To configure a secondary region, select Secondary region under Regions. This will create endpoint services in the both regions with the specified IAM principals.
Select Save. GitLab creates the endpoint services and the service endpoint names become available on the Configuration page.
Then, for each region you configured, complete the AWS setup:
To automate the AWS VPC endpoint setup, you can use the
terraform-inbound-privatelink
Terraform module. The module also outputs 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 for each 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.
Outbound PrivateLink connections in Switchboard use service connections to manage connectivity. A service connection links a DNS alias to a VPC endpoint service in your AWS account. Each service connection can have up to two VPC endpoints, one for each region (primary and secondary). When you create a service connection, you choose how DNS is resolved:
For aliases that do not require a VPC endpoint, you can create a custom DNS record instead.
Create a service connection to route outbound traffic from your GitLab Dedicated instance through AWS PrivateLink to a service in your VPC.
To keep this connection available during regional failover, configure a secondary region endpoint. Without this, outbound connections are unavailable if your primary region becomes unavailable. Switchboard displays a warning if a service connection has VPC endpoints in only one region.
Prerequisites:
To create a service connection:
my-service.example.com.com.amazonaws.vpce.us-east-1.vpce-svc-0a123bcd4e5f678gh), or select
Existing VPC endpoint and choose an endpoint from the dropdown list.GitLab configures your instance to create the necessary VPC endpoints and DNS records (unless Private DNS is selected, in which case AWS manages DNS resolution). After setup, GitLab routes matching outbound connections into your VPC over PrivateLink.
Use custom DNS records for DNS aliases that do not point to a VPC endpoint. For example, use a custom DNS record when you need your GitLab Dedicated instance to resolve a private domain name to a publicly accessible or internally routed service.
By default, the alias splits at the first dot into a record name and private hosted zone
name. For example, service.example.com splits into record name service and zone
example.com. If this split causes domain shadowing or conflicts with existing service
connection aliases or custom domains, use the advanced option to customize the split.
A private hosted zone (PHZ) is a container that holds information about how Amazon Route 53 responds to DNS queries for a domain and its subdomains within your GitLab Dedicated VPC. For more information, see private hosted zones.
Changes to custom DNS records, or to service connections when using GitLab-managed DNS (private hosted zones), can disrupt services that use these records for up to five minutes.
To add a custom DNS record:
my-internal-service.example.com.If you cannot use Switchboard to configure outbound PrivateLink connections:
You can delete a service connection or a VPC endpoint independently. Each has its own tab in Switchboard: Service connections and VPC endpoints.
To delete a service connection:
To delete a VPC endpoint:
IPv6 connectivity lets clients reach your GitLab Dedicated instance over IPv6, in addition to IPv4. Cloudflare receives this traffic and translates it to IPv4 before forwarding requests to your instance's existing IPv4 infrastructure. Internal communication between GitLab Dedicated platform services remains IPv4-only.
When you turn on IPv6 for your instance:
Prerequisites:
Switchboard doesn't support this configuration. To turn on IPv6 connectivity, open a support ticket and confirm you want IPv6 connectivity turned on for HTTPS and SSH access to your instance.
After IPv6 is turned on, the public IP addresses for your instance change for both IPv4 and IPv6. If you've allowlisted these addresses in firewalls, DNS records, or monitoring systems, update those configurations after the change is applied. Turning off IPv6 changes the IP addresses again.
The configuration is applied during the next maintenance window.
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.
In the left sidebar, 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 or 2001:db8::1).192.168.1.0/24 or 2001:db8::/32).At the top of the page, choose whether to apply the changes immediately or during the next maintenance window.
To delete IP addresses from the allowlist:
Sign in to Switchboard.
In the left sidebar, 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 identify your instance's outbound connections to external services. They typically remain consistent but can change if a regional failover occurs, because the instance is rebuilt with new infrastructure.
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: