pkg/namespaces

Namespace propagation through context.Context. A two-line helper at the heart of containerd's multi-tenancy story.

Purpose

• Carry the current namespace through ctx across gRPC boundaries.
• Validate namespace names with pkg/identifiers.
• Express "this call requires a namespace" once instead of every handler reimplementing it.

API

package namespaces

func WithNamespace(ctx context.Context, ns string) context.Context
func Namespace(ctx context.Context) (string, bool)
func NamespaceRequired(ctx context.Context) (string, error)

The package also exposes constants NamespaceEnvVar = "CONTAINERD_NAMESPACE" and a default namespace "default".

How it crosses gRPC

• The client puts the namespace into a gRPC metadata header (containerd-namespace) before sending a request.
• The server's interceptor (in pkg/namespaces/grpc.go) reads the header and stores it back into the request context with WithNamespace.
• ttrpc has the same plumbing in pkg/namespaces/ttrpc.go.

This means inside a handler, namespaces.NamespaceRequired(ctx) returns the caller's namespace and an error if none was set.

How the daemon uses it

Almost every gRPC handler starts with:

ns, err := namespaces.NamespaceRequired(ctx)
if err != nil {
    return nil, err
}

The metadata store and content store wrappers then key reads/writes by ns. Namespaces are isolating: two clients on namespaces kubernetes.io and default see disjoint containers, images, snapshots, leases.

How ctr and the CRI plugin set it

• ctr reads --namespace (or $CONTAINERD_NAMESPACE).
• The CRI plugin hardcodes namespace k8s.io for everything it creates.
• The Go client default is default unless overridden via client.New(..., WithDefaultNamespace("foo")).

Entry points for modification

• New propagation transport: add a sibling to grpc.go / ttrpc.go.
• Default namespace policy: see pkg/namespaces/context.go.