# toctoc/kubernetes-action architecture

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

- Interactive diagram: https://gitdiagram.com/toctoc/kubernetes-action
- Repository: https://github.com/toctoc/kubernetes-action

## Overview

##### Project type and purpose
- This is an open-source GitHub Action (“kubernetes-action”) that wraps `kubectl` (and optionally AWS EKS credentials) in a Docker container.
- Its purpose is to let users run arbitrary `kubectl` commands against a Kubernetes cluster (including EKS) as a step in a GitHub workflow.

##### File structure
- Top-level files:
- Dockerfile – builds the container image with `kubectl` (and AWS CLI) installed
- entrypoint.sh – the shell script that decodes secrets, invokes `kubectl`, and returns output
- action.yml – metadata for the GitHub Action (inputs, outputs, runs-on specification)
- README.md – documentation
- No frontend/backend split; this is a single containerized CLI tool.
- No microservices or multiple modules. The container is the sole deployment unit.

##### Extract architectural insights from the README
- Inputs: `KUBE_CONFIG_DATA` (base64 kubeconfig), plus optional AWS creds for EKS
- Workflow integration: users include this action in a job step after checkout (and optional AWS credentials action)
- Outputs: the action captures stdout from `kubectl` and returns it as the `result` output variable

a. Main Components
1. GitHub Actions Runner – the VM/container that hosts the workflow steps
2. Jberlinsky/kubernetes-action Container – built from Dockerfile, includes `kubectl` & entrypoint.sh
3. Kubernetes Cluster (generic) or AWS EKS Control Plane – the target API server
4. (Optional) AWS IAM / AWS STS – for EKS authentication when AWS creds are provided
5. GitHub Secrets Store – holds `KUBE_CONFIG_DATA`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`

b. Relationships & Interactions
- Developer pushes code → GitHub Events → GitHub Actions Runner spins up
- Runner retrieves secrets from GitHub Secrets and injects them as environment variables into the container
- Runner invokes the Action container, running entrypoint.sh with the user-supplied `args`
- entrypoint.sh decodes `KUBE_CONFIG_DATA` to `$HOME/.kube/config`, invokes AWS CLI (if EKS), then calls `kubectl`
- `kubectl` sends HTTPS requests to the Kubernetes API server (generic or EKS control plane)
- Runner captures stdout/stderr of `kubectl`, maps it to the action’s `result` output
- Downstream steps in the workflow can reference `${{ steps.<id>.outputs.result }}`

c. Architectural patterns & principles
- Containerized CLI as a reusable GitHub Action
- Single responsibility: one action focuses solely on running `kubectl` commands
- Declarative interface via `action.yml` inputs/outputs
- Secure secret management via GitHub’s secrets injection

d. Key technologies/frameworks
- Docker
- GitHub Actions toolkit (action.yml, metadata syntax)
- bash shell scripting (entrypoint.sh)
- kubectl
- AWS CLI (for EKS integration)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "GitHub Platform"
        GHEvents["GitHub Events"]:::github
        GHRunner["GitHub Actions Runner"]:::github
        Secrets["GitHub Secrets Store"]:::github
    end

    GHEvents --> GHRunner
    Secrets -->|inject KUBE_CONFIG_DATA & AWS creds| GHRunner

    GHRunner -->|invokes action| ContainerImg

    subgraph "kubernetes-action Docker Container"
        ContainerImg["Docker Container"]:::container
        Dockerfile["Dockerfile"]:::config
        Entrypoint["entrypoint.sh"]:::script
        ActionYML["action.yml"]:::config
        Docs["README.md"]:::doc
    end

    ContainerImg -->|built from| Dockerfile
    ContainerImg -->|metadata| ActionYML
    ContainerImg -->|startup| Entrypoint
    ContainerImg -->|docs| Docs

    Entrypoint -->|decode KUBE_CONFIG_DATA to $HOME/.kube/config| ConfigFile["$HOME/.kube/config"]:::note
    Entrypoint -->|optional AWS CLI auth| AWS["AWS IAM / AWS STS"]:::aws
    Entrypoint -->|invoke| Kubectl["kubectl"]:::container

    Kubectl -->|HTTPS requests| K8s["Kubernetes API Server"]:::k8s
    Kubectl -->|stdout/stderr → result output| GHRunner

    classDef github fill:#0366d6,stroke:#0366d6,color:#fff;
    classDef container fill:#2ea44f,stroke:#2ea44f,color:#fff;
    classDef aws fill:#ff9900,stroke:#ff9900,color:#fff;
    classDef k8s fill:#663399,stroke:#663399,color:#fff;
    classDef config fill:#94d3a2,stroke:#94d3a2,color:#000;
    classDef script fill:#d73a49,stroke:#d73a49,color:#fff;
    classDef doc fill:#f6f8fa,stroke:#c6cbd1,color:#000;
    classDef note fill:#e1e4e8,stroke:#e1e4e8,color:#000;

    click Dockerfile "https://github.com/toctoc/kubernetes-action/tree/desarrollo/Dockerfile"
    click ActionYML "https://github.com/toctoc/kubernetes-action/blob/desarrollo/action.yml"
    click Entrypoint "https://github.com/toctoc/kubernetes-action/blob/desarrollo/entrypoint.sh"
    click Docs "https://github.com/toctoc/kubernetes-action/blob/desarrollo/README.md"
```
