Route53 / DNS — konfig-konector Docs

HostedZone # ✅ Working

Creates a Route 53 hosted zone (public or private). For private zones, the zone is associated with the specified VPC. Name server records returned in status must be configured at your domain registrar for public zones.

Spec

Field	Type	Required	Description
name	string	✅	Domain name for the hosted zone. Must end with a trailing dot (e.g. `example.com.`).
comment	string		Optional comment for the hosted zone.
private	bool		Create a private hosted zone. Default: false (public zone).
vpcRef.id	string		VPC ID to associate with a private hosted zone. Required when `private: true`.
vpcRef.region	string		AWS region of the VPC. Required when `private: true`.
delegationSetId	string		Reusable delegation set ID for consistent name servers across zones.
tags	map[string]string		AWS tags applied to the hosted zone.

Status

Field	Description
hostedZoneId	The Route 53 hosted zone ID (e.g. `Z1234ABCDEFGH`).
nameServers	List of authoritative name servers for the zone. These must be configured at your domain registrar for public zones.
conditions	Standard Kubernetes conditions.
observedGeneration	Last reconciled generation.
lastSyncTime	RFC3339 timestamp of last sync.

Example — Public Zone

apiVersion: aws.konfig.io/v1alpha1
kind: HostedZone
metadata:
  name: example-com-zone
  namespace: dns
spec:
  name: example.com.
  comment: "Production DNS zone for example.com"
  tags:
    env: prod

Example — Private Zone

apiVersion: aws.konfig.io/v1alpha1
kind: HostedZone
metadata:
  name: internal-example-com-zone
  namespace: dns
spec:
  name: internal.example.com.
  comment: "Internal DNS zone"
  private: true
  vpcRef:
    id: vpc-0abc123
    region: us-east-1
  tags:
    env: prod
    visibility: private

Notes

The controller uses the CR's UID as the CallerReference to ensure idempotency. Creating two CRs with the same zone name will create two separate hosted zones in Route 53.
For public zones, the name server addresses returned in status.nameServers must be added as NS records at your domain registrar or parent zone.

Deletion

Blocked if zone has records. Route 53 refuses to delete a hosted zone that contains records other than the default NS and SOA records. Delete all RecordSet CRs (and any manually created records) first.

RecordSet # ✅ Working

Creates and manages a DNS record set in a Route 53 hosted zone. Supports simple records, alias records (for ALB/CloudFront/S3), weighted routing, failover routing, and health check associations.

Spec

