|
| 1 | +--- |
| 2 | +title: NKP architecture |
| 3 | +id: nkp-architecture |
| 4 | +description: A conceptual tour of how Nebari Kubernetes Platform is layered, what the nic CLI does and doesn't do, and how applications reach the cluster via GitOps. |
| 5 | +--- |
| 6 | + |
| 7 | +# NKP architecture |
| 8 | + |
| 9 | +Nebari Kubernetes Platform (NKP) is how end users get to AI capabilities like chat assistants, document analyzers, and code review tools, without their team having to assemble a platform first. |
| 10 | + |
| 11 | +Developers package each capability as a **Software Pack**. NKP wires in login, routing, TLS, and observability, so users just open the landing page and click in. |
| 12 | + |
| 13 | +Software Packs come from two places: |
| 14 | + |
| 15 | +- **Official packs** maintained by OpenTeams. |
| 16 | +- **Community packs** built and maintained by anyone outside OpenTeams: open-source contributors, businesses building on Nebari, or your own internal team. |
| 17 | + |
| 18 | +## How the layers fit together |
| 19 | + |
| 20 | +NKP is a stack of layers, each doing one job. Because the layers connect through stable, well-defined interfaces, you can change one layer without rewriting the others. |
| 21 | + |
| 22 | +{/* Diagram source: docs/static/img/explanations/_sources/nkp-architecture.html |
| 23 | + (open in a browser to view, or import the JSX into Paper / any React renderer to edit) */} |
| 24 | + |
| 25 | + |
| 26 | + |
| 27 | +**Used by end users** |
| 28 | + |
| 29 | +- **Capabilities**: the AI features end users actually rely on (chat assistants, document analyzers, code review tools, and so on). |
| 30 | +- **Landing page**: the home page where users sign in and open each installed Capability. |
| 31 | + |
| 32 | +**Built by developers** |
| 33 | + |
| 34 | +- **Software Pack**: an installable Capability (chat assistant, document analyzer, code review tool, and so on). |
| 35 | + |
| 36 | +**Managed by platform engineers** |
| 37 | + |
| 38 | +- **Nebari Operator**: the automation that deploys each Software Pack and connects it to the Foundational software. |
| 39 | +- **Foundational software**: shared services (secure connections, login, traffic routing, monitoring, continuous delivery from Git) that power the operator and every running pack. |
| 40 | + |
| 41 | +**Where it all runs** |
| 42 | + |
| 43 | +- **Managed Kubernetes cluster**: hosts every container above. EKS for AWS, K3s for Hetzner and local development. |
| 44 | +- **Cloud or bare-metal provider**: the physical infrastructure underneath. AWS, Hetzner, or your own machine for development. |
| 45 | + |
| 46 | +<details> |
| 47 | +<summary>**What's in the foundational layer**</summary> |
| 48 | + |
| 49 | +- **cert-manager**: keeps secure connections working. Automatically requests, renews, and rotates HTTPS certificates for every domain in the cluster. |
| 50 | +- **Envoy Gateway**: handles traffic routing. Inspects incoming requests and forwards each one to the right service, with built-in rate limiting and authentication checks. |
| 51 | +- **Keycloak**: handles login. One sign-on covers every app on the platform (ArgoCD, Grafana, Software Packs), with support for multi-factor authentication and connection to an existing identity provider like Active Directory. |
| 52 | +- **OpenTelemetry Collector**: collects logs, metrics, and traces from every running pack so they can be forwarded to an observability backend. |
| 53 | + |
| 54 | +</details> |
| 55 | + |
| 56 | +## The `nic` CLI |
| 57 | + |
| 58 | +The `nic` CLI (short for **Nebari Infrastructure Core**) is the command-line tool for installing, updating, and tearing down NKP's cloud infrastructure. |
| 59 | + |
| 60 | +### What `nic` does |
| 61 | + |
| 62 | +- **Creates the cloud infrastructure.** This includes the network, the managed Kubernetes cluster and its worker machines, the identity and access controls, and the persistent storage. |
| 63 | +- **Prepares the cluster.** Sets up the basic Kubernetes structures the platform relies on: organizational groupings (namespaces), permission rules (RBAC), storage templates (storage classes), and network rules (network policies). |
| 64 | +- **Installs ArgoCD.** ArgoCD is the GitOps engine that delivers everything above the cluster (the foundational software, the operator, and the packs). `nic` installs it directly so the rest of the platform can flow in from a Git repository. |
| 65 | + |
| 66 | +### What `nic` does not do |
| 67 | + |
| 68 | +- **`nic` is not an application manager.** It does not install or upgrade Software Packs, the Nebari Operator, or any of the foundational software beyond ArgoCD. Those are all delivered from Git through ArgoCD. |
| 69 | +- **`nic` does not change the cluster directly after install.** Anything that needs to happen inside a running cluster (a new pack, an updated config) goes through Git first, and ArgoCD applies it. |
| 70 | + |
| 71 | +This split keeps cluster work (the bottom of the stack) and pack work (the top) from blocking each other. Updating the cluster's underlying machines doesn't affect the running packs, and rolling out a new pack version doesn't require a `nic` deploy. |
| 72 | + |
| 73 | +{/* Diagram source: docs/static/img/explanations/_sources/nkp-architecture-split.html |
| 74 | + (open in a browser to view, or import the HTML into Paper via the write_html MCP tool) */} |
| 75 | + |
| 76 | + |
| 77 | +## GitOps via ArgoCD |
| 78 | + |
| 79 | +[ArgoCD](https://github.com/argoproj/argo-cd) is an open-source deployment tool for Kubernetes. It installs and updates every foundational component on the cluster from two kinds of sources: |
| 80 | + |
| 81 | +- **OpenTeams Git repositories:** for OpenTeams-built pieces like the [landing page](https://github.com/nebari-dev/nebari-landing) and the [Nebari Operator](https://github.com/nebari-dev/nebari-operator). |
| 82 | +- **Upstream Helm charts:** for external open-source pieces like [Keycloak](https://github.com/keycloak/keycloak), [cert-manager](https://github.com/cert-manager/cert-manager), [Envoy Gateway](https://github.com/envoyproxy/gateway), and the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector). |
| 83 | + |
| 84 | +A few properties follow from this: |
| 85 | + |
| 86 | +- **No hidden changes:** Every piece of software in the cluster is there because ArgoCD pulled it from a known source. Nothing runs that you can't trace back to a repository or a Helm chart. |
| 87 | +- **Self-healing:** If a user manually deletes or changes something in the cluster, ArgoCD detects the difference and restores it from the source. |
| 88 | +- **Audit trail and easy rollback:** Every platform change is captured in Git, so you can see who changed what and when, and undoing a change is a single `git revert`. |
| 89 | +- **Independent updates:** Each Software Pack moves on its own cadence. Updating one pack doesn't require coordinating with the others, and removing one leaves the rest untouched. |
| 90 | + |
| 91 | +## State and locking |
| 92 | + |
| 93 | +For providers that use OpenTofu under the hood (AWS today), `nic` keeps a state record of everything it builds. This record gives `nic` two abilities on those providers: |
| 94 | + |
| 95 | +- **Locking:** If two engineers run `nic deploy` at the same time, the second one waits until the first one finishes, so they can't make conflicting changes. |
| 96 | + |
| 97 | + ```mermaid |
| 98 | + sequenceDiagram |
| 99 | + participant E1 as Engineer 1 |
| 100 | + participant SF as State file |
| 101 | + participant E2 as Engineer 2 |
| 102 | + E1->>SF: nic deploy (acquires lock) |
| 103 | + Note over E1,SF: Lock held by Engineer 1 |
| 104 | + E2->>SF: nic deploy (lock busy, waits) |
| 105 | + E1->>SF: changes applied, releases lock |
| 106 | + SF-->>E2: lock available |
| 107 | + E2->>SF: acquires lock, applies changes |
| 108 | + ``` |
| 109 | + |
| 110 | +- **Catches manual changes:** When someone makes a manual change in the cloud (resizing a node group in the console, editing an IAM policy by hand), running `nic deploy --dry-run` shows the difference, and `nic deploy` applies the correction. |
| 111 | + |
| 112 | +Providers that don't use OpenTofu (Hetzner today) take a different provisioning path and don't rely on this state file. |
| 113 | + |
| 114 | +## Where to go next |
| 115 | + |
| 116 | +- [Get started with NKP](/docs/nkp/get-started): install the platform and run your first cluster. |
| 117 | +- [Browse Software Packs](/docs/software-packs/): see what Capabilities are available out of the box. |
0 commit comments