Introduction

Kubernetes does not use one universal naming rule for everything. Container names and named ports look similar, but they follow different validation rules, and mixing those rules up is a common reason manifests fail admission with confusing validation errors.

Container Names

Container names in a Pod must follow Kubernetes DNS label style rules. In practice, that means:

• lowercase letters and digits are allowed
• hyphens are allowed
• no spaces, underscores, or uppercase letters
• the name must start and end with an alphanumeric character
• the maximum length is 63 characters

A valid Pod snippet:

1apiVersion: v1
2kind: Pod
3metadata:
4  name: api-pod
5spec:
6  containers:
7    - name: web-api
8      image: nginx:1.27

Invalid container names include:

• 'WebApi because uppercase letters are not allowed'
• 'web_api because underscores are not allowed'
• '-web because names cannot start with a hyphen'

Port Names

Named ports use a stricter rule. Kubernetes service and container port names follow the IANA_SVC_NAME style, which is designed for service names rather than general object names.

In practice, a named port should:

• use lowercase alphanumeric characters and hyphens
• start and end with an alphanumeric character
• stay short, with a maximum length of 15 characters

Example:

1apiVersion: v1
2kind: Pod
3metadata:
4  name: demo
5spec:
6  containers:
7    - name: app
8      image: nginx:1.27
9      ports:
10        - name: http
11          containerPort: 8080
12        - name: metrics
13          containerPort: 9090

These names are often referenced by Services and probes, so keeping them simple helps.

Why Port Names Matter

Port names are optional when only one port is exposed, but they become important when:

• a Service targets a port by name instead of by number
• probes refer to named ports
• multiple ports exist and you want the intent to be obvious

For example:

1apiVersion: v1
2kind: Service
3metadata:
4  name: demo-service
5spec:
6  selector:
7    app: demo
8  ports:
9    - name: http
10      port: 80
11      targetPort: http

Here, targetPort: http resolves against the container port name, so the name must be valid and spelled exactly the same.

Container Names and Pod Names Are Not the Same Thing

Developers often assume container names and Pod names share exactly the same semantics because both "look like Kubernetes names." They do not mean the same thing operationally:

• the Pod name identifies the Pod object
• the container name identifies one container inside that Pod
• the port name identifies a specific named network port

That distinction matters when reading validation errors or wiring Services, probes, and logs.

Naming Recommendations

A few conventions make manifests easier to maintain:

• use descriptive container names such as api, worker, or nginx
• use protocol or purpose for ports such as http, https, grpc, or metrics
• avoid generated-looking names unless automation requires them

These names appear in logs, events, and debugging output, so clarity helps during operations.

Common Pitfalls

The most common mistake is using underscores. Kubernetes allows underscores in some other contexts, such as parts of label values, but not in container names or named ports.

Another issue is mixing up general object-name rules with port-name rules. Container names can be longer, while named ports are much shorter because they follow service-name style validation.

Finally, do not use uppercase letters even if your YAML parser accepts them. Kubernetes validation happens after YAML parsing, and the API server will reject those names.

Summary

• Container names use lowercase alphanumeric characters and hyphens, up to 63 characters.
• Port names are stricter and should follow short IANA_SVC_NAME style rules.
• Neither container names nor port names allow underscores or uppercase letters.
• Both must start and end with an alphanumeric character.
• Use clear names because Services, probes, and debugging output rely on them.