Overview#

The Domain Routing Manager (DRM) is a critical component of GritivaCore that facilitates the routing of domains to specific application scopes. Unlike generic DNS or domain registrars, the DRM acts as a reconciler, ensuring that a desired state—such as routing domain X to scope Y on port Z—is achieved through a series of provisioning steps. The process involves creating a Cloudflare DNS record, configuring ingress rules in cloudflared, setting up nginx within the target scope's network namespace, and generating a TLS certificate using either Cloudflare's edge certificate or Let's Encrypt.

User -> Cloudflare Edge -> cloudflared -> nginx-in-scope -> App

Key Features#

The DRM reconciles four essential layers:

1. Cloudflare DNS: Provisioning DNS records to direct traffic.
2. Cloudflared Tunnel Rules: Managing ingress rules for secure connections.
3. Nginx Configuration: Setting up the web server within the designated scope.
4. TLS Certificate Management: Handling SSL certificates for secure communications.

Lifecycle Commands#

The following commands are essential for managing domains within the DRM:

gritivactl domain add app.example.com --scope my-app --port 8080
gritivactl domain remove app.example.com
gritivactl domain list
gritivactl domain reconcile

Reconciler Loop#

The DRM operates a reconciler loop that runs every 30 seconds. This loop is responsible for converging any drift between the desired and actual states across the four layers mentioned above.

Pending Services Owner Column#

A known issue exists regarding the services table, which requires an owner column to disambiguate pending services. This is documented as TBD in ADR-0003.

Common Failure Modes#

Operators should be aware of the following common failure modes:

• Cloudflare API Rate Limiting: Excessive requests may lead to rate limits.
• Cloudflared Not Picking Up New Ingress: Requires a SIGHUP signal to refresh.
• Nginx Not in Scope's Netns: Ensure nginx is correctly configured within the appropriate network namespace.