Deploy an ODA Component¶
Table of Contents¶
What Happens When You Deploy?¶
Deploying an ODA Component triggers a multi-stage lifecycle managed by the Canvas operators:
Helm installs the chart — this creates Kubernetes Deployments, Services, and a
ComponentCustom ResourceComponent Operator reads the Component CR — it decomposes
spec.coreFunction,spec.managementFunction,spec.securityFunction, andspec.eventNotificationinto child resources: ExposedAPIs, DependentAPIs, IdentityConfig, SecretsManagement, PublishedNotifications, SubscribedNotificationsAPI Operator processes each ExposedAPI — creates API Gateway routes, applies CORS/rate-limit/quota policies, reports readiness
Identity Operator processes the IdentityConfig — configures Keycloak realm, creates roles, registers webhook listener
Secrets Operator processes SecretsManagement — configures vault sidecar injection (if declared)
Dependency Operator processes each DependentAPI — searches for matching ExposedAPIs, writes resolved URLs
Component Operator updates overall status — progresses through
In-Progress-CompCon→In-Progress-IDConfOp→In-Progress-SecretMan→In-Progress-DepApi→Complete
To see the authoritative Component CRD schema: charts/oda-crds/templates/oda-component-crd.yaml (v1 schema starts ~line 1858).
An example component YAML used in testing: feature-definition-and-test-kit/testData/productcatalog-v1/templates/component-productcatalog.yaml.
Step 1: Ensure Helm Repo¶
The repo index must be updated before searching — stale or missing indexes cause “No results found” errors.
helm repo add oda-components https://tmforum-oda.github.io/reference-example-components 2>&1
helm repo update oda-components
Step 1b: Check Existing Releases¶
Before deploying, check what’s already installed to avoid name collisions:
helm list -n components
Show any existing releases with chart versions and status.
Step 2: List Available Charts¶
helm search repo oda-components
Currently available:
Chart |
Component |
Description |
|---|---|---|
|
TMFC001 |
Product Catalog Management |
|
TMFC005 |
Product Inventory Management |
Ask the user to select a chart.
Federated Catalog Scenario¶
If a productcatalog component is already deployed, offer to deploy a second instance with dependent APIs enabled to demonstrate cross-component API wiring:
Important: Use a short release name (max 5 characters). See Release Name Constraint — longer names cause deployment failures.
helm install pc2 oda-components/productcatalog -n components \
--set component.dependentAPIs.enabled=true
The second instance will declare a DependentAPI on the downstream Product Catalog Management API. The Canvas dependency operator will automatically resolve this against the first instance’s ExposedAPI. Use release name pc2 (or allow user override, max 5 chars). After deployment, suggest viewing DependentAPIs (action 3) to see the resolution status.
Step 3: Optional Overrides¶
After chart selection, offer optional --set overrides:
Override |
Default |
Description |
|---|---|---|
|
|
Enable dependent API declarations |
|
|
Enable MCP Server for AI agent capabilities |
Ask if the user wants to enable any optional features.
Step 4: Install¶
Always deploy to the components namespace:
helm install <release-name> oda-components/<chart-name> \
-n components \
[--set key=value ...]
Release Name Constraint¶
Critical: Kubernetes port names must be 15 characters or fewer. ODA component charts derive port names by combining the release name with internal suffixes (e.g., <release>-prodinvapi, <release>-prodcatapi). A release name that is too long will cause the Helm install to fail.
Always use short release names — maximum 5 characters. Recommended defaults:
Chart |
Default Release Name |
Second Instance |
|---|---|---|
|
|
|
|
|
|
Allow user override but reject names longer than 5 characters with a warning explaining the port name limit. Never use descriptive names like prodcat, prodinv, or prodcat2 — they will exceed the 15-character limit when suffixes are appended.
Step 5: Explain what is happening¶
Whilst the component is deploying, this is a good time to explain what is happening. Use the ‘01-about-oda-canvas.md’ reference to explain to the user what the Canvas Operators do when you deploy a component.
Step 6: Query Deployment¶
Query the component status: The component-name is made up of pc1-productcatalogmanagement.
kubectl get component <component-name> -n components
Don’t offer to monitor the component status until it reaches Complete: Instead offer to replay the query above.
If status does not reach Complete within 5 iterations, suggest:
kubectl describe component <name> -n components
kubectl get events -n components --sort-by='.lastTimestamp'
If the component status is still not Complete then start troubleshooting.
Step 7: Explore the Decomposed Resources¶
Once the component reaches Complete (or even while it’s progressing), show the user the child resources that the Component Operator created. This helps them understand the decomposition:
# See all resources created from this component
kubectl get exposedapis -n components -l oda.tmforum.org/componentName=<component-name>
kubectl get dependentapis -n components -l oda.tmforum.org/componentName=<component-name>
kubectl get identityconfigs -n components -l oda.tmforum.org/componentName=<component-name>
kubectl get secretsmanagements -n components -l oda.tmforum.org/componentName=<component-name>
Explain each resource type:
ExposedAPIs — one per API in the component’s core/management/security functions. The API Operator configured gateway routes for each.
DependentAPIs — only present if
component.dependentAPIs.enabled=truewas set. The Dependency Operator resolves these against other components’ ExposedAPIs.IdentityConfig — created from
securityFunction.canvasSystemRoleandcomponentRole[]. The Identity Operator configured Keycloak with these roles.SecretsManagement — only present if
securityFunction.secretsManagementwas declared. Configures vault sidecar injection for component pods.
Uninstall¶
helm delete <release-name> -n components
After uninstalling, explain that the Component Operator cleans up all child resources (ExposedAPIs, DependentAPIs, IdentityConfig, etc.) through Kubernetes owner references. The API Gateway routes and Identity Management configurations are also removed.
Contextual Next Steps¶
Present these options using ask_questions:
# |
Next Step |
|---|---|
1 |
View the deployed component — Inspect status, APIs, and decomposed resources |
2 |
View ExposedAPIs — See the API Gateway routes created for this component |
3 |
View DependentAPIs — Check if cross-component dependencies are declared and resolved |
4 |
View observability data — Explore Prometheus metrics and Jaeger traces |
5 |
Return to main menu |