View ExposedAPIs¶
Table of Contents¶
What is an ExposedAPI?¶
An ExposedAPI is a child Custom Resource created by the Component Operator when it decomposes a Component. For every API entry in spec.coreFunction.exposedAPIs[], spec.managementFunction.exposedAPIs[], and spec.securityFunction.exposedAPIs[], the Component Operator creates a corresponding ExposedAPI resource.
The API Operator then watches these ExposedAPI resources and configures the API Gateway (e.g., Istio, Kong, APISIX) to:
Create a route from the public path to the backend service
Apply gateway policies: CORS, rate limiting, API key verification, OAS validation, quotas
Report the public URL and readiness status back to the ExposedAPI’s
.status
Key concepts:
The
segmentfield (coreFunction / managementFunction / securityFunction) indicates which section of the parent Component this API came fromThe
apiTypedetermines how the API is handled:openapi(REST),prometheus/openmetrics(metrics scraping),mcp(AI Model Context Protocol)The
gatewayConfigurationsub-fields (CORS, rateLimit, quota, OASValidation, apiKeyVerification) are optional non-functional policies applied at the gateway level
To explore the ExposedAPI CRD schema:
kubectl explain exposedapi.spec
The CRD definition is in charts/oda-crds/templates/oda-exposedapi-crd.yaml (v1 schema starts around line 337).
Default Namespace¶
Use components as the default namespace.
Commands¶
Follow the same dual-output pattern (raw + structured):
# Summary table
kubectl get exposedapis -n components
# Full YAML for detailed inspection
kubectl get exposedapis -n components -o yaml
# Detail for a specific ExposedAPI
kubectl describe exposedapi <name> -n components
Key Fields¶
The raw kubectl get output already shows useful columns: API_ENDPOINT and IMPLEMENTATION_READY.
Field |
YAML Path |
Description |
|---|---|---|
Name |
|
ExposedAPI resource name |
Namespace |
|
Namespace |
Parent Component |
|
Owning Component name |
API Type |
|
e.g., |
TMF ID |
|
TMF Forum API identifier, e.g., |
Segment |
|
One of: |
Implementation |
|
Backend service name |
Path |
|
API path |
Port |
|
Backend port |
Ready |
|
Boolean, is the implementation ready |
URL |
|
Published API URL |
Developer UI |
|
Swagger/docs URL |
Drill-Down¶
After the concise list, offer to drill into a specific ExposedAPI:
kubectl get exposedapi <name> -n components -o yaml
Interpret the YAML output to show:
Full
.specincluding: implementation service, path, port, API specification URL.spec.CORS— CORS configuration (enabled, allowOrigins, handlePreflightRequests).spec.rateLimit— Rate limiting configuration (enabled, limit, interval, identifier).spec.apiKeyVerification— API key verification settings.spec.OASValidation— OpenAPI specification validation settings.spec.specification[]— Links to the OpenAPI specification documentsFull
.status(apiStatus, implementation details)
After drill-down, explain what each section means:
Implementation + Port — the Kubernetes Service and port that the API Operator routes traffic to through the gateway
Path — the public URL path segment, typically
/<release>-<componentname>/tmf-api/<apiName>/v4CORS / rateLimit / quota — non-functional policies the API Operator configures at the API Gateway level
specification[] — links to the OpenAPI/Swagger JSON documents that define the API contract
status.apiStatus.url — the fully qualified URL where this API is accessible externally
status.implementation.ready — whether the backend pod is running and the gateway route is configured
You can also view the raw YAML to see the complete ExposedAPI resource:
kubectl get exposedapi <name> -n components -o yaml
Understanding the CRD Schema¶
Offer to explore the ExposedAPI schema in depth:
Live cluster exploration:
kubectl explain exposedapi.spec
kubectl explain exposedapi.spec.CORS
kubectl explain exposedapi.spec.rateLimit
kubectl explain exposedapi.spec.OASValidation
Key v1 schema properties (from charts/oda-crds/templates/oda-exposedapi-crd.yaml):
Field |
Type |
Description |
|---|---|---|
|
string |
API name (required) |
|
enum: openapi, prometheus, openmetrics, mcp |
How the API is handled (required) |
|
string |
Backend Kubernetes Service name (required) |
|
string |
URL path for the API (required) |
|
integer |
Backend service port (required) |
|
enum: coreFunction, managementFunction, securityFunction |
Which component section it came from |
|
array of {url, version} |
Links to API specification documents |
|
object |
Cross-origin resource sharing policy |
|
object |
Rate limiting: enabled, identifier, limit, interval |
|
object |
Request quota: identifier, limit |
|
object |
OpenAPI spec validation for requests/responses |
|
object |
API key verification: enabled, location |
|
string |
Pre-configured gateway policy template |
Example from test data — the productcatalog-v1 component declares these ExposedAPIs (see feature-definition-and-test-kit/testData/productcatalog-v1/templates/component-productcatalog.yaml):
Core function:
productcatalogmanagement(openapi, port 8080) — the TMF620 Product Catalog Management APIManagement function:
metrics(prometheus, port 4000) — Prometheus metrics endpointSecurity function:
partyrole(openapi, port 8080) — TMF669 Party Role Management API
MCP Server Inspection¶
After displaying the ExposedAPI list, check if any ExposedAPIs have apiType: mcp. If MCP-type APIs are present, proactively offer to inspect the MCP server to discover its tools, resources, and prompts.
Detecting MCP APIs¶
When parsing the ExposedAPI list JSON output, look for entries where API Type is mcp. For each MCP API found, note the URL from .status.apiStatus.url — this is the MCP server endpoint.
Inspecting an MCP Server¶
Use the helper script to inspect the MCP server:
python <scripts>/inspect_mcp_server.py <mcp-endpoint-url>
For example:
python <scripts>/inspect_mcp_server.py https://localhost/pc1-productcatalogmanagement/mcp
The script uses the MCP Streamable HTTP transport (the current MCP standard) and performs:
Initialize — establishes a session, reports server name/version and capabilities
tools/list — discovers all tools with their names, descriptions, and input schemas
resources/list — discovers any exposed resources (data the server makes available)
prompts/list — discovers any prompt templates the server offers
The requests Python package is required. If not installed, run pip install requests first.
Connecting an MCP Client¶
⚠️ Use a separate agent or chat thread to interact with a component’s MCP server. This tutorial agent is scoped to Canvas operations (Kubernetes, Helm, kubectl). Mixing Canvas management commands with MCP tool calls in the same session causes confusion. Open a new chat thread (or a different AI agent configured with the MCP server) to actually invoke the component’s tools.
To connect an MCP client (Claude Desktop, VS Code GitHub Copilot, etc.) to a component’s MCP server, use the public URL from .status.apiStatus.url.
SSL Certificates on localhost¶
If the Canvas is running on localhost (e.g., Docker Desktop Kubernetes), the gateway will typically present a self-signed certificate. MCP clients reject self-signed certificates by default. The recommended approach is to use mcp-proxy — a lightweight stdio-to-HTTP bridge that can be configured to skip SSL verification.
Claude Desktop (claude_desktop_config.json):
"mcpServers": {
"product-catalog": {
"command": "uvx",
"args": [
"mcp-proxy",
"--transport",
"streamablehttp",
"--no-verify-ssl",
"https://localhost/<component-path>/mcp"
]
}
}
VS Code / GitHub Copilot (.vscode/mcp.json) — VS Code’s http type does not support --no-verify-ssl, so use mcp-proxy via stdio:
{
"servers": {
"product-catalog": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-proxy",
"--transport",
"streamablehttp",
"--no-verify-ssl",
"https://localhost/<component-path>/mcp"
]
}
}
}
Replace <component-path> with the path prefix from the ExposedAPI status (e.g., pc1-productcatalogmanagement). uvx installs and runs mcp-proxy on first use — no separate install step needed if uv is available.
If the Canvas uses HTTP on port 80 (valid and safe on the local loopback interface),
--no-verify-sslis not needed and you can use"type": "http"directly in VS Code.
Explaining MCP Server Results¶
After showing the inspection output, explain:
Server info — The MCP server name and version correspond to the ODA Component that hosts it. The protocol version (e.g.,
2025-03-26) indicates which MCP specification it implements.Tools — These are operations an AI agent can invoke on the component. For a Product Catalog component, tools typically map to TMF620 CRUD operations (catalog, category, product specification, product offering, product offering price). Each tool has a JSON Schema
inputSchemadefining its parameters.Resources — Static or dynamic data the server exposes for reading (e.g., catalog data snapshots, schemas). May be empty if the server only exposes tools.
Prompts — Reusable prompt templates the server offers for common interactions. May be empty if no prompts are defined.
Capabilities — The
capabilitiesfield returned during initialization declares which MCP features (tools, resources, prompts, subscriptions) the server supports.
Manual MCP Inspection (curl)¶
If the helper script is not available, the same inspection can be done with curl:
# Step 1: Initialize session
curl -sk -X POST \
-H "Accept: text/event-stream, application/json" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}' \
<mcp-endpoint-url>
# Note the Mcp-Session-Id from the response header
# Step 2: List tools
curl -sk -X POST \
-H "Accept: text/event-stream, application/json" \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: <session-id>" \
-d '{"jsonrpc":"2.0","id":"2","method":"tools/list","params":{}}' \
<mcp-endpoint-url>
# Step 3: List resources
curl -sk -X POST \
-H "Accept: text/event-stream, application/json" \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: <session-id>" \
-d '{"jsonrpc":"2.0","id":"3","method":"resources/list","params":{}}' \
<mcp-endpoint-url>
# Step 4: List prompts
curl -sk -X POST \
-H "Accept: text/event-stream, application/json" \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: <session-id>" \
-d '{"jsonrpc":"2.0","id":"4","method":"prompts/list","params":{}}' \
<mcp-endpoint-url>
Important: Never Modify Gateway Resources Directly¶
All API Gateway configuration (routes, authentication plugins, rate limiting) is managed by the API Operator based on the ExposedAPI CRD spec. Never create, delete, or modify gateway resources directly — this includes:
KongPlugins (JWT, rate-limiting, CORS, etc.)
HTTPRoutes
KongConsumers / JWT credentials
Istio VirtualServices / EnvoyFilters
APISIX routes / plugins
Always make changes by upgrading the Helm release for the parent Component using helm upgrade --reuse-values. This updates the Component CR (the source of truth), which the Component Operator decomposes into updated ExposedAPI child resources, and the API Operator then reconciles into the correct gateway configuration.
Quick/temporary alternative: You can also
kubectl patchan ExposedAPI resource directly for one-off testing, but these changes will be overwritten on the nexthelm upgradesince the Component CR managed by Helm is the source of truth.
To view gateway resources for debugging purposes (e.g., confirming a KongPlugin was created), use kubectl get — but never kubectl delete, kubectl edit, or kubectl patch on these resources.
Setting a Rate Limit¶
When the user selects this option, present the list of openapi-type ExposedAPIs (rate limiting is not applicable to prometheus or mcp types) using ask_questions and let them pick one.
Then ask for the desired rate limit using ask_questions with a default of 60 requests per minute:
Option |
Description |
|---|---|
60 per minute (recommended) |
Standard rate limit suitable for most APIs |
10 per minute |
Restrictive — good for expensive or sensitive operations |
120 per minute |
Permissive — for high-throughput APIs |
Custom |
Let the user specify a custom limit and interval |
Apply the rate limit by upgrading the Helm release for the parent Component. Use --set-string for the limit field because the CRD schema expects a string — using --set coerces bare numbers to integers and fails validation:
helm upgrade <release> oda-components/<chart> -n components \
--set component.apipolicy.rateLimit.enabled=true \
--set-string component.apipolicy.rateLimit.limit=<LIMIT> \
--set component.apipolicy.rateLimit.interval=pm \
--reuse-values
--reuse-valuespreserves all other settings from the current release. Without it, non-overridden values revert to chart defaults.
After upgrading, verify the change by querying the ExposedAPI and showing the updated rate limit fields. The Component Operator propagates the change from the Component CR to the ExposedAPI child resource, and the API Operator then configures the corresponding rate-limiting plugin on the API Gateway (Kong plugin, Istio EnvoyFilter, or APISIX plugin depending on the gateway in use).
To remove a rate limit:
helm upgrade <release> oda-components/<chart> -n components \
--set component.apipolicy.rateLimit.enabled=false \
--reuse-values
Quick/temporary alternative (kubectl patch)¶
Warning: Direct patches on ExposedAPI resources will be overwritten on the next
helm upgrade, since the Component CR managed by Helm is the source of truth. Use this only for one-off testing.
# PowerShell
'{"spec":{"rateLimit":{"enabled":true,"limit":"<LIMIT>","interval":"pm"}}}' | Out-File -Encoding utf8NoBOM -FilePath patch.json
kubectl patch exposedapi <name> -n components --type=merge --patch-file patch.json
Remove-Item patch.json
# bash
kubectl patch exposedapi <name> -n components --type=merge \
-p '{"spec":{"rateLimit":{"enabled":true,"limit":"<LIMIT>","interval":"pm"}}}'
Enable Authentication¶
When the user selects this option, enable JWT authentication on one or more ExposedAPIs by setting apiKeyVerification.enabled: true.
Which APIs to protect¶
Present the list of ExposedAPIs and let the user choose. Recommend enabling authentication only on user-facing APIs (typically coreFunction with apiType: openapi or mcp). Leave these open:
managementFunctionAPIs (e.g., prometheus metrics) — needed by Prometheus for scrapingsecurityFunctionAPIs (e.g., TMF672 Party Role) — needed by the Identity Config Operator
Apply the change¶
Upgrade the Helm release for the parent Component:
helm upgrade <release> oda-components/<chart> -n components \
--set component.apipolicy.apiKeyVerification.enabled=true \
--reuse-values
--reuse-valuespreserves all other settings (e.g., rate limits, dependent APIs) from the current release.
Quick/temporary alternative (kubectl patch)¶
Warning: Direct patches on ExposedAPI resources will be overwritten on the next
helm upgrade. Use this only for one-off testing.
# PowerShell
'{"spec":{"apiKeyVerification":{"enabled":true}}}' | Out-File -Encoding utf8NoBOM -FilePath patch.json
kubectl patch exposedapi <name> -n components --type=merge --patch-file patch.json
Remove-Item patch.json
# bash
kubectl patch exposedapi <name> -n components --type=merge \
-p '{"spec":{"apiKeyVerification":{"enabled":true}}}'
Verify¶
After patching, verify:
KongPlugins created: The API Operator should create a JWT KongPlugin for each patched API:
kubectl get kongplugins -n components -l oda.tmforum.org/type=apiauthentication
HTTPRoute annotated: The KongPlugin should be referenced in the HTTPRoute:
kubectl get httproutes -n components -o jsonpath='{range .items[*]}{.metadata.name}: {.metadata.annotations.konghq\.com/plugins}{"\n"}{end}'
API returns 401 without token: Test that unauthenticated requests are rejected:
try { Invoke-RestMethod -Uri "https://localhost/<API_PATH>" -SkipCertificateCheck } catch { Write-Host "Status: $($_.Exception.Response.StatusCode) (expected: 401)" }
After enabling authentication, remind the user that they also need to set up the Keycloak-Kong JWT bridge (see Manage Identities → Check Keycloak-Kong JWT integration) for token validation to work. Without it, Kong will reject all requests including those with valid tokens.
Disable authentication¶
To disable authentication on an API, upgrade the Helm release:
helm upgrade <release> oda-components/<chart> -n components \
--set component.apipolicy.apiKeyVerification.enabled=false \
--reuse-values
The Component Operator propagates the change to the ExposedAPI child resource, and the API Operator removes the corresponding JWT plugin from the gateway automatically.
Never delete KongPlugin or other gateway resources directly. Always disable features by upgrading the Helm release or patching the ExposedAPI CRD — the API Operator handles cleanup.
Contextual Next Steps¶
Present these options using ask_questions.
If MCP-type ExposedAPIs are present, include the MCP inspection option:
# |
Next Step |
|---|---|
1 |
Inspect MCP Server — Discover tools, resources, and prompts exposed by the MCP server |
2 |
Drill into a specific ExposedAPI — See CORS, rate limits, specification URLs, and full status |
3 |
Set a rate limit on an ExposedAPI — Configure rate limiting on a selected API (default: 60 requests per minute) |
4 |
Enable authentication on ExposedAPIs — Enable JWT authentication via apiKeyVerification |
5 |
View the parent component — See the Component that owns these ExposedAPIs |
6 |
View observability data — Explore Prometheus metrics (especially for prometheus/openmetrics ExposedAPIs) |
7 |
View DependentAPIs — See which APIs other components depend on |
8 |
Return to main menu |
If no MCP-type ExposedAPIs are present, omit option 1 and renumber:
# |
Next Step |
|---|---|
1 |
Drill into a specific ExposedAPI — See CORS, rate limits, specification URLs, and full status |
2 |
Set a rate limit on an ExposedAPI — Configure rate limiting on a selected API (default: 60 requests per minute) |
3 |
Enable authentication on ExposedAPIs — Enable JWT authentication via apiKeyVerification |
4 |
View the parent component — See the Component that owns these ExposedAPIs |
5 |
View observability data — Explore Prometheus metrics (especially for prometheus/openmetrics ExposedAPIs) |
6 |
View DependentAPIs — See which APIs other components depend on |
7 |
Return to main menu |