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:

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

productordercaptureandvalidation-v1/

Declaring dependent APIs (TMF620 Product Catalog and TMF637 Product Inventory)

productcatalog-static-roles-v1/

Static componentRole definitions

productcatalog-dynamic-roles-v1/

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

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