Skip to content
Draft
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
1 change: 1 addition & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,4 @@
node_modules
docs/.vitepress/dist
docs/.vitepress/cache
docs/_upstream
16 changes: 16 additions & 0 deletions .github/workflows/static.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -3,3 +3,4 @@ docs/.vitepress/dist
docs/.vitepress/cache
bin
build
docs/_upstream/
6 changes: 5 additions & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
@@ -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"]
CMD ["npm", "run", "docs:dev", "--", "--host=0.0.0.0"]
24 changes: 23 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
56 changes: 36 additions & 20 deletions docs/.vitepress/config.mts
Original file line number Diff line number Diff line change
@@ -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([{
Expand Down Expand Up @@ -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/' }],
},
],
};
}

Expand Down Expand Up @@ -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/' }],
Expand Down Expand Up @@ -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'
},

Expand Down Expand Up @@ -311,7 +327,7 @@ export default withMermaid({
]),
...storageSidebar(),
...networkSidebar(),
...openstackSidebar(),
...(await openstackSidebar()),
...overviewSidebar(),
...operationsSidebar(),
...governanceSidebar(),
Expand Down
107 changes: 107 additions & 0 deletions docs/.vitepress/overlay.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
// Build-time overlay of an upstream repository's VitePress docs into this site.
// The upstream checkout lives in docs/_upstream/<name> (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<string, string> // per-file overrides: upstream docs path -> path below mount
groupTitles?: Record<string, string> // 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<any[]> {
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 }
}
6 changes: 4 additions & 2 deletions docs/getting-started/full-deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 β”‚
Expand Down Expand Up @@ -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

Expand Down
12 changes: 12 additions & 0 deletions docs/getting-started/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
13 changes: 4 additions & 9 deletions docs/getting-started/minimal.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
β”‚
Expand Down Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions docs/networking/ovn.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Loading