Custom Domains

About

How DNS works on the Tawa platform and how to add your own domain to a service. Covers automatic platform DNS, adding domains via Cloudflare (instant) or external providers (manual CNAME), domain verification, and the complete tawa domain command reference. Includes how ingress patching works internally.

Skill Content

This is the raw markdown that gets installed as a Claude Code command.

# Custom Domains

## What this skill covers
How DNS works on Tawa and how to add custom domains to your service.

## Automatic DNS

Every service gets a platform domain automatically on deploy:

| Environment | URL |
|-------------|-----|
| Sandbox | `{service}.sandbox.tawa.insureco.io` |
| Production | `{service}.tawa.insureco.io` |
| UAT | `{service}.uat.tawa.insureco.io` |

The builder creates a Cloudflare CNAME record pointing to the platform ingress. DNS is proxied through Cloudflare for TLS and CDN.

## Adding a Custom Domain

### Cloudflare-managed DNS (automatic)
```bash
tawa domain add portal.example.com --cloudflare

# Output:
# ✓ DNS record created: portal.example.com → my-svc.tawa.insureco.io
# ✓ Domain registered in platform
# ✓ Domain is live at portal.example.com
```

### External DNS provider (manual)
```bash
tawa domain add portal.example.com --external

# Output:
# ℹ Please add a CNAME record at your DNS provider:
#     portal.example.com → my-svc.tawa.insureco.io
#
# After adding the record, run:
#   tawa domain verify portal.example.com
```

Then add the CNAME at your provider and verify:
```bash
tawa domain verify portal.example.com
# ✓ DNS verified: portal.example.com → my-svc.tawa.insureco.io
```

## Domain Commands

```bash
# Add a domain
tawa domain add mydomain.com --cloudflare
tawa domain add mydomain.com --external

# Verify DNS propagation
tawa domain verify mydomain.com

# Check domain status
tawa domain status mydomain.com

# List all custom domains
tawa domain list
tawa domain list --service my-svc

# Remove a domain
tawa domain remove mydomain.com
```

## Command Options

| Option | Description |
|--------|-------------|
| `--service <name>` | Target service (default: from catalog-info.yaml) |
| `--env <environment>` | Target environment: prod (default), sandbox, uat |
| `--cloudflare` | Auto-configure DNS via Cloudflare |
| `--external` | Manual DNS — you add the CNAME yourself |
| `--yes` | Skip confirmation prompts |

## How It Works Internally

1. Builder creates a CNAME record pointing to the platform ingress
2. Domain is registered in Koko's domain registry
3. Kubernetes ingress is patched to accept traffic on the new hostname
4. TLS certificate is provisioned automatically (Cloudflare Total TLS or cert-manager)
5. On subsequent deploys, verified custom domains are included in Helm values

Custom domains are patched into the live ingress immediately — no redeploy needed after adding.

## Troubleshooting

| Issue | Cause | Fix |
|-------|-------|-----|
| "No CNAME record" on verify | DNS not propagated | Wait and retry (up to 48h) |
| TLS error on domain | Certificate not provisioned | Wait a few minutes |
| Domain resolves to wrong service | CNAME points to wrong target | Check `tawa domain status` |
| Domain stops working after deploy | Domain wasn't verified before deploy | Run `tawa domain verify` then redeploy |

## Key Facts
- Platform domains are created automatically — you only need custom domain commands for your own domains
- Cloudflare-managed domains are live within seconds
- External domains may take up to 48 hours for DNS propagation
- Custom domains get TLS certificates automatically
- Ingress updates happen immediately without redeploying

Install

Copy the skill content and save it to:

~/.claude/commands/dns-custom-domains.md

Details

Format

Command

Category

provision

Version

1.0.0

Tokens

~900

Updated

2026-02-13