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 |
|
2 |
Install ODA Canvas — Check prerequisites, choose a gateway (Istio/Kong/APISIX), and install or troubleshoot a Canvas |
|
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 |
|
6 |
Manage Identities — View IdentityConfig resources, access Keycloak UI, and create external clients for API access |
|
7 |
Run BDD Feature Tests — Execute Behaviour-Driven Design test scenarios |
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:
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
kubectlorhelmcommands 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 |
|
CRD Helm templates |
Show authoritative schema |
Read from |
Example components |
Show concrete YAML |
Read from |
CRD template files (in charts/oda-crds/templates/):
File |
Resource |
v1 schema location |
|---|---|---|
|
Component |
~line 1858 |
|
ExposedAPI |
~line 337 |
|
DependentAPI |
~line 176 |
|
IdentityConfig |
~line 66 |
|
SecretsManagement |
~line 150 |
|
PublishedNotification |
~line 231 |
|
SubscribedNotification |
~line 237 |
Example component directories (in feature-definition-and-test-kit/testData/):
Directory |
Demonstrates |
|---|---|
|
Base component: core, management, and security functions |
|
Declaring dependent APIs (TMF620 Product Catalog and TMF637 Product Inventory) |
|
Static |
|
Dynamic roles: permission specification sets created through the TMF672 API |
The full list of test charts, and the features that use each one, is in feature-definition-and-test-kit/testData/README.md.
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 |
|---|---|---|
|
Find observability services |
|
|
Keycloak user and client management |
|
|
Check BDD test dependencies |
|
|
Generate TMF620 API metrics |
|
|
Inspect MCP server capabilities |
|
|
Generate Postman collection for authenticated API testing |
|
These scripts work on both bash and PowerShell.
Do¶
Verify cluster access with
kubectl cluster-infobefore running commandsDefault to the
componentsnamespace for ODA resourcesPresent 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 appropriateReference example component YAMLs from
feature-definition-and-test-kit/testData/when explaining resource structureAlways 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-componentsbeforehelm search repoCheck existing Helm releases with
helm list -n componentsbefore deployingMonitor component deployment until
Completestatus or timeoutAuto-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 cleanupUse 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 resultsDo not print Kubernetes secrets or credentials in plain text unless required
Do not use bash-only syntax without PowerShell alternatives
Do not use
ask_questionsfor menus — always present options as a simple numbered list and let the user reply with a numberDo 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 automaticallyDo 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