Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# CobaltCore Docs

## Sidebar pattern

Every section uses a dedicated sidebar function in `docs/.vitepress/config.mts` instead of the generic `generateSidebar` call. The function filters out `index.md` from the generated items and prepends it manually as a pinned "Overview" entry at the top.

Sections using this pattern: Storage, Observability, Network, OpenStack, Overview.

When adding a new section, add a dedicated `<name>Sidebar()` function following the same shape, remove the section from the raw `generateSidebar` array, and spread the new function into the `sidebar` object.
199 changes: 90 additions & 109 deletions bun.lock

Large diffs are not rendered by default.

68 changes: 46 additions & 22 deletions docs/.vitepress/config.mts
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,50 @@ function storageSidebar() {
};
}

function networkSidebar() {
const generated = generateSidebar([{
documentRootPath: '/docs/',
scanStartPath: 'network',
resolvePath: '/network/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
}]);
const items = generated['/network/'].items.filter((i: any) => i.link !== 'index.md');
return {
'/network/': {
base: '/network/',
items: [
{ text: 'Network', items: [{ text: 'Overview', link: 'index.md' }, ...items] },
],
},
};
}

function openstackSidebar() {
const generated = generateSidebar([{
documentRootPath: '/docs/',
scanStartPath: 'openstack',
resolvePath: '/openstack/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
}]);
const items = generated['/openstack/'].items.filter((i: any) => i.link !== 'index.md');
return {
'/openstack/': {
base: '/openstack/',
items: [
{ text: 'OpenStack', items: [{ text: 'Overview', link: 'index.md' }, ...items] },
],
},
};
}

function overviewSidebar() {
const generated = generateSidebar([{
documentRootPath: '/docs/',
Expand Down Expand Up @@ -178,28 +222,6 @@ export default withMermaid({
sortMenusByFrontmatterOrder: true,
},
{
documentRootPath: '/docs/',
scanStartPath: 'openstack',
resolvePath: '/openstack/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
},
{
documentRootPath: '/docs/',
scanStartPath: 'network',
resolvePath: '/network/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
useFolderLinkFromIndexFile: true,
useFolderTitleFromIndexFile: true,
sortMenusByFrontmatterOrder: true,
},
{
documentRootPath: '/docs/',
scanStartPath: 'community',
resolvePath: '/community/',
capitalizeFirst: false,
useTitleFromFrontmatter: true,
Expand All @@ -220,6 +242,8 @@ export default withMermaid({
]),
...storageSidebar(),
...observabilitySidebar(),
...networkSidebar(),
...openstackSidebar(),
...overviewSidebar(),
},

Expand Down
2 changes: 1 addition & 1 deletion docs/compute/gpu.md
Original file line number Diff line number Diff line change
Expand Up @@ -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](/network/ovn)
- [Network](/network/)
2 changes: 1 addition & 1 deletion docs/getting-started/full-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Follow the [Minimal Environment](/getting-started/minimal) guide first to unders

### Networking layer

- [ ] OVN control plane deployed - see [Networking - OVN](/network/ovn)
- [ ] OVN control plane deployed - see [OpenStack Network Integration](/network/openstack-integration)
- [ ] OVN Controller daemonset running on all hypervisor nodes
- [ ] Neutron API connected to OVN Northbound DB

Expand Down
20 changes: 12 additions & 8 deletions docs/network/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,20 @@ 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.
CobaltCore is generally agnostic of the underlying data center network, but its reference implementation expects a vendor-based network provisioned with [WireAPI](https://wireapi.dev/) and integrated with OpenStack services for further provisioning and lifecycle management.

## Components
## Provision Network with WireAPI

| Component | Role |
|---|---|
| [OVN](/network/ovn) | Virtual networking for VMs - provides L2/L3 switching and routing |
WireAPI is a [Kubernetes-native Network Operator](https://wireapi.dev/architecture-overview.html) that automates the provisioning and lifecycle management of network devices. It extends the Kubernetes API with declarative, multi-vendor network automation, letting you manage physical network infrastructure with the same tools and workflows you use for your applications. Network devices and their configurations are represented as Kubernetes objects, bridging your cloud-native environment with your networking hardware.

## How it fits in the stack
## Getting Started

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.
Check out WireAPI's [getting started](https://wireapi.dev/overview/getting-started.html) guide and [Tutorials](https://wireapi.dev/tutorials/).

See [OpenStack - Neutron](/openstack/neutron) for the Neutron API layer, and [Networking - OVN](/network/ovn) for the OVN data plane details.
## Neutron Integration

TBD

## Load Balancing with Octavia

TBD
8 changes: 8 additions & 0 deletions docs/network/openstack-integration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
title: OpenStack Integration
order: 10
---

# OpenStack Network Integration

TBD
66 changes: 0 additions & 66 deletions docs/network/ovn.md

This file was deleted.

2 changes: 1 addition & 1 deletion docs/openstack/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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](/network/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 [OpenStack Network Integration](/network/openstack-integration).

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

Expand Down
4 changes: 1 addition & 3 deletions docs/openstack/neutron.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,10 +59,8 @@ 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](/network/ovn) for the full OVN architecture and CobaltCore-specific configuration.

## See also

- [Networking - OVN](/network/ovn)
- [OpenStack Network Integration](/network/openstack-integration)
- [OpenStack Neutron docs](https://docs.openstack.org/neutron/latest/)
- [OVN architecture overview](https://www.ovn.org/en/architecture/)
Loading