# aws/credentials-fetcher architecture

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

- Interactive diagram: https://gitdiagram.com/aws/credentials-fetcher
- Repository: https://github.com/aws/credentials-fetcher

## Overview

##### Project Type and Purpose
- This is a Linux system daemon (credentials-fetcher) written in C++ that exposes a gRPC API over a Unix domain socket to retrieve and renew group Managed Service Account (gMSA) Kerberos credentials from Active Directory (AD).
- It runs as a systemd service (daemon), integrates with AWS Secrets Manager (in domainless mode), and is used by containers (e.g., on ECS/Fargate) to obtain Kerberos tickets for AD authentication.

##### High-Level File-Structure Analysis
- api/              ⇨ gRPC service implementation (credentialsfetcher.proto, service handlers, integration tests)
- daemon/           ⇨ main event loop, gRPC server bootstrap
- auth/             ⇨ Kerberos logic (kinit, ticket cache management), UTF-16 decoding plugin
- renewal/          ⇨ lease renewal logic, periodic refresh of Kerberos tickets
- metadata/         ⇨ metadata fetching/parsing from AD (LDAP)
- configuration/    ⇨ loading & templating of config (krb5.conf, paths, env vars)
- common/           ⇨ shared utilities, constants, error handling
- cdk/              ⇨ AWS CDK stacks & scripts for infra (Domain Controllers, ECS tasks)
- setup-scripts/, package/, sample/ ⇒ installation, packaging, example usage

##### Key Runtime Components
- Systemd Service / CLI: starts credentials-fetcherd (daemon mode) or standalone for dev.
- Unix Domain Socket (default: CF_UNIX_DOMAIN_SOCKET_DIR/credentials_fetcher.sock)
- gRPC Server / API Layer: exposes AddKerberosLease, Renew, Delete methods.
- Core Daemon Layer: orchestrates request → modules → response.
- Configuration Module: reads env vars and config templates (`configuration/`).
- Auth Module: calls MIT Kerberos (`kinit`) with credentialspec or via AWS SM secrets.
- Metadata Module: contacts AD via LDAP to retrieve or validate service account info.
- Renewal Module: schedules and invokes renewals before ticket expiry.
- Storage (Filesystem): Kerberos ticket cache directory (`CF_KRB_DIR`) for each lease.
- Logging: writes to `CF_LOGGING_DIR`, viewable via `journalctl -u credentials-fetcher`.
- External Services:
- Active Directory Domain Controllers (LDAP/Kerberos)
- AWS Secrets Manager (domainless mode)
- AWS ECS / Fargate runtime

##### Interactions and Data Flow
- Client (container or CLI) calls gRPC endpoint over Unix socket.
- gRPC server parses request, forwards to Core Daemon dispatch.
- Core reads configuration (paths, env vars).
- Depending on mode:
- Domain-joined: Metadata Module verifies AD config, then Auth Module calls `kinit` with gMSA account.
- Domainless: Auth Module fetches username/password & DN from AWS Secrets Manager, then calls `kinit`.
- Auth Module writes Kerberos credentials to `<CF_KRB_DIR>/<lease_id>/<account>/krb5cc`.
- Renewal Module schedules periodic renew calls via same Auth Module.
- Core returns lease_id and file paths to client.
- Client can later call Delete to clean up files.

##### Architectural Patterns and Principles
- Layered modular architecture: API → Core → Modules (Config, Auth, Metadata, Renewal) → OS/Network.
- Plugin-style integration: UNIX domain socket endpoint, MIT Kerberos, AWS SM plugin.
- Single-process, event-driven daemon, managed by systemd.
- Clear separation: service API vs business logic vs infra integrations.

##### Detail Level and Component Breakdown
- Drill into each module sufficiently to show its responsibility.
- Essential architectural elements: gRPC interface, core dispatcher, modular services, external dependencies, data flow, scheduling loop.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client and transport
    gRPC_Client["gRPC Client (CLI/Container)"]:::external
    UnixSocket["Unix Domain Socket"]:::internal
    gRPC_Client -->|"AddKerberosLease RPC"| UnixSocket

    %% Daemon and layers
    subgraph "Daemon Process" 
        direction TB
        API_Layer["gRPC API Layer"]:::internal
        Core_Dispatcher["Core Dispatcher"]:::internal
        subgraph "Modules"
            direction TB
            Config_Metadata["Config & Metadata Module"]:::internal
            Auth_Module["Auth / kinit Engine"]:::internal
            Renewal_Module["Renewal Scheduler"]:::internal
            Common_Utils["Common Utilities"]:::internal
        end
    end

    UnixSocket -->|"RPC Request"| API_Layer
    API_Layer -->|"dispatch()"| Core_Dispatcher
    Core_Dispatcher -->|"load config"| Config_Metadata
    Core_Dispatcher -->|"invoke auth"| Auth_Module
    Core_Dispatcher -->|"schedule renew"| Renewal_Module
    Core_Dispatcher -->|"utilities"| Common_Utils

    %% Module interactions
    Auth_Module -->|"kinit invocation"| Filesystem
    Auth_Module -->|"LDAP bind/search"| ActiveDirectory
    Auth_Module -->|"Secrets fetch"| AWS_SM
    Renewal_Module -->|"renew() calls"| Auth_Module
    Config_Metadata -->|"reads env/LDAP"| ActiveDirectory
    Common_Utils -->|"logging API"| Logging

    %% Data stores and logging
    Filesystem["Filesystem (CF_KRB_DIR)"]:::storage
    Logging["Logging (CF_LOGGING_DIR)"]:::storage

    %% External systems
    ActiveDirectory["Active Directory (LDAP/Kerberos)"]:::external
    AWS_SM["AWS Secrets Manager"]:::external
    AWS_ECS["AWS ECS / Fargate"]:::external
    AWS_CDK["AWS CDK Infra"]:::infra

    %% External flows
    gRPC_Client -->|"runs on"| AWS_ECS
    AWS_CDK -->|"provisions infra"| AWS_ECS

    %% Click events
    click API_Layer "https://github.com/aws/credentials-fetcher/tree/mainline/api/"
    click Core_Dispatcher "https://github.com/aws/credentials-fetcher/blob/mainline/daemon/src/daemon.cpp"
    click Config_Metadata "https://github.com/aws/credentials-fetcher/blob/mainline/configuration/src/config.cpp"
    click Auth_Module "https://github.com/aws/credentials-fetcher/blob/mainline/auth/kerberos/src/krb.cpp"
    click Auth_Module "https://github.com/aws/credentials-fetcher/blob/mainline/auth/kinit_client/kinit.c"
    click Config_Metadata "https://github.com/aws/credentials-fetcher/blob/mainline/metadata/src/metadata.cpp"
    click Renewal_Module "https://github.com/aws/credentials-fetcher/blob/mainline/renewal/src/renewal.cpp"
    click Common_Utils "https://github.com/aws/credentials-fetcher/blob/mainline/common/util.hpp"
    click AWS_CDK "https://github.com/aws/credentials-fetcher/tree/mainline/cdk/"

    %% Styling
    classDef internal fill:#E0F7FA,stroke:#00838F,stroke-width:1px
    classDef external fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef storage fill:#ECEFF1,stroke:#455A64,stroke-width:1px,stroke-dasharray: 5 5
    classDef infra fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px
```
