# akka/akka-sample-cluster-kubernetes-scala architecture

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

- Interactive diagram: https://gitdiagram.com/akka/akka-sample-cluster-kubernetes-scala
- Repository: https://github.com/akka/akka-sample-cluster-kubernetes-scala

## Overview

##### Project Type and Purpose
- This is a Scala/SBT example demonstrating how to build and deploy an Akka Cluster using Kubernetes as the orchestration and discovery mechanism.
- The code lives under src/main/scala/akka/sample/cluster/kubernetes and uses Akka Cluster Bootstrap + Kubernetes API discovery to form a dynamic cluster inside Kubernetes pods.

##### File-Structure Analysis
- Top‐level SBT build files: build.sbt, project/plugins.sbt (includes Docker/SBT plugin).
- kubernetes/: YAML manifests for namespace, Deployment, Service.
- scripts/: helper scripts for Minikube and Docker Desktop workflows.
- src/main/resources: application.conf (Akka settings), logback.xml.
- src/main/scala/akka/sample/cluster/kubernetes: DemoApp.scala (actor system + HTTP endpoint), DemoHealthCheck.scala (health check actor).

##### Key Architectural Patterns
- Micro-service pods running a reactive Akka ActorSystem in cluster mode.
- Akka Cluster Bootstrap with Kubernetes API discovery (no static seed nodes).
- Side effect: HTTP interface (port 8080) for “hello world” plus Management HTTP (port 8558) for cluster status.

##### Main Components
a. CI/Build Pipeline
- SBT Build → Docker Image → Docker Registry
b. Kubernetes Cluster
- Namespace (appka-1)
- Deployment “appka” (2+ replicas)
- Service (LoadBalancer on port 8080)
- Kubernetes API Server (for discovery)
c. Pod Internals (per replica)
- Container running DemoApp ActorSystem
- Akka Management HTTP endpoint (8558)
- DemoHealthCheck actor
d. External Clients
- User/browser or curl hitting Service:8080 → pods
- curl to Management port for cluster members

##### Relationships and Data Flow
- CI pushes Docker image to registry → Kubernetes pulls image.
- Kubernetes Deployment creates pods → each pod queries the Kubernetes API Server to discover peer pods.
- Pods form an Akka Cluster via Bootstrap.
- Client HTTP requests (8080) hit the Service → LoadBalancer → one of the pods → handled by DemoApp.
- Monitoring calls (8558) go directly to the pod’s Management HTTP interface.
- All pods maintain cluster gossip and message passing internally over Akka remoting ports.

## Diagram (Mermaid)

```mermaid
graph TB
    %% CI / Build Pipeline
    subgraph "CI/Build Pipeline"
        SBT["SBT Build"]:::external
        Plugins["SBT Plugins"]:::external
        BuildProps["SBT Version"]:::external
        CIConfig["CI Configuration"]:::external
        SBT -->|build| Plugins
    end

    %% Docker Registry
    DockerRegistry["Docker Registry"]:::registry

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        subgraph "Control Plane"
            K8sAPI["Kubernetes API Server"]:::k8s
        end

        subgraph "appka-1 Namespace"
            NamespaceRes["Namespace Manifest"]:::k8s
            DeploymentYAML["Deployment & Service"]:::k8s

            DockerRegistry -->|image pull| DeploymentYAML
            DeploymentYAML -->|creates pods| Pods

            subgraph "Pods" 
                direction TB
                subgraph "Pod Replica 1"
                    DemoApp1["DemoApp (HTTP 8080)\nActorSystem"]:::akka
                    Mgmt1["Akka Mgmt HTTP (8558)"]:::akka
                    Health1["DemoHealthCheck"]:::akka
                    DemoApp1 -->|management| Mgmt1
                    DemoApp1 -->|health| Health1
                    Mgmt1 -->|cluster join| K8sAPI
                end
                subgraph "Pod Replica 2"
                    DemoApp2["DemoApp (HTTP 8080)\nActorSystem"]:::akka
                    Mgmt2["Akka Mgmt HTTP (8558)"]:::akka
                    Health2["DemoHealthCheck"]:::akka
                    DemoApp2 -->|management| Mgmt2
                    DemoApp2 -->|health| Health2
                    Mgmt2 -->|cluster join| K8sAPI
                end

                %% Cluster gossip between replicas
                DemoApp1 --- DemoApp2
            end

            ServiceLB["Service (LoadBalancer) :8080"]:::k8s
            Pods -->|pod IPs| ServiceLB
            K8sAPI -.->|discovery| Mgmt1
            K8sAPI -.->|discovery| Mgmt2
        end
    end

    %% Clients and Monitoring
    User["User / curl"]:::external
    Monitor["Monitoring Client"]:::external
    User -->|HTTP 8080| ServiceLB
    Monitor -->|HTTP 8558| Mgmt1
    Monitor -->|HTTP 8558| Mgmt2

    %% Scripts
    subgraph "Scripts"
        SetupMini["setup-minikube-for-linux.sh"]:::external
        TestDocker["test_docker_desktop.sh"]:::external
        TestGeneric["test.sh"]:::external
    end

    %% Resources
    subgraph "Resources"
        Conf["application.conf"]:::external
        Logback["logback.xml"]:::external
    end

    %% Repo Root Files
    subgraph "Repo Root Files"
        License["LICENSE"]:::external
        Readme["README.md"]:::external
        Gitignore[".gitignore"]:::external
    end

    %% Connections outside
    Plugins -->|configure docker| DockerRegistry
    BuildProps --> Plugins
    CIConfig --> SBT

    %% Click Events
    click SBT "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/build.sbt"
    click Plugins "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/project/plugins.sbt"
    click BuildProps "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/project/build.properties"
    click CIConfig "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/.travis.yml"
    click NamespaceRes "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/kubernetes/namespace.json"
    click DeploymentYAML "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/kubernetes/akka-cluster.yml"
    click SetupMini "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/scripts/setup-minikube-for-linux.sh"
    click TestDocker "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/scripts/test_docker_desktop.sh"
    click TestGeneric "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/scripts/test.sh"
    click Conf "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/src/main/resources/application.conf"
    click Logback "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/src/main/resources/logback.xml"
    click DemoApp1 "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/src/main/scala/akka/sample/cluster/kubernetes/DemoApp.scala"
    click DemoApp2 "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/src/main/scala/akka/sample/cluster/kubernetes/DemoApp.scala"
    click Health1 "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/src/main/scala/akka/sample/cluster/kubernetes/DemoHealthCheck.scala"
    click Health2 "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/src/main/scala/akka/sample/cluster/kubernetes/DemoHealthCheck.scala"
    click License "https://github.com/akka/akka-sample-cluster-kubernetes-scala/tree/master/LICENSE"
    click Readme "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/README.md"
    click Gitignore "https://github.com/akka/akka-sample-cluster-kubernetes-scala/blob/master/.gitignore"

    %% Styles
    classDef k8s fill:#D0E7FF,stroke:#0044CC,stroke-width:1px
    classDef akka fill:#FFDAB9,stroke:#FF8C00,stroke-width:1px
    classDef external fill:#E6FFEA,stroke:#2E8B57,stroke-width:1px
    classDef registry fill:#F0F0F0,stroke:#555555,stroke-width:1px
```
