From cf512f87a6c0216e7b8933b55cb3768cd34da1f7 Mon Sep 17 00:00:00 2001 From: Artem Kovalov Date: Wed, 21 Oct 2026 18:16:37 +0200 Subject: [PATCH] feat: restructure docs navigation menu MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Bare Metal Management as first item in Documentation dropdown - Rename networking → network (folder + all internal links) - Remove platform, management, and api sections with their folders - Add Operations dropdown (linked to /overview/) containing Platform and Observability - Stub bare-metal and platform index pages for build compatibility - Clean up broken links across compute, getting-started, openstack, and overview docs Signed-off-by: Artem Kovalov --- docs/.vitepress/config.mts | 43 +- docs/api/index.md | 12 - docs/api/kvm.cloud.sap/v1/eviction.md | 235 -------- docs/api/kvm.cloud.sap/v1/hypervisor.md | 572 ------------------- docs/api/kvm.cloud.sap/v1alpha1/migration.md | 304 ---------- docs/bare-metal/index.md | 6 + docs/compute/gpu.md | 2 +- docs/compute/ha-service.md | 1 - docs/compute/hypervisor.md | 6 +- docs/getting-started/full-deployment.md | 14 +- docs/getting-started/minimal.md | 1 - docs/network/index.md | 20 + docs/network/ovn.md | 66 +++ docs/openstack/index.md | 2 +- docs/openstack/neutron.md | 4 +- docs/openstack/nova.md | 2 +- docs/overview/architecture.md | 6 +- docs/platform/index.md | 15 - 18 files changed, 129 insertions(+), 1182 deletions(-) delete mode 100644 docs/api/index.md delete mode 100644 docs/api/kvm.cloud.sap/v1/eviction.md delete mode 100644 docs/api/kvm.cloud.sap/v1/hypervisor.md delete mode 100644 docs/api/kvm.cloud.sap/v1alpha1/migration.md create mode 100644 docs/bare-metal/index.md create mode 100644 docs/network/index.md create mode 100644 docs/network/ovn.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 9916cea..a675deb 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -88,14 +88,19 @@ export default withMermaid({ { text: 'Documentation', items: [ - { text: 'Platform', link: '/platform/' }, + { text: 'Bare Metal Management', link: '/bare-metal/' }, { text: 'Compute', link: '/compute/' }, - { text: 'OpenStack', link: '/openstack/' }, { text: 'Storage', link: '/storage/' }, - { text: 'Networking', link: '/networking/' }, - { text: 'Observability', link: '/observability/' }, - { text: 'Management', link: '/management/' }, - { text: 'API Reference', link: '/api/' }, + { text: 'Network', link: '/network/' }, + { text: 'OpenStack', link: '/openstack/' }, + { + text: 'Operations', + link: '/overview/', + items: [ + { text: 'Platform', link: '/platform/' }, + { text: 'Observability', link: '/observability/' }, + ], + }, ], }, { text: 'Blog', link: '/blog/' }, @@ -121,8 +126,8 @@ export default withMermaid({ ...generateSidebar([ { documentRootPath: '/docs/', - scanStartPath: 'overview', - resolvePath: '/overview/', + scanStartPath: 'bare-metal', + resolvePath: '/bare-metal/', capitalizeFirst: false, useTitleFromFrontmatter: true, useFolderLinkFromIndexFile: true, @@ -131,8 +136,8 @@ export default withMermaid({ }, { documentRootPath: '/docs/', - scanStartPath: 'getting-started', - resolvePath: '/getting-started/', + scanStartPath: 'overview', + resolvePath: '/overview/', capitalizeFirst: false, useTitleFromFrontmatter: true, useFolderLinkFromIndexFile: true, @@ -141,8 +146,8 @@ export default withMermaid({ }, { documentRootPath: '/docs/', - scanStartPath: 'platform', - resolvePath: '/platform/', + scanStartPath: 'getting-started', + resolvePath: '/getting-started/', capitalizeFirst: false, useTitleFromFrontmatter: true, useFolderLinkFromIndexFile: true, @@ -171,18 +176,8 @@ export default withMermaid({ }, { documentRootPath: '/docs/', - scanStartPath: 'networking', - resolvePath: '/networking/', - capitalizeFirst: false, - useTitleFromFrontmatter: true, - useFolderLinkFromIndexFile: true, - useFolderTitleFromIndexFile: true, - sortMenusByFrontmatterOrder: true, - }, - { - documentRootPath: '/docs/', - scanStartPath: 'management', - resolvePath: '/management/', + scanStartPath: 'network', + resolvePath: '/network/', capitalizeFirst: false, useTitleFromFrontmatter: true, useFolderLinkFromIndexFile: true, diff --git a/docs/api/index.md b/docs/api/index.md deleted file mode 100644 index c13e185..0000000 --- a/docs/api/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: API Reference ---- - -# API Reference - -The CobaltCore API reference provides detailed information about the custom resources and their specifications used within the CobaltCore environment. This documentation is intended for developers and operators who need to interact with or extend the functionality of CobaltCore. - -## Packages -- [kvm.cloud.sap/v1/hypervisor](kvm.cloud.sap/v1/hypervisor) Hypervisor CRD -- [kvm.cloud.sap/v1/eviction](kvm.cloud.sap/v1/eviction) Eviction CRD -- [kvm.cloud.sap/v1alpha1/migration](kvm.cloud.sap/v1alpha1/migration) Migration CRD \ No newline at end of file diff --git a/docs/api/kvm.cloud.sap/v1/eviction.md b/docs/api/kvm.cloud.sap/v1/eviction.md deleted file mode 100644 index 91d07cf..0000000 --- a/docs/api/kvm.cloud.sap/v1/eviction.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -title: Eviction -weight: 1 -description: Eviction CRD ---- - -Packages: - -- [kvm.cloud.sap/v1](#kvmcloudsapv1) - -# kvm.cloud.sap/v1 - -Resource Types: - -- [Eviction](#eviction) - - - - -## Eviction -[↩ Parent](#kvmcloudsapv1 ) - - - - - - -Eviction is the Schema for the evictions API - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionRequired
apiVersionstringkvm.cloud.sap/v1true
kindstringEvictiontrue
metadataobjectRefer to the Kubernetes API documentation for the fields of the `metadata` field.true
specobject - EvictionSpec defines the desired state of Eviction
- 		false
statusobject - EvictionStatus defines the observed state of Eviction
- 		false
- - -### Eviction.spec -[↩ Parent](#eviction) - - - -EvictionSpec defines the desired state of Eviction - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionRequired
hypervisorstring - Name of hypervisor to evict
-
- Validations:
  • self == oldSelf: Value is immutable
    • -     		true
    reasonstring - Reason for eviction, always required
    -     		true
    - - -### Eviction.status -[↩ Parent](#eviction) - - - -EvictionStatus defines the observed state of Eviction - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    conditions[]object - Conditions is an array of current conditions
    -     		false
    hypervisorServiceIdstring -
    -     		false
    outstandingInstances[]string -
    -     		false
    outstandingRamMbinteger -
    -
    - Format: int64
    - Default: 0
    -     		false
    - - -### Eviction.status.conditions[index] -[↩ Parent](#evictionstatus) - - - -Condition contains details for one aspect of the current state of this API Resource. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    lastTransitionTimestring - lastTransitionTime is the last time the condition transitioned from one status to another. -This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
    -
    - Format: date-time
    -     		true
    messagestring - message is a human readable message indicating details about the transition. -This may be an empty string.
    -     		true
    reasonstring - reason contains a programmatic identifier indicating the reason for the condition's last transition. -Producers of specific condition types may define expected values and meanings for this field, -and whether the values are considered a guaranteed API. -The value should be a CamelCase string. -This field may not be empty.
    -     		true
    statusenum - status of the condition, one of True, False, Unknown.
    -
    - Enum: True, False, Unknown
    -     		true
    typestring - type of condition in CamelCase or in foo.example.com/CamelCase.
    -     		true
    observedGenerationinteger - observedGeneration represents the .metadata.generation that the condition was set based upon. -For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date -with respect to the current state of the instance.
    -
    - Format: int64
    - Minimum: 0
    -     		false
    diff --git a/docs/api/kvm.cloud.sap/v1/hypervisor.md b/docs/api/kvm.cloud.sap/v1/hypervisor.md deleted file mode 100644 index 4de78d2..0000000 --- a/docs/api/kvm.cloud.sap/v1/hypervisor.md +++ /dev/null @@ -1,572 +0,0 @@ ---- -title: Hypervisor -weight: 1 -description: Hypervisor CRD ---- - -Packages: - -- [kvm.cloud.sap/v1](#kvmcloudsapv1) - -# kvm.cloud.sap/v1 - -Resource Types: - -- [Hypervisor](#hypervisor) - - - - -## Hypervisor -[↩ Parent](#kvmcloudsapv1 ) - - - - - - -Hypervisor is the Schema for the hypervisors API - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    apiVersionstringkvm.cloud.sap/v1true
    kindstringHypervisortrue
    metadataobjectRefer to the Kubernetes API documentation for the fields of the `metadata` field.true
    specobject - HypervisorSpec defines the desired state of Hypervisor
    -     		false
    statusobject - HypervisorStatus defines the observed state of Hypervisor
    -     		false
    - - -### Hypervisor.spec -[↩ Parent](#hypervisor) - - - -HypervisorSpec defines the desired state of Hypervisor - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    createCertManagerCertificateboolean - Require to issue a certificate from cert-manager for the hypervisor, to be used for -secure communication with the libvirt API.
    -
    - Default: false
    -     		true
    customTraits[]string - CustomTraits are used to apply custom traits to the hypervisor.
    -
    - Default: []
    -     		true
    evacuateOnRebootboolean - EvacuateOnReboot request an evacuation of all instances before reboot.
    -
    - Default: true
    -     		true
    highAvailabilityboolean - HighAvailability is used to enable the high availability handling of the hypervisor.
    -
    - Default: true
    -     		true
    installCertificateboolean - InstallCertificate is used to enable the installations of the certificates via kvm-node-agent.
    -
    - Default: true
    -     		true
    lifecycleEnabledboolean - LifecycleEnabled enables the lifecycle management of the hypervisor via hypervisor-operator.
    -
    - Default: true
    -     		true
    rebootboolean - Reboot request an reboot after successful installation of an upgrade.
    -
    - Default: false
    -     		true
    skipTestsboolean - SkipTests skips the tests during the onboarding process.
    -
    - Default: false
    -     		true
    versionstring - OperatingSystemVersion represents the desired operating system version.
    -     		false
    - - -### Hypervisor.status -[↩ Parent](#hypervisor) - - - -HypervisorStatus defines the observed state of Hypervisor - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    numInstancesinteger - Represent the num of instances
    -
    - Default: 0
    -     		true
    capabilitiesobject - The capabilities of the hypervisors as reported by libvirt.
    -     		false
    conditions[]object - Represents the Hypervisor node conditions.
    -     		false
    hypervisorIdstring - HypervisorID is the unique identifier of the hypervisor in OpenStack.
    -     		false
    instances[]object - Represents the Hypervisor hosted Virtual Machines
    -     		false
    libVirtVersionstring - Represents the LibVirt version.
    -
    - Default: unknown
    -     		false
    operatingSystemobject - Represents the Operating System status.
    -     		false
    serviceIdstring - ServiceID is the unique identifier of the compute service in OpenStack.
    -     		false
    specHashstring -
    -     		false
    updateStatusobject - Represents the Hypervisor update status.
    -     		false
    - - -### Hypervisor.status.capabilities -[↩ Parent](#hypervisorstatus) - - - -The capabilities of the hypervisors as reported by libvirt. - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    cpuArchstring - The hosts CPU architecture (not the guests).
    -
    - Default: unknown
    -     		false
    cpusint or string - Total host cpus available as a sum of cpus over all numa cells.
    -     		false
    memoryint or string - Total host memory available as a sum of memory over all numa cells.
    -     		false
    - - -### Hypervisor.status.conditions[index] -[↩ Parent](#hypervisorstatus) - - - -Condition contains details for one aspect of the current state of this API Resource. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    lastTransitionTimestring - lastTransitionTime is the last time the condition transitioned from one status to another. -This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
    -
    - Format: date-time
    -     		true
    messagestring - message is a human readable message indicating details about the transition. -This may be an empty string.
    -     		true
    reasonstring - reason contains a programmatic identifier indicating the reason for the condition's last transition. -Producers of specific condition types may define expected values and meanings for this field, -and whether the values are considered a guaranteed API. -The value should be a CamelCase string. -This field may not be empty.
    -     		true
    statusenum - status of the condition, one of True, False, Unknown.
    -
    - Enum: True, False, Unknown
    -     		true
    typestring - type of condition in CamelCase or in foo.example.com/CamelCase.
    -     		true
    observedGenerationinteger - observedGeneration represents the .metadata.generation that the condition was set based upon. -For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date -with respect to the current state of the instance.
    -
    - Format: int64
    - Minimum: 0
    -     		false
    - - -### Hypervisor.status.instances[index] -[↩ Parent](#hypervisorstatus) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    activeboolean - Represents the instance state.
    -     		true
    idstring - Represents the instance ID (uuidv4).
    -     		true
    namestring - Represents the instance name.
    -     		true
    - - -### Hypervisor.status.operatingSystem -[↩ Parent](#hypervisorstatus) - - - -Represents the Operating System status. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    firmwareDatestring - FirmwareDate
    -
    - Format: date-time
    -     		false
    firmwareVendorstring - FirmwareVendor
    -     		false
    firmwareVersionstring - FirmwareVersion
    -     		false
    hardwareModelstring - HardwareModel
    -     		false
    hardwareSerialstring - HardwareSerial
    -     		false
    hardwareVendorstring - HardwareVendor
    -     		false
    kernelNamestring - KernelName
    -     		false
    kernelReleasestring - KernelRelease
    -     		false
    kernelVersionstring - KernelVersion
    -     		false
    prettyVersionstring - PrettyVersion
    -     		false
    versionstring - Represents the Operating System version.
    -     		false
    - - -### Hypervisor.status.updateStatus -[↩ Parent](#hypervisorstatus) - - - -Represents the Hypervisor update status. - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    inProgressboolean - Represents a running Operating System update.
    -
    - Default: false
    -     		true
    retryinteger - Represents the number of retries.
    -
    - Default: 3
    -     		true
    installedstring - Represents the Operating System installed update version.
    -
    - Default: unknown
    -     		false
    diff --git a/docs/api/kvm.cloud.sap/v1alpha1/migration.md b/docs/api/kvm.cloud.sap/v1alpha1/migration.md deleted file mode 100644 index 8b47806..0000000 --- a/docs/api/kvm.cloud.sap/v1alpha1/migration.md +++ /dev/null @@ -1,304 +0,0 @@ ---- -title: Migration -weight: 1 -description: Migration CRD ---- - -Packages: - -- [kvm.cloud.sap/v1alpha1](#kvmcloudsapv1alpha1) - -# kvm.cloud.sap/v1alpha1 - -Resource Types: - -- [Migration](#migration) - - - - -## Migration -[↩ Parent](#kvmcloudsapv1alpha1 ) - - - - - - -Migration is the Schema for the migrations API. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    apiVersionstringkvm.cloud.sap/v1alpha1true
    kindstringMigrationtrue
    metadataobjectRefer to the Kubernetes API documentation for the fields of the `metadata` field.true
    specobject - MigrationSpec defines the desired state of Migration.
    -     		false
    statusobject - MigrationStatus defines the observed state of Migration.
    -     		false
    - - -### Migration.status -[↩ Parent](#migration) - - - -MigrationStatus defines the observed state of Migration. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameTypeDescriptionRequired
    autoConvergeThrottlestring -
    -     		false
    dataProcessedstring -
    -     		false
    dataRemainingstring -
    -     		false
    dataTotalstring -
    -     		false
    destinationstring -
    -     		false
    diskBpsstring -
    -     		false
    diskProcessedstring -
    -     		false
    diskRemainingstring -
    -     		false
    diskTotalstring -
    -     		false
    downtimestring -
    -     		false
    errMsgstring -
    -     		false
    memBpsstring -
    -     		false
    memConstantinteger -
    -
    - Format: int64
    -     		false
    memDirtyRatestring -
    -     		false
    memIterationinteger -
    -
    - Format: int64
    -     		false
    memNormalinteger -
    -
    - Format: int64
    -     		false
    memNormalBytesstring -
    -     		false
    memPageSizestring -
    -     		false
    memPostcopyRequestsinteger -
    -
    - Format: int64
    -     		false
    memProcessedstring -
    -     		false
    memRemainingstring -
    -     		false
    memTotalstring -
    -     		false
    operationstring -
    -     		false
    originstring -
    -     		false
    setupTimestring -
    -     		false
    startedstring -
    -
    - Format: date-time
    -     		false
    timeElapsedstring -
    -     		false
    timeRemainingstring -
    -     		false
    typestring -
    -     		false
    diff --git a/docs/bare-metal/index.md b/docs/bare-metal/index.md new file mode 100644 index 0000000..b939555 --- /dev/null +++ b/docs/bare-metal/index.md @@ -0,0 +1,6 @@ +--- +title: Bare Metal Management +order: 1 +--- + +# Bare Metal Management diff --git a/docs/compute/gpu.md b/docs/compute/gpu.md index a26b03f..331c888 100644 --- a/docs/compute/gpu.md +++ b/docs/compute/gpu.md @@ -36,4 +36,4 @@ SR-IOV (Single Root I/O Virtualization) allows a single physical NIC to present ## See also - [Compute - Hypervisor](/compute/hypervisor) -- [Networking - OVN](/networking/ovn) +- [Networking - OVN](/network/ovn) diff --git a/docs/compute/ha-service.md b/docs/compute/ha-service.md index 735f4fc..d2cdc54 100644 --- a/docs/compute/ha-service.md +++ b/docs/compute/ha-service.md @@ -69,5 +69,4 @@ graph LR; ## See also -- [API Reference - Eviction](/api/kvm.cloud.sap/v1/eviction) - [Compute - Hypervisor](/compute/hypervisor) diff --git a/docs/compute/hypervisor.md b/docs/compute/hypervisor.md index 46f8372..5e89b36 100644 --- a/docs/compute/hypervisor.md +++ b/docs/compute/hypervisor.md @@ -14,7 +14,7 @@ The hypervisor is the bare metal node that runs virtual machines. CobaltCore man ## Component stack -Each hypervisor node runs the following components on top of [GardenLinux](/platform/gardenlinux): +Each hypervisor node runs the following components on top of GardenLinux: ```mermaid block-beta @@ -101,7 +101,7 @@ node001-bb234 node001-bb234 Garden Linux 1933.0 11 PowerEdge R860 node006-bb123 node006-bb123 Garden Linux 1933.0 0 ProLiant DL560 Gen11 6.12.38-amd64 27h ``` -See the [API Reference](/api/kvm.cloud.sap/v1/hypervisor) for the full spec. +See the full spec for details. ### `migrations.kvm.cloud.sap` @@ -114,7 +114,7 @@ NAME ORIGIN DESTINATION TYPE 1552e60a-bdba-4850-84da-07dd635bce2c node006-bb086 node003-bb087 completed migration_out 22d 35.078s 64.0 GiB ``` -See the [API Reference](/api/kvm.cloud.sap/v1alpha1/migration) for the full spec. +See the full spec for details. ## KVM HA Agent diff --git a/docs/getting-started/full-deployment.md b/docs/getting-started/full-deployment.md index 4e5542c..ef23cdf 100644 --- a/docs/getting-started/full-deployment.md +++ b/docs/getting-started/full-deployment.md @@ -33,9 +33,9 @@ Follow the [Minimal Environment](/getting-started/minimal) guide first to unders ## Prerequisites -- IronCore configured and managing your bare metal nodes - see [Platform - IronCore](/platform/ironcore) -- Gardener cluster provisioned - see [Platform - Gardener](/platform/gardener) -- GardenLinux deployed on hypervisor nodes - see [Platform - GardenLinux](/platform/gardenlinux) +- IronCore configured and managing your bare metal nodes +- Gardener cluster provisioned +- GardenLinux deployed on hypervisor nodes - At least 3 control plane nodes for HA Kubernetes - At least 2 data centers (or failure domains) for stretched Ceph @@ -65,7 +65,7 @@ Follow the [Minimal Environment](/getting-started/minimal) guide first to unders ### Networking layer -- [ ] OVN control plane deployed - see [Networking - OVN](/networking/ovn) +- [ ] OVN control plane deployed - see [Networking - OVN](/network/ovn) - [ ] OVN Controller daemonset running on all hypervisor nodes - [ ] Neutron API connected to OVN Northbound DB @@ -87,9 +87,9 @@ Follow the [Minimal Environment](/getting-started/minimal) guide first to unders ### Management layer -- [ ] Greenhouse connected to the cluster - see [Management - Greenhouse](/management/greenhouse) -- [ ] Aurora management frontend accessible - see [Management - Aurora](/management/aurora) -- [ ] Cortex placement configured and integrated with Nova - see [Management - Cortex](/management/cortex) +- [ ] Greenhouse connected to the cluster +- [ ] Aurora management frontend accessible +- [ ] Cortex placement configured and integrated with Nova ## Operational readiness diff --git a/docs/getting-started/minimal.md b/docs/getting-started/minimal.md index 27b098a..c392420 100644 --- a/docs/getting-started/minimal.md +++ b/docs/getting-started/minimal.md @@ -42,7 +42,6 @@ CobaltCore uses [Gardener](https://gardener.cloud) for cluster lifecycle managem The control plane must be reachable from the hypervisor node. -See [Platform - Bootstrap](/platform/bootstrap) for details on how CobaltCore clusters are set up in production. ## Step 2: Install the Hypervisor Operator diff --git a/docs/network/index.md b/docs/network/index.md new file mode 100644 index 0000000..9e9a6c1 --- /dev/null +++ b/docs/network/index.md @@ -0,0 +1,20 @@ +--- +title: Networking +order: 1 +--- + +# Networking + +CobaltCore uses OVN (Open Virtual Network) as the virtual networking layer for VMs. OVN is managed by Neutron's OVN backend and provides virtual networks, routers, and security groups at scale without per-node agent complexity. + +## Components + +| Component | Role | +|---|---| +| [OVN](/network/ovn) | Virtual networking for VMs - provides L2/L3 switching and routing | + +## How it fits in the stack + +Neutron (in the OpenStack layer) owns the logical network model - networks, subnets, ports, routers, security groups. OVN translates those logical resources into forwarding rules on each hypervisor node via the OVN Controller daemonset. VMs get virtual interfaces managed by OVS. + +See [OpenStack - Neutron](/openstack/neutron) for the Neutron API layer, and [Networking - OVN](/network/ovn) for the OVN data plane details. diff --git a/docs/network/ovn.md b/docs/network/ovn.md new file mode 100644 index 0000000..5909ebb --- /dev/null +++ b/docs/network/ovn.md @@ -0,0 +1,66 @@ +--- +title: OVN +order: 10 +outline: deep +--- + +# OVN (Open Virtual Network) + +OVN is the virtual networking backend for CobaltCore. It replaces the traditional per-node Neutron Open vSwitch agents with a centralized control plane and distributed forwarding, giving consistent network state across all hypervisor nodes. + +## Architecture + +```mermaid +graph TB + subgraph "Control Plane" + NeutronAPI["Neutron API"] + OVNNB["OVN Northbound DB\n(logical state)"] + OVNNorthD["OVN-NorthD\n(translation)"] + OVNSB["OVN Southbound DB\n(physical state / flows)"] + end + subgraph "Hypervisor Node A" + OVNCtrlA["OVN Controller"] + OVSA["Open vSwitch (OVS)"] + VMA["VM interfaces"] + end + subgraph "Hypervisor Node B" + OVNCtrlB["OVN Controller"] + OVSB["Open vSwitch (OVS)"] + VMB["VM interfaces"] + end + + NeutronAPI -->|"writes logical state"| OVNNB + OVNNorthD -->|"reads"| OVNNB + OVNNorthD -->|"writes flows"| OVNSB + OVNSB -->|"distributes"| OVNCtrlA + OVNSB -->|"distributes"| OVNCtrlB + OVNCtrlA -->|"programs"| OVSA + OVNCtrlB -->|"programs"| OVSB + OVSA -->|"manages"| VMA + OVSB -->|"manages"| VMB +``` + +## Data flow + +| Component | Role | +|---|---| +| **Neutron API** | Writes logical network resources (networks, ports, routers, security groups) to OVN Northbound DB via the OVN ML2 driver | +| **OVN Northbound DB** | Stores the logical network model - what the network should look like | +| **OVN-NorthD** | Translates the logical model into forwarding rules and populates OVN Southbound DB | +| **OVN Southbound DB** | Stores the physical network state - which hypervisor hosts which port, and what flows to install | +| **OVN Controller** | Runs as a daemonset on each hypervisor; reads its local flows from OVN-SB and programs OVS | +| **OVS** | Kernel-level datapath that forwards VM traffic according to the flows installed by OVN Controller | + +## Why OVN over Neutron's legacy agents? + +With traditional OVS agents, each hypervisor node runs its own Neutron agent that independently manages network state. At scale this creates coordination complexity, slow convergence, and debugging difficulty. OVN centralizes the control plane: + +- Network state is authoritative in OVN-NB - no drift between nodes +- Adding a hypervisor node requires no per-node Neutron agent configuration +- Troubleshooting uses OVN-trace to follow a packet's path through logical flows + +## See also + +- [OpenStack - Neutron](/openstack/neutron) +- [OVN architecture overview](https://www.ovn.org/en/architecture/) +- [Red Hat OVN guide](https://docs.redhat.com/en/documentation/red_hat_openstack_platform/13/html/networking_with_open_virtual_network/open_virtual_network_ovn) diff --git a/docs/openstack/index.md b/docs/openstack/index.md index e9a9604..96c7cf8 100644 --- a/docs/openstack/index.md +++ b/docs/openstack/index.md @@ -40,7 +40,7 @@ Compute Clusters ## CobaltCore-specific choices -**Why OVN for networking?** Neutron's OVN backend replaces the per-node Open vSwitch agents with a centralized control plane (OVN-NB/SB databases) and distributed forwarding. This reduces per-node complexity and scales better at large node counts. See [Networking - OVN](/networking/ovn). +**Why OVN for networking?** Neutron's OVN backend replaces the per-node Open vSwitch agents with a centralized control plane (OVN-NB/SB databases) and distributed forwarding. This reduces per-node complexity and scales better at large node counts. See [Networking - OVN](/network/ovn). **Why NetApp/NFS for Cinder?** In CobaltCore's reference configuration, Cinder uses a NetApp filer for block volumes delivered as NFS mounts. This enables thin provisioning and hardware-level snapshots. Ceph RBD is an alternative backend for environments without a NetApp filer. diff --git a/docs/openstack/neutron.md b/docs/openstack/neutron.md index d852bbd..4a89080 100644 --- a/docs/openstack/neutron.md +++ b/docs/openstack/neutron.md @@ -59,10 +59,10 @@ OVN replaces Neutron's traditional agent-per-node model: | **OVN Controller** | Runs on each compute node; translates SB flows into OVS rules | | **OVS** | Open vSwitch - the kernel datapath that forwards VM traffic | -See [Networking - OVN](/networking/ovn) for the full OVN architecture and CobaltCore-specific configuration. +See [Networking - OVN](/network/ovn) for the full OVN architecture and CobaltCore-specific configuration. ## See also -- [Networking - OVN](/networking/ovn) +- [Networking - OVN](/network/ovn) - [OpenStack Neutron docs](https://docs.openstack.org/neutron/latest/) - [OVN architecture overview](https://www.ovn.org/en/architecture/) diff --git a/docs/openstack/nova.md b/docs/openstack/nova.md index 6ff96c7..eeb0cbc 100644 --- a/docs/openstack/nova.md +++ b/docs/openstack/nova.md @@ -56,7 +56,7 @@ Nova Compute Agents run as Kubernetes daemonsets on hypervisor nodes managed by The [HA Service](/compute/ha-service) calls Nova's host evacuation API when a hypervisor fails. -[Cortex](/management/cortex) integrates with Nova's placement API to make intelligent scheduling decisions based on cluster state. +Cortex integrates with Nova's placement API to make intelligent scheduling decisions based on cluster state. ## See also diff --git a/docs/overview/architecture.md b/docs/overview/architecture.md index c1ca33b..52378f0 100644 --- a/docs/overview/architecture.md +++ b/docs/overview/architecture.md @@ -28,7 +28,7 @@ CobaltCore is organized as a layered stack. Each layer has a clear responsibilit ## Platform -The foundation. Kubernetes provides the control plane. [IronCore](/platform/ironcore) handles bare metal discovery and lifecycle. [Gardener](/platform/gardener) manages cluster lifecycle (creating, upgrading, and deleting Kubernetes clusters). [GardenLinux](/platform/gardenlinux) is the hardened Linux OS that runs on hypervisor nodes. +The foundation. Kubernetes provides the control plane. IronCore handles bare metal discovery and lifecycle. Gardener manages cluster lifecycle (creating, upgrading, and deleting Kubernetes clusters). GardenLinux is the hardened Linux OS that runs on hypervisor nodes. Everything above this layer runs as Kubernetes workloads. @@ -38,7 +38,7 @@ The infrastructure data plane - the raw execution environment for virtual machin - **[Compute](/compute/)** - KVM hypervisors managed by a Kubernetes operator. VMs run on bare metal nodes via libvirt. The HA service monitors hypervisor health and triggers evacuation when nodes fail. - **[Storage](/storage/)** - Ceph provides block (RBD), object (RGW), and file (CephFS) storage. Rook operates Ceph as a Kubernetes-native workload. Arbiter enables stretched clusters across two data centers. Chorus handles S3 object replication. -- **[Networking](/networking/)** - OVN provides virtual networking for VMs. Neutron's OVN integration manages the control plane. +- **[Networking](/network/)** - OVN provides virtual networking for VMs. Neutron's OVN integration manages the control plane. ## Observability @@ -52,7 +52,7 @@ The cloud services layer. OpenStack APIs (Nova, Neutron, Cinder, Keystone, Glanc ## Management -The operations and control plane UI. [Aurora](/management/aurora) is the cloud management frontend. [Greenhouse](/management/greenhouse) provides the monitoring and management umbrella. [Cortex](/management/cortex) handles intelligent placement and scheduling of workloads across the cluster. +The operations and control plane UI. Aurora is the cloud management frontend. Greenhouse provides the monitoring and management umbrella. Cortex handles intelligent placement and scheduling of workloads across the cluster. ## Data flow: provisioning a VM diff --git a/docs/platform/index.md b/docs/platform/index.md index 4f12620..90b84d6 100644 --- a/docs/platform/index.md +++ b/docs/platform/index.md @@ -4,18 +4,3 @@ order: 1 --- # Platform - -The platform layer is the foundation that everything else in CobaltCore runs on. It covers bare metal lifecycle, cluster orchestration, and the operating system on hypervisor nodes. - -## Components - -| Component | Role | -|---|---| -| [IronCore](/platform/ironcore) | Bare metal discovery, provisioning, and lifecycle management | -| [Gardener](/platform/gardener) | Kubernetes cluster lifecycle (create, upgrade, delete) | -| [GardenLinux](/platform/gardenlinux) | Hardened Linux OS for hypervisor nodes | -| [Bootstrap](/platform/bootstrap) | How a new CobaltCore cluster is stood up end-to-end | - -## How the layers relate - -IronCore discovers physical machines and makes them available as managed resources. Gardener uses those resources to provision Kubernetes clusters. GardenLinux is the OS deployed on the hypervisor nodes that Gardener provisions. Everything above - Kubernetes operators, OpenStack services, Ceph - runs on top of this foundation.