# lerentis/bitwarden-crd-operator architecture

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

- Interactive diagram: https://gitdiagram.com/lerentis/bitwarden-crd-operator
- Repository: https://github.com/lerentis/bitwarden-crd-operator

## Overview

##### Project type and purpose
- This is a Kubernetes Operator (open-source tool) written in Python.
- It leverages Kopf (Kubernetes Operator Pythonic Framework) to watch custom resources (CRDs) and automatically generate native Kubernetes Secret objects from Bitwarden entries.
- It ships as a Helm chart for easy deployment in any Kubernetes cluster.

##### File structure
- Top-level files: Dockerfile, Makefile, requirements.txt, skaffold.yaml, Helm chart under `charts/bitwarden-crd-operator`, plus CI/CD configs (.drone.yml, GitHub workflows).
- `src/`: contains the core operator logic
- bitwardenCrdOperator.py – main controller registration and event handlers
- dockerlogin.py – logic for RegistryCredential CRD → .dockerconfigjson secrets
- kv.py – general key/value helper
- lookups/bitwarden_lookup.py – implements bitwarden_lookup for Jinja2 templates
- template.py – implements BitwardenTemplate functionality
- utils/utils.py – shared utility functions
- `charts/bitwarden-crd-operator/`: Helm chart, CRD definitions, Kubernetes resources (Deployment, RBAC, HPA, ServiceAccount, etc.)
- Example YAMLs demonstrating how to instantiate CRDs

##### README for additional insights
- Describes three CRD kinds: BitwardenSecret, RegistryCredential, BitwardenTemplate
- Explains how the operator uses the bitwarden CLI for background sync and login intervals
- Shows desired resulting Kubernetes Secret manifests and how Jinja2 templates are rendered

##### Essential architectural elements
- Helm’s initial setup steps (CRD and Deployment) separate from runtime
- Configuration parameters (BW_SYNC_INTERVAL, BW_RELOGIN_INTERVAL) as operator env vars

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Packaging Layer
    subgraph "Packaging (Helm)" 
        direction TB
        HelmChart["Helm Chart"]:::helm
        ChartYAML["Chart.yaml"]:::helm
        ValuesYAML["values.yaml"]:::helm
        CRDs["CRD Definitions"]:::helm
        Templates["Manifest Templates"]:::helm
    end

    %% Control Plane
    subgraph "Kubernetes Control Plane"
        direction TB
        KubeAPI["API Server"]:::control
        Etcd["etcd Database"]:::control
    end

    %% Operator Runtime
    subgraph "Operator Pod" 
        direction TB
        OperatorContainer["Operator Container"]:::operator
        BWCLI["bitwarden CLI"]:::operator
        subgraph "Operator Code" 
            direction TB
            Controller["Operator Controller"]:::operator
            DockerLogin["DockerRegistry Handler"]:::operator
            KVHelper["Key/Value Helper"]:::operator
            BWLookup["Bitwarden Lookup"]:::operator
            TemplateMod["Template Renderer"]:::operator
            Utils["Shared Utilities"]:::operator
        end
    end

    %% External System
    BitwardenSvc["Bitwarden Service"]:::external

    %% Relationships
    HelmChart -->|"install CRDs & Deployment"| KubeAPI
    KubeAPI -->|"watch events (Kopf)"| OperatorContainer
    OperatorContainer -->|"invoke CLI"| BWCLI
    BWCLI -->|"bw sync/get"| BitwardenSvc
    OperatorContainer -->|"create/update secrets"| KubeAPI
    KubeAPI -->|"persist"| Etcd

    %% Click Events
    click Controller "https://github.com/lerentis/bitwarden-crd-operator/blob/main/src/bitwardenCrdOperator.py"
    click DockerLogin "https://github.com/lerentis/bitwarden-crd-operator/blob/main/src/dockerlogin.py"
    click KVHelper "https://github.com/lerentis/bitwarden-crd-operator/blob/main/src/kv.py"
    click BWLookup "https://github.com/lerentis/bitwarden-crd-operator/blob/main/src/lookups/bitwarden_lookup.py"
    click TemplateMod "https://github.com/lerentis/bitwarden-crd-operator/blob/main/src/template.py"
    click Utils "https://github.com/lerentis/bitwarden-crd-operator/blob/main/src/utils/utils.py"
    click HelmChart "https://github.com/lerentis/bitwarden-crd-operator/tree/main/charts/bitwarden-crd-operator"
    click ChartYAML "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/Chart.yaml"
    click ValuesYAML "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/values.yaml"
    click CRDs "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/crds/bitwarden-secrets.yaml"
    click CRDs "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/crds/bitwarden-templates.yaml"
    click CRDs "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/crds/registry-credentials.yaml"
    click Templates "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/templates/deployment.yaml"
    click Templates "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/templates/clusterrole.yaml"
    click Templates "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/templates/rolebinding.yaml"
    click Templates "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/templates/serviceaccount.yaml"
    click Templates "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/templates/hpa.yaml"
    click Templates "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/templates/_helpers.tpl"
    click Templates "https://github.com/lerentis/bitwarden-crd-operator/blob/main/charts/bitwarden-crd-operator/templates/NOTES.txt"
    click OperatorContainer "https://github.com/lerentis/bitwarden-crd-operator/tree/main/Dockerfile"

    %% Styles
    classDef helm fill:#D8BFD8,stroke:#9370DB,color:#000
    classDef control fill:#ADD8E6,stroke:#1E90FF,color:#000
    classDef operator fill:#90EE90,stroke:#32CD32,color:#000
    classDef external fill:#FFDAB9,stroke:#FF8C00,color:#000
```
