Skip to content

Domain Manager

Domain Manager

Category: Networking Type: Dashboard Tags: cluster-level · dashboard · networking · dns

Overview

Custom domains fail for boring reasons: the record was never added, it points at an old address, or the certificate is still pending. Domain Manager is a page inside Genesis that answers all three at a glance.

It lists every hostname published from the cluster, whether it comes from an Ingress or a Gateway API HTTPRoute, and for each one shows the record that should exist, whether DNS currently resolves to this cluster, and the state of its certificate.

How It Works

Dashboard - Installed once per cluster and embedded in Genesis as an iFrame, gated to admin users.

It reads Ingresses and HTTPRoutes across every namespace and takes the target address from what the ingress controller itself published, in status.loadBalancer, or from the parent Gateway's status. That means the record it shows is the address traffic actually arrives on, not a value someone typed into a config file.

For each hostname it resolves the name and compares the answer against that address:

State Meaning
Pointing here The hostname resolves to this cluster and should work
Points at ... The hostname resolves somewhere else. Usually an old record, or a proxy in front
No record found The name does not resolve at all. The record has not been added yet

The record column shows A when the ingress address is an IP, and CNAME when it is a hostname, which is what cloud load balancers publish.

Prerequisites

  • An ingress controller that reports a load balancer address on Ingress status, which is standard behaviour
  • The Certificate Manager plugin, if you want the certificate column populated

Installation

  1. Open Terra and navigate to the Plugin Marketplace
  2. Search for "Domain Manager"
  3. Click Install
  4. Fill in the configuration fields below
  5. Click Confirm to deploy

The page then appears in Genesis at the configured prefix.

Configuration

Install-Time Fields

Field Details
host string · Required
The DNS name of your Genesis host. Also used to mark which row is the platform host
prefix string · Required · Default: /domains
Path the page is served on
registry string · Required · Default: ghcr.io
Registry to pull the image from
repo string · Required · Default: umer-jahangier/domain-manager
Image repository
tag string · Required · Default: 0.1.0
Image version. Published versions are listed in the image repository
namespace string · Required · Default: domain-manager
Namespace the page runs in, created if absent

The Image

The page ships as a versioned container image built from umer-jahangier/domain-manager, published for linux/amd64 and linux/arm64. Each release is tested, started and health checked before it is pushed, and tag pins the version this plugin runs, so upgrading the page is a field change in Terra.

Permissions

The page reads, and only reads:

Resource Why
ingresses The hostnames served and the address the controller publishes
httproutes, gateways The same, on clusters running the Gateway API
certificates Whether cert-manager has issued each certificate

It has no write permission anywhere, holds no DNS provider credential, and changes nothing. Adding records is done in your DNS provider, or by the ExternalDNS plugin.

Notes

  • Hostnames appear once a route exists for them, so publish the workload first and then add the record. The page tells you which record to add
  • A row showing an address but no DNS answer usually means the record was added to the wrong zone, or has not propagated yet
  • Certificates issued through a DNS-01 challenge can show as pending for a few minutes while the TXT record propagates. That is normal, not a failure
  • The page runs the reads on request, so reloading is the refresh
  • One row per hostname, not per route. A hostname served by several routes shows the route count instead
plugins/domain-manager/terra.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
resource_id: domain-manager
name: Domain Manager
icon: https://github.com/juno-fx/Terra-Official-Plugins/blob/main/plugins/domain-manager/assets/icon.svg?raw=true
description: A page inside Genesis listing every hostname published from this cluster, the DNS record each one needs, whether that record currently points at the cluster, and the state of its certificate.
category: Networking
tags:
  - cluster-level
  - dashboard
  - networking
  - dns
editable: true
fields:
  - name: host
    description: The DNS name of your Genesis host.
    required: true
    type: string
  - name: prefix
    description: Connection URL prefix. i.e. `/domains`. This doesn't need changing in most cases.
    required: true
    default: /domains
    type: string
  - name: registry
    description: Registry to pull the image from.
    required: true
    default: ghcr.io
    type: string
  - name: repo
    description: Repository to pull the image from.
    required: true
    default: umer-jahangier/domain-manager
    type: string
  - name: tag
    description: Image version to run. See https://github.com/umer-jahangier/domain-manager for published versions.
    required: true
    default: "0.1.0"
    type: string
  - name: namespace
    description: Namespace the page runs in. Created if it does not exist.
    required: true
    default: domain-manager
    type: string