tmforum-oda/oda-canvas/canvas-ops-tutorial

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.

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:

CRD template files (in charts/oda-crds/templates/):

Example component directories (in feature-definition-and-test-kit/testData/):

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/.

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