# jenkinsci/kubernetes-operator architecture

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

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

## Overview

##### Main Components

a. Core Components:
- Kubernetes API Server (external)
- Jenkins Operator Controller
- Jenkins Custom Resource Definition (CRD)
- Jenkins Instances (managed by the operator)
- Backup System
- Webhook Server
- Configuration Management System

b. Supporting Components:
- Notification System (with providers: Slack, MS Teams, SMTP, Mailgun)
- Monitoring/Metrics (Prometheus integration)
- Authentication/Authorization (RBAC)

##### Component Relationships

**Kubernetes API Server <--> Jenkins Operator Controller**
- (watches for Jenkins CRD changes)

- > Jenkins Instances
- (creates/updates/monitors)

- > Backup System
- (manages backup/restore operations)

- > Configuration Management
- (handles CasC and seed jobs)

- > Notification System
- (sends alerts/events)

##### Detailed Component Breakdown

Jenkins Operator Controller:
- Base Configuration (/pkg/configuration/base)
- User Configuration (/pkg/configuration/user)
- Backup/Restore (/pkg/configuration/backuprestore)
- Groovy Script Management (/pkg/groovy)
- Client Operations (/pkg/client)

Configuration Management:
- CasC Configuration
- Seed Jobs Configuration
- Plugin Management
- Security Settings

##### Key Interactions to Highlight

a. Control Flow:
- Kubernetes API Server → Operator (CRD events)
- Operator → Jenkins Instances (lifecycle management)
- Operator → Backup System (scheduled backups)
- Operator → Notification System (status updates)

b. Data Flow:
- Configuration → Jenkins Instances
- Backup Data → Storage
- Metrics → Prometheus
- Events → Notification Providers

##### Additional Elements

Supporting features:
- Webhook handling for Jenkins
- RBAC configuration
- Service accounts
- PVC management for backups
- Health/readiness probes

##### Implementation Details

Directories and their purposes:
**/api          - API definitions**
**/controllers  - Core controller logic**
**/pkg          - Main implementation**
**/backup       - Backup functionality**
**/config       - Kubernetes configurations**

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Kubernetes
        K8S[Kubernetes API Server]:::k8s
        CRD["Jenkins CRD"]:::k8s
        click CRD "https://github.com/jenkinsci/kubernetes-operator/blob/master/api/v1alpha2/jenkins_types.go"
    end

    subgraph "Jenkins Operator"
        CTRL["Jenkins Operator Controller"]:::operator
        click CTRL "https://github.com/jenkinsci/kubernetes-operator/blob/master/controllers/jenkins_controller.go"
        
        subgraph "Configuration Management"
            BASECFG["Base Configuration"]:::config
            click BASECFG "https://github.com/jenkinsci/kubernetes-operator/tree/master/pkg/configuration/base"
            USERCFG["User Configuration"]:::config
            click USERCFG "https://github.com/jenkinsci/kubernetes-operator/tree/master/pkg/configuration/user"
            CASC["Configuration as Code"]:::config
            click CASC "https://github.com/jenkinsci/kubernetes-operator/tree/master/pkg/configuration/user/casc"
            SEEDJOBS["Seed Jobs"]:::config
            click SEEDJOBS "https://github.com/jenkinsci/kubernetes-operator/tree/master/pkg/configuration/user/seedjobs"
        end

        subgraph "Backup System"
            BACKUP["Backup Controller"]:::backup
            PVC["PVC Storage"]:::backup
            click BACKUP "https://github.com/jenkinsci/kubernetes-operator/blob/master/pkg/configuration/backuprestore/backuprestore.go"
            click PVC "https://github.com/jenkinsci/kubernetes-operator/tree/master/backup/pvc"
        end

        subgraph "Client Operations"
            CLIENT["Jenkins Client"]:::client
            JOBS["Jobs Manager"]:::client
            click CLIENT "https://github.com/jenkinsci/kubernetes-operator/blob/master/pkg/client/jenkins.go"
            click JOBS "https://github.com/jenkinsci/kubernetes-operator/blob/master/pkg/client/job.go"
        end

        subgraph "Security"
            RBAC["RBAC Controller"]:::security
            SA["Service Accounts"]:::security
            click RBAC "https://github.com/jenkinsci/kubernetes-operator/blob/master/pkg/configuration/base/rbac.go"
            click RBAC "https://github.com/jenkinsci/kubernetes-operator/tree/master/config/rbac"
        end

        subgraph "Notifications"
            NOTIFY["Notification Controller"]:::notify
            SLACK["Slack Provider"]:::notify
            TEAMS["MS Teams Provider"]:::notify
            SMTP["SMTP Provider"]:::notify
            MAILGUN["Mailgun Provider"]:::notify
            click NOTIFY "https://github.com/jenkinsci/kubernetes-operator/tree/master/pkg/notifications"
            click SLACK "https://github.com/jenkinsci/kubernetes-operator/tree/master/pkg/notifications/slack"
            click TEAMS "https://github.com/jenkinsci/kubernetes-operator/tree/master/pkg/notifications/msteams"
            click SMTP "https://github.com/jenkinsci/kubernetes-operator/tree/master/pkg/notifications/smtp"
            click MAILGUN "https://github.com/jenkinsci/kubernetes-operator/tree/master/pkg/notifications/mailgun"
        end

        WEBHOOK["Webhook Server"]:::operator
        click WEBHOOK "https://github.com/jenkinsci/kubernetes-operator/tree/master/config/webhook"
    end

    subgraph "Jenkins Instances"
        JENKINS["Jenkins Pods"]:::jenkins
        PLUGINS["Plugins"]:::jenkins
        JOBS_CONFIG["Jobs Configuration"]:::jenkins
    end

    %% Relationships
    K8S <--> CRD
    CRD <--> CTRL
    CTRL --> JENKINS
    CTRL --> BACKUP
    BACKUP --> PVC
    CTRL --> NOTIFY
    NOTIFY --> SLACK & TEAMS & SMTP & MAILGUN
    CTRL --> WEBHOOK
    CTRL --> CLIENT
    CLIENT --> JOBS
    BASECFG & USERCFG --> JENKINS
    CASC & SEEDJOBS --> JENKINS
    RBAC --> SA
    SA --> JENKINS

    %% Styles
    classDef k8s fill:#326CE5,stroke:#fff,stroke-width:2px,color:#fff
    classDef operator fill:#00AA5E,stroke:#fff,stroke-width:2px,color:#fff
    classDef config fill:#FFA500,stroke:#fff,stroke-width:2px,color:#fff
    classDef backup fill:#FFFF00,stroke:#333,stroke-width:2px,color:#333
    classDef client fill:#FF7F50,stroke:#fff,stroke-width:2px,color:#fff
    classDef security fill:#FF0000,stroke:#fff,stroke-width:2px,color:#fff
    classDef notify fill:#800080,stroke:#fff,stroke-width:2px,color:#fff
    classDef jenkins fill:#D24939,stroke:#fff,stroke-width:2px,color:#fff

    %% Legend
    subgraph Legend
        L1[Kubernetes]:::k8s
        L2[Operator]:::operator
        L3[Configuration]:::config
        L4[Backup]:::backup
        L5[Client]:::client
        L6[Security]:::security
        L7[Notifications]:::notify
        L8[Jenkins]:::jenkins
    end
```
