# openservicemesh/osm architecture

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

- Interactive diagram: https://gitdiagram.com/openservicemesh/osm
- Repository: https://github.com/openservicemesh/osm

## Overview

##### Project Type & Purpose
- OSM is a Kubernetes-native service mesh that builds a control plane around Envoy sidecar proxies to enable mTLS, traffic policies, observability, and secure inter-service communication.
- The project is composed of multiple executable components (e.g. CLI, bootstrap, controller, injector, healthcheck) that work together with Kubernetes and SMI resources.

##### Analyzing the File Structure
- Notice the “cmd” directory with subdirectories for different executables (e.g., “osm-bootstrap”, “osm-controller”, “osm-healthcheck”, “osm-injector”, “osm-preinstall”, and “cli”) – these represent the primary runtime components.
- The “pkg” directory contains core libraries and modules for certificate management, policy enforcement, Envoy configuration generation, Kubernetes interactions, debugging, reconciliation, and more.
- The “charts” directory hosts Helm charts for deployment, indicating that OSM is installed on Kubernetes.
- Directories such as “docs”, “demo”, and “tests” support documentation, demonstration apps (like the bookstore demo), and end-to-end testing respectively.
- Several configuration files (e.g., Dockerfiles, Tiltfile, CI/CD workflows) indicate integration with container build/deployment pipelines.

a. Main Components:
- OSM Control Plane: Represent the control plane comprising the main executables (e.g., osm-controller, osm-bootstrap, osm-healthcheck, etc.). Emphasize that these orchestrate proxy configuration and enforce policies.
- CLI: The osm CLI used by operators to interact with the mesh.
- Certificate Management: Modules under “pkg/certificate” and the different provider implementations (e.g., certmanager, tresor, vault) should be depicted.
- Envoy Sidecars: Illustrate the injected Envoy sidecar proxies that live alongside application pods. They handle traffic routing, mTLS termination, and observability.
- Injector: Show the component that automatically injects the sidecars into application workloads.
- SMI Interfaces: Include the Service Mesh Interface APIs (TrafficTarget, HTTPRouteGroup, TCPRoute, TrafficSplit, etc.) that offer an abstraction for traffic policies.
- External Integrations: Add external systems (e.g., external certificate authorities, observability dashboards, Kafka, or Vault as seen in the demo scripts) and how they integrate with OSM.

b. Relationships & Interactions:
- How the Injector intercepts application deployments and adds the sidecars.
- How the Certificate Management component supplies mTLS certificates to both the sidecars and control plane.
- How SMI resources (CRDs) in Kubernetes are consumed by the control plane to update policies and routing rules.
- Feedback loops such as health checks (osm-healthcheck) and debugging endpoints.

c. Architectural Patterns & Design Principles:
- Microservices architecture within the control plane that utilizes composability and modularity.
- Use of Kubernetes APIs, CRDs, and controllers as part of the reconciliation loop pattern.
- Call out the layered design where the control plane operates at a higher configuration layer while Envoy sidecars handle data plane traffic.
- Integration of CI/CD, Helm deployment (via charts), and container orchestration.

d. Mention Key Technologies, Frameworks, and Libraries:
- Go (primary language) – building the executables.
- Envoy Proxy (as the sidecar).
- Kubernetes (as target deployment platform) with CRDs for SMI.
- Helm (for deployment charts).
- Certificate providers such as cert-manager, Tresor, and Vault.
- CI/CD integration with GitHub Actions and Docker.

##### Specific Elements
- Clearly labeled components (CLI, controller, bootstrap, injector, healthcheck, certificate manager, etc.).
- If possible, also include a note on how upgrades and health checks are managed since tests and healthcheck modules are prominent in the file structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Entry: CLI
    A["CLI"]:::cli

    %% OSM Control Plane Subgraph with executables
    subgraph "OSM Control Plane"
        B["osm-bootstrap"]:::control
        C["osm-controller"]:::control
        D["osm-healthcheck"]:::control
        E["osm-preinstall"]:::control
    end

    %% Certificate Management Subgraph
    subgraph "Certificate Management"
        F["Certificate Core"]:::certificate
        F1["Certificate Providers"]:::certificate
    end
    F -->|"includes"| F1

    %% Injector Subgraph
    subgraph "Injector"
        G["Injector CLI"]:::injector
        G1["Injector Library"]:::injector
    end
    G -->|"uses"| G1

    %% Envoy Sidecars Subgraph
    subgraph "Envoy Sidecars"
        H["Envoy Base"]:::envoy
        H1["Envoy Bootstrap"]:::envoy
    end
    H1 -->|"initializes"| H

    %% Other Components
    I["SMI Interfaces"]:::smi
    J["Kubernetes Cluster (Data Plane)"]:::k8s
    K["External Integrations (Helm)"]:::external

    %% Connections
    A -->|"commands"| C
    C -->|"fetchesCerts"| F
    C -->|"readsSMI"| I
    C -->|"triggersInject"| G
    G -->|"injectsSidecar"| H1
    C -->|"updatesEnvoy"| H
    F -->|"suppliesCerts"| H
    J -->|"sendsEvents"| C
    J -->|"hostsSMI"| I
    J -->|"runsPods"| H
    K -->|"deploysOSM"| C

    %% Class Definitions with Colors
    classDef control fill:#a2d9ff,stroke:#000,stroke-width:2px;
    classDef cli fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef certificate fill:#c3f7c9,stroke:#000,stroke-width:2px;
    classDef injector fill:#f7c6c7,stroke:#000,stroke-width:2px;
    classDef envoy fill:#d2dae2,stroke:#000,stroke-width:2px;
    classDef smi fill:#f0e68c,stroke:#000,stroke-width:2px;
    classDef k8s fill:#c8e6c9,stroke:#000,stroke-width:2px;
    classDef external fill:#d1c4e9,stroke:#000,stroke-width:2px;

    %% Click Events
    click A "https://github.com/openservicemesh/osm/tree/main/cmd/cli"
    click B "https://github.com/openservicemesh/osm/tree/main/cmd/osm-bootstrap"
    click C "https://github.com/openservicemesh/osm/tree/main/cmd/osm-controller"
    click D "https://github.com/openservicemesh/osm/tree/main/cmd/osm-healthcheck"
    click E "https://github.com/openservicemesh/osm/tree/main/cmd/osm-preinstall"
    click F "https://github.com/openservicemesh/osm/tree/main/pkg/certificate"
    click F1 "https://github.com/openservicemesh/osm/tree/main/pkg/certificate/providers"
    click G "https://github.com/openservicemesh/osm/tree/main/cmd/osm-injector"
    click G1 "https://github.com/openservicemesh/osm/tree/main/pkg/injector"
    click H "https://github.com/openservicemesh/osm/tree/main/pkg/envoy"
    click H1 "https://github.com/openservicemesh/osm/tree/main/pkg/envoy/bootstrap"
    click I "https://github.com/openservicemesh/osm/tree/main/pkg/smi"
    click J "https://github.com/openservicemesh/osm/tree/main/pkg/k8s"
    click K "https://github.com/openservicemesh/osm/tree/main/charts/osm"
```
