Namespace Label Design¶
This document defines a unified namespace labeling strategy across the entire platform.
Design Principles¶
- Consistency: Use the same label key and value patterns across all namespaces
- Discoverability: Easily filterable with
kubectl get ns -l <label>=<value> - Security: Leverage label selectors in NetworkPolicy, RBAC, etc.
- Standards Compliance: Follow Kubernetes recommended labels (
app.kubernetes.io/*)
Label Schema¶
Required Labels (Applied to All Namespaces)¶
| Label Key | Value | Description |
|---|---|---|
app.kubernetes.io/managed-by |
argocd |
Identifies the GitOps tool (Kubernetes recommended label) |
kensan-lab.platform/environment |
production | development | infrastructure |
Environment type |
kensan-lab.platform/tier |
platform | application |
Responsibility layer (PE-managed vs AD-managed) |
Optional Labels (Applied as Needed)¶
| Label Key | Example Values | Description | Target |
|---|---|---|---|
kensan-lab.platform/component |
keycloak, backstage, monitoring, service-mesh, core |
Component identification | Platform tier only |
kensan-lab.platform/pss-level |
privileged | restricted |
Declares the Pod Security Standards level (read by Kyverno; unset = the baseline floor) | Only namespaces that depart from the floor |
istio-injection |
enabled |
Istio automatic sidecar injection | Namespaces targeted by service mesh |
kensan-lab.platform/vault-managed-postgres |
"true" |
Opt-in declaration for namespaces hosting a Postgres managed by vault-database-engine. Read by the selectors of CCNP ccnp-postgres-ingress / cnp-vault-egress |
Only namespaces with a Postgres targeted by Vault dynamic credentials (e.g. platform-auth-prod, kensan) |
Label Value Definitions¶
kensan-lab.platform/environment¶
| Value | Description | Example Namespaces |
|---|---|---|
infrastructure |
Core cluster infrastructure / platform services | kube-system, istio-system, monitoring, argocd, vault, platform-auth-prod |
production |
Production app/workload environment | app-prod, app-kensan, kensan |
development |
Currently unused. The dev/prod split was retired — see ADR-006 / ADR-014. The value is reserved in case a dev environment is added later | — |
kensan-lab.platform/tier¶
| Value | Description | Manager | Example Namespaces |
|---|---|---|---|
platform |
Platform infrastructure tier | Platform Engineer (PE) | istio-system, backstage, platform-auth-prod |
application |
Application tier | Application Developer (AD) | app-prod, app-kensan, kensan |
kensan-lab.platform/pss-level¶
Declares the Pod Security Standards level. Only Kyverno reads it (PSA is inactive — the v2 unified design, revised in ADR-012).
The legacy pod-security.kubernetes.io/* (PSA) labels are removed at the same time Kyverno is promoted to Enforce.
| Value | Description | Example Namespaces |
|---|---|---|
| (unset) | The pss-baseline floor applies (default) |
Most namespaces |
privileged |
Exempt from the floor. Only tier=platform namespaces may declare it (enforced by ns-label-contract) |
kube-system, istio-system, longhorn-system, local-path-storage |
restricted |
Applies PSS restricted, stricter than the floor (opt-in) | app-kensan |
The contract for this label (required labels and the conditions for declaring them) is enforced mechanically by the Kyverno ns-label-contract policy.
Details: policy-enforcement.md
kensan-lab.platform/component¶
| Value | Description | Target Namespace |
|---|---|---|
core |
Core Kubernetes system | kube-system |
service-mesh |
Service mesh control plane | istio-system |
gitops |
GitOps tooling | argocd |
observability |
Monitoring and log management | monitoring |
keycloak |
Authentication platform | platform-auth-prod |
developer-portal |
Developer portal | backstage |
Namespace Definition Templates¶
Platform Infrastructure Tier (Environment-Independent)¶
apiVersion: v1
kind: Namespace
metadata:
name: <namespace-name>
labels:
app.kubernetes.io/managed-by: argocd
kensan-lab.platform/environment: infrastructure
kensan-lab.platform/tier: platform
kensan-lab.platform/component: <component-name>
# Optional: when using Istio
# istio-injection: enabled
Platform Tier (Environment-Specific)¶
apiVersion: v1
kind: Namespace
metadata:
name: <namespace-name>
labels:
app.kubernetes.io/managed-by: argocd
kensan-lab.platform/environment: production|development
kensan-lab.platform/tier: platform
kensan-lab.platform/component: <component-name>
istio-injection: enabled
Application Tier¶
app-* namespaces require the team / app labels (the app-namespace contract from ADR-014, enforced by Kyverno ns-label-contract). environment is currently production only (development is unused).
apiVersion: v1
kind: Namespace
metadata:
name: app-<name>
labels:
app.kubernetes.io/managed-by: argocd
kensan-lab.platform/environment: production
kensan-lab.platform/tier: application
kensan-lab.platform/team: <team>
kensan-lab.platform/app: <app>
istio-injection: enabled
Label Usage Examples¶
2. NetworkPolicy Usage¶
# Allow communication between platform tier namespaces
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-platform-tier
namespace: backstage
spec:
podSelector: {}
policyTypes:
- Ingress
ingress:
- from:
- namespaceSelector:
matchLabels:
kensan-lab.platform/tier: platform
# Allow production applications to access Keycloak
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
name: allow-prod-apps-to-keycloak
namespace: platform-auth-prod
spec:
podSelector:
matchLabels:
app: keycloak
policyTypes:
- Ingress
ingress:
- from:
- namespaceSelector:
matchLabels:
kensan-lab.platform/environment: production
kensan-lab.platform/tier: application
3. RBAC Usage¶
# Grant Application Developers access to application tier namespaces
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: app-developer
rules:
- apiGroups: ["*"]
resources: ["*"]
verbs: ["*"]
# Access limited to the application tier
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
name: app-developers-binding
namespace: app-kensan
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: app-developer
subjects:
- kind: Group
name: application-developers
apiGroup: rbac.authorization.k8s.io
4. Prometheus ServiceMonitor Selectors¶
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
name: platform-services
namespace: monitoring
spec:
namespaceSelector:
matchLabels:
kensan-lab.platform/tier: platform
selector:
matchLabels:
monitoring: enabled
5. Istio Sidecar Auto-Injection Verification¶
# Check namespaces with Istio enabled
kubectl get ns -l istio-injection=enabled
# Enable Istio auto-injection on a new namespace
kubectl label namespace my-new-namespace istio-injection=enabled
Migration Guide¶
Steps for migrating existing namespace labels to the unified design:
Phase 1: Apply to New Namespaces First (Priority: High)¶
All namespaces created going forward must conform to this label design.
Phase 2: Update Application Tier (Priority: Medium)¶
# app-kensan/namespace.yaml
# Before:
labels:
environment: production
# After:
labels:
app.kubernetes.io/managed-by: argocd
kensan-lab.platform/environment: production
kensan-lab.platform/tier: application
kensan-lab.platform/team: <team>
kensan-lab.platform/app: <app>
istio-injection: enabled
Phase 3: Update Platform Tier (Priority: Low)¶
Gradually update existing namespaces. Proceed while confirming no impact on cluster operations.
Notes: - Label changes do not affect the namespace itself, but check existing resources that use label selectors (NetworkPolicy, ServiceMonitor, etc.) beforehand - Update via Argo CD (maintain GitOps principles)
Summary¶
Label Matrix¶
| Namespace | environment | tier | component | istio-injection |
|---|---|---|---|---|
| kube-system | infrastructure | platform | core | No |
| istio-system | infrastructure | platform | service-mesh | No |
| argocd | infrastructure | platform | gitops | No |
| monitoring | infrastructure | platform | observability | No |
| backstage | production | platform | developer-portal | Yes |
| platform-auth-prod | infrastructure | platform | keycloak | Yes |
| vault | infrastructure | platform | secrets | No |
| app-prod | production | application | - | Yes |
| app-kensan | production | application | - (team=yu, app=kensan) | Yes |
| kensan | production | application | - | Yes |
Best Practices¶
- Always set required labels:
managed-by,environment,tier - Component label for platform tier only: Not needed for the application tier
- Set istio-injection explicitly: Only for namespaces targeted by the service mesh
- Minimize custom labels: Use the
kensan-lab.platform/prefix when necessary - Check NetworkPolicies when changing labels: Selectors may be affected
This label design improves consistency, discoverability, and security across the entire platform.