diff --git a/.dockerignore b/.dockerignore index 2874976..43db1e7 100644 --- a/.dockerignore +++ b/.dockerignore @@ -2,3 +2,4 @@ node_modules docs/.vitepress/dist docs/.vitepress/cache +docs/_upstream diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml index 3260e24..02009bf 100644 --- a/.github/workflows/static.yml +++ b/.github/workflows/static.yml @@ -8,6 +8,9 @@ on: types: [ assigned, opened, synchronize, reopened ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: + # Rebuilds nightly, so changes to the C5C3/cobaltcore docs reach the OpenStack section within a day + schedule: + - cron: "0 3 * * *" # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages permissions: @@ -27,6 +30,19 @@ jobs: steps: - name: Checkout uses: actions/checkout@v7 + # The OpenStack section is the documentation of C5C3/cobaltcore (docs/.vitepress/overlay.ts). + # Its pages import files from tests/ and deploy/, so those are checked out too. + - name: Checkout C5C3/cobaltcore docs + uses: actions/checkout@v7 + with: + repository: C5C3/cobaltcore + ref: main + path: docs/_upstream/cobaltcore + persist-credentials: false + sparse-checkout: | + docs + tests + deploy - name: Setup Node uses: actions/setup-node@v7 with: diff --git a/.gitignore b/.gitignore index 313d80c..48f7e82 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ docs/.vitepress/dist docs/.vitepress/cache bin build +docs/_upstream/ diff --git a/Dockerfile b/Dockerfile index a9ff100..df76d90 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,6 +1,10 @@ FROM node:26-alpine +# The predocs:dev hook runs hack/sync-cobaltcore.sh, which needs bash and git +# to clone C5C3/cobaltcore into the mounted docs/_upstream/cobaltcore. +RUN apk add --no-cache bash git WORKDIR /app COPY package*.json ./ RUN npm install +COPY hack/sync-cobaltcore.sh hack/ EXPOSE 5173 -CMD ["npm", "run", "docs:dev", "--", "--host=0.0.0.0"] \ No newline at end of file +CMD ["npm", "run", "docs:dev", "--", "--host=0.0.0.0"] diff --git a/README.md b/README.md index bbe8f00..469df29 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,9 @@ Use **Docker** if you'd rather not install Node.js locally. ### Local -Requires [Node.js](https://nodejs.org/) 18+. +Requires [Node.js](https://nodejs.org/) 22.18 or newer, and git. The build +loads a TypeScript module of C5C3/cobaltcore with Node's built-in type +stripping (see [The OpenStack section](#the-openstack-section)). ```sh npm install @@ -26,6 +28,26 @@ docker compose up In both cases the documentation is accessible at [http://localhost:5173/](http://localhost:5173/). +### The OpenStack section + +The pages under `/openstack/` are the documentation of +[C5C3/cobaltcore](https://github.com/C5C3/cobaltcore). Before `docs:dev` and +`docs:build`, npm runs `npm run docs:sync`, which clones C5C3/cobaltcore into +`docs/_upstream/cobaltcore` unless a checkout is already there. The directory is +ignored by git; delete it to fetch a fresh copy. + +To preview changes in a local C5C3/cobaltcore checkout, copy it in and start the +development server: + +```sh +COBALTCORE_SRC=../cobaltcore npm run docs:sync +npm run docs:dev +``` + +Run `docs:sync` with `COBALTCORE_SRC` again after each change; copying needs +rsync. [Publishing to cobaltcore.dev](https://c5c3.github.io/cobaltcore/contributing/publishing-to-cobaltcore-dev.html) +describes which pages are published and how their links resolve. + ## Support, Feedback, Contributing This project is open to feature requests and suggestions, bug reports etc. via diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 2e3facc..649e73c 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -1,6 +1,21 @@ import { withMermaid } from "vitepress-plugin-mermaid"; import { generateSidebar } from 'vitepress-sidebar'; import { fileURLToPath, URL } from 'node:url' +import { createOverlay } from './overlay' + +// The OpenStack section is the documentation of C5C3/cobaltcore, checked out into +// docs/_upstream/cobaltcore by `npm run docs:sync` (or the CI workflow) and mounted +// under /openstack/. See https://c5c3.github.io/cobaltcore/contributing/publishing-to-cobaltcore-dev.html +const cobaltcore = createOverlay({ + srcDir: fileURLToPath(new URL('..', import.meta.url)), + checkout: '_upstream/cobaltcore', + mount: 'openstack', + routes: Object.fromEntries( + ['keystone', 'horizon', 'glance', 'placement', 'barbican', 'ovn', 'neutron', 'cinder', 'nova'] + .map(s => [`reference/${s}/index.md`, `${s}.md`]), + ), + groupTitles: { 'Getting Started': 'Quick Starts', 'Reference': 'Services' }, +}) function storageSidebar() { const generated = generateSidebar([{ @@ -47,25 +62,17 @@ function networkSidebar() { }; } -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'); +// The upstream sidebar, pruned to the published pages, already opens with the +// Overview entry (/openstack/), so nothing is filtered out or prepended here. +async function openstackSidebar() { return { - '/openstack/': { - base: '/openstack/', - items: [ - { text: 'OpenStack', items: [{ text: 'Overview', link: 'index.md' }, ...items] }, - ], - }, + '/openstack/': [ + ...(await cobaltcore.sidebar()), + { + text: 'Reference', + items: [{ text: 'Operator reference (c5c3.github.io)', link: cobaltcore.manifest.canonical + 'reference/keystone/' }], + }, + ], }; } @@ -194,6 +201,11 @@ export default withMermaid({ title: "CobaltCore", description: "Infrastructure management for cloud native and traditional workloads. Get your cloud running in weeks with Kubernetes-native orchestration and OpenStack-compatible API surface, fully open source.", base: "/", + srcExclude: cobaltcore.srcExclude, + rewrites: cobaltcore.rewrites, + // The OpenStack quick starts name port-forward URLs that never resolve during the build. + ignoreDeadLinks: [/^https?:\/\/localhost(:\d+)?/], + markdown: { config: (md) => cobaltcore.markdown(md) }, head: [ ['link', { rel: 'icon', href: 'https://raw.githubusercontent.com/cobaltcore-dev/.github/refs/heads/main/assets/Logo_Cobalt_Core_background_white.svg' }], ['link', { rel: 'canonical', href: 'https://cobaltcore.dev/' }], @@ -252,7 +264,11 @@ export default withMermaid({ ], editLink: { - pattern: 'https://github.com/cobaltcore-dev/docs/edit/main/docs/:path', + // VitePress serializes this function into the client bundle: it must not + // reference anything outside its own body. + pattern: ({ filePath }) => filePath.startsWith('_upstream/cobaltcore/') + ? `https://github.com/C5C3/cobaltcore/edit/main/${filePath.slice('_upstream/cobaltcore/'.length)}` + : `https://github.com/cobaltcore-dev/docs/edit/main/docs/${filePath}`, text: 'Edit this page on GitHub' }, @@ -311,7 +327,7 @@ export default withMermaid({ ]), ...storageSidebar(), ...networkSidebar(), - ...openstackSidebar(), + ...(await openstackSidebar()), ...overviewSidebar(), ...operationsSidebar(), ...governanceSidebar(), diff --git a/docs/.vitepress/overlay.ts b/docs/.vitepress/overlay.ts new file mode 100644 index 0000000..b654a00 --- /dev/null +++ b/docs/.vitepress/overlay.ts @@ -0,0 +1,107 @@ +// Build-time overlay of an upstream repository's VitePress docs into this site. +// The upstream checkout lives in docs/_upstream/ (gitignored) and is never modified: +// pages are mapped with `rewrites`, everything not published is excluded with `srcExclude`, +// and links are resolved in source space so they survive any URL mapping. +import fs from 'node:fs' +import path from 'node:path' +import { pathToFileURL } from 'node:url' +import type MarkdownIt from 'markdown-it' + +export interface OverlayOptions { + srcDir: string // absolute path of this site's srcDir + checkout: string // upstream checkout, relative to srcDir + mount: string // URL prefix on this site, e.g. 'openstack' + ref?: string // upstream ref used for blob links + routes?: Record // per-file overrides: upstream docs path -> path below mount + groupTitles?: Record // rename upstream sidebar groups +} + +interface Manifest { canonical: string; repository: string; publish: string[] } + +const globToRegExp = (g: string) => + new RegExp('^' + g.split('**').map(p => p.split('*').map(s => s.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*')).join('.*') + '$') + +function walk(dir: string, base = dir): string[] { + return fs.readdirSync(dir, { withFileTypes: true }).flatMap(e => { + const p = path.join(dir, e.name) + return e.isDirectory() ? walk(p, base) : [path.relative(base, p).split(path.sep).join('/')] + }) +} + +export function createOverlay(o: OverlayOptions) { + const root = path.join(o.srcDir, o.checkout) + const docs = path.join(root, 'docs') + const manifestFile = path.join(docs, '.vitepress', 'publish.json') + const present = fs.existsSync(manifestFile) + const manifest: Manifest = present + ? JSON.parse(fs.readFileSync(manifestFile, 'utf8')) + : { canonical: '', repository: '', publish: [] } + const ref = o.ref ?? 'main' + const published = manifest.publish.map(globToRegExp) + const isPublished = (rel: string) => published.some(r => r.test(rel)) + const prefix = `${o.checkout}/docs/` + + // upstream docs path (e.g. 'guides/x.md') -> site path (e.g. 'openstack/guides/x.md') + const route = (rel: string) => `${o.mount}/${o.routes?.[rel] ?? rel}` + + const srcExclude = present + ? walk(root).filter(f => f.endsWith('.md')) + .filter(f => !(f.startsWith('docs/') && isPublished(f.slice(5)))) + .map(f => `${o.checkout}/${f}`) + : [] + + const rewrites = (id: string) => (id.startsWith(prefix) ? route(id.slice(prefix.length)) : id) + + // Resolve a link target found in an upstream page to a URL on this site, the canonical + // upstream site (unpublished pages) or the upstream repository (files outside docs/). + function resolveHref(href: string, realPath: string): string | undefined { + if (/^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith('//') || href.startsWith('#')) return + const [p, hash = ''] = href.split(/(?=#)/) + const abs = p.startsWith('/') ? path.join(docs, p) : path.resolve(path.dirname(realPath), p) + const inDocs = path.relative(docs, abs) + if (inDocs.startsWith('..')) return `${manifest.repository}/blob/${ref}/${path.relative(root, abs)}${hash}` + let rel = inDocs.split(path.sep).join('/') + if (p.endsWith('/') || rel === '') rel = rel ? `${rel}/index.md` : 'index.md' + else if (rel.endsWith('.html')) rel = rel.slice(0, -5) + '.md' + else if (!path.extname(rel)) rel += '.md' + if (!rel.endsWith('.md')) return `${manifest.repository}/blob/${ref}/docs/${rel}` + if (isPublished(rel)) return `/${route(rel)}${hash}` + return manifest.canonical + rel.replace(/(^|\/)index\.md$/, '$1').replace(/\.md$/, '.html') + hash + } + + function markdown(md: MarkdownIt) { + md.core.ruler.push('upstream-links', state => { + const realPath: string | undefined = state.env?.realPath ?? state.env?.path + if (!realPath || !realPath.startsWith(docs + path.sep)) return + for (const t of state.tokens) { + for (const c of t.children ?? []) { + if (c.type !== 'link_open') continue + const href = c.attrGet('href') + const next = href && resolveHref(href, realPath) + if (next) c.attrSet('href', next) + } + } + }) + } + + // Upstream sidebar, reduced to published pages and mapped to site URLs. + async function sidebar(): Promise { + if (!present) return [] + const { default: raw } = await import(pathToFileURL(path.join(docs, '.vitepress', 'sidebar.ts')).href) + const map = (link: string) => { + let rel = link.replace(/^\//, '') + rel = rel === '' || rel.endsWith('/') ? `${rel}index.md` : `${rel}.md` + return isPublished(rel) ? `/${route(rel)}`.replace(/(^|\/)index\.md$/, '$1').replace(/\.md$/, '') : undefined + } + const prune = (item: any): any | undefined => { + const link = item.link ? map(item.link) : undefined + let items = item.items?.map(prune).filter(Boolean) + if (items && link && items.every((i: any) => i.link === link && !i.items)) items = undefined + if (!link && !items?.length) return + return { ...item, text: o.groupTitles?.[item.text] ?? item.text, link, items } + } + return raw.map(prune).filter(Boolean) + } + + return { present, manifest, srcExclude, rewrites, markdown, sidebar } +} diff --git a/docs/getting-started/full-deployment.md b/docs/getting-started/full-deployment.md index c5370d9..e61cec7 100644 --- a/docs/getting-started/full-deployment.md +++ b/docs/getting-started/full-deployment.md @@ -16,7 +16,8 @@ Follow the [Minimal Environment](/getting-started/minimal) guide first to unders ┌────────────────────────────────────────────────────────────────────┐ │ Management Plane Aurora · Greenhouse · Cortex │ ├────────────────────────────────────────────────────────────────────┤ -│ OpenStack Nova · Neutron · Cinder · Keystone · Glance │ +│ OpenStack Keystone · Horizon · Glance · Placement │ +│ Barbican · Nova · Neutron · Cinder · OVN │ │ (HA, multi-replica, RabbitMQ cluster) │ ├────────────────────────────────────────────────────────────────────┤ │ Observability Prysm · Prometheus · Perses │ @@ -71,12 +72,13 @@ Follow the [Minimal Environment](/getting-started/minimal) guide first to unders ### OpenStack layer -- [ ] All services deployed with HA configuration (multi-replica, clustered RabbitMQ/MariaDB) +- [ ] Control plane deployed from a `ControlPlane` resource with the `Standard` sizing profile (three replicas of each component) - see [Quick Start (ControlPlane)](/openstack/quick-start-controlplane) - [ ] Keystone identity configured - see [OpenStack - Keystone](/openstack/keystone) - [ ] Glance image service configured - see [OpenStack - Glance](/openstack/glance) - [ ] Nova compute service verified (create test VM) - see [OpenStack - Nova](/openstack/nova) - [ ] Neutron networking verified (create test network and port) - see [OpenStack - Neutron](/openstack/neutron) - [ ] Cinder block storage verified (create test volume) - see [OpenStack - Cinder](/openstack/cinder) +- [ ] Placement, Barbican and Horizon verified - see [OpenStack - Placement](/openstack/placement), [OpenStack - Barbican](/openstack/barbican) and [OpenStack - Horizon](/openstack/horizon) ### Observability layer diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index b47a74d..9fa86a9 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -30,3 +30,15 @@ Start here if you are deploying CobaltCore to run real workloads at scale. **What you get:** HA control plane, multiple hypervisor nodes, Ceph stretched cluster with Arbiter, full observability stack (Prysm, Prometheus, Perses), and the management frontend (Aurora, Greenhouse). **Prerequisites:** familiarity with Kubernetes operators and Helm, access to bare metal infrastructure managed by IronCore. + +--- + +### OpenStack control plane + +Start here if you want to run the CobaltCore OpenStack control plane on your workstation. + +→ [Quick Start (ControlPlane)](/openstack/quick-start-controlplane) + +**What you get:** a kind cluster on which one `ControlPlane` resource brings up Keystone, Horizon, Glance, Placement, Barbican, Neutron and Nova, from `git clone` to an authenticated Keystone API call. [The other quick starts](/openstack/) cover a standalone Keystone, bare metal with metal-stack, and ordering resources from a second cluster. + +**Prerequisites:** the toolchain of the [Quick Start](/openstack/quick-start) plus `make` and the OpenStack CLI, and a host with 4 CPU cores, 16 GB of memory and 10 GB of free disk. diff --git a/docs/getting-started/minimal.md b/docs/getting-started/minimal.md index c392420..8e8429d 100644 --- a/docs/getting-started/minimal.md +++ b/docs/getting-started/minimal.md @@ -15,7 +15,7 @@ This is not a production configuration - it has no high availability and no redu ``` ┌─────────────────────────────────┐ │ Control Plane Node │ -│ Kubernetes · OpenStack (Helm) │ +│ Kubernetes · OpenStack │ │ Ceph (single node) │ └──────────────┬──────────────────┘ │ @@ -179,16 +179,11 @@ for the production three-node cluster configuration. ## Step 5: Deploy OpenStack -OpenStack services are deployed via Helm. A minimal configuration enables Nova, Neutron, Cinder, Keystone, and Glance: +CobaltCore runs OpenStack with Kubernetes operators. One `ControlPlane` resource describes the control plane, the c5c3-operator creates a resource per service from it, and a service operator reconciles each of them. -```bash -helm install openstack cobaltcore/openstack \ - --namespace openstack \ - --create-namespace \ - --values minimal-values.yaml -``` +[Quick Start (ControlPlane)](/openstack/quick-start-controlplane) takes such a resource on a kind cluster from `git clone` to an authenticated Keystone API call. [Quick Start (metal-stack)](/openstack/quick-start-metal-stack) runs the same resource on a Gardener cluster on metal-stack and turns every worker into a KVM hypervisor. -See [OpenStack](/openstack/) for service-level configuration. +See [OpenStack](/openstack/) for the services and their guides. ## Step 6: Verify diff --git a/docs/networking/ovn.md b/docs/networking/ovn.md index 5909ebb..d1b9de2 100644 --- a/docs/networking/ovn.md +++ b/docs/networking/ovn.md @@ -62,5 +62,6 @@ With traditional OVS agents, each hypervisor node runs its own Neutron agent tha ## See also - [OpenStack - Neutron](/openstack/neutron) +- [OpenStack - OVN operator](/openstack/ovn) - [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/cinder.md b/docs/openstack/cinder.md deleted file mode 100644 index bd6e3ba..0000000 --- a/docs/openstack/cinder.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Cinder (Block Storage) -order: 30 -outline: deep ---- - -# Cinder (Block Storage) - -Cinder is the OpenStack block storage service. It manages volume lifecycle - creation, attachment, snapshots, and deletion - and connects VMs to persistent storage backends. - -## Architecture - -```mermaid -C4Deployment - Deployment_Node(cp, "Control Plane"){ - Deployment_Node(nova, "Nova Deployment", "Helm chart"){ - Container(novaapi, "Nova API", "deployment", "") - ContainerQueue(novamq, "RabbitMQ", "deployment", "") - Container(novacond, "Conductor", "deployment", "") - } - Deployment_Node(cinder, "Cinder", "Helm chart"){ - Container(cindervolume, "Volume Services", "deployment", "") - ContainerQueue(cindermq, "RabbitMQ", "deployment", "") - ContainerDb(cinderdb, "DB", "deployment", "") - Container(cinderapi, "Cinder API", "deployment", "") - } - } - Deployment_Node(cc, "Compute Cluster(s)"){ - Deployment_Node(node, "Hypervisor Node"){ - Deployment_Node(kubelet, "Kubernetes managed", ""){ - Container(computeagent, "Nova Compute Agent", "daemonset") - } - Container_Boundary(systemd, "systemd managed", "Delivered in Image"){ - Container_Ext(libvirtd, "libvirtd", "unit") - Container_Ext(vm, "VM", "unit") - Container_Ext(mount, "Share", "mount") - } - } - } - Deployment_Node(ext, "Infrastructure"){ - System_Ext(netapp, "Filer (NetApp)") - } - Rel(novaapi, novamq, "", "AMQP") - BiRel(novamq, computeagent, "", "AMQP") - BiRel(novamq, novacond, "", "AMQP") - Rel(computeagent, libvirtd, "Instructs", "UNIX") - Rel(libvirtd, vm, "Manages") - Rel(cinderapi, cindermq, "", "AMQP") - BiRel(cindermq, cindervolume, "", "AMQP") - Rel(cinderapi, cinderdb, "", "MYSQL") - Rel(cindervolume, cinderdb, "", "MYSQL") - Rel(cindervolume, netapp, "Manages", "REST") - Rel(cindervolume, novaapi, "Calls", "REST") - Rel(computeagent, mount, "Mounts") - Rel(computeagent, cinderapi, "Calls") - Rel(mount, netapp, "Accesses", "NFS") - UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1") -``` - -## Storage backend - -In CobaltCore's reference configuration, Cinder uses a **NetApp filer** as the storage backend. Volumes are delivered as NFS mounts to compute nodes. The Cinder Volume Service manages volume lifecycle via the NetApp REST API. - -For environments without a NetApp filer, Ceph RBD is a supported alternative backend - volumes are attached directly to VMs using the `librbd` driver. - -## See also - -- [Storage - Ceph](/storage/ceph) (for RBD backend) -- [OpenStack Cinder docs](https://docs.openstack.org/cinder/latest/) diff --git a/docs/openstack/glance.md b/docs/openstack/glance.md deleted file mode 100644 index 75d7f92..0000000 --- a/docs/openstack/glance.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Glance (Image) -order: 50 ---- - -# Glance (Image) - -Glance is the OpenStack image service. It stores and distributes VM images that Nova uses when creating virtual machines. - -## Role in CobaltCore - -When a user requests a new VM, Nova asks Glance for the image. Glance retrieves it from its backend store and streams it to the compute node (or serves it via a URL that the hypervisor can fetch directly). - -## Key concepts - -| Concept | Description | -|---|---| -| **Image** | A VM disk image in a format Nova can boot (qcow2, raw, ISO) | -| **Image store** | The backend where image data is persisted (Ceph RBD or Swift) | -| **Image metadata** | Properties attached to an image (minimum RAM, disk size, OS type, architecture) | - -## Backend - -In CobaltCore, Glance typically uses **Ceph RBD** as its image store. Images uploaded to Glance are stored as RBD objects, and Nova can use copy-on-write cloning to provision VM disks from Glance images without copying data. - -## Deployment - -Glance is deployed via Helm as part of the OpenStack chart set. - -::: info -Detailed configuration documentation (image import workflows, image signing, multi-store configuration) is being added. See the [OpenStack Glance docs](https://docs.openstack.org/glance/latest/) in the meantime. -::: diff --git a/docs/openstack/index.md b/docs/openstack/index.md deleted file mode 100644 index bf2cbea..0000000 --- a/docs/openstack/index.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: OpenStack -order: 1 -outline: deep ---- - -# OpenStack - -OpenStack is the cloud services layer in CobaltCore. It provides the compute, networking, block storage, identity, and image APIs that users and automation tools interact with. CobaltCore deploys OpenStack via Helm charts, with each service configured to integrate with the underlying compute, storage, and networking layers. - -## Services - -| Service | API | Role | -|---|---|---| -| [Nova](/openstack/nova) | Compute | VM lifecycle, scheduling, live migration | -| [Neutron](/openstack/neutron) | Networking | Virtual networks, ports, security groups via OVN | -| [Cinder](/openstack/cinder) | Block Storage | Volume management backed by NetApp/NFS or Ceph RBD | -| [Keystone](/openstack/keystone) | Identity | Authentication and service catalog | -| [Glance](/openstack/glance) | Image | VM image storage and distribution | - -## Deployment model - -All services are deployed as Kubernetes workloads via Helm into a dedicated namespace. Each service runs with its own MariaDB database and connects to a shared RabbitMQ cluster for async messaging. - -``` -Control Plane Cluster -├── openstack namespace -│ ├── nova (API, Conductor, Scheduler) -│ ├── neutron (API, OVN-NB, OVN-SB, OVN-NorthD) -│ ├── cinder (API, Volume Services) -│ ├── keystone -│ └── glance -│ -Compute Clusters -└── Per node (daemonsets) - ├── nova-compute-agent - ├── ovn-controller - └── (hypervisor agents - see Compute layer) -``` - -## 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 [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. - -**Cells architecture:** Nova's multi-cell architecture is available but simplified in CobaltCore's default configuration. See the [Nova cells documentation](https://docs.openstack.org/nova/latest/admin/cells.html) for production cell design. diff --git a/docs/openstack/keystone.md b/docs/openstack/keystone.md deleted file mode 100644 index 44c7a4a..0000000 --- a/docs/openstack/keystone.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Keystone (Identity) -order: 40 ---- - -# Keystone (Identity) - -Keystone is the OpenStack identity service. It authenticates users and services, and provides the service catalog that clients use to discover API endpoints. - -## Role in CobaltCore - -All OpenStack services (Nova, Neutron, Cinder, Glance) authenticate requests through Keystone. Users, service accounts, and automation tools obtain tokens from Keystone before calling any OpenStack API. - -## Key concepts - -| Concept | Description | -|---|---| -| **Domain** | Top-level grouping of users and projects | -| **Project** | A tenant - the unit of resource ownership and quota enforcement | -| **User** | An identity that can authenticate and receive tokens | -| **Role** | A set of permissions assigned to a user within a project | -| **Service catalog** | The list of services and their endpoint URLs, returned with each token | - -## Deployment - -Keystone is deployed via Helm as part of the OpenStack chart set. It uses a MariaDB database for its identity store. - -::: info -Detailed configuration documentation (LDAP integration, federation, domain configuration) is being added. See the [OpenStack Keystone docs](https://docs.openstack.org/keystone/latest/) in the meantime. -::: diff --git a/docs/openstack/neutron.md b/docs/openstack/neutron.md deleted file mode 100644 index 84cc8ca..0000000 --- a/docs/openstack/neutron.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Neutron (Networking) -order: 20 -outline: deep ---- - -# Neutron (Networking) - -Neutron is the OpenStack networking service. In CobaltCore, Neutron uses OVN (Open Virtual Network) as its backend, providing virtual networks, ports, routers, and security groups for VMs. - -## Architecture - -```mermaid -C4Deployment - Deployment_Node(cp, "Control Plane"){ - Deployment_Node(neutron, "Neutron Deployment", "Helm chart"){ - Container(neutronapi, "Neutron API", "deployment", "") - ContainerDb(neutrondb, "DB", "deployment", "") - Container(ovnnb, "OVN-NB", "statefulset", "") - ContainerQueue(neutronmq, "RabbitMQ", "deployment", "") - Container(ovnsb, "OVN-SB", "statefulset", "") - Container(ovnnorthd, "OVN-NorthD", "statefulset", "") - } - } - Deployment_Node(cc, "Compute Cluster(s)"){ - Deployment_Node(node, "Hypervisor Node"){ - Deployment_Node(kubelet, "Kubernetes managed", ""){ - Container(ovncontroller, "OVN Controller", "daemonset") - } - Container_Boundary(systemd, "systemd managed", "Delivered in Image"){ - Container_Ext(vm, "VM", "unit") - Container_Ext(vmnic, "Interface", "Interface") - Container_Ext(ovs, "OVS", "unit") - } - } - } - BiRel(neutronapi, neutronmq, "AMQP") - Rel(neutronapi, neutrondb, "", "MYSQL") - Rel(neutronapi, ovnnb, "Configures", "OVS-DB") - Rel(ovnnorthd, ovnnb, "Reads", "OVS-DB") - Rel(ovnnorthd, ovnsb, "Translates", "OVS-DB") - Rel(ovnsb, ovncontroller, "Reads", "OVS-DB") - Rel(ovncontroller, ovs, "Translates", "OVS-DB") - Rel(vm, vmnic, "Uses") - Rel(ovncontroller, vmnic, "Creates") - Rel(ovs, vmnic, "Manages") - UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1") -``` - -## OVN data plane - -OVN replaces Neutron's traditional agent-per-node model: - -| Component | Role | -|---|---| -| **OVN-NB (Northbound DB)** | High-level logical network state written by Neutron API | -| **OVN-NorthD** | Translates logical network state into low-level flow rules in OVN-SB | -| **OVN-SB (Southbound DB)** | Physical network state and flow rules consumed by OVN Controllers | -| **OVN Controller** | Runs on each compute node; translates SB flows into OVS rules | -| **OVS** | Open vSwitch - the kernel datapath that forwards VM traffic | - -## See also - -- [OpenStack Network Integration](/network/openstack-integration) -- [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 deleted file mode 100644 index eeb0cbc..0000000 --- a/docs/openstack/nova.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Nova (Compute) -order: 10 -outline: deep ---- - -# Nova (Compute) - -Nova is the OpenStack compute service. It handles VM lifecycle - scheduling, spawning, live migration, and evacuation - across the hypervisor nodes. - -## Architecture - -```mermaid -C4Deployment - Deployment_Node(cp, "Control Plane"){ - Deployment_Node(nova, "Nova Deployment", "Helm chart"){ - Container(novaapi, "API", "deployment", "") - ContainerDb(novadb, "DBs", "deployment", "") - ContainerQueue(novamq, "RabbitMQ", "deployment", "") - Container(novacond, "Conductor", "deployment", "") - } - } - Deployment_Node(cc, "Compute Cluster(s)"){ - Deployment_Node(node, "Hypervisor Node"){ - Deployment_Node(kubelet, "Kubernetes managed", ""){ - Container(computeagent, "Nova Compute Agent", "daemonset") - } - Container_Boundary(systemd, "systemd managed", "Delivered in Image"){ - Container_Ext(libvirtd, "libvirtd", "unit") - Container_Ext(vm, "VM", "unit") - } - } - } - Rel(novaapi, novamq, "", "AMQP") - BiRel(novamq, computeagent, "", "AMQP") - BiRel(novamq, novacond, "", "AMQP") - Rel(computeagent, libvirtd, "Instructs", "UNIX") - Rel(novaapi, novadb, "", "MYSQL") - Rel(novacond, novadb, "", "MYSQL") - Rel(libvirtd, vm, "Manages") - UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1") -``` - -## Components - -| Component | Role | -|---|---| -| **Nova API** | REST API for VM operations; accepts requests from users and Cinder | -| **Nova Conductor** | Mediates database access from compute agents; handles complex workflows like live migration | -| **Nova Compute Agent** | Runs on each hypervisor node as a daemonset; instructs libvirtd to create/delete/migrate VMs | -| **RabbitMQ** | Async messaging between API, Conductor, and Compute Agents | - -## Integration with CobaltCore compute - -Nova Compute Agents run as Kubernetes daemonsets on hypervisor nodes managed by the [Hypervisor Operator](/compute/hypervisor). When the Hypervisor Operator registers a new node, it also registers the node's compute capacity with Nova. - -The [HA Service](/compute/ha-service) calls Nova's host evacuation API when a hypervisor fails. - -Cortex integrates with Nova's placement API to make intelligent scheduling decisions based on cluster state. - -## See also - -- [Compute - Hypervisor](/compute/hypervisor) -- [Compute - HA Service](/compute/ha-service) -- [OpenStack Nova docs](https://docs.openstack.org/nova/latest/) diff --git a/docs/operations/platform/bootstrap.md b/docs/operations/platform/bootstrap.md index b21f9e8..084a222 100644 --- a/docs/operations/platform/bootstrap.md +++ b/docs/operations/platform/bootstrap.md @@ -42,7 +42,7 @@ Once the cluster is running, CobaltCore components are installed in order: 1. Rook and Ceph (storage must be ready before OpenStack services that need volumes) 2. OVN (networking must be ready before Nova and Neutron) 3. Hypervisor Operator -4. OpenStack (Nova, Neutron, Cinder, Keystone, Glance via Helm) +4. OpenStack: the CobaltCore operators and a `ControlPlane` resource (see [OpenStack](/openstack/)) 5. Observability stack (Prysm, Prometheus, Perses) 6. Management layer (Greenhouse, Aurora, Cortex) diff --git a/docs/overview/architecture.md b/docs/overview/architecture.md index 160e8c5..094f163 100644 --- a/docs/overview/architecture.md +++ b/docs/overview/architecture.md @@ -10,8 +10,9 @@ outline: deep ┌──────────────────────────────────────────────────────────┐ │ Management Aurora · Greenhouse · Cortex │ ├──────────────────────────────────────────────────────────┤ -│ OpenStack Nova · Neutron · Cinder · Keystone │ -│ Glance │ +│ OpenStack Keystone · Horizon · Glance │ +│ Placement · Barbican · Nova │ +│ Neutron · Cinder · OVN │ ├──────────────────────────────────────────────────────────┤ │ Compute KVM Hypervisor · HA Service · GPU │ │ Storage Ceph · Rook · Arbiter · Chorus │ diff --git a/hack/sync-cobaltcore.sh b/hack/sync-cobaltcore.sh new file mode 100755 index 0000000..9249327 --- /dev/null +++ b/hack/sync-cobaltcore.sh @@ -0,0 +1,56 @@ +#!/usr/bin/env bash + +# Puts the documentation of C5C3/cobaltcore into docs/_upstream/cobaltcore, where +# docs/.vitepress/overlay.ts mounts it under /openstack/. npm runs this script +# before `docs:dev` and `docs:build`, and `npm run docs:sync` runs it on its own. +# +# - Without a checkout, it clones C5C3/cobaltcore (branch COBALTCORE_REF, default +# main) sparsely: docs/ for the pages, tests/ and deploy/ for the files the +# pages import. +# - An existing checkout is left alone. The CI workflow of this repository and +# the docs-overlay job of C5C3/cobaltcore put one there before the build. +# Delete the directory to fetch a fresh copy. +# - With COBALTCORE_SRC set to a C5C3/cobaltcore checkout, it copies docs/, +# tests/ and deploy/ from there instead, to preview local changes. +set -euo pipefail + +root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +target="$root/docs/_upstream/cobaltcore" +ref="${COBALTCORE_REF:-main}" + +if [[ -n "${COBALTCORE_SRC:-}" ]]; then + if ! command -v rsync >/dev/null; then + echo "sync-cobaltcore: copying from COBALTCORE_SRC needs rsync" >&2 + exit 1 + fi + for dir in docs tests deploy; do + if [[ ! -d "$COBALTCORE_SRC/$dir" ]]; then + echo "sync-cobaltcore: $COBALTCORE_SRC/$dir does not exist" >&2 + exit 1 + fi + done + mkdir -p "$target" + rsync -a --delete --exclude .vitepress/cache --exclude .vitepress/dist \ + "$COBALTCORE_SRC/docs" "$COBALTCORE_SRC/tests" "$COBALTCORE_SRC/deploy" "$target/" + echo "sync-cobaltcore: copied docs/, tests/ and deploy/ from $COBALTCORE_SRC" + exit 0 +fi + +if [[ -f "$target/docs/.vitepress/publish.json" ]]; then + echo "sync-cobaltcore: using $target (delete it to fetch a fresh copy)" + exit 0 +fi +if [[ -e "$target" ]]; then + echo "sync-cobaltcore: $target holds no docs/.vitepress/publish.json; delete it and run npm run docs:sync" >&2 + exit 1 +fi + +if ! command -v git >/dev/null; then + echo "sync-cobaltcore: cloning C5C3/cobaltcore needs git" >&2 + exit 1 +fi +mkdir -p "$(dirname "$target")" +git clone --quiet --depth 1 --filter=blob:none --sparse --branch "$ref" \ + https://github.com/C5C3/cobaltcore.git "$target" +git -C "$target" sparse-checkout set docs tests deploy +echo "sync-cobaltcore: cloned C5C3/cobaltcore ($ref) into $target" diff --git a/package.json b/package.json index 8c1fe8f..f220cdc 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,10 @@ "mermaid": "^10" }, "scripts": { + "docs:sync": "bash hack/sync-cobaltcore.sh", + "predocs:dev": "bash hack/sync-cobaltcore.sh", "docs:dev": "vitepress dev docs", + "predocs:build": "bash hack/sync-cobaltcore.sh", "docs:build": "vitepress build docs", "docs:preview": "vitepress preview docs", "docs:clean": "rm -rf docs/.vitepress/cache docs/.vitepress/dist",