# kubeideas/linkedsecrets architecture

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

- Interactive diagram: https://gitdiagram.com/kubeideas/linkedsecrets
- Repository: https://github.com/kubeideas/linkedsecrets

## Overview

##### Project Type and Purpose
- This is a Kubernetes Operator (“Linkedsecrets”) implemented in Go using Kubebuilder.
- Purpose: Reconcile custom LinkedSecret resources in Kubernetes by fetching/updating secrets from multiple cloud secret managers (AWS SM, GCP SM, Azure Key Vault, IBM Secrets Manager).

##### High-Level File Structure Analysis
- api/v1: Go types for the LinkedSecret CRD (Custom Resource Definition).
- controllers/: The reconciliation logic for LinkedSecrets (watch loop, finalizers, provider-specific handlers).
- config/: YAML manifests for CRDs, RBAC, manager Deployment, mutating webhooks, Prometheus ServiceMonitor.
- helm/linkedsecrets: Helm chart for packaging and deploying the operator.
- main.go: Entrypoint—boots the controller manager, registers schemes.
- docs/, examples/: Usage guides and sample CR YAMLs per cloud provider.

##### README Insights
- Confirms operator’s role: synchronize Kubernetes secrets from cloud secret managers.
- Illustrates architecture in img/linkedsecrets-architecture.png (CRD → Controller → Cloud → Secret).
- Mentions supported providers and installation (via Helm or Kustomize).

a. Kubernetes Cluster boundary
- API Server with LinkedSecret CRD registered
- etcd (implicit)
b. Operator (Controller Manager Pod)
- linkedsecret-controller (single binary housing multiple reconcilers)
- Provider Handlers (AWS, GCP, Azure, IBM modules)
- Webhook server (if used)
- Metrics endpoint (ServiceMonitor)
c. Cloud Secret Managers (external systems)
- AWS Secrets Manager
- Google Secret Manager
- Azure Key Vault
- IBM Secrets Manager
d. Kubernetes Secret resources
e. Deployment & Packaging
- Helm chart / Kustomize overlays
- RBAC (ServiceAccount, Roles, ClusterRoles)
- Prometheus scraping resources

##### Relationships and Data Flows
- User applies a LinkedSecret CR → kube-apiserver.
- Controller watches for CR events → reconciliation loop.
- Reconciler fetches secret data via cloud provider APIs.
- Operator writes/updates a native Kubernetes Secret resource.
- Metrics emitted by operator → scraped by Prometheus via ServiceMonitor.
- Helm/Kustomize used to bundle & deploy CRDs, RBAC, Deployment.

