# ilijamt/vault-plugin-secrets-gitlab architecture

> Architecture diagram of the GitHub repository ilijamt/vault-plugin-secrets-gitlab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ilijamt/vault-plugin-secrets-gitlab
- Repository: https://github.com/ilijamt/vault-plugin-secrets-gitlab

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global Entities
    User["User"]:::external
    VaultCore["Vault Core"]:::vaultCore
    VaultStorage["Vault Storage Backend"]:::storage
    GitLabAPI["GitLab API Server"]:::gitlab

    %% Plugin Process Subgraph
    subgraph "Vault GitLab Plugin Process"
        direction TB
        Entrypoint["Plugin Entrypoint"]:::plugin
        Backend["Plugin Bootstrap & Wiring"]:::plugin
        subgraph "Entry Layer"
            direction TB
            EntryConfig["Configuration Entry"]:::plugin
            EntryRole["Role Entry"]:::plugin
            EntryToken["Token Entry"]:::plugin
        end
        subgraph "Path Layer"
            direction TB
            PathConfig["Config CRUD Paths"]:::plugin
            PathRole["Role CRUD Path"]:::plugin
            PathToken["Token Generation Path"]:::plugin
        end
        StorageInterface["Storage Interface"]:::plugin
        GitLabClient["GitLab Client"]:::plugin
        Scheduler["Scheduler / Periodic Tasks"]:::plugin
        subgraph "Helpers & Types"
            direction TB
            SecretTypes["Secret Type Definitions"]:::helper
            Helpers["Shared Helpers & Utilities"]:::helper
            DataTypes["Data Type Definitions"]:::helper
            Defs["Global Definitions & Constants"]:::helper
        end
    end

    %% Connections
    User -->|"vault write/read"| VaultCore
    VaultCore -->|"gRPC LogicalBackend Call"| Entrypoint
    Entrypoint -->|calls| Backend
    Backend -->|initializes| EntryConfig
    Backend -->|initializes| EntryRole
    Backend -->|initializes| EntryToken
    EntryConfig -->|routes to| PathConfig
    EntryRole -->|routes to| PathRole
    EntryToken -->|routes to| PathToken
    PathConfig -->|"Read/Write"| StorageInterface
    PathRole -->|"Read/Write"| StorageInterface
    PathToken -->|"HTTP POST /tokens"| GitLabClient
    GitLabClient -->|"HTTP Response"| PathToken
    PathToken -->|"returns Secret + Lease"| VaultCore
    VaultCore -->|"response"| User

    VaultCore -.->|Periodic Invoke| Scheduler
    Scheduler -->|"HTTP POST /rotate"| GitLabClient
    GitLabClient -->|"HTTP Response"| Scheduler

    %% Storage and External
    StorageInterface -->|"KV Read/Write"| VaultStorage
    GitLabClient -->|"HTTPS"| GitLabAPI

    %% Click Events
    click Entrypoint "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/cmd/vault-plugin-secrets-gitlab/main.go"
    click Backend "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/backend.go"
    click EntryConfig "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/entry_config.go"
    click EntryRole "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/entry_role.go"
    click PathConfig "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/path_config.go"
    click PathConfig "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/path_config_list.go"
    click PathConfig "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/path_config_rotate.go"
    click PathRole "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/path_role.go"
    click PathToken "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/path_token_role.go"
    click GitLabClient "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/gitlab_client.go"
    click Scheduler "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/events.go"
    click SecretTypes "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/secret_access_tokens.go"
    click Helpers "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/utils.go"
    click Helpers "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/name_tpl.go"
    click DataTypes "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/type_access_level.go"
    click DataTypes "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/type_token_scope.go"
    click DataTypes "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/type_token_type.go"
    click Defs "https://github.com/ilijamt/vault-plugin-secrets-gitlab/blob/main/defs.go"

    %% Styles
    classDef vaultCore fill:#bfdbfe,stroke:#333,stroke-width:1px
    classDef plugin fill:#a7f3d0,stroke:#333,stroke-width:1px
    classDef gitlab fill:#fecaca,stroke:#333,stroke-width:1px
    classDef storage fill:#e5e7eb,stroke:#333,stroke-width:1px
    classDef helper fill:#fce7f3,stroke:#333,stroke-width:1px
    classDef external fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
