Custom domain

Set up a custom domain for your Ona management plane with TLS termination

This feature is only available on the Enterprise tier. Contact your account manager to request access.

This guide walks you through setting up a custom domain for your Ona management plane, enabling you to access Ona services through your own domain name with TLS termination.

Overview

The setup involves two main steps:

1. Register the custom domain in your organization settings
2. Configure AWS infrastructure to route traffic to the Ona management plane

Custom domains are currently supported on AWS only. Support for GCP is coming soon.

Prerequisites

Before you begin, ensure you have:

• Admin access to your Ona organization settings
• Single Sign-On (SSO) configured - Custom domains require SSO to be set up. See the SSO documentation for setup instructions.
• An AWS account with appropriate permissions
• A registered domain name (e.g., ona.example.com)
• An AWS Certificate Manager (ACM) certificate covering your domain name

Step 1: Register custom domain with Ona

Register your custom domain name with the management plane through the Ona dashboard.

Access domain settings

1. Navigate to Settings → Organization → Login and security → Domain & Access
2. Click Set Up

Configure domain

Enter the following information:

• AWS Account ID: The 12-digit AWS account ID where you will set up the infrastructure (Load Balancer, VPC Endpoint). Find this in the AWS Management Console under My Account.
• Domain name: Your custom domain (e.g., ona.example.com).

Note: The AWS account ID you specify here must match the account where you create the VPC Endpoint. This is validated when requests come through your custom domain.

After registering your custom domain, you’ll need to complete the AWS infrastructure setup below. There is no automatic validation - the configuration is verified only when requests are made through your custom domain.

Custom domain settings

Step 2: Configure AWS infrastructure

Now that the domain is registered with Ona, you need to set up the AWS infrastructure to route traffic from your domain to the Ona management plane.

2.1 Prepare your certificate

Ensure you have an AWS Certificate Manager (ACM) certificate that covers your custom domain name. This certificate will be used for TLS termination on the Load Balancer.

The certificate must be provisioned in the same AWS region where you’ll create your Network Load Balancer.

---

2.2 Create security groups

Create two separate security groups: one for the Network Load Balancer and another for the VPC endpoint.

Load Balancer security group

Create a security group with the following rules:

• Inbound: HTTPS (443) from your desired source (e.g., your corporate network, internet).
• Outbound: HTTPS (443) to the VPC Endpoint security group (to be created below).

VPC Endpoint security group

Create a security group with the following rules:

• Inbound: HTTPS (443) from the Load Balancer security group (created above).
• Outbound: All traffic (or as per your security requirements).

Note the security group IDs for both—you’ll need them for the following configuration.

---

2.3 Create VPC endpoint

Create a VPC Endpoint to connect to the Ona management plane service.

Configuration

1. Navigate to VPC Console → Endpoints → Create Endpoint

2. Service Configuration:

   • Service category: Select Endpoint services that use NLBs and GWLBs.
   • Service name: com.amazonaws.vpce.us-east-1.vpce-svc-00fa18d41fdd25cad.
   • Click Verify service.
   

   Create VPC Endpoint

   ⚠️ Important: If you are in a region other than us-east-1, you must:

   • Enable cross-region VPC endpoint.

   • Specify us-east-1 as the service region.

   • The VPC endpoint service is available in the following Availability Zones:

     use1-az1 (us-east-1a)
     use1-az2 (us-east-1b)
     

3. VPC and Subnets:

   • Select the VPC and subnets where you want your VPC endpoint to be created.
   • Select at least 2 Availability Zones for high availability.
   

   VPC Endpoint Network Settings

4. Security Groups:

   • Select the security group created earlier for the VPC endpoint.

5. Create Endpoint and wait for it to become Available.

6. Note the Private IP Addresses:

   • Once the VPC Endpoint is available, navigate to the Subnets tab.
   • Note down all the private IP addresses assigned to the endpoint (one per subnet/AZ).
   

   VPC Endpoint Private IPs

---

2.4 Create target group

Create a Target Group to route traffic from the Load Balancer to the VPC Endpoint.

Configuration

1. Navigate to EC2 Console → Target Groups → Create Target Group

2. Basic Configuration:

   • Target type: IP addresses.
   • Target group name: Give it a descriptive name (e.g., ona-vpce-targets).
   • Protocol: TCP.
   • Port: 443.
   • VPC: Select the same VPC.
   

   Target Group Configuration

3. Health Checks:

   • Protocol: TCP.
   • Leave the default health check settings.

4. Register Targets:

   • Click Next.
   • Add each private IP address from the VPC Endpoint (noted in step 2.3).
   • Port: 443 for each IP.
   • Click Include as pending below.
   • Click Create target group.
   

   Register Target IPs

---

2.5 Create Network Load Balancer

Create a Network Load Balancer (NLB) to handle incoming traffic.

Configuration

1. Navigate to EC2 Console → Load Balancers → Create Load Balancer

2. Choose Load Balancer Type:

   • Select Network Load Balancer.

     

     Choose Load Balancer Type

3. Configure Load Balancer:

   • Name: Give it a descriptive name (e.g., ona-custom-domain-lb).
   • Scheme: Choose Internal or Internet-facing based on your access requirements.
   • IP address type: IPv4.
   • VPC: Select the VPC of your VPC endpoint.
   • Availability Zones: Select the same Availability Zones chosen for the VPC endpoint (must be at least 2).

4. Select the Security Group:

   

   Load Balancer Security Groups

   • Select the security group created earlier for the load balancer.

5. Configure Listener:

   • Protocol: TLS.
   • Port: 443.
   • Default action: Forward to the target group created in step 2.4.
   • Default SSL/TLS server certificate: Select the ACM certificate you prepared.
   • ⚠️ ALPN policy: Select HTTP/2 preferred as the ALPN policy. This is important for optimal performance when connecting to the management plane.
   

   Listener Configuration

6. Create Load Balancer.

---

Step 3: Configure DNS

Point your custom domain to the Load Balancer.

1. Get Load Balancer DNS Name:

   • In the Load Balancer details, copy the DNS name.

     

     Load Balancer DNS Name

2. Create DNS Record:
   • In your DNS provider (Route 53, Cloudflare, etc.), create a CNAME or ALIAS record:
     • Name: Your custom domain (e.g., ona.example.com).
     • Type: CNAME (or ALIAS if using Route 53).
     • Value: Load Balancer DNS name.

---

Step 4: Verify setup

1. Wait for DNS propagation (typically 5-15 minutes).
2. Access your custom domain in a browser: https://ona.example.com.
3. Verify that:
   • TLS certificate is valid.
   • You can reach the Ona management plane.
   • No certificate warnings appear.

---

Step 5: Update your SSO configuration

Update your SSO configuration to allow the new redirect URL using your custom domain:

https://ona.example.com/auth/oidc/callback

This step is required - authentication will fail without updating the SSO callback URL. See the SSO documentation for provider-specific instructions.

---

Step 6: Recreate your runner

Destroy any existing runners and create a new one by accessing the management plane from your custom domain. Follow the usual runner creation setup.

Why this is necessary: Runners are configured during creation with the management plane URL they should connect to. Existing runners will continue trying to connect via the old domain. Creating a new runner from your custom domain ensures it’s configured with the correct endpoint and can properly communicate with the management plane through your infrastructure.

---

Step 7: Enforce custom domain access (Optional)

After completing the setup, you can optionally enable a policy to require all users to access Ona exclusively through your custom domain:

1. Navigate to Settings → Organization → Login and security.
2. Enable Enforce custom domain access.

When enabled:

• Users will be blocked from accessing via the default domain (app.gitpod.io).
• Organization admins can always access via the default domain as a fail-safe.
• This ensures all traffic goes through your controlled infrastructure.

Note: Users who are currently logged in with an active session can continue using the default domain until their session expires. The enforcement only applies to new login attempts.

---

Troubleshooting

Connection issues

If you cannot connect to your custom domain:

1. Verify DNS propagation using dig or nslookup.
2. Check that the Load Balancer is in an Active state.
3. Verify the target group shows healthy targets.
4. Ensure security group rules allow traffic from your source.

Certificate errors

If you see certificate warnings:

1. Verify the ACM certificate covers your domain name.
2. Check that the certificate is attached to the Load Balancer listener.
3. Ensure the certificate is valid and not expired.

Performance issues

If you experience slow connections:

1. Verify the ALPN policy is set to HTTP/2 preferred on the Load Balancer listener.
2. Check that you’ve selected at least 2 Availability Zones for high availability.
3. Verify the VPC Endpoint is in an Available state.

AWS Account ID mismatch

If you see “AWS account ID mismatch” errors:

1. Verify the VPC Endpoint was created in the same AWS account registered in your custom domain settings.
2. Check the AWS account ID in Settings → Organization → Login and security → Domain & Access.
3. If the account ID is incorrect, edit the custom domain configuration to update it.

VPC Endpoint connection issues

If you see “Failed to resolve VPC Endpoint ID” errors:

1. Verify the VPC Endpoint is connected to the Ona VPC Endpoint Service.
2. Check that Proxy Protocol v2 is enabled on the Network Load Balancer target group.
3. Ensure the VPC Endpoint is in an Available state.
4. Verify the target group shows healthy targets.

For additional support, Enterprise customers can reach out to your account manager.