From 86bf7fe5170f6005f2317e12a9a7a61bba70b60d Mon Sep 17 00:00:00 2001 From: braghettos Date: Thu, 11 Jun 2026 20:24:38 +0200 Subject: [PATCH] docs: add umbrella -> kagent quickstart A happy-path quickstart modeled on the ironic-kog quickstart: prerequisites (cert-manager + core-provider) -> register the umbrella CompositionDefinition -> deploy one Openstack Composition (profile/enabled, self-bootstrap watch) -> reconfigure a component via spec.componentValues -> verify -> optionally install the openstack-blueprint-expert kagent SME (Vertex or the chart's default provider). Linked from the README Quickstarts section. Block-style YAML only. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 3 + docs/quickstart.md | 188 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 191 insertions(+) create mode 100644 docs/quickstart.md diff --git a/README.md b/README.md index f036ca1..01c88a6 100644 --- a/README.md +++ b/README.md @@ -184,6 +184,9 @@ kubectl -n openstack run osclient --rm -it --restart=Never \ ## Quickstarts +- [`docs/quickstart.md`](docs/quickstart.md) — the happy path: deploy the umbrella `Openstack` + Composition, reconfigure a component via `spec.componentValues`, then (optionally) install the + [`openstack-blueprint-expert`](kagent) kagent SME. - [`quickstart-kind.md`](quickstart-kind.md) — identity plane on a local kind cluster (Apple Silicon supported via amd64 image pre-loading). - [`quickstart-gke.md`](quickstart-gke.md) — disposable GKE cluster with the compute plane diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..9af6a4a --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,188 @@ +# Quickstart — deploy the umbrella, then install the kagent SME + +Stand up a whole OpenStack install from **one** `Openstack` Composition (the +orchestrator rolls the components out in dependency order), then optionally add +the [`openstack-blueprint-expert`](../kagent) kagent agent so an LLM can read +and drive it. + +For cluster-specific notes (image pre-loading, compute on QEMU, Horizon over a +LoadBalancer, teardown) see [`quickstart-kind.md`](../quickstart-kind.md) and +[`quickstart-gke.md`](../quickstart-gke.md). This page is the happy path: +**umbrella up → kagent.** + +## Prerequisites + +A Kubernetes cluster with `kubectl` access plus Helm 3 and Krateo's +`core-provider`. The identity plane runs on kind (Apple Silicon supported); +the compute and bare-metal planes need an amd64 cluster — see the GKE +quickstart. + +```sh +helm repo add jetstack https://charts.jetstack.io +helm repo add krateo https://charts.krateo.io +helm repo update + +helm upgrade --install cert-manager jetstack/cert-manager -n cert-manager \ + --create-namespace --set crds.enabled=true --wait + +helm upgrade --install core-provider krateo/core-provider \ + --version 1.0.0 -n krateo-system --create-namespace --wait +``` + +## 1. Register the orchestrator blueprint + +Only the umbrella `CompositionDefinition` is registered by hand — it registers +each component blueprint itself. + +```sh +kubectl create namespace openstack-system +kubectl apply -f blueprints/openstack/compositiondefinition.yaml +kubectl wait compositiondefinition/openstack -n openstack-system \ + --for=condition=Ready --timeout=180s +``` + +`core-provider` pulls `oci://ghcr.io/braghettos/charts/openstack:0.2.0`, +generates the `Openstack` CRD (`composition.krateo.io/v0-2-0`) and its +controller. + +## 2. Deploy one OpenStack install + +One `Openstack` Composition = one install. Pick the scope with `spec`: + +- `profile: identity` — MariaDB + Memcached + Keystone + Glance + Horizon. +- `profile: full` — the whole 34-component catalog (needs a large amd64 + cluster). +- `spec.enabled` — an explicit component list that overrides `profile` and is + expanded to its **transitive dependency closure**, so you get exactly what + you ask for plus what it needs. + +```sh +kubectl create namespace openstack +kubectl apply -f examples/openstack.yaml # spec.profile: identity +``` + +Or deploy a precise subset — e.g. just Heat and everything it depends on: + +```sh +kubectl apply -f - <<'EOF' +apiVersion: composition.krateo.io/v0-2-0 +kind: Openstack +metadata: + name: openstack + namespace: openstack +spec: + enabled: + - heat # -> heat + keystone + rabbitmq + mariadb + memcached +EOF +``` + +The umbrella self-bootstraps: on the first reconcile only zero-dependency +components render; each later pass unlocks the next tier once its dependency +Compositions report `Ready=True`. Watch it converge: + +```sh +kubectl get openstack openstack -n openstack -o \ + jsonpath='{.status.conditions}' ; echo +kubectl get compositions.composition.krateo.io -n openstack +helm list -n openstack # per-component releases appear in dep order +``` + +To **reconfigure** a component without touching its Composition, patch the +`Openstack` CR's `spec.componentValues.` (strictly typed — every +component's own `values.schema.json` is merged into the umbrella CRD). For +example, scale keystone-api to 2 replicas: + +```sh +kubectl patch openstack openstack -n openstack --type merge -p ' +spec: + componentValues: + keystone: + pod: + replicas: + api: 2 +' +``` + +The umbrella re-renders keystone's Composition and the composition-dynamic- +controller reconciles it — `keystone-api` scales 1 -> 2 live. + +## 3. Verify + +```sh +kubectl -n openstack run osclient --rm -it --restart=Never \ + --image=quay.io/airshipit/openstack-client:2025.1-ubuntu_jammy \ + --env OS_AUTH_URL=http://keystone-api.openstack.svc.cluster.local:5000/v3 \ + --env OS_USERNAME=admin --env OS_PASSWORD=password --env OS_PROJECT_NAME=admin \ + --env OS_USER_DOMAIN_NAME=Default --env OS_PROJECT_DOMAIN_NAME=Default \ + --env OS_IDENTITY_API_VERSION=3 --env OS_REGION_NAME=RegionOne --env OS_INTERFACE=internal \ + --command -- openstack token issue +``` + +For the compute plane (`profile: full` on GKE) also try `compute service +list`, `hypervisor list`, `network agent list`, and log in to Horizon as +`admin` / `password` (domain `Default`). See [`quickstart-gke.md`](../quickstart-gke.md). + +## 4. (Optional) Install the kagent SME + +[`kagent/openstack-blueprint-expert`](../kagent) is a [kagent](https://kagent.dev) +Agent CRD that turns an LLM into a subject-matter expert on this blueprint — it +reads the live `Openstack` / `Composition` / `CompositionDefinition` objects, +explains the two-pass engine, and can patch `spec.componentValues` to +(re)configure a component (with confirmation). + +```sh +kubectl create ns kagent --dry-run=client -o yaml | kubectl apply -f - + +helm upgrade --install kagent-crds \ + oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \ + --version 0.9.6 --namespace kagent --wait --timeout 5m + +helm upgrade --install kagent \ + oci://ghcr.io/kagent-dev/kagent/helm/kagent \ + --version 0.9.6 --namespace kagent \ + --set providers.default=anthropic \ + --set providers.anthropic.model=claude-sonnet-4-6 \ + --timeout 10m +``` + +The agent ships referencing a `GeminiVertexAI` ModelConfig named +`vertex-gemini`. Either create that (one-time GCP prep + `kagent-vertex` +secret, see [`kagent/README.md`](../kagent/README.md)) and apply both files, or +point the agent at the chart's auto-created `default-model-config` for whatever +provider you set above: + +```sh +# Option A — Vertex Gemini (what the repo ships) +kubectl -n kagent create secret generic kagent-vertex \ + --from-file=key.json=$HOME/Downloads/.json +$EDITOR kagent/modelconfig-vertex-gemini.yaml # set projectID + location +kubectl apply -f kagent/modelconfig-vertex-gemini.yaml +kubectl apply -f kagent/agent-openstack-expert.yaml + +# Option B — reuse the provider you installed kagent with +sed 's/modelConfig: vertex-gemini/modelConfig: default-model-config/' \ + kagent/agent-openstack-expert.yaml | kubectl apply -f - +``` + +```sh +kubectl -n kagent get agent openstack-blueprint-expert +``` + +Open the kagent UI (or its A2A endpoint) and ask one of the skill examples: + +- "How does the Openstack umbrella roll out components in dependency order?" +- "How do I deploy just heat and its dependencies via the umbrella?" +- "How do I scale keystone to 2 replicas without touching its Composition?" +- "My Openstack Composition is Synced=False with a lookup error." +- "Is the umbrella values.yaml equal to kolla's globals.yml?" + +The agent reads before it acts, configures components by patching the +`Openstack` CR (never `helm_upgrade` on a CDC-owned release), and walks you +through GC ordering before any `CompositionDefinition` delete. See +[`kagent/README.md`](../kagent/README.md) for what it will and won't do. + +## Next steps + +- [`README.md`](../README.md) — the per-component + umbrella architecture. +- [`quickstart-kind.md`](../quickstart-kind.md) / [`quickstart-gke.md`](../quickstart-gke.md) — cluster-specific recipes. +- [`docs/kolla-ansible-audit-and-helm-plan.md`](kolla-ansible-audit-and-helm-plan.md) — the kolla-ansible comparison the kagent SME quotes.