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.

Custom domains for custom scopes

To assign a custom domain to a custom scope, the creator of the custom scope must explicitly declare that it supports the feature.

This is done by adding the attribute support_custom_domains with the value true in the scope specification. If this attribute is not set, any attempt to create a domain for the scope will result in an API error:

Error: The scope does not support custom domains.

Here's an example of a service payload supporting custom domains:

Service payload example

{
   "name": "My scope name",
   "type": "scope",
   "visible_to": [
       "organization=1:account=2:namespace=3:application=4"
   ],
   "attributes": {
       "schema": {
           "type": "object",
           "required": ["warmup"],
           "properties": {
               "asset_type": {
                   "type": "string",
                   "export": false,
                   "default": "docker-image",
                   "readOnly": true
               },
               "custom_domains": {
                  "type": "object",
                  "required": [
                      "enabled"
                  ],
                  "properties": {
                      "enabled": {
                          "type": "boolean",
                          "default": true,
                          "description": "Enable/disable custom domains"
                      }
                  },
                  "export": false,
                  "default": true,
                  "readOnly": true
             },
               "warmup": {
                   "type": "boolean",
                   "export": false,
                   "readOnly": false
               }           }
       },
       "values": {}
   },
   "selectors": {
       "category": "Deployment Services",
       "imported": false,
       "provider": "AWS",
       "sub_category": "Custom Scope"
   }
}