Subdomains for Microservices: Architectural Patterns and Best Practices
In microservices architectures, subdomains provide clean, publicly accessible URLs for individual services while allowing the underlying infrastructure to evolve independently. Whether you are building a new platform or decomposing a monolith, understanding how to use subdomains effectively in a microservices context is essential.
Common Microservices Subdomain Patterns
The most common pattern assigns each major service or service group a dedicated subdomain: api.example.com for the core API gateway, auth.example.com for authentication services, cdn.example.com for static assets, ws.example.com for WebSocket connections, and webhooks.example.com for inbound webhook processing. This pattern provides clear semantic boundaries, enables independent SSL certificate management, and allows different services to be hosted on different infrastructure with separate scaling policies.
Versioning can be incorporated at the subdomain level: v1.api.example.com and v2.api.example.com, or at the path level: api.example.com/v1/ — path-based versioning is generally preferred for maintainability as it keeps authority consolidated.
Kubernetes and Subdomain Management
In Kubernetes deployments, Ingress controllers handle subdomain routing. An Ingress rule mapping api.example.com to a service named "api" inside the cluster, combined with a wildcard DNS record pointing to the load balancer, allows services to be created and exposed without manual DNS record creation for each. The Kubernetes External DNS project automates DNS record creation from Ingress and Service annotations, maintaining DNS records in sync with the cluster state.
Internal vs. External Subdomains
In split-horizon DNS architectures, internal services might be accessible at service.internal.example.com or through a private DNS namespace, while external services use public subdomains. This ensures internal microservice communications do not route through the public internet and allows different network security policies for internal traffic. Service mesh solutions like Istio manage internal service-to-service communication with their own DNS-based discovery, separate from public subdomain routing.
Monitoring and Managing Subdomains at Scale
As subdomain count grows, inventory management becomes critical. Infrastructure-as-code tools (Terraform with DNS providers, AWS CDK) ensure subdomain creation and deletion are tracked in version control. Certificate management automation (cert-manager in Kubernetes, AWS Certificate Manager) handles the SSL lifecycle. Monitoring tools should alert on certificate expiration across all subdomains — a forgotten subdomain with an expired certificate can cause unexpected outages or security warnings.
Explore our subdomain tools for enumeration and DNS lookup utilities, or browse our full blog archive for more subdomain architecture guides.