From bccc941e3bbcb9a6df662a9b97aaad181c4db5b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Jeanneret?= Date: Tue, 16 Jun 2026 17:11:46 +0200 Subject: [PATCH] docs(skills): add skill for creating controlplane service components Add a new skill document that provides step-by-step instructions for adding OpenStack service components to the controlplane catalog. This codifies the implicit pattern shown in the watcher service example and ensures consistency across future service additions. The skill covers: - Directory structure and file scaffolding - Kustomization component configuration - OpenStackControlPlane CR patch templates - YAML conventions and validation steps - References to existing examples and documentation Updated AGENTS.md to include a new "Skills" section linking to the skill document, making it discoverable for both human contributors and AI agents. AI-Tool: Claude Code AI-Model: Claude Sonnet 4.5 (2025-09-29) --- AGENTS.md | 4 + docs/skills/add-controlplane-service.md | 116 ++++++++++++++++++++++++ 2 files changed, 120 insertions(+) create mode 100644 docs/skills/add-controlplane-service.md diff --git a/AGENTS.md b/AGENTS.md index 3b7764d..cb2dc88 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,4 +17,8 @@ This document describes how AI agents should work with this repository. The goal - **Releases, tags, and `?ref=`** → [docs/agents/releases.md](docs/agents/releases.md) - **Branches, PRs, commits, expectations for changes** → [CONTRIBUTING.md](CONTRIBUTING.md) +**Skills (repeatable tasks)** + +- **Adding a new controlplane service component** → [docs/skills/add-controlplane-service.md](docs/skills/add-controlplane-service.md) + **Domain context (operators and consumers):** the root [README.md](README.md) documents RHOSO deployment, ArgoCD conventions (e.g. sync-waves, pinned `?ref=`), and how applications are sliced—it does not define repository editing policy. Use the links above for how to change this repository. \ No newline at end of file diff --git a/docs/skills/add-controlplane-service.md b/docs/skills/add-controlplane-service.md new file mode 100644 index 0000000..2301581 --- /dev/null +++ b/docs/skills/add-controlplane-service.md @@ -0,0 +1,116 @@ +# Add Controlplane Service Component + +This skill creates a new service component for the OpenStack controlplane. + +## Purpose + +Scaffolds the directory structure and boilerplate files needed to add a new OpenStack service to the controlplane components catalog. + +## Usage + +When an AI agent or contributor needs to add a new service component to `/components/rhoso/controlplane/services/`, use this skill to ensure consistency with the repository's patterns. + +## Prerequisites + +- Service name (kebab-case, e.g., `barbican`, `designate`, `octavia`) +- Understanding of the service's configuration requirements +- Red Hat OpenStack Services on OpenShift documentation link for the service (if available) + +## Steps + +### 1. Create Service Directory + +```bash +SERVICE_NAME="" # e.g., barbican, designate, octavia +mkdir -p components/rhoso/controlplane/services/${SERVICE_NAME} +``` + +### 2. Create `kustomization.yaml` + +Create `components/rhoso/controlplane/services/${SERVICE_NAME}/kustomization.yaml`: + +```yaml +--- +apiVersion: kustomize.config.k8s.io/v1alpha1 +kind: Component + +patches: + - path: service.yaml + target: + kind: OpenStackControlPlane +``` + +### 3. Create `service.yaml` + +Create `components/rhoso/controlplane/services/${SERVICE_NAME}/service.yaml`: + +```yaml +--- +# https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html-single/... +# TODO: Replace with actual documentation link for this service +apiVersion: core.openstack.org/v1beta1 +kind: OpenStackControlPlane +metadata: + name: openstack-control-plane +spec: + : + enabled: true + template: + # Service-specific configuration goes here + # Refer to the OpenStackControlPlane CRD and service operator documentation +``` + +**Important:** +- Replace `` with the actual service name in camelCase (e.g., `barbican`, `octavia`, `designate`) +- Replace the documentation URL with the actual Red Hat documentation link +- Add service-specific template configuration based on the service operator's CRD + +### 4. Validate the Component + +Run kustomize build to ensure the component is valid: + +```bash +kustomize build components/rhoso/controlplane/services/${SERVICE_NAME} +``` + +### 5. Add to Examples (Optional but Recommended) + +Consider adding an example that uses this service component in `/example` to demonstrate usage. + +### 6. Run CI Validation + +Before committing, run the validation commands from `.github/workflows/` to ensure the component passes CI checks: + +```bash +# Check the .github/workflows/ directory for exact validation commands +# Typically includes: +# - YAML linting +# - Kustomize build tests +``` + +## YAML Conventions + +Ensure all files follow repository conventions: + +- **Document header:** Every YAML file must start with `---` (comments may appear above it) +- **Documentation links:** Include Red Hat documentation URLs in comments +- **Indentation:** Use 2 spaces (consistent with existing files) +- **One object per file:** Unless the pattern clearly uses multi-document files + +## Reference Example + +See `/components/rhoso/controlplane/services/watcher/` for a complete working example. + +## Related Documentation + +- [Repository structure](../agents/repository.md) +- [YAML, Helm, and Kustomize conventions](../agents/yaml-helm-kustomize.md) +- [CI and validation](../agents/ci-and-validation.md) +- [OpenStackControlPlane CR reference](https://docs.redhat.com/en/documentation/red_hat_openstack_services_on_openshift/18.0/html/deploying_red_hat_openstack_services_on_openshift/assembly_creating-the-control-plane#ref_example-OpenStackControlPlane-CR_controlplane) + +## Notes for AI Agents + +- This is a **component catalog**, not a full cluster configuration +- Prefer conservative, backwards-compatible changes +- Do not open PRs without explicit human request +- Follow Conventional Commits with `AI-Tool` / `AI-Model` footers when contributing