How aws/credentials-fetcher works
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.