| name | canvas-ops-tutorial |
| description | Interactive tutorial for learning and exploring the ODA Canvas on Kubernetes. Guides users through architecture concepts, CRD schemas, component deployment, API inspection, dependency resolution, observability, and BDD testing via context-aware menus. Use when a user wants to understand, explore, or operate an ODA Canvas cluster. |
ODA Canvas Kubernetes Tutorial
An interactive, guided tutorial for learning and operating the ODA Canvas on Kubernetes. Present the main menu below as a numbered list and let the user choose an action by number.
| # | Action | Reference |
|---|
| 1 | About ODA Canvas — Learn the architecture, CRDs, operators, and how components are decomposed | references/01-about-oda-canvas.md |
| 2 | Install ODA Canvas — Check prerequisites, choose a gateway (Istio/Kong/APISIX), and install or troubleshoot a Canvas | references/02-install-oda-canvas.md |
| 3 | Manage ODA Components — Deploy, view, and inspect Component custom resources | references/03-deploy-component.md, references/04-view-components.md |
| 4 | View APIs — Inspect ExposedAPI and DependentAPI custom resources and their status | references/05-view-exposedapis.md, references/06-view-dependentapis.md |
| 5 | View Observability Data — Access Prometheus, Grafana, and Jaeger UIs | references/07-view-observability.md |
| 6 | Manage Identities — View IdentityConfig resources, access Keycloak UI, and create external clients for API access | references/08-manage-identities.md |
| 7 | Run BDD Feature Tests — Execute Behaviour-Driven Design test scenarios | references/09-run-bdd-tests.md |
Read the corresponding reference file(s) before executing the user's chosen action. For consolidated items (3 and 4), present a numbered sub-menu so the user can pick the specific action by number (e.g., deploy vs. view components, or ExposedAPIs vs. DependentAPIs), then read the relevant reference file.
Tutorial Interaction Rules
Follow these rules throughout every interaction:
Menu Presentation
- On activation:
Check that kubernetes is installed and configured correctly by running
kubectl cluster-info. If this fails, inform the user that a valid kubeconfig and cluster connection are required to proceed with the tutorial.
Check if the ODA Canvas is installed by running kubectl get ns components and kubectl get crds | grep oda. If not installed, inform the user and direct them to option 2 to install the Canvas before proceeding with other actions.
Present the 7-item main menu above as a numbered list so the user can pick by number.
- After every action: Present a contextual sub-menu of 4–6 suggested next steps relevant to what was just done, as a numbered list with "Return to main menu" always as the last option.
- On "Return to main menu": Re-present the full 7-item main menu.
Educational Explanations
- After running any command or showing any output, explain what the output means in the context of the ODA Canvas architecture: what the resources are, which operator manages them, and how they fit into the component lifecycle.
- Show CRD schema context when relevant — use one or more of the three CRD sources described below to show users the actual resource structure.
- Show the reproducible commands — always display the
kubectl or helm commands used, formatted as copyable code blocks, so the user can repeat them independently.
CRD Education — Three Sources
When explaining resource structures, reference these sources:
| Source | When to use | How |
|---|
| Live cluster | Interactive exploration | kubectl explain component.spec, kubectl get crd <name> -o yaml |
| CRD Helm templates | Show authoritative schema | Read from charts/oda-crds/templates/ — see file table below |
| Example components | Show concrete YAML | Read from feature-definition-and-test-kit/testData/ — see directory table below |
CRD template files (in charts/oda-crds/templates/):
| File | Resource | v1 schema location |
|---|
oda-component-crd.yaml | Component | ~line 1858 |
oda-exposedapi-crd.yaml | ExposedAPI | ~line 337 |
oda-dependentapi-crd.yaml | DependentAPI | ~line 176 |
oda-identityconfig-crd.yaml | IdentityConfig | ~line 66 |
oda-secretsmanagement-crd.yaml | SecretsManagement | ~line 150 |
oda-publishednotification-crd.yaml | PublishedNotification | ~line 231 |
oda-subscribednotification-crd.yaml | SubscribedNotification | ~line 237 |
Example component directories (in feature-definition-and-test-kit/testData/):
| Directory | Demonstrates |
|---|
productcatalog-v1/ | Base component: core, management, and security functions |
productcatalog-dependendent-API-v1/ | Declaring dependent APIs |
productcatalog-static-roles-v1/ | Static componentRole definitions |
productcatalog-v1-sman/ | secretsManagement sidecar config |
productcatalog-dynamic-roles-v1/ | MCP API type + gatewayConfiguration |
productinventory-v1/ | Product Inventory component |
The rendered component template is in each directory's templates/component-productcatalog.yaml. Show these to users as concrete examples of Component specifications.
Prerequisites
Verify cluster access before running any commands:
kubectl cluster-info
If this fails, inform the user that a valid kubeconfig and cluster connection are required.
Shell Compatibility
Commands use bash syntax. On Windows PowerShell: replace grep with Select-String, 2>/dev/null with 2>$null, and use && carefully.
YAML Output Interpretation
Use kubectl get <resource> -o yaml to retrieve full resource details in human-readable format. The agent interprets the YAML output directly — no external parsing scripts are needed. Use the Key Fields tables in each reference file to identify the important fields.
For drill-downs, use kubectl get <resource> <name> -n components -o yaml and interpret the spec and status sections.
Helper Scripts
Replace <scripts> with the absolute path to .github/skills/canvas-ops-tutorial/scripts/.
| Script | Purpose | Usage |
|---|
discover_observability.py | Find observability services | kubectl get svc -A -o json | python <scripts>/discover_observability.py |
manage_keycloak_users.py | Keycloak user and client management | python <scripts>/manage_keycloak_users.py --keycloak-url <URL> --admin-password <PASS> --realm odari --action <ACTION> |
check_bdd_deps.py | Check BDD test dependencies | python <scripts>/check_bdd_deps.py <path-to-feature-definition-and-test-kit> |
exercise_catalog_api.py | Generate TMF620 API metrics | python <scripts>/exercise_catalog_api.py <api-base-url> [--rounds N] [--cleanup] |
inspect_mcp_server.py | Inspect MCP server capabilities | python <scripts>/inspect_mcp_server.py <mcp-endpoint-url> |
generate_postman_collection.py | Generate Postman collection for authenticated API testing | python <scripts>/generate_postman_collection.py --keycloak-url <URL> --client-id <ID> --client-secret <SECRET> --api-base-url <URL> --output <FILE> |
These scripts work on both bash and PowerShell.
Do
- Verify cluster access with
kubectl cluster-info before running commands
- Default to the
components namespace for ODA resources
- Present kubectl output and interpret YAML results directly; offer drill-down after summaries
- After every action, explain what the output means: what the resources are, which operator manages them, and how they fit into the ODA component lifecycle
- Show relevant CRD schema snippets when explaining resources — use
kubectl explain, CRD template files, or testData examples as appropriate
- Reference example component YAMLs from
feature-definition-and-test-kit/testData/ when explaining resource structure
- Always show the kubectl/helm commands used so the user can repeat them independently
- Present contextual sub-menus after each action as a numbered list with 4–6 relevant next steps plus "Return to main menu"
- Auto-discover observability service locations — do not assume a namespace
- Handle missing observability stack or DependentAPIs gracefully with guidance
- Run port-forward as a background process so UIs remain accessible
- Run
helm repo update oda-components before helm search repo
- Check existing Helm releases with
helm list -n components before deploying
- Monitor component deployment until
Complete status or timeout
- Auto-check and install npm dependencies before running BDD tests
- Check for required environment variables based on the specific test
- Highlight the Cucumber Report URL from test output
- Warn that BDD tests deploy their own components (release name
ctk) and offer cleanup
- Use shell-appropriate commands (bash vs PowerShell) based on the user's environment
- When a user asks to use or interact with a component's MCP server, recommend opening a separate agent or chat thread configured with the MCP server — mixing Canvas management commands with MCP tool invocations in the same session causes confusion
Don't
- Do not show output without explaining what it means and how it relates to the ODA architecture
- Do not assume the observability stack or ServiceMonitor CRDs are installed — check first
- Do not run BDD tests without verifying dependencies (all 5 utility packages + main)
- Do not hard-code IP addresses or external URLs for services
- Do not leave port-forward processes or BDD test components running without offering cleanup
- Do not run all BDD tests at once without user confirmation (full suite can take over an hour)
- Do not deploy components without confirming chart selection with the user
- Do not skip
helm repo update — stale indexes return no results
- Do not print Kubernetes secrets or credentials in plain text unless required
- Do not use bash-only syntax without PowerShell alternatives
- Do not use
ask_questions for menus — always present options as a simple numbered list and let the user reply with a number
- Do not offer to remove or uninstall Istio — all gateway options (Istio, Kong, APISIX) require Istio for internal traffic management inside the cluster; the gateway choice only affects which component handles external API exposure
- Do not create, delete, or modify gateway resources (KongPlugins, HTTPRoutes, KongConsumers, Istio VirtualServices, etc.) directly — all gateway configuration should be done by upgrading the Helm release for the Component (using
helm upgrade --reuse-values), which is the source of truth. Patching ExposedAPI CRDs directly is a temporary alternative for one-off testing — changes will be overwritten on the next Helm upgrade. The API Operator translates ExposedAPI specs to gateway-specific resources automatically
- Do not attempt to invoke MCP tool calls (e.g., listing resources, calling tools) directly from within this tutorial agent — recommend the user connect via a dedicated MCP client (Claude Desktop or VS Code) in a separate session instead
