How ilijamt/vault-plugin-secrets-gitlab works
Project Type and Purpose
• This is an open-source Vault Secrets plugin written in Go.
• It implements the Vault plugin interface to dynamically generate, rotate, and revoke GitLab access tokens (personal, project, group, service-account, deploy, pipeline tokens) on demand.
High-Level File Structure
• cmd/vault-plugin-secrets-gitlab/main.go
→ Plugin entrypoint, registers the plugin with Vault’s plugin catalog.
• backend.go
→ Bootstraps the plugin, wires up entry points, storage, periodic tasks.
• entry_*.go
→ Defines the logical “entries” (config, roles, token) that Vault calls.
• path_*.go
→ Implements the HTTP-style paths under vault://gitlab/(config|roles|token).
• gitlab_client.go / gitlab_record_client.go
→ Wrap GitLab REST API calls for token creation/revocation.
• utils.go, name_tpl.go, type_*.go
→ Helpers for templating, data types, validation.
• testdata / tests
→ Wide coverage of unit/integration tests against example YAMLs.
• local-env / examples
→ Docker-Compose and Terraform examples for manual testing.
Core Components
A. Vault Core
• Receives user requests (CLI/API).
• Sits in front of the plugin, handles auth, leases, storage backend.
B. Vault Plugin Process
• gRPC plugin served by the Go binary.
• Implements LogicalBackend interface.
C. Plugin Internal Layers
1. Entry Layer
– entry_config, entry_role, entry_token define how Vault invokes operations.
2. Path Layer
– path_config_*.go: CRUD of plugin configuration (GitLab creds, base_url, rotate).
– path_role_*.go: CRUD of roles (name, path, scopes, ttl).
– path_token_*.go: Generate tokens per role, return secrets + lease.
3. Storage Interface
– Vault passes in a Storage object; plugin reads/writes config and role metadata.
4. GitLab Client
– Makes HTTP calls to GitLab (Create Access Token, Revoke Token, Rotate Token).
– Implements retry/error handling.
5. Scheduler/Periodic
– events.go hooks a periodic function for auto-rotation of the main GitLab token.
D. External Systems
– GitLab API Server (saas/self-hosted).
– Vault Storage Backend (Consul, BoltDB, etc.) where configs and leases are persisted.
Component Relationships and Data Flows
1. User → Vault CLI/API → Vault Core
• Vault authenticates and authorizes the request.
2. Vault Core → Plugin (gRPC)
• Calls the appropriate path handler (e.g., write gitlab/config/default).
3. Plugin Path Handler → Storage
• Reads or writes config/role entries to Vault’s backend.
4. Plugin Path Handler → GitLab Client
• For token generation/revocation/rotation, issues HTTP(S) calls to GitLab.
5. GitLab API → Plugin
• Returns token credentials or revocation confirmation.
6. Plugin → Vault Core
• Returns a Secret object (includes token, metadata) and issues a lease.
7. Vault Core → User
• Responds with credentials; stores lease in Storage.
8. Periodic Auto-Rotate
• Vault scheduler invokes plugin’s periodic function → plugin calls GitLab to rotate the main token.
Architectural Patterns and Principles
• Layered Architecture (Entry → Path → Client).
• Dependency Injection (backend.go wires storage, GitLab client).
• Command Pattern for each Vault operation (each path is a command handler).
• Separation of Concerns (templating, HTTP client, Vault API, business logic).
Technologies and Frameworks
• Go (1.x modules).
• HashiCorp Vault Plugin SDK (gRPC & plugin catalog).
• GitLab REST API (HTTP + JSON).
• Vault Storage Interface (abstract key-value store).
• text/template for dynamic token naming.
Essential Elements to Capture
• Vault Core and plugin registration/handshake.
• gRPC method calls (LogicalBackend interface).
• Storage reads/writes (config & roles).
• GitLab Client interactions (create, revoke, rotate).
• Lease issuance and automatic rotation hooks.
• User interaction points (vault write/read commands).