# twingate/kubernetes-operator architecture

> Architecture diagram of the GitHub repository twingate/kubernetes-operator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/twingate/kubernetes-operator
- Repository: https://github.com/twingate/kubernetes-operator

## Overview

##### Main Components

a. Kubernetes Cluster Components:
- Custom Resource Definitions (CRDs) - Found in /deploy/twingate-operator/crds/
- Operator Controller Pod
- ServiceAccount, ClusterRole, and ClusterRoleBinding
- Kubernetes API Server (external interaction)

b. Operator Internal Components:
- API Client Layer (/app/api/)
- Handlers Layer (/app/handlers/)
- Version Policy Providers (/app/version_policy_providers/)
- Resource Controllers (for each CRD)

c. External Systems:
- Twingate API
- Twingate Remote Network
- Docker Registry (for version policies)

##### External Services (right side)

Use the following representation guidelines:

- Kubernetes     |     |    Operator     |     |    External      |
- Cluster      <----->    Components    <----->    Services      |

##### Component Relationships

- CRDs → Operator Controller (watches)
- Operator Controller → Handlers (processes events)
- Handlers → API Client (makes API calls)
- API Client → Twingate API (external communication)
- Version Policy Providers → Docker Registry (version checks)

##### Detailed Component Breakdown

Specific CRDs (found in /deploy/twingate-operator/crds/):
- TwingateConnector
- TwingateGroup
- TwingateResource
- TwingateResourceAccess

Handler implementations for each:
- ConnectorHandler
- GroupHandler
- ResourceHandler
- ResourceAccessHandler
- ServiceHandler

##### Additional Elements

Supporting components:
- Configuration management (/app/settings.py)
- Utility functions (/app/utils.py)
- Error handling (/app/api/exceptions.py)

##### Deployment Context

Deployment-related elements:
- Helm chart configuration
- Security contexts
- Resource requirements
- API authentication flow

##### Notes Section

A notes section indicating:
- Required Kubernetes version (1.16+)
- API token requirements
- Remote Network prerequisites
- Version policy provider capabilities

- Nested components
- Export to standard formats (SVG/PNG)
- Text annotations

Remember to maintain a balance between detail and clarity, focusing on the architectural relationships while avoiding overwhelming technical implementation details.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Core Components Layer
    subgraph Controller["Controller Layer"]
        APIClient["API Client Layer"]:::core
        CRDCore["Custom Resource Definitions"]:::core
        ResourceHandlers["Resource Handlers"]:::core
        VersionProviders["Version Policy Providers"]:::core
    end

    %% Resource Management Layer
    subgraph ResourceManagement["Resource Management Layer"]
        ConnectorCRD["TwingateConnector CRD"]:::crd
        GroupCRD["TwingateGroup CRD"]:::crd
        ResourceCRD["TwingateResource CRD"]:::crd
        AccessCRD["TwingateResourceAccess CRD"]:::crd
    end

    %% External Integration Layer
    subgraph ExternalServices["External Integration Layer"]
        K8sAPI["Kubernetes API Server"]:::external
        TwingateCloud["Twingate Cloud Infrastructure"]:::external
        ContainerRegistry["Container Registries"]:::external
        RemoteNetworks["Remote Networks"]:::external
    end

    %% Component Interactions
    APIClient --> TwingateCloud
    CRDCore --> K8sAPI
    ResourceHandlers --> APIClient
    VersionProviders --> ContainerRegistry
    
    ConnectorCRD --> ResourceHandlers
    GroupCRD --> ResourceHandlers
    ResourceCRD --> ResourceHandlers
    AccessCRD --> ResourceHandlers
    
    TwingateCloud --> RemoteNetworks

    %% Click Events
    click APIClient "https://github.com/Twingate/kubernetes-operator/tree/main/app/api"
    click CRDCore "https://github.com/Twingate/kubernetes-operator/blob/main/app/crds.py"
    click ResourceHandlers "https://github.com/Twingate/kubernetes-operator/tree/main/app/handlers"
    click VersionProviders "https://github.com/Twingate/kubernetes-operator/tree/main/app/version_policy_providers"
    click ConnectorCRD "https://github.com/Twingate/kubernetes-operator/blob/main/deploy/twingate-operator/crds/twingate.com.twingateconnector.yaml"
    click GroupCRD "https://github.com/Twingate/kubernetes-operator/blob/main/deploy/twingate-operator/crds/twingate.com.twingategroup.yaml"
    click ResourceCRD "https://github.com/Twingate/kubernetes-operator/blob/main/deploy/twingate-operator/crds/twingate.com.twingateresources.yaml"
    click AccessCRD "https://github.com/Twingate/kubernetes-operator/blob/main/deploy/twingate-operator/crds/twingate.com.twingateresourceaccesses.yaml"

    %% Styling
    classDef core fill:#2374e1,stroke:#164b91,color:#fff
    classDef crd fill:#37b24d,stroke:#2b8a3e,color:#fff
    classDef external fill:#495057,stroke:#343a40,color:#fff
    
    %% Legend
    subgraph Legend
        CoreComponent["Core Component"]:::core
        CRDComponent["CRD Component"]:::crd
        ExternalComponent["External Service"]:::external
    end
```
