ODA Canvas Operator Catalog¶
All Python/KOPF operators live under source/operators/. The Go-based operators
(pdb-management/, oauth2EnvoyfilterOperator/) are outside the scope of this skill.
Component Management Operator¶
Location: source/operators/TMFOP001-Component-Management/component-management/componentOperator.py
Helm chart: charts/component-operator/
CRDs watched: components.oda.tmforum.org
Docker image: tmforumodacanvas/component-operator
kopf decorators used:
@kopf.on.startup()@kopf.on.resume/create/update× 6 handlers (coreAPIs, managementAPIs, securityAPIs, coreDependentAPIs, managementDependentAPIs, securityDependentAPIs)@kopf.on.update— watches child resources to propagate status up to parent component@kopf.on.resume/create— adopts existing K8s child resources (Services, Deployments, PVCs, Jobs, StatefulSets, CronJobs, ConfigMaps, Secrets, ServiceAccounts, Roles, RoleBindings)@kopf.on.field— responds to component status field changes
Key patterns:
Data-driven
SEGMENT_CONFIGdict — maps handler name to spec path and status key, allowing one function body to service all six segment handlerskopf.adopt()— sets ownerReferences so child resources are deleted with the componentChild → parent status propagation —
@kopf.on.updateon child CRDs reads child status and patches the parent component’s statusCreates
ExposedAPIandDependentAPIcustom resources as children ofComponentsafe_get(default, dict, *paths)helper — safely navigates nested dicts without KeyErrorquick_get_comp_name(body)helper — extracts component name fromoda.tmforum.org/componentNamelabel
Use as template when:
Building an operator that decomposes a top-level CRD into multiple child CRDs
Implementing status rollup from child resources to parent
Managing many resource types as children of a single parent
API Management — Kong¶
Location: source/operators/TMFOP002-API-Management/kong/apiOperatorKong.py
Helm chart: charts/kong-gateway/
CRDs watched: exposedapis.oda.tmforum.org
Docker image: tmforumodacanvas/api-operator-kong
kopf decorators used:
@kopf.on.startup()@kopf.on.resume/create/update— ExposedAPI lifecycle@kopf.on.delete— cleanup routing rules and plugins
Key patterns:
Creates
HTTPRoute(Gateway API) resources referencing the component’s ServiceCreates
ReferenceGrantto allow cross-namespace HTTPRoute → Service referencesCreates
KongPluginresources for rate limiting, API key verification, CORSTimeout values expressed in milliseconds format (Kong-specific)
Mix of sync and async handlers
Use as template when:
Building an API gateway integration using standard Kubernetes Gateway API (HTTPRoute)
Managing Kong-specific plugin configuration alongside routing rules
API Management — Apache APISIX¶
Location: source/operators/TMFOP002-API-Management/apache-apisix/apiOperatorApisix.py
Helm chart: charts/apisix-gateway/
CRDs watched: exposedapis.oda.tmforum.org
Docker image: tmforumodacanvas/api-operator-apisix
kopf decorators used:
@kopf.on.startup()@kopf.on.resume/create/update— ExposedAPI lifecycle@kopf.on.delete— cleanup@kopf.on.field— watchesstatus.apiStatusandstatus.implementation
Key patterns:
Creates
ApisixRouteandApisixPluginConfigresourcesTemplate-based plugin generation for policies
Timeout values in string format (e.g.,
"60s","900s") — APISIX-specific
Use as template when:
Building an operator that creates APISIX-specific routing and plugin resources
Implementing field-watching to respond to status transitions set by another operator
API Management — Istio¶
Location: source/operators/TMFOP002-API-Management/istio/apiOperatorIstio.py
Helm chart: charts/api-operator-istio/
CRDs watched: exposedapis.oda.tmforum.org, endpointslices.discovery.k8s.io
Docker image: tmforumodacanvas/api-operator-istio
kopf decorators used:
@kopf.on.startup()@kopf.on.create/update— ExposedAPI and EndpointSlice lifecycle@kopf.on.field— watchesstatus.apiStatusandstatus.implementation
Key patterns:
Watches
EndpointSliceresources (discovery.k8s.io/v1) alongside custom CRDs — used to discover service implementation details (pod IPs, ports)Creates Istio
VirtualServiceresources for service mesh routingDiscovers public hostname/IP from the
istio-ingressgatewayServiceSupports multiple observability implementations: ServiceMonitor, PrometheusAnnotation, DataDogAnnotation via environment variable switch
Use as template when:
Building an operator that watches non-CRD Kubernetes resources (EndpointSlice, Services, Pods) alongside custom resources
Integrating with Istio service mesh
Implementing observability configuration alongside routing
API Management — Apigee¶
Location: source/operators/TMFOP002-API-Management/apigee/apiOperatorApigee.py
Helm chart: charts/apigee-gateway/
CRDs watched: exposedapis.oda.tmforum.org
kopf decorators used:
@kopf.on.startup()@kopf.on.create— create Apigee API proxy@kopf.on.delete— remove Apigee API proxy
Key patterns:
Creates Apigee API proxies with spike arrest, API key verification, CORS policies
Template-based policy generation
Google Cloud authentication via
google-authlibrary
Use as template when: Building an operator that provisions resources in an external cloud API management platform.
Identity Config Operator (Keycloak)¶
Location: source/operators/TMFOP003-Identity-Config/keycloak/identityConfigOperatorKeycloak.py
Helm chart: charts/identityconfig-operator-keycloak/
CRDs watched: identityconfigs.oda.tmforum.org
Docker image: tmforumodacanvas/identityconfig-operator-keycloak
Deployment: Dual-container (operator + Keycloak listener sidecar on port 5000)
kopf decorators used:
@kopf.on.startup()@kopf.on.resume/create/update— IdentityConfig lifecycle@kopf.on.delete— deregister Keycloak client@kopf.timer(GROUP, VERSION, "identityconfigs", interval=300.0, idle=30.0)— periodic health probe / reconciliation@kopf.on.probe(id="keycloak-check")— Kubernetes liveness health check
Key patterns:
Timer handler fires every 5 minutes to reconcile identity configuration and verify external service connectivity
Probe handler exposes a health endpoint that Kubernetes liveness probes call
External HTTP API integration via
requestslibrary (Keycloak REST API)Global listener registry dictionary shared between handlers for the same resource
Dual-container: main kopf operator + a separate listener web service deployed as sidecar in the same pod
Use as template when:
Building an operator that integrates with an external service API
Implementing periodic reconciliation (timer) alongside event-driven handlers
Exposing custom Kubernetes health check probes
Deploying operator alongside a sidecar service in the same pod
Secrets Management Operator (HashiCorp Vault)¶
Location: source/operators/TMFOP007-Secrets-Management/vault/docker/secretsmanagementOperatorHC.py
Helm chart: charts/secretsmanagement-operator/
CRDs watched: secretsmanagements.oda.tmforum.org, pods (via admission webhook)
Docker image: tmforumodacanvas/secretsmanagement-operator-hc
Scope: --all-namespaces
kopf decorators used:
@kopf.on.startup()— configures peering priority=200, custom ServiceTunnel, admission@kopf.on.mutate("", "v1", "pods", operation="CREATE")— mutating admission webhook@kopf.on.resume/create/update— SecretsManagement CRD lifecycle@kopf.on.delete— Vault policy cleanup@kopf.on.field— field watchers
Key patterns:
Mutating admission webhook intercepts pod CREATE events and injects a sidecar container (vault-agent) with volume mounts
Custom
ServiceTunnelclass implementskopf.WebhookFnprotocol to configure the webhook server as an in-cluster Kubernetes Service, so the Kubernetes API server calls back into the operator pod via a stable Service DNS namesettings.peering.priority = 200— highest priority in ODA Canvas, ensuring admission webhook is never blockedsettings.admission.managed = "auto.kopf.dev"— kopf automatically creates/updatesMutatingWebhookConfigurationMultiple Vault token configuration methods: plaintext, encrypted, or Kubernetes Secret references
Pod selector matching by name patterns, namespace, and service account
Use as template when:
Building an operator with admission webhooks (pod mutation/injection)
Implementing in-cluster webhook service using a custom tunnel class
Integrating with HashiCorp Vault
Building an operator that needs the highest execution priority
Dependent API Simple Operator¶
Location: source/operators/TMFOP005-Dependency-Management/simple-dependency-management/docker/src/dependentApiSimpleOperator.py
Helm chart: charts/dependentapi-simple-operator/
CRDs watched: dependentapis.oda.tmforum.org
Docker image: tmforumodacanvas/dependentapi-simple-operator
kopf decorators used:
@kopf.on.startup()— configures peering priority=110, peering name=”dependentapi”@kopf.on.resume/create/update— DependentAPI lifecycle@kopf.on.delete— cleanup service inventory entry
Key patterns:
settings.peering.priority = 110— mid-range prioritysettings.peering.name = "dependentapi"— operator uses a named peering object (not the default), preventing collision with other operators’ peeringCross-resource discovery: calls
list_cluster_custom_object()onExposedAPIsto find matching APIs and resolve their URLsUpdates TMF Service Inventory API with resolved dependency URLs
Uses
Jinja2templating for resource body construction
Use as template when:
Building an operator that needs to discover and cross-reference other CRDs cluster-wide (dependency resolution)
Implementing named peering to isolate operator coordination
Integrating with an external service inventory or catalogue
Credentials Management Operator¶
Location: source/operators/TMFOP004-Credentials-Management/credentials-management/credentialsManagementOperator.py
Helm chart: charts/credentialsmanagement-operator/
CRDs watched: identityconfigs.oda.tmforum.org
Docker image: tmforumodacanvas/credentials-management-operator
kopf decorators used:
@kopf.on.startup()@kopf.on.field(GROUP, VERSION, "identityconfigs", field="status.identityConfig", when=is_status_changed)— field handler withwhen=callback filter
Key patterns:
Field handler with
when=callback — only fires whenstatus.identityConfigchanges to a specific value (avoids spurious re-processing)Retrieves Keycloak client credentials via REST API
Creates a
kubernetes.client.V1SecretusingCoreV1Apikopf.adopt(secret)— makes the Secret owned by the IdentityConfig (cascaded deletion)Uses standard Python
logging(notLogWrapper) — simpler operators can skipLogWrapper
Use as template when:
Building an operator that reacts only to specific status field transitions
Creating Kubernetes Secrets from external service credential retrieval
Writing a lightweight operator watching a CRD owned by another operator
Helm Chart Conventions¶
Standard Chart Structure¶
charts/<operator-name>/
Chart.yaml # name, version, appVersion (operator version)
values.yaml # deployment image/version/prerelease, namespaces, loglevel
templates/
deployment.yaml # Operator pod, image, env, command
rbac.yaml # ServiceAccount + ClusterRole + ClusterRoleBinding (+ Role/RoleBinding for namespaced ops)
configMap.yaml # Non-sensitive config (log level, namespace, service URLs)
_helpers.tpl # dockerimage, selectorLabels, labels, monitoredNamespacesCLIOpts
Some charts add: secret.yaml (credentials), certificate.yaml (cert-manager), webhook.yaml.
Namespace CLI Options Helper¶
Converts comma-separated namespace list to kopf CLI flags:
{{- define "myoperator.monitoredNamespacesCLIOpts" -}}
{{- printf "-n %s" .Values.deployment.monitoredNamespaces | replace "," " -n " }}
{{- end -}}
"components,odacompns-*" → -n components -n odacompns-*
Used in deployment command:
command: ["/bin/sh"]
args: ["-c", "kopf run $COMPONENT_NAMESPACES_CLI --verbose /operator/myoperator.py"]
ConfigMap vs Secret vs Inline Env Vars¶
Type |
Use for |
Helm encoding |
|---|---|---|
ConfigMap |
Non-sensitive config: log level, namespaces, service URLs |
Plain values, |
Secret |
Credentials: passwords, client_id/secret, tokens, Vault keys |
|
Inline |
Simple values, field references ( |
Direct |
Multi-Container Deployment Pattern (identityconfig-operator-keycloak)¶
containers:
- name: identityconfig-operator
image: {{ include "identityconfig.dockerimage" . }}
command: ["/bin/sh"]
args: ["-c", "kopf run $COMPONENT_NAMESPACES_CLI --verbose /identityConfigOperator/identityConfigOperatorKeycloak.py"]
envFrom:
- configMapRef:
name: {{ include "identityconfig.fullname" . }}-config
- name: identityconfig-listener
image: {{ include "identityconfig-listener.dockerimage" . }}
ports:
- containerPort: 5000
RBAC Minimums for All Kopf Operators¶
Every operator needs these in its ClusterRole:
rules:
# KOPF peering (required by kopf framework)
- apiGroups: [kopf.dev]
resources: [clusterkopfpeerings]
verbs: [list, watch, patch, get]
- apiGroups: [kopf.dev]
resources: [kopfpeerings]
verbs: [list, watch, patch, get]
# K8s events (kopf posts events on handled objects)
- apiGroups: ["", "events.k8s.io"]
resources: [events]
verbs: [create, patch, get]
# CRD management (kopf discovers CRDs at startup)
- apiGroups: [apiextensions.k8s.io]
resources: [customresourcedefinitions]
verbs: [list, watch, get]
# ODA resources this operator manages
- apiGroups: [oda.tmforum.org]
resources: [components, exposedapis, dependentapis, ...]
verbs: [list, watch, get, create, update, patch, delete]
Add gateway-specific CRD permissions (Kong, APISIX, Istio) for API-management operators.
Operators that create namespace-scoped resources (Secrets, ConfigMaps) need a Role + RoleBinding in addition to the ClusterRole.