# oracle/karpenter-provider-oci architecture

> Architecture diagram of the GitHub repository oracle/karpenter-provider-oci, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oracle/karpenter-provider-oci
- Repository: https://github.com/oracle/karpenter-provider-oci

## Overview

Karpenter Provider OCI provisions and manages OKE worker nodes in response to workload demand. The documented path runs from unschedulable pods and placement constraints through instance-type selection and OCI-backed launch, then feeds registered-node capacity observations back into future sizing. Cloud-provider operations also support node removal and fleet optimization. NodeClass reconciliation manages OCI prerequisites; additional providers cover networking, images, reservations, placement, and related resources. The graph uses README workflow statements and SOURCE INDEX references; unsampled relationships are omitted rather than inferred.

Main entry points: [`pkg/cloudprovider/cloud_provider.go`](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/cloudprovider/cloud_provider.go) (Cloud provider), [`pkg/controllers/nodeclasses/ocinodeclass_controller.go`](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/controllers/nodeclasses/ocinodeclass_controller.go) (NodeClass reconciliation), [`pkg/operator/operator.go`](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/operator/operator.go) (Operator wiring), [`pkg/controllers/controllers.go`](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/controllers/controllers.go) (Controller registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and control"]
  node_main["Application entry<br/>[main.go]"]
  node_operator["Operator wiring<br/>[operator.go]"]
  node_controllers["Controller registration<br/>[controllers.go]"]
  node_metrics["Metrics<br/>[metrics.go]"]
end

subgraph group_scheduling["Scheduling and launch"]
  node_cloudprovider["Cloud provider<br/>[cloud_provider.go]"]
  node_instance["Instance lifecycle<br/>[provider.go]"]
  node_instancetype["Instance types<br/>[provider.go]"]
  node_placement["Placement proposals<br/>[provider.go]"]
end

subgraph group_resources["OCI resource management"]
  node_oci_clients["OCI clients<br/>[client.go]"]
  node_nodeclass_api["NodeClass API"]
  node_nodeclass_reconcile["NodeClass reconciliation"]
  node_image["Image provider<br/>[provider.go]"]
  node_network["Network provider<br/>[provider.go]"]
  node_capacity_reservation["Capacity reservations<br/>[provider.go]"]
end

subgraph group_feedback["Fleet feedback"]
  node_capacity_discovery["Capacity discovery<br/>[provider.go]"]
  node_discovery_controller["Discovery controller<br/>[controller.go]"]
  node_orphan_controller["Orphan cleanup<br/>[controller.go]"]
end

node_workloads(("Workloads"))
node_kubernetes["Kubernetes API"]
node_oci["Oracle Cloud"]

node_workloads -->|"trigger provisioning"| node_cloudprovider
node_cloudprovider -->|"select types"| node_instancetype
node_cloudprovider -->|"manage instances"| node_instance
node_cloudprovider -.->|"request placement"| node_placement
node_instance -.->|"call OCI"| node_oci_clients
node_oci_clients -->|"access services"| node_oci
node_main -->|"create operator"| node_operator
node_main -->|"construct provider"| node_cloudprovider
node_main -->|"register controllers"| node_controllers
node_operator -->|"create clients"| node_oci_clients
node_operator -->|"initialize provider"| node_instance
node_operator -.->|"initialize provider"| node_instancetype
node_controllers -->|"register"| node_nodeclass_reconcile
node_controllers -->|"register"| node_discovery_controller
node_controllers -->|"register"| node_orphan_controller
node_nodeclass_reconcile -->|"resolve images"| node_image
node_nodeclass_reconcile -->|"resolve networking"| node_network
node_nodeclass_reconcile -->|"resolve reservations"| node_capacity_reservation
node_nodeclass_reconcile -->|"reconcile resource"| node_nodeclass_api
node_discovery_controller -->|"read node claims"| node_cloudprovider
node_discovery_controller -->|"record capacity"| node_capacity_discovery
node_capacity_discovery -.->|"inform sizing"| node_instancetype
node_orphan_controller -->|"list and delete"| node_cloudprovider
node_cloudprovider -.->|"record metrics"| node_metrics
node_workloads -->|"deprovision unused nodes"| node_cloudprovider
node_workloads -->|"consolidate fleet"| node_cloudprovider

click node_main "https://github.com/oracle/karpenter-provider-oci/blob/main/cmd/main.go"
click node_operator "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/operator/operator.go"
click node_controllers "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/controllers/controllers.go"
click node_cloudprovider "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/cloudprovider/cloud_provider.go"
click node_instance "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/instance/provider.go"
click node_instancetype "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/instancetype/provider.go"
click node_placement "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/placement/provider.go"
click node_oci_clients "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/oci/client.go"
click node_nodeclass_api "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/apis/v1beta1/ocinodeclass_types.go"
click node_nodeclass_reconcile "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/controllers/nodeclasses/ocinodeclass_controller.go"
click node_image "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/image/provider.go"
click node_network "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/network/provider.go"
click node_capacity_reservation "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/capacityreservation/provider.go"
click node_capacity_discovery "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/capacitydiscovery/provider.go"
click node_discovery_controller "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/controllers/capacitydiscovery/controller.go"
click node_orphan_controller "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/controllers/orphaninstance/controller.go"
click node_metrics "https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/metrics/metrics.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_operator,node_controllers,node_metrics toneBlue
class node_cloudprovider,node_instance,node_instancetype,node_placement toneAmber
class node_oci_clients,node_nodeclass_api,node_nodeclass_reconcile,node_image,node_network,node_capacity_reservation,node_kubernetes toneMint
class node_capacity_discovery,node_discovery_controller,node_orphan_controller toneRose
class node_workloads,node_oci toneIndigo
```

## Components

### Runtime and control

- [Application entry](https://github.com/oracle/karpenter-provider-oci/blob/main/cmd/main.go): `cmd/main.go`
- [Operator wiring](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/operator/operator.go): `pkg/operator/operator.go`
- [Controller registration](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/controllers/controllers.go): `pkg/controllers/controllers.go`
- [Metrics](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/metrics/metrics.go): `pkg/metrics/metrics.go`

### Scheduling and launch

- [Cloud provider](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/cloudprovider/cloud_provider.go): `pkg/cloudprovider/cloud_provider.go`
- [Instance lifecycle](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/instance/provider.go): `pkg/providers/instance/provider.go`
- [Instance types](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/instancetype/provider.go): `pkg/providers/instancetype/provider.go`
- [Placement proposals](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/placement/provider.go): `pkg/providers/placement/provider.go`

### OCI resource management

- [OCI clients](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/oci/client.go): `pkg/oci/client.go`
- [NodeClass API](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/apis/v1beta1/ocinodeclass_types.go): `pkg/apis/v1beta1/ocinodeclass_types.go`
- [NodeClass reconciliation](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/controllers/nodeclasses/ocinodeclass_controller.go): `pkg/controllers/nodeclasses/ocinodeclass_controller.go`
- [Image provider](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/image/provider.go): `pkg/providers/image/provider.go`
- [Network provider](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/network/provider.go): `pkg/providers/network/provider.go`
- [Capacity reservations](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/capacityreservation/provider.go): `pkg/providers/capacityreservation/provider.go`

### Fleet feedback

- [Capacity discovery](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/providers/capacitydiscovery/provider.go): `pkg/providers/capacitydiscovery/provider.go`
- [Discovery controller](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/controllers/capacitydiscovery/controller.go): `pkg/controllers/capacitydiscovery/controller.go`
- [Orphan cleanup](https://github.com/oracle/karpenter-provider-oci/blob/main/pkg/controllers/orphaninstance/controller.go): `pkg/controllers/orphaninstance/controller.go`

### Other components

- **Workloads**
- **Kubernetes API**
- **Oracle Cloud**

## Connections

- Workloads → Cloud provider: trigger provisioning
- Cloud provider → Instance types: select types (evidence: `pkg/cloudprovider/cloud_provider.go`)
- Cloud provider → Instance lifecycle: manage instances (evidence: `pkg/cloudprovider/cloud_provider.go`)
- Cloud provider → Placement proposals: request placement
- Instance lifecycle → OCI clients: call OCI
- OCI clients → Oracle Cloud: access services
- Application entry → Operator wiring: create operator (evidence: `cmd/main.go`)
- Application entry → Cloud provider: construct provider (evidence: `cmd/main.go`)
- Application entry → Controller registration: register controllers (evidence: `cmd/main.go`)
- Operator wiring → OCI clients: create clients (evidence: `pkg/operator/operator.go`)
- Operator wiring → Instance lifecycle: initialize provider (evidence: `pkg/operator/operator.go`)
- Operator wiring → Instance types: initialize provider
- Controller registration → NodeClass reconciliation: register (evidence: `pkg/controllers/controllers.go`)
- Controller registration → Discovery controller: register (evidence: `pkg/controllers/controllers.go`)
- Controller registration → Orphan cleanup: register (evidence: `pkg/controllers/controllers.go`)
- NodeClass reconciliation → Image provider: resolve images (evidence: `pkg/controllers/nodeclasses/ocinodeclass_controller.go`)
- NodeClass reconciliation → Network provider: resolve networking (evidence: `pkg/controllers/nodeclasses/ocinodeclass_controller.go`)
- NodeClass reconciliation → Capacity reservations: resolve reservations (evidence: `pkg/controllers/nodeclasses/ocinodeclass_controller.go`)
- NodeClass reconciliation → NodeClass API: reconcile resource (evidence: `pkg/controllers/nodeclasses/ocinodeclass_controller.go`)
- Discovery controller → Cloud provider: read node claims (evidence: `pkg/controllers/capacitydiscovery/controller.go`)
- Discovery controller → Capacity discovery: record capacity (evidence: `pkg/controllers/capacitydiscovery/controller.go`)
- Capacity discovery → Instance types: inform sizing
- Orphan cleanup → Cloud provider: list and delete (evidence: `pkg/controllers/orphaninstance/controller.go`)
- Cloud provider → Metrics: record metrics
- Workloads → Cloud provider: deprovision unused nodes
- Workloads → Cloud provider: consolidate fleet
