# kubernetes-sigs/hierarchical-namespaces architecture

> Architecture diagram of the GitHub repository kubernetes-sigs/hierarchical-namespaces, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kubernetes-sigs/hierarchical-namespaces
- Repository: https://github.com/kubernetes-sigs/hierarchical-namespaces

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    A("kubectl-hns Plugin"):::client

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        B("Kubernetes API Server"):::k8s

        %% HNC Controller Manager with its submodules
        subgraph "HNC Controller Manager"
            C("HNC Controller Manager"):::controller
            D("Anchor Reconciler"):::controller
            E("Hierarchy Config Reconciler"):::controller
            F("HNC Config Reconciler"):::controller
            G("Hierarchical Resource Quotas (HRQ)"):::controller
            C --> D
            C --> E
            C --> F
            C --> G
        end

        H("CRDs & Custom API Extensions"):::config
        I("Webhook Servers"):::controller
    end

    %% Deployment and Configuration
    subgraph "Deployment & Configuration"
        J("Helm Chart for Deployment"):::config
        K("CI/CD / Build Pipelines"):::cicd
    end

    %% Interactions
    A -->|"commands"| B
    B -->|"triggers"| C
    B -->|"manages"| H
    C -->|"calls"| I
    I -->|"feedback"| B
    K -->|"automates"| J
    J -->|"deploys"| C

    %% Click Events for Component Mapping
    click A "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/cmd/kubectl"
    click A "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/internal/kubectl"
    click C "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/cmd/manager"
    click H "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/api/v1alpha2"
    click H "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/config/crd"
    click J "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/charts/hnc"
    click I "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/charts/hnc/templates"
    click I "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/config/webhook"
    click D "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/internal/anchor"
    click E "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/internal/hierarchyconfig"
    click F "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/internal/hncconfig"
    click G "https://github.com/kubernetes-sigs/hierarchical-namespaces/tree/master/internal/hrq"
    click K "https://github.com/kubernetes-sigs/hierarchical-namespaces/blob/master/cloudbuild.yaml"
    click K "https://github.com/kubernetes-sigs/hierarchical-namespaces/blob/master/cloudbuild-build.yaml"
    click K "https://github.com/kubernetes-sigs/hierarchical-namespaces/blob/master/.github"

    %% Styles
    classDef client fill:#f9c,stroke:#333,stroke-width:2px;
    classDef k8s fill:#bbf,stroke:#333,stroke-width:2px;
    classDef controller fill:#cfc,stroke:#333,stroke-width:2px;
    classDef config fill:#ffd,stroke:#333,stroke-width:2px;
    classDef cicd fill:#fdd,stroke:#333,stroke-width:2px;
```