##### Architectural Patterns & Design Principles
- Operator Pattern / Control Loop
- Strategy pattern for provider-specific secret fetch modules
- Declarative configuration (CRDs + Kustomize/Helm)
- Single-binary multi-reconciler design
- Separation of concerns: API types, controllers, cloud client helpers

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Legend
    subgraph "Legend"
        direction LR
        A[External Systems]:::external
        B[Operator Components]:::operator
        C[Cluster Components]:::kube
        D[(Data Stores)]:::datastore
        E[Packaging & Config]:::packaging
    end

    %% External Actor
    User["User"]:::external

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        direction TB
        APIServer["API Server\n(CRD Registered)"]:::kube
        Etcd[(etcd)]:::datastore

        subgraph "Controller Manager Pod"
            direction TB
            Main["Controller Manager\n(main.go)"]:::operator
            Reconciler["LinkedSecret Controller\n(controllers/linkedsecret_controller.go)"]:::operator
            Finalizer["Finalizer & Deletion\n(controllers/linkedsecret_finalizer.go\ncontrollers/linkedsecret_deletion.go)"]:::operator
            SecretLogic["Secret Create/Update\n(controllers/linkedsecret_new_secret.go\ncontrollers/linkedsecret_update.go)"]:::operator
            Providers["Provider Handlers"]:::operator
            AWS["AWS SM Handler\n(controllers/secret_aws.go)"]:::operator
            GCP["GCP SM Handler\n(controllers/secret_gcp.go)"]:::operator
            Azure["Azure KV Handler\n(controllers/secret_azure.go)"]:::operator
            IBM["IBM SM Handler\n(controllers/secret_ibm.go)"]:::operator
            Helpers["Shared Helpers\n(controllers/secret_helpers.go\ncontrollers/parser_helpers.go\ncontrollers/constants.go)"]:::operator
            Webhook["Webhook Server"]:::operator
            Metrics["Metrics Endpoint"]:::operator

            Providers --> AWS
            Providers --> GCP
            Providers --> Azure
            Providers --> IBM
            Reconciler --> Finalizer
            Reconciler --> SecretLogic
            Reconciler --> Providers
            Reconciler --> Helpers
            Main --> Reconciler
            Main --> Webhook
            Main --> Metrics
        end

        Secrets[(Kubernetes Secrets)]:::datastore
    end

    %% External Systems
    subgraph "Cloud Secret Managers"
        direction TB
        AWSCloud["AWS Secrets Manager"]:::external
        GCPCloud["Google Secret Manager"]:::external
        AzureCloud["Azure Key Vault"]:::external
        IBMCloud["IBM Secrets Manager"]:::external
    end

    %% Packaging and Config
    subgraph "Installation & Packaging"
        direction TB
        CRDTypes["LinkedSecret Types\n(api/v1/linkedsecret_types.go)"]:::packaging
        CRDManifest["CRD YAML\n(config/crd/bases/security.kubeideas.io_linkedsecrets.yaml)"]:::packaging
        CRDKustomize["Kustomize CRD Overlays\n(config/crd/kustomization.yaml\nconfig/crd/patches/webhook_in_linkedsecrets.yaml)"]:::packaging
        ManagerConfig["Manager Deployment\n(config/manager/manager.yaml\ncontroller_manager_config.yaml\nkustomization.yaml)"]:::packaging
        RBAC["RBAC Manifests\n(config/rbac/kustomization.yaml)"]:::packaging
        ServiceMonitor["Prometheus ServiceMonitor\n(config/prometheus/monitor.yaml)"]:::packaging
        HelmChart["Helm Chart\n(helm/linkedsecrets/Chart.yaml & templates/)"]:::packaging
        SampleCR["Sample LinkedSecret CRs\n(config/samples/security_v1_linkedsecret.yaml and examples)"]:::packaging
    end

    %% User flow
    User -->|"Create LinkedSecret CR"| APIServer
    APIServer -->|"Watch Events"| Main
    Main -->|"FetchSecret() via API"| AWSCloud
    Main -->|"FetchSecret() via API"| GCPCloud
    Main -->|"FetchSecret() via API"| AzureCloud
    Main -->|"FetchSecret() via API"| IBMCloud
    Main -->|"Update Secret"| APIServer
    APIServer -->|"Persist Secret"| Secrets
    Prometheus["Prometheus"]:::external -->|"Scrape Metrics"| Metrics

    %% Packaging flows
    HelmChart --> APIServer
    CRDManifest --> APIServer
    CRDKustomize --> CRDManifest
    ManagerConfig --> Main
    RBAC --> Main
    ServiceMonitor --> Prometheus
    CRDTypes -.-> CRDManifest
    SampleCR --> User

    %% Click Events
    click CRDTypes "https://github.com/kubeideas/linkedsecrets/blob/main/api/v1/linkedsecret_types.go"
    click CRDManifest "https://github.com/kubeideas/linkedsecrets/blob/main/config/crd/bases/security.kubeideas.io_linkedsecrets.yaml"
    click CRDKustomize "https://github.com/kubeideas/linkedsecrets/blob/main/config/crd/kustomization.yaml"
    click CRDKustomize "https://github.com/kubeideas/linkedsecrets/blob/main/config/crd/patches/webhook_in_linkedsecrets.yaml"
    click ManagerConfig "https://github.com/kubeideas/linkedsecrets/blob/main/config/manager/manager.yaml"
    click ManagerConfig "https://github.com/kubeideas/linkedsecrets/blob/main/config/manager/controller_manager_config.yaml"
    click ManagerConfig "https://github.com/kubeideas/linkedsecrets/blob/main/config/manager/kustomization.yaml"
    click RBAC "https://github.com/kubeideas/linkedsecrets/blob/main/config/rbac/kustomization.yaml"
    click ServiceMonitor "https://github.com/kubeideas/linkedsecrets/blob/main/config/prometheus/monitor.yaml"
    click Main "https://github.com/kubeideas/linkedsecrets/blob/main/main.go"
    click Reconciler "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/linkedsecret_controller.go"
    click Finalizer "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/linkedsecret_finalizer.go"
    click Finalizer "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/linkedsecret_deletion.go"
    click SecretLogic "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/linkedsecret_new_secret.go"
    click SecretLogic "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/linkedsecret_update.go"
    click AWS "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/secret_aws.go"
    click GCP "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/secret_gcp.go"
    click Azure "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/secret_azure.go"
    click IBM "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/secret_ibm.go"
    click Helpers "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/secret_helpers.go"
    click Helpers "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/parser_helpers.go"
    click Helpers "https://github.com/kubeideas/linkedsecrets/blob/main/controllers/constants.go"
    click HelmChart "https://github.com/kubeideas/linkedsecrets/blob/main/helm/linkedsecrets/Chart.yaml"
    click SampleCR "https://github.com/kubeideas/linkedsecrets/blob/main/config/samples/security_v1_linkedsecret.yaml"

    %% Styles
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef kube fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef datastore fill:#87CEEB,stroke:#333,stroke-width:1px
    classDef operator fill:#90EE90,stroke:#333,stroke-width:1px
    classDef packaging fill:#EEE8AA,stroke:#333,stroke-width:1px
```
