> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/introduction/architecture-overview.md). # Architecture Overview How the management plane, the hosts you supply, the platform services, the deployment models, and the regional topology fit together. ## Overview space.vars.product\_name separates the software that operates your private cloud from the hardware that runs your workloads. A **management plane** holds the core services, the API, and the user interface. A **data plane** of physical hosts that you supply runs your virtual machines and the nodes of your Kubernetes clusters. The two are joined by an agent that Platform9 installs on each host, and everything you configure (clusters, networks, storage, images) is expressed against that split. This page assumes no prior knowledge of space.vars.product\_acronym and no existing deployment. It is written for the cloud administrator who will plan, deploy, and operate the platform, and it is a useful orientation before you read any of the feature sections. Each concept introduced here links to the section that covers it in depth, so treat this page as a map rather than a reference. In this guide, you will learn how the management plane and the data plane divide responsibility, which core services make up space.vars.product\_acronym, different deployment models supported and how the SaaS and self-hosted deployment models differ, how Kubernetes clusters fit that same architecture, and how regions, tenants, and clusters organize your infrastructure. ## Architecture The following diagram describes the overall space.vars.product\_acronym architecture.
## Management Plane and Data Plane Every space.vars.product\_acronym deployment has exactly two layers. The management plane (also sometimes called the control plane) runs the core services and presents the UI and the API. The data plane is the set of physical hosts you contribute: they run the KVM hypervisor, hold your virtual machines, and serve the storage and images those machines use. Your workloads always run in your own data center, on your own hardware, regardless of where the management plane runs. ### The Management Plane The management plane holds the state metadata for your cloud and makes the decisions. It authenticates users, authorizes API requests, records the desired configuration of every cluster and host, decides which host a new virtual machine should run on, and drives the cluster-level automation described below. It does not run your workloads. ### The Data Plane The data plane is made up of hosts. A host is a physical machine you supply, containing the CPU, memory, storage, and network interfaces your virtual machines and / or containers consume. A host can run either as a hypervisor or as a bare metal node in a Kubernetes cluster (see [Kubernetes Clusters](#kubernetes-clusters)). space.vars.product\_name standardizes on the open source KVM hypervisor, which runs directly in the Linux kernel on the host hardware. ### Host Agent The Platform9 host agent is the first component installed on each host, and it is the only path between the two layers. Based on the roles assigned to a host, the agent downloads and configures the software that role requires, then keeps that host integrated with the management plane. It also reports host health continuously, detecting failures and errors, and it carries out upgrades when you move your deployment to a newer version. Agent traffic travels over the network interface you designate for management traffic in your host network configuration. That same interface carries communication between the management plane and your hosts in both deployment models, which makes it the connection to protect and to size for reliability. See [Network Traffic Types](/private-cloud-director/virtualized-networking/networking-overview.md#network-traffic-types) for the full set of traffic types you can assign to an interface. ### Host Roles A host does not have a fixed purpose. You assign it one or more **roles** during authorization, and the agent installs the corresponding software. Roles are how data-plane function is placed onto hardware: * **Hypervisor:** runs virtual machines. Assign this role to most hosts in a cluster. * **Image Library:** stores the cluster copy of the source images that new virtual machines are provisioned from. Every cluster needs at least one. * **Persistent (Block) Storage:** connects the cluster to your block storage backends and serves persistent volumes. * **DNS:** enables DNS as a Service, which is optional. * **Advanced Remote Support:** allows Platform9 support to gather detailed telemetry from a host. This role is off by default. Networking is not a role you assign in the common case. When Distributed Virtual Routing is enabled, the networking components are installed uniformly on every host added to a cluster, and two agents (the OVN Controller Gateway agent and the OVN Neutron agent) run on each one. If you disable Distributed Virtual Routing, you assign the Network Node role explicitly instead. For the full role assignment procedure and host lifecycle, see [Host](/private-cloud-director/virtualized-clusters/add-hosts-virtualized-cluster.md). ## Cluster Management & Core Services The management plane is a set of cooperating services, each owning one domain of your cloud. You interact with all of them through the same UI, API, and CLI. | Service | Responsibility | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Cluster Management | Virtualized cluster management is handled via a set of services such as Platform9 resource manager, VM high availability service and DRR service. | | Compute Service | Provisions virtual machines, decides which host each one runs on, and manages the VM lifecycle. | | Image Library Service | Manages virtual machine images and snapshots, and serves image contents to a hypervisor during provisioning. | | Persistent Storage Service | Provides persistent block storage volumes to virtual machines and integrates your storage backends. | | Networking Service | Provides software defined networking: virtual networks, subnets, routers, security groups, and load balancing. | | Identity Service | Authenticates users and API clients, and authorizes every request against your domains, tenants, and roles. | | Metadata Service | Serves instance metadata to cloud-init on each network. | You can see the live status of these services, per host, on the [Service Health Dashboard](/private-cloud-director/monitoring-and-observability/service-health-dashboard.md). ### Cluster-Level Automation Two capabilities run above the individual services and act on a whole virtualized cluster. Both are configured per cluster and are optional: * **Virtual Machine High Availability (VM HA)** monitors host health across the cluster. When a host fails, it recovers the affected virtual machines on healthy hosts without manual intervention. * **Dynamic Resource Rebalancing (DRR)** monitors CPU and memory utilization across the cluster and live migrates virtual machines to relieve imbalances before they degrade performance. ## Platform Services On top of cluster management and core services, space.vars.product\_acronym offers a layer of Platform-as-a-Service (PaaS) services, including Load Balancer as a Service and DNS as a Service. space.vars.product\_acronym can also integrate with your existing, compatible firewall and VPN components to offer Firewall as a Service and VPN as a Service for your end users. ## Kubernetes Clusters space.vars.product\_acronym runs Kubernetes clusters on the architecture described above: the same management plane, the same hosts you supply, and the same tenants. You create and operate Kubernetes clusters and virtual machines from one UI and one API. A Kubernetes cluster and a virtualized cluster are not the same object, and the distinction matters when you plan capacity. A [virtualized cluster](#virtualized-cluster) is a grouping of hypervisor hosts whose capacity is presented as a single pool. A Kubernetes cluster is a set of nodes that run your containers. Creating one does not create the other. Those nodes come from one of two places, and which you choose determines how the cluster draws on your hardware. In the common case they are virtual machines running on a virtualized cluster, so one virtualized cluster can carry many Kubernetes clusters belonging to different tenants. Alternatively they are physical machines dedicated to the cluster, which do not belong to a virtualized cluster at all. Worker Nodes and Bare Metal Nodes below describe each in turn. ### Where the Kubernetes Control Plane Runs The management plane hosts the Kubernetes control planes themselves, running them as pods rather than dedicating a virtual or physical machine to each cluster. Control plane high availability, upgrades, and scaling are therefore handled for you, and a new cluster does not spend your own host capacity on control plane machines. Each tenant can hold several Kubernetes clusters, and every cluster gets an isolated control plane with its own role assignments. Because these control planes live in the management plane, where they physically run follows the deployment model described in the next section: Platform9 operates them in the SaaS model, and you operate them on your own hardware in the self-hosted model. ### Worker Nodes Worker nodes are where your containers run, and they are ordinary data-plane workloads. In the common case they are virtual machines provisioned from the cluster blueprint and bootstrapped into the cluster, so they draw on the same host CPU, memory, and storage, and count against the same tenant quota, as any other virtual machine. You configure worker nodes in **node groups**, a template that defines a set of nodes sharing server, storage, and network properties, and a node group can scale manually or automatically. Change is applied by replacing nodes rather than modifying them: a Kubernetes version upgrade rolls out by creating new nodes and retiring the old ones, so size a cluster with enough nodes that losing one to replacement does not disrupt your workloads. Node virtual machines attach to a managed network you create in space.vars.product\_acronym, and the pod and service address ranges must not overlap your private networks. See [Cluster Networking](/private-cloud-director/kubernetes-clusters/cluster-lifecycle/cluster-networking.md) for the ranges involved and their defaults. ### Bare Metal Nodes A Kubernetes cluster can also run on physical machines rather than virtual ones, which is the second thing a host can be in the data plane. Bare metal nodes are onboarded with the `byohctl` tool rather than by assigning a host role, which is why no Kubernetes entry appears in the host role list above. Bare metal support for Kubernetes is currently in beta. ### Cluster Lifecycle Cluster creation, scaling, upgrade, and deletion are declarative. You describe the cluster you want, and Cluster API components in the management plane reconcile toward it while space.vars.product\_acronym provisions the virtual machines, networks, and storage underneath. See [Cluster Lifecycle](/private-cloud-director/kubernetes-clusters/cluster-lifecycle.md) for the day-to-day operations. ## Deployment Models space.vars.product\_name ships in two commercial deployment models. They differ only in where the management plane runs and who operates it. The data plane is identical in both. ### SaaS Platform9 hosts and operates the management plane for you, and you consume it as a service. Your infrastructure stays in your data center: the hosted management plane communicates remotely with your hosts over the management interface to configure and run your private cloud. Platform9 patches and upgrades the management plane, so your operational responsibility is limited to your hosts and the network path to them. This model suits organizations that want the platform without the work of running it. ### Self-Hosted You run the management plane on your own hardware, in your own data center or a co-location facility. space.vars.self\_hosted\_product\_name is installed and lifecycle-managed with the `airctl` command line tool, which also handles adding regions, scaling the management cluster, backup and restore, and management plane upgrades. This model suits organizations with compliance, sovereignty, or air-gap requirements that rule out a hosted management plane. Two things follow from operating the management plane yourself. First, upgrades are yours to schedule and run: you upgrade the management plane with `airctl` before you upgrade hosts. Second, a self-hosted deployment always provisions an internal region named `Infra` to host the Identity Service. It is not visible in the UI, but it is always required. ### Community Edition Community Edition is a completely free version of space.vars.product\_name. It is free to download and use, and is intended for home labs and test setups. ### Platform9 OS Platform9 OS is a Platform9 certified version of Rocky Linux, offered as a single ISO-based installation for easy deployment, with PXE and Kickstart options for installing at scale. ### What Does Not Change Whichever model you choose, the host agent, the host roles, the cluster blueprint, the core services, and every workflow in this documentation behave the same way. Where a procedure applies only to a self-hosted management plane, usually because it involves `airctl`, the documentation calls that out explicitly. ## Regions, Tenants, and Clusters Two hierarchies organize a space.vars.product\_acronym deployment. One is physical and describes where your hardware sits and how it is grouped. The other is logical and describes who owns which resources. They are independent: a tenant's virtual machines can run on any cluster the tenant is entitled to use. ### Region A **region** generally represents a physical location, such as a data center. It is one management plane governing one set of hypervisors, and it is the outermost boundary of the physical hierarchy. Regions are provisioned during onboarding; to add more, contact your Platform9 representative. A region has documented capacity limits (clusters, hosts, virtual machines, tenants, and concurrent operations). Plan for multiple regions if you need to scale beyond them, and see [Configuration Maximums](/private-cloud-director/getting-started/configuration-maximums.md) for the current values. ### Cluster Blueprint Each region has exactly one **cluster blueprint**: the base configuration that every virtualized cluster in that region inherits. It defines host networking and physical networks, the available block storage types, where images are stored, the ephemeral disk path on each hypervisor, and the console proxy address. Creating the blueprint is the first step after your instance is set up, and it is what lets capacity you add later conform automatically to the architecture you chose up front. ### Virtualized Cluster A **virtualized cluster** is a grouping of hosts within a region whose CPU, memory, and GPU are presented as a single pool. When you create a virtual machine in a cluster, the Compute Service places it on one of the cluster's hosts according to available capacity and any placement constraints you set. Clusters are the level at which VM HA, Distributed Resource Rebalancing, and GPU support are switched on, so they are also your unit of fault isolation and of hardware specialization. Common reasons to run more than one are tenant isolation, licensing boundaries, and separating specialized hardware such as GPU or high-memory hosts. A virtualized cluster is distinct from a Kubernetes cluster, which runs as a workload on the capacity a virtualized cluster provides. See [Kubernetes Clusters](#kubernetes-clusters). Within a cluster, two further groupings are available, and they are mutually exclusive: * A **host aggregate** groups hosts that share a property you define as a key-value pair, such as a software license. You then create a flavor that references the aggregate, so virtual machines needing that property land on those hosts. * A **stretched cluster** splits one cluster across two sites as two **failure domains**, gives each virtual machine a soft affinity to one of them, and relies on VM HA to recover workloads on the surviving site if a whole site fails. ### Tenant The logical hierarchy is owned by the Identity Service. A **domain** is the high-level container for tenants, users, and groups. A **tenant** (called a project in the API and CLI) is the base unit of ownership: every resource in space.vars.product\_acronym belongs to exactly one tenant. Users and groups are granted **roles** on a tenant or a domain, and those role assignments determine what each user can do. Names are unique within a domain rather than globally, which is what allows separate sub-organizations to coexist in one deployment. ## Next Steps * To set up your instance and onboard your first hosts, see [Getting Started](/private-cloud-director/getting-started/getting-started.md). * To define the base configuration your clusters inherit, see [Cluster Blueprint](/private-cloud-director/virtualized-clusters/virtualized-cluster-blueprint.md). * To create your first Kubernetes cluster, see [Getting Started](/private-cloud-director/kubernetes-clusters/getting-started-with-kubernetes-in-pcd.md). ## Related Pages * [Design Principles](/private-cloud-director/introduction/design-principles.md): the product philosophy behind the architecture on this page * [Overview & Architecture](/private-cloud-director/virtualized-networking/networking-overview.md): the networking layer in depth, including host network configuration * [Overview](/private-cloud-director/identity-and-multi-tenancy/identity-and-multi-tenancy-overview.md): domains, tenants, users, roles, and tokens in depth * [Configuration Maximums](/private-cloud-director/getting-started/configuration-maximums.md): tested limits per region, cluster, and tenant * [Architecture and Technical Overview](/private-cloud-director/kubernetes-clusters/architecture-and-technical-overview.md): the Kubernetes components in depth --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.platform9.com/private-cloud-director/introduction/architecture-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.