# keycloak/terraform-provider-keycloak architecture

> Architecture diagram of the GitHub repository keycloak/terraform-provider-keycloak, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/keycloak/terraform-provider-keycloak
- Repository: https://github.com/keycloak/terraform-provider-keycloak

## Overview

##### Main Components
- Terraform CLI/Configuration – The client side that runs Terraform commands.
- Terraform Provider Plugin (this project) – The heart of this project, which handles resource definitions, state management, and API interactions.
▪ The “provider” package: Contains the Terraform provider implementation, data sources, and resource schemas.
▪ The “keycloak” package: Contains the underlying client code that interacts with the Keycloak API (handling HTTP calls, parsing data, error management, etc.).
▪ Custom integrations (e.g., custom-user-federation-example): Provides examples and extensions like custom identity providers or event listeners.
▪ Tests & CI Support: Represent the acceptance tests (both unit and integration) and the local development environment (using Docker Compose) which includes Keycloak, PostgreSQL, and OpenLDAP.
- External Keycloak Server – The target system where the provider pushes configuration changes.
- (Optionally) Local development environment – The Docker Compose setup that spins up Keycloak along with dependent services for testing.

##### Relationships and Data Flows
- The provider plugin internally routes operations to the keycloak package, which then invokes Keycloak REST API endpoints to create, update, or delete configurations.
- For acceptance tests and local development, show that the Docker Compose environment (including Keycloak, PostgreSQL, OpenLDAP) is used to simulate production-like interactions.
- That configuration and authentication details flow from the Terraform configuration (including provider arguments and environment variables) to the provider.

##### Architectural Patterns & Design Principles
- Modularity: The project separates concerns between the Terraform provider (which maps to Terraform’s plugin interface) and the lower-level Keycloak API client layer.
- Extensibility: With custom packages (like custom-user-federation-example) and a wide range of supported Keycloak resources, the design supports a modular and extensible structure.
- Continuous integration and automated releases (using GitHub Actions and GoReleaser) are also part of the architecture.
- Testing: Emphasize the layered testing strategy (unit tests in the “keycloak” package and acceptance tests in the “provider” package).

##### Relevant Technologies and Frameworks
- Go (with Go Modules for dependency management)
- Terraform SDK (for provider integration)
- Keycloak APIs (REST endpoints)
- Docker Compose (for local development/testing)
- GitHub Actions (for CI/CD pipelines)
- GoReleaser (for automated release building)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Components
    A["Terraform CLI/Configuration"]:::cli
    click A "https://github.com/keycloak/terraform-provider-keycloak/blob/main/example/main.tf"
    
    B["Terraform Provider Plugin"]:::plugin
    click B "https://github.com/keycloak/terraform-provider-keycloak/blob/main/provider/provider.go"
    
    %% Subcomponents inside Provider Plugin
    subgraph "Provider Internal"
        BP["Provider Package"]:::pkg
        click BP "https://github.com/keycloak/terraform-provider-keycloak/tree/main/provider/"
        
        KC["Keycloak API Client"]:::api
        click KC "https://github.com/keycloak/terraform-provider-keycloak/tree/main/keycloak/"
        
        CI["Custom Integrations"]:::custom
        click CI "https://github.com/keycloak/terraform-provider-keycloak/tree/main/custom-user-federation-example"
        
        BP -->|"calls"| KC
        BP -->|"integrates"| CI
    end

    %% External System
    X["Keycloak Server"]:::external
    KC -->|"APIcalls"| X

    %% Connections from CLI to Provider Plugin
    A -->|"executes"| B
    B --> BP

    %% Testing & CI Support Subgraph
    subgraph "Tests & CI Support"
        T["Acceptance & Unit Tests"]:::tests
        click T "https://github.com/keycloak/terraform-provider-keycloak/tree/main/provider/"
        CD["CI/CD & Release"]:::ci
        click CD "https://github.com/keycloak/terraform-provider-keycloak/tree/main/.github/workflows"
    end
    T -->|"validates"| B
    CD -->|"releases"| B

    %% Local Development Environment Subgraph
    subgraph "Local Development"
        LDE["Docker Compose (Local Dev)"]:::dev
        click LDE "https://github.com/keycloak/terraform-provider-keycloak/blob/main/docker-compose.yml"
        S["Supporting Scripts"]:::dev
        click S "https://github.com/keycloak/terraform-provider-keycloak/blob/main/scripts/wait-for-local-keycloak.sh"
    end
    LDE -->|"simulates"| X
    S -->|"supports"| LDE

    %% Styles
    classDef cli fill:#f9d6a5, stroke:#333, stroke-width:2px;
    classDef plugin fill:#d6e8f9, stroke:#333, stroke-width:2px;
    classDef pkg fill:#c2f0c2, stroke:#333, stroke-width:2px;
    classDef api fill:#efc2f2, stroke:#333, stroke-width:2px;
    classDef external fill:#f7c6c7, stroke:#333, stroke-width:2px;
    classDef tests fill:#f7f3a5, stroke:#333, stroke-width:2px;
    classDef ci fill:#d3d3d3, stroke:#333, stroke-width:2px;
    classDef custom fill:#e6c2d6, stroke:#333, stroke-width:2px;
    classDef dev fill:#d6f9e8, stroke:#333, stroke-width:2px;
```
