Skip to content

Developing controllers

This documentation covers how to write a new ORC controller from scratch.

ORC controllers follow a unified pattern built on the generic reconciler framework. Each controller:

  • Defines a Kubernetes API (CRD) for the OpenStack resource
  • Implements an actuator that performs CRUD operations against OpenStack
  • Implements a status writer that maps OpenStack state to Kubernetes status
  • Uses the generic reconciler to handle common logic (status, conditions, dependencies)
flowchart TB
    subgraph Your Controller
        api[API Types<br/><i>api/v1alpha1/*_types.go</i>]
        actuator[Actuator<br/><i>actuator.go</i>]
        status[Status Writer<br/><i>status.go</i>]
        controller[Controller Init<br/><i>controller.go</i>]
    end

    subgraph Generic Framework
        reconciler[Generic Reconciler]
        deps[Dependency Manager]
        conditions[Condition Handler]
    end

    subgraph OpenStack
        osapi[OpenStack APIs]
    end

    controller --> reconciler
    api --> reconciler
    actuator --> reconciler
    status --> reconciler
    reconciler --> deps
    reconciler --> conditions
    actuator --> osapi

Prerequisites

See the Development Quickstart for setting up your environment.

Getting started

Start by scaffolding a new controller, which generates the boilerplate and TODO(scaffolding) markers that point you to the relevant pages:

Reference controllers

When implementing a new controller, use these existing controllers as examples:

Controller Complexity Notable features
internal/controllers/servergroup/ Simple No dependencies, fully immutable
internal/controllers/flavor/ Simple Immutable except extra specs (reconcileExtraSpecs)
internal/controllers/securitygroup/ Medium Project dependency, rules reconciliation
internal/controllers/trunk/ Medium updateResource + reconcileSubports + tags
internal/controllers/server/ Complex Multiple dependencies, many reconcilers

Reference documentation