{Operator Name}¶
Overview¶
{Provide 2-3 paragraphs explaining:
The purpose of this operator
What resources it manages
How it fits into the ODA Canvas architecture
Key responsibilities and lifecycle processes }
This operator follows the Kubernetes Operator Pattern and is part of the ODA Canvas modular architecture.
Sequence Diagram¶
The following diagram shows how the {Operator Name} interacts with the Kubernetes API and other Canvas components:
Key Features¶
{Feature 1}: {Description}
{Feature 2}: {Description}
{Feature 3}: {Description}
Managed Resources¶
This operator manages the following Kubernetes resources:
Custom Resources¶
{CustomResourceName}: {Purpose and description}
API Group:
{api-group}Version:
{version}(e.g., v1beta3)Kind:
{Kind}
Created Resources¶
The operator creates and manages:
Deployment- {Description of deployments created}Service- {Description of services created}ConfigMap- {Description of config maps created}Secret- {Description of secrets created if applicable}{Other resources}
Architecture¶
Operator Components¶
{Operator Name}
├── {Component 1} - {Purpose}
├── {Component 2} - {Purpose}
└── {Component 3} - {Purpose}
Integration Points¶
Kubernetes API: {How it interacts with K8s API}
Other Operators: {Dependencies on or interactions with other operators}
External Services: {Integration with API Gateway, Identity Management, etc.}
Reference Implementation¶
The reference implementation is written in {Language} using {Framework}.
Technology Stack¶
Language: {Python/Java/Go/etc.}
Framework: {KOPF/Operator SDK/Kubebuilder/Spring Boot/etc.}
Kubernetes Client: {kubernetes-client library version}
Dependencies: {Key libraries or frameworks}
Project Structure¶
{operator-directory}/
├── {main-file}.{ext} # Main operator logic
├── {handler-file}.{ext} # Event handlers
├── {utility-dir}/ # Utility functions
├── requirements.txt # Python dependencies (or equivalent)
├── Dockerfile # Container image definition
└── README.md # This file
Development¶
Prerequisites¶
{Prerequisite 1, e.g., Python 3.9+}
{Prerequisite 2, e.g., kubectl configured with cluster access}
{Prerequisite 3, e.g., Access to Kubernetes cluster (local or remote)}
Local Development Setup¶
Clone the repository:
git clone https://github.com/tmforum-oda/oda-canvas.git
cd oda-canvas/source/operators/{operator-directory}
Install dependencies:
# For Python/KOPF
pip install -r requirements.txt
# For Java/Maven
mvn clean install
# For Go
go mod download
Configure environment:
# Set required environment variables
export LOG_LEVEL=DEBUG
export {OTHER_ENV_VAR}={value}
Interactive Development and Testing¶
Run the operator locally in standalone mode:
# For Python/KOPF
kopf run --namespace={namespace} --standalone ./{operator-file}.py
# For Java/Spring Boot
mvn spring-boot:run
# For Go
go run main.go
Note: Standalone mode allows testing operator logic without deploying to the cluster. The operator will watch the specified namespace and respond to resource events.
Testing with Sample Resources¶
Create a test custom resource:
kubectl apply -f examples/{sample-resource}.yaml -n {namespace}
Watch operator logs:
# If running locally
# Logs appear in terminal
# If deployed to cluster
kubectl logs -n {namespace} deployment/{operator-deployment} -f
Verify expected resources are created:
kubectl get {resource-type} -n {namespace}
kubectl describe {resource-type} {resource-name} -n {namespace}
Debugging¶
Enable debug logging:
# For KOPF
export LOG_LEVEL=DEBUG
kopf run --verbose --namespace={namespace} --standalone ./{operator-file}.py
# For others
{framework-specific debug command}
Common debugging commands:
# Check operator status
kubectl get pods -n {namespace} -l app={operator-name}
# View operator logs
kubectl logs -n {namespace} deployment/{operator-deployment}
# Check custom resource status
kubectl get {crd-name} -n {namespace}
kubectl describe {crd-name} {instance-name} -n {namespace}
# Check events
kubectl get events -n {namespace} --sort-by='.lastTimestamp'
Build Automation¶
Building Container Image¶
Build the Docker image:
docker build -t {image-name}:{tag} .
Continuous Integration¶
This operator uses GitHub Actions for CI/CD:
Build: Triggered on PR to master/main
Test: Unit and integration tests run automatically
Release: Docker images published to {registry} on version tags
See .github/workflows/{workflow-file}.yaml for details.
Versioning¶
This operator follows semantic versioning:
Major: Breaking changes to CRD or behavior
Minor: New features, backward compatible
Patch: Bug fixes, backward compatible
Deployment¶
Deploy with Helm¶
This operator is typically deployed as part of the Canvas installation:
helm install {release-name} ./charts/{chart-name} -n {namespace}
Standalone Deployment¶
To deploy just this operator:
# Install CRDs
kubectl apply -f charts/{chart-name}/crds/
# Deploy operator
helm install {operator-release} ./charts/{chart-name} -n {namespace}
Configuration¶
Environment Variables¶
Variable |
Description |
Default |
|---|---|---|
|
Logging level (DEBUG, INFO, WARNING, ERROR) |
|
|
{Description} |
|
Operator Parameters¶
Configured via Helm values or deployment manifest:
Parameter |
Description |
Default |
|---|---|---|
|
{Description} |
|
Use Cases¶
This operator implements the following use cases:
-
{Brief description of operator’s role in this use case}
Contributing¶
For information about contributing to this operator, see CONTRIBUTING.md.
License¶
This operator is part of the ODA Canvas project. See LICENSE for details.