Setting up a Custom Domain

All Kf Apps that serve HTTP traffic to users or applications outside of the cluster must be associated with a domain name.

Kf has three locations where domains can be configured. Ordered by precedence, they are:

  1. Apps
  2. Spaces
  3. The config-defaults ConfigMap in the kf Namespace

The config-defaults ConfigMap

The config-defaults ConfigMap holds cluster-wide settings for Kf and can be edited by cluster administrators. The values in the ConfigMap are read by the Spaces controller and modify their configuration. Domain values are reflected in the Space's field.

To modify Kf cluster's domain, edit the config-defaults ConfigMap in the kf Namespace:

kubectl edit configmap config-defaults -n kf

Add or update the entry for the spaceClusterDomain key like the following:


To validate the configuration was updated correctly, check the domain value in a space:

kf space SPACE_NAME -o "jsonpath={[]['domain']}"

The output will look similar to:

Getting Space some-space

Each Space prefixes the cluster domains with its own name. This prevents conflicts between Apps.

Space domains

Spaces are the authoritative location for domain configuration. You can assign domains and sub-domains to each space for developers to use. The field for configuring domains is

Use kf space to view the domains assigned to a Space:

kf space SPACE_NAME

In the output, the Spec field contains specific configuration for the Space and the Status field reflects configuration for the Space with cluster-wide defaults appended to the end:

  Network Config:
  Network Config:

Configuration with the CLI

The kf CLI supports mutations on Space domains. Each command outputs a diff between the old and new configurations.

Add a new domain with kf configure-space append-domain:

kf configure-space append-domain SPACE_NAME

Add or make an existing domain the default with kf configure-space set-default-domain:

kf configure-space set-default-domain SPACE_NAME

And finally, remove a domain:

kf configure-space remove-domain SPACE_NAME


Apps can specify domains as part of their configuration. Routes are mapped to Apps during kf push using the following logic:

let current_routes  = The set of routes already on the app
let manifest_routes = The set of routes defined by the manifest
let flag_routes     = The set of routes supplied by the --route flag(s)
let no_route        = Whether the manifest has no-route:true or --no-route is set
let random_route    = Whether the manifest has random-route:true or --random-route is set

let new_routes = Union(current_routes, manifest_routes, flag_routes)

if new_routes.IsEmpty() then
  if random_route then

if no_route then

return new_routes

If an App doesn't specify a Route, or requests a random Route, the first domain on the Space will be used. If the first domain on a Space changes, all Apps in the space using the default domain will be updated to reflect it.

Domain templates

Kf supports variable substitution in domains. Substitution allows a single cluster-wide domain to be customized per-Space and to react to changes to the ingress IP. Substitution is performed on variables with the syntax $(VARIABLE_NAME) that occur in a domain.

Variable Description
CLUSTER_INGRESS_IP The IPV4 address of the cluster ingress.
SPACE_NAME The name of the Space.


The following examples demonstrate how domain variables can be used to support a variety of different organizational structures and cluster patterns.

  • Using a wildcard DNS service like

  • Domain for an organization with centrally managed DNS:

  • Domain for teams who manage their own DNS:

  • Domain for a cluster with warm failover and external circuit breaker:


Differences between Kf and CF

  • Kf Spaces prefix the cluster-wide domain with the Space name.
  • Kf does not check for domain conflicts on user-specified routes.