Field	Type	Required	Description
hostedZoneRef.name	string	✅	Name of the `HostedZone` CR in the same namespace.
hostedZoneRef.id	string		Direct Route 53 hosted zone ID (alternative to `hostedZoneRef.name`).
name	string	✅	Fully qualified domain name with trailing dot (e.g. `api.example.com.`).
type	string	✅	Record type: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `NS`, `SRV`, `CAA`, `PTR`.
ttl	int64		TTL in seconds. Required for non-alias records.
records	[]string		Record values. Required for non-alias records.
alias.dnsName	string		DNS name of the alias target (e.g. ALB DNS name). Mutually exclusive with `records`.
alias.hostedZoneId	string		Hosted zone ID of the alias target (e.g. the ALB's hosted zone ID).
alias.evaluateTargetHealth	bool		Route 53 evaluates the health of the alias target. Default: false.
weight	int64		Weight for weighted routing policy (0–255). Set on multiple records with the same name/type.
setIdentifier	string		Unique identifier for weighted, failover, or geolocation routing records.
failover	string		`PRIMARY` or `SECONDARY` for failover routing policy.
healthCheckRef.name	string		Name of a `HealthCheck` CR to associate with this record.
healthCheckRef.id	string		Direct Route 53 health check ID (alternative to `healthCheckRef.name`).

Status

Field	Description
changeId	The Route 53 change ID for the last submitted change (e.g. `/change/C2345EXAMPLE`).
changeStatus	`PENDING` or `INSYNC`. Route 53 propagation status.
hostedZoneId	The resolved hosted zone ID.
conditions	Standard Kubernetes conditions.
observedGeneration	Last reconciled generation.
lastSyncTime	RFC3339 timestamp of last sync.

Example — Simple A Record

apiVersion: aws.konfig.io/v1alpha1
kind: RecordSet
metadata:
  name: api-a-record
  namespace: dns
spec:
  hostedZoneRef:
    name: example-com-zone
  name: api.example.com.
  type: A
  ttl: 300
  records:
    - 203.0.113.10

Example — ALB Alias Record

apiVersion: aws.konfig.io/v1alpha1
kind: RecordSet
metadata:
  name: www-alb-alias
  namespace: dns
spec:
  hostedZoneRef:
    name: example-com-zone
  name: www.example.com.
  type: A
  alias:
    dnsName: prod-alb-1234567890.us-east-1.elb.amazonaws.com.
    hostedZoneId: Z35SXDOTRQ7X7K
    evaluateTargetHealth: true

Example — Weighted Routing Pair

apiVersion: aws.konfig.io/v1alpha1
kind: RecordSet
metadata:
  name: api-blue
  namespace: dns
spec:
  hostedZoneRef:
    name: example-com-zone
  name: api.example.com.
  type: CNAME
  ttl: 60
  records:
    - blue.api.example.com.
  weight: 80
  setIdentifier: blue
---
apiVersion: aws.konfig.io/v1alpha1
kind: RecordSet
metadata:
  name: api-green
  namespace: dns
spec:
  hostedZoneRef:
    name: example-com-zone
  name: api.example.com.
  type: CNAME
  ttl: 60
  records:
    - green.api.example.com.
  weight: 20
  setIdentifier: green

Example — TXT Record (Domain Verification)

apiVersion: aws.konfig.io/v1alpha1
kind: RecordSet
metadata:
  name: acme-challenge
  namespace: dns
spec:
  hostedZoneRef:
    name: example-com-zone
  name: _acme-challenge.example.com.
  type: TXT
  ttl: 300
  records:
    - '"abc123verificationtoken"'

Notes

DNS changes propagate asynchronously. status.changeStatus moves from PENDING to INSYNC typically within 60 seconds, but can take longer.
Record names must be fully qualified (end with a trailing dot).
TXT record values must be enclosed in double quotes within the YAML string.
Route 53 throttles ChangeResourceRecordSets API calls. The controller handles throttling automatically with exponential backoff.

Deletion

Immediate. The record set is deleted from the hosted zone. DNS changes propagate asynchronously after deletion.

HealthCheck # ✅ Working

Creates a Route 53 health check to monitor endpoint availability. Health checks can be associated with RecordSet CRs to enable failover routing.

Spec

Field	Type	Required	Description
type	string	✅	Health check type: `HTTP`, `HTTPS`, `HTTP_STR_MATCH`, `HTTPS_STR_MATCH`, `TCP`, or `CALCULATED`.
ipAddress	string		IP address to check. Either `ipAddress` or `fqdn` is required.
fqdn	string		Fully qualified domain name to check (sends Host header).
port	int32		Port to connect to. Defaults: HTTP=80, HTTPS=443, TCP=80.
resourcePath	string		Path to request for HTTP/HTTPS checks (e.g. `/health`).
searchString	string		String to match in the response body (for `_STR_MATCH` types).
requestInterval	int32		Seconds between health checks: `10` or `30`. Default: 30. Interval of 10 costs more.
failureThreshold	int32		Consecutive failures before marking unhealthy (1–10). Default: 3.
tags	map[string]string		AWS tags applied to the health check.

Status

Field	Description
healthCheckId	The Route 53 health check ID. Use this in `RecordSet.spec.healthCheckRef.id`.
conditions	Standard Kubernetes conditions.
observedGeneration	Last reconciled generation.
lastSyncTime	RFC3339 timestamp of last sync.

Example — HTTPS Health Check

apiVersion: aws.konfig.io/v1alpha1
kind: HealthCheck
metadata:
  name: prod-api-health
  namespace: dns
spec:
  type: HTTPS
  fqdn: api.example.com
  port: 443
  resourcePath: /health
  requestInterval: 30
  failureThreshold: 3
  tags:
    env: prod
    service: api

Example — Failover with Health Check

apiVersion: aws.konfig.io/v1alpha1
kind: HealthCheck
metadata:
  name: primary-api-health
  namespace: dns
spec:
  type: HTTPS
  fqdn: primary.api.example.com
  port: 443
  resourcePath: /health
  requestInterval: 10
  failureThreshold: 2
  tags:
    env: prod
---
apiVersion: aws.konfig.io/v1alpha1
kind: RecordSet
metadata:
  name: api-primary
  namespace: dns
spec:
  hostedZoneRef:
    name: example-com-zone
  name: api.example.com.
  type: A
  alias:
    dnsName: primary.api.example.com.
    hostedZoneId: Z35SXDOTRQ7X7K
    evaluateTargetHealth: true
  failover: PRIMARY
  setIdentifier: primary
  healthCheckRef:
    name: primary-api-health
---
apiVersion: aws.konfig.io/v1alpha1
kind: RecordSet
metadata:
  name: api-secondary
  namespace: dns
spec:
  hostedZoneRef:
    name: example-com-zone
  name: api.example.com.
  type: A
  alias:
    dnsName: secondary.api.example.com.
    hostedZoneId: Z35SXDOTRQ7X7K
    evaluateTargetHealth: true
  failover: SECONDARY
  setIdentifier: secondary

Notes

Either ipAddress or fqdn is required. When both are provided, fqdn is used as the Host header while connecting to ipAddress.
requestInterval: 10 (fast health checks) costs more than the default 30-second interval.
The healthCheckId in status is used in RecordSet.spec.healthCheckRef.id for association.

Deletion

Immediate. The Route 53 health check is deleted. Associated record sets are not automatically updated — remove the healthCheckRef from any RecordSets before deleting.