{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:

{operator-name}-sequence

plantUML code

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

  1. Clone the repository:

git clone https://github.com/tmforum-oda/oda-canvas.git
cd oda-canvas/source/operators/{operator-directory}
  1. Install dependencies:

# For Python/KOPF
pip install -r requirements.txt

# For Java/Maven
mvn clean install

# For Go
go mod download
  1. 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

LOG_LEVEL

Logging level (DEBUG, INFO, WARNING, ERROR)

INFO

{VAR_NAME}

{Description}

{default}

Operator Parameters

Configured via Helm values or deployment manifest:

Parameter

Description

Default

{param.name}

{Description}

{default}

Use Cases

This operator implements the following use cases:

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.