17.3.1.2 Service Name Clarity

Service name clarity addresses the specific constraints and naming philosophy behind choosing a Compose service name, since that name becomes a DNS hostname other services actually resolve over the network, and the right choice balances technical validity, semantic meaningfulness, and resilience to future technology changes.

DNS validity constraints

A Compose service name needs to be a valid DNS label, since it functions as a hostname other services resolve directly; while Compose itself is fairly permissive about what it accepts as a service key, the underlying DNS resolution layer has real constraints worth respecting deliberately rather than discovering through a confusing resolution failure:

services:
  my_api_service:

services:
  my-api-service:

Underscores, while sometimes accepted by Compose itself depending on version, are not valid characters in a standard DNS hostname and can cause resolution problems with certain clients or libraries that strictly validate hostname format; using hyphens instead, which are universally valid in DNS labels, avoids this category of issue entirely.

Naming by role rather than by underlying technology

Naming a service after its functional role, what it does within the architecture, rather than the specific technology currently implementing that role, keeps references to it meaningful even if the underlying technology changes later:

services:
  postgres:
  cache:

services:
  db:
  session-store:

If postgres were ever replaced with a different database engine, every reference to it throughout the application's configuration and connection strings would need updating purely because of the naming choice; naming it db instead, reflecting its functional role rather than its specific current implementation, means a future technology change requires updating only the image reference, not every place the service name itself is referenced.

Avoiding generic names that risk ambiguity

While role-based naming is generally preferable to technology-based naming, an excessively generic name, particularly one likely to collide conceptually with a service in a different, unrelated project that might later need to interact with this one, deserves slightly more specific naming to avoid future ambiguity:

services:
  service:
  app:

services:
  payment-api:
  order-worker:

The second set remains role-based rather than technology-based, but is specific enough to avoid the confusion that an overly generic name like service or app would create once a project has more than a small handful of services, or once it needs to interact with services from another project.

Consistency between service name, image name, and repository name

Keeping a service's Compose name reasonably aligned with its image's repository name reduces the cognitive translation required when moving between the Compose file, the image registry, and any deployment tooling referencing the same logical service under potentially different names:

services:
  payment-api:
    image: registry.example.com/payment-api:1.4.2

services:
  svc-a:
    image: registry.example.com/payment-processing-service:1.4.2

The first example keeps the Compose service name and the image repository name clearly, directly related; the second requires anyone reading the file to mentally map between two seemingly unrelated names referring to the same actual service, which is unnecessary friction that consistent naming avoids entirely.

Length and complexity considerations

While DNS technically permits fairly long hostnames, an excessively long or compound service name becomes unwieldy to type repeatedly in configuration, connection strings, and command-line invocations; a name that is descriptive but reasonably concise serves better than one that tries to encode every possible detail about the service into its name:

services:
  user-authentication-and-session-management-service:

services:
  auth:

The second, shorter name remains clear within its actual context and is considerably more practical to reference repeatedly throughout configuration files, scripts, and ordinary conversation about the system.

Consistency across multiple Compose files referencing the same service

When a service is referenced across a base file and several override files, or across multiple Compose files in a monorepo using the include directive, keeping its name exactly consistent everywhere it appears avoids the kind of subtle, easy-to-miss naming mismatch covered in dedicated troubleshooting around incorrect service name references:

grep -rn "depends_on\|environment.*=.*db" *.yml

Periodically searching across every Compose file for every reference to a given service name, particularly after any renaming, confirms consistency has actually been maintained rather than assumed.

Common mistakes

• Using underscores in a service name, risking DNS resolution issues with clients or libraries that strictly validate standard hostname format.
• Naming a service after its specific underlying technology rather than its functional role, creating unnecessary churn if that technology is ever replaced.
• Choosing an overly generic name that risks future ambiguity once a project grows or needs to interact with services from another project.
• Letting a service's Compose name drift unnecessarily far from its image's actual repository name, requiring constant mental translation between the two.
• Allowing a service name to become excessively long or compound, making it unwieldy to reference repeatedly throughout configuration and tooling.

Service name clarity balances DNS validity, role-based rather than technology-based naming for future resilience, sufficient specificity to avoid ambiguity, and reasonable consistency with the underlying image's own naming, all of which keep a service's name genuinely useful as both a technical hostname and a meaningful, durable label for what it actually does within the system.