How kubernetes-sigs/hierarchical-namespaces works
Project Type and Purpose
• The project is a Kubernetes controller/operator that extends native Kubernetes namespaces with hierarchical relationships. It introduces custom resources and enforces policies (e.g., RBAC, network policies) across related namespaces.
• The README shows that end users interact with HNC through kubectl commands (for example, “kubectl hns create …” and “kubectl hns tree …”). This indicates a full controller-manager design with an accompanying kubectl plugin.
File Structure Analysis
• Directories like “api”, “config”, “charts”, and “internal” are key. For instance:
• The “api” folder defines the v1alpha2 API types corresponding to the CRDs.
• The “charts/hnc” folder contains Helm charts that package the installation and deployment configuration (including CRDs, RBAC roles, webhook setups, and the controller manager deployment).
• The “cmd” directory has multiple subdirectories (such as “manager”, “kubectl”, and “apiextension”) which compile into binaries that deploy or extend Kubernetes functionalities.
• The “internal” folder holds the main business logic split into packages such as “anchor”, “hierarchyconfig”, “hncconfig”, and “hrq” (related to hierarchical resource quotas), all following the controller and reconciliation patterns.
• The “config” folder provides a large number of manifests such as CRD configurations, kustomizations, and webhook service definitions.
• There are extensive tests under “test/e2e” and “internal/integtest”, which show that the project follows Kubernetes’ operator/testing approaches.
a. Main Components:
• Client Side – Kubectl Plugin:
• “kubectl-hns” plugin (from cmd/kubectl) that users run to interact with HNC.
• This as a client tool that sends commands and receives structured output (e.g., namespace hierarchy trees).
• Kubernetes API Server:
• HNC Controller Manager:
• Primary controller (built from cmd/manager) that runs inside a Pod.
• Within this component, include internal reconcilers for various functionalities:
▪ Anchor reconciler (managing subnamespace anchors)
▪ Hierarchy configuration reconciler (enforcing parent–child relationships)
▪ HNC configuration reconciler (reactive to changes in controller settings)
▪ Hierarchical Resource Quota (HRQ) subsystem
• CRDs and Custom API Extensions:
• Webhook Servers:
• Both validating and mutating webhook configurations (deployed along with the controller manager from charts and config/webhook).
• Deployment & Package Management:
• Helm Chart (charts/hnc) used to deploy the controllers, CRDs, RBAC, and webhooks.
• CI/CD/Build Pipelines:
b. Relationships and Interactions:
• API Server communicating with (or triggering) the controller manager’s reconciler loops once CRDs are manipulated.
• Controller manager’s interactions with:
• The CRD definitions (to detect changes in hierarchical namespace objects)
• The webhook endpoints that may validate or mutate requests coming into the API Server.
c. Architectural Patterns & Design Principles:
• Use of the controller (reconciliation loop, watch events) pattern that is common in Kubernetes.
• That the design follows a separation of concerns: the kubectl plugin deals with command-line interactions, the API Server mediates requests, and the controller manager “reconciles” state across namespaces.
• Point out that the internal packages are modularized by functionality (anchor, hierarchyconfig, hrq), following micro-component or service-like boundaries within the controller logic.
• Integration of Helm charts for deployments and kustomize configurations for environment-specific customizations.
d. Technologies, Frameworks, and Libraries:
• Kubernetes API and CRDs (which are central to the design).
• Helm (for packaging and deployment).
• Kustomize (for environment-based customization in the “config” directories).
• Go Modules (go.mod and go.sum indicate Go language dependencies).
• Prow and Cloud Build for CI/CD.