Skip to main content

Custom domains

What is a custom domain?​

Custom domains allow you to define one or more domains and associate them with a scope. These custom domains do not replace the automatically generated domain but serve as an additional option.

When you create a scope, nullplatform automatically generates a domain using the namespace, application, and scope slugs, along with a hash to prevent collisions.

For example, if your:

  • organization is called Crypto Inc,
  • namespace is Billing,
  • application is Payments API, and
  • scope is Production Argentina;

The domain generated by nullplatform would look something like this:
billing-payments-api-production-argentina-$hash.crypto-inc.com

While this domain allows traffic to be routed to the scope, it is not a user-friendly name suitable for public use. For that reason, you can create custom domains and associate them with your scopes.

Configuring a custom domain​

To configure a custom domain, go to Platform settings and select Custom Domains under the Networking menu.

The setup involves:

  • Making sure your certificate supports the new domain before setting it up.
  • Entering the fully qualified domain name (FQDN) without the protocol (http, https). For example, api.crypto-inc.com.
  • Selecting the application and scope to associate the domain with.
Need to know

Each scope can have multiple custom domains, but a custom domain can only be assigned to a single scope.

For more details, see the Custom domain API reference.

What happens when a domain is associated with a scope?​

When a domain is associated with a scope, nullplatform configures a rule in the relevant load balancer (e.g., ALB for AWS instances, Ingress for Kubernetes) to route all requests for that domain to the scope’s infrastructure.

Important
  • The user setting up the domain is responsible for creating the domain and configuring traffic routing to the appropriate load balancer.
  • Like any changes made to scopes, the new domain will take effect starting from the next deployment.

Troubleshooting​

Verify DNS configuration​

If your custom domain isn’t working, start by checking your DNS settings:

  • Register the domain: Make sure your custom domain is properly registered with your DNS provider.
  • Create necessary DNS records:
    • Ensure that DNS records are pointing to the correct infrastructure endpoint — whether that’s an ALB, API Gateway, or another ingress controller.
    • Example: If you're using AWS API Gateway, a CNAME should point to the gateway's domain name.

Check the gateway objects​

If you're using Kubernetes with Istio, verify that the cluster is configured to accept the custom domain.

  • Check the Istio Gateway resources, such as gateway-private and gateway-public.
  • These gateway objects must be configured to route requests for your custom domains.

For example, if HTTP routes are not working, it's often necessary to review the Gateway configuration.

Within the gateway objects:

  • Ensure the domain validation is correctly set to match your custom domains.
  • Confirm that the TLS certificates associated with the gateway are valid and cover all configured custom domains.

An invalid or missing domain entry or certificate could prevent traffic from reaching your services.