modern-gitops-stack-module-keycloak

A Modern GitOps Stack module to deploy and configure Keycloak as an OIDC provider. It is meant to be used mainly for testing purposes when deploying a local cluster using KinD.

This repository contains 2 charts:

keycloak-operator: contains the CRDs and the other Kubernetes resources in order to install the operator as recommended for a vanilla Kubernetes installation in Keycloak’s documentation;
keycloak: installs Keycloak and associated resources (such as an ingress) as well as PostgreSQL deployment (optional if you provide the credentials for an external database).

The Keycloak version installed is the 20.0.3. Here you will find the official guides of Keycloak, namely the ones used for this module in the Operator section.

Besides this module, we developed a submodule to bootstrap a realm, groups and users so you can be up an running as fast as possible.

Usage

This module can be declared by adding the following block on your Terraform configuration (below is an example when using KinD, but nothing stops you of using this module with the other cluster modules of the Modern GitOps Stack):

module "keycloak" {
  source = "git::https://github.com/GersonRS/modern-gitops-stack-module-keycloak.git?ref=<RELEASE>"

  cluster_name     = local.cluster_name
  base_domain      = format("%s.nip.io", replace(module.ingress.external_ip, ".", "-"))
  cluster_issuer   = local.cluster_issuer
  argocd_namespace = module.argocd_bootstrap.argocd_namespace

  dependency_ids = {
    traefik      = module.ingress.id
    cert-manager = module.cert-manager.id
  }
}

Database Configuration

We do not recommend using the PostgreSQL deployment in a production environment. It should be used only for development purposes and the persistence of the database is not guaranteed.

In a production environment, it is recommended to use an external SQL database and to give this module only the connection details. In that case, the default PostgreSQL sidecar will not be deployed.

You can provide the credentials for connecting Keycloak to an external SQL database as follows:

module "keycloak" {
  source = "git::https://github.com/GersonRS/modern-gitops-stack-module-keycloak.git?ref=<RELEASE>"

  cluster_name     = local.cluster_name
  base_domain      = format("%s.nip.io", replace(module.ingress.external_ip, ".", "-"))
  cluster_issuer   = local.cluster_issuer
  argocd_namespace = module.argocd_bootstrap.argocd_namespace

  database = {
    vendor   = "mariadb | mssql | mysql | oracle | postgres"
    host     = "<HOSTNAME>"
    username = "<USERNAME>"
    password = "<PASSWORD>"
  }

  dependency_ids = {
    traefik      = module.ingress.id
    cert-manager = module.cert-manager.id
  }
}

The official documentation provides more information about the supported database vendors.

Technical Reference

Dependencies

`module.argocd_bootstrap`

This module needs a working Argo CD, so at least it depends on module.argocd_bootstrap.

`module.ingress.id`

Since there is an ingress deployed with this module, it needs to be deployed after Traefik so it depends on module.ingress.

Requirements

The following requirements are needed by this module:

argocd (>= 6)
kubernetes (>= 2)
null (>= 3)
random (>= 3)
utils (>= 1)

Providers

The following providers are used by this module:

kubernetes (>= 2)
random (>= 3)
argocd (>= 6)
utils (>= 1)
null (>= 3)

Resources

The following resources are used by this module:

argocd_application.operator (resource)
argocd_application.this (resource)
argocd_project.this (resource)
kubernetes_secret_v1.keycloak_db_secret (resource)
null_resource.dependencies (resource)
null_resource.this (resource)
null_resource.wait_for_keycloak (resource)
random_password.db_password (resource)
kubernetes_secret_v1.admin_credentials (data source)
utils_deep_merge_yaml.values (data source)

Required Inputs

The following input variables are required:

cluster_name

Description: Name given to the cluster. Value used for the ingress' URL of the application.

Type: string

base_domain

Description: Base domain of the cluster. Value used for the ingress' URL of the application.

Type: string

Optional Inputs

The following input variables are optional (have default values):

project_source_repo

Description: Repository allowed to be scraped in this AppProject.

Type: string

Default: "https://github.com/GersonRS/modern-gitops-stack-module-keycloak.git"

namespace

Description: Namespace where the applications’s Kubernetes resources should be created. Namespace will be created in case it doesn’t exist.

Type: string

Default: "management"

argocd_namespace

Description: Namespace used by Argo CD where the Application and AppProject resources should be created.

Type: string

Default: "argocd"

subdomain

Description: Subdomain of the cluster. Value used for the ingress' URL of the application.

Type: string

Default: "apps"

argocd_project

Description: Name of the Argo CD AppProject where the Application should be created. If not set, the Application will be created in a new AppProject only for this Application.

Type: string

Default: null

argocd_labels

Description: Labels to attach to the Argo CD Application resource.

Type: map(string)

Default: {}

destination_cluster

Description: Destination cluster where the application should be deployed.

Type: string

Default: "in-cluster"

target_revision

Description: Override of target revision of the application chart.

Type: string

Default: "v2.8.0"

cluster_issuer

Description: SSL certificate issuer to use. Usually you would configure this value as letsencrypt-staging or letsencrypt-prod on your root *.tf files.

Type: string

Default: "selfsigned-issuer"

enable_service_monitor

Description: Enable Prometheus ServiceMonitor in the Helm chart.

Type: bool

Default: false

helm_values

Description: Helm chart value overrides. They should be passed as a list of HCL structures.

Type: any

Default: []

replicas

Description: Number of keycloak pods to be deployed.

Type: number

Default: 1

app_autosync

Description: Automated sync options for the Argo CD Application resource.

Type:

object({
    allow_empty = optional(bool)
    prune       = optional(bool)
    self_heal   = optional(bool)
  })

Default:

{
  "allow_empty": false,
  "prune": true,
  "self_heal": true
}

dependency_ids

Description: IDs of the other modules on which this module depends on.

Type: map(string)

Default: {}

database

Description: Keycloak external database server configuration.

Type:

object({
    host     = string
    username = string
    password = string
  })

Default: null

enable_custom_theme

Description: Enable the Modern GitOps custom login theme.

Type: bool

Default: true

theme_config

Description: Configuration for the custom Keycloak theme loaded from a Git repository.

Type:

object({
    name                 = optional(string, "modern-gitops")
    init_container_image = optional(string, "alpine/git")
    repository_url       = optional(string, "https://github.com/GersonRS/keycloak-templates.git")
    repository_branch    = optional(string, "main")
    repository_path      = optional(string, "themes/modern-gitops")
  })

Default: {}

gateway_name

Description: Name of the Istio Gateway resource to attach HTTPRoutes to.

Type: string

Default: "istio-gateway"

gateway_namespace

Description: Namespace where the Istio Gateway resource is deployed.

Type: string

Default: "istio-ingress"

Outputs

The following outputs are exported:

id

Description: ID to pass other modules in order to refer to this module as a dependency.

admin_credentials

Description: Credentials for the administrator user of the master realm created on deployment.

Reference in table format

Show tables

= Requirements

Name	Version
argocd	>= 6
kubernetes	>= 2
null	>= 3
random	>= 3
utils	>= 1

Name

Version

>= 6

>= 2

>= 3

>= 3

>= 1

= Providers

Name	Version
kubernetes	>= 2
random	>= 3
argocd	>= 6
utils	>= 1
null	>= 3

Name

Version

>= 2

>= 3

>= 6

>= 1

>= 3

= Resources

Name	Type
argocd_application.operator	resource
argocd_application.this	resource
argocd_project.this	resource
kubernetes_secret_v1.keycloak_db_secret	resource
null_resource.dependencies	resource
null_resource.this	resource
null_resource.wait_for_keycloak	resource
random_password.db_password	resource
kubernetes_secret_v1.admin_credentials	data source
utils_deep_merge_yaml.values	data source

Name

Type

argocd_application.operator

resource

argocd_application.this

resource

argocd_project.this

resource

kubernetes_secret_v1.keycloak_db_secret

resource

null_resource.dependencies

resource

null_resource.this

resource

null_resource.wait_for_keycloak

resource

random_password.db_password

resource

kubernetes_secret_v1.admin_credentials

data source

utils_deep_merge_yaml.values

data source

= Inputs

Name Description Type Default Required

Name	Description	Type	Default	Required
project_source_repo	Repository allowed to be scraped in this AppProject.	`string`	`"https://github.com/GersonRS/modern-gitops-stack-module-keycloak.git"`	no
namespace	Namespace where the applications’s Kubernetes resources should be created. Namespace will be created in case it doesn’t exist.	`string`	`"management"`	no
argocd_namespace	Namespace used by Argo CD where the Application and AppProject resources should be created.	`string`	`"argocd"`	no
cluster_name	Name given to the cluster. Value used for the ingress' URL of the application.	`string`	n/a	yes
base_domain	Base domain of the cluster. Value used for the ingress' URL of the application.	`string`	n/a	yes
subdomain	Subdomain of the cluster. Value used for the ingress' URL of the application.	`string`	`"apps"`	no
argocd_project	Name of the Argo CD AppProject where the Application should be created. If not set, the Application will be created in a new AppProject only for this Application.	`string`	`null`	no
argocd_labels	Labels to attach to the Argo CD Application resource.	`map(string)`	`{}`	no
destination_cluster	Destination cluster where the application should be deployed.	`string`	`"in-cluster"`	no
target_revision	Override of target revision of the application chart.	`string`	`"v2.8.0"`	no
cluster_issuer	SSL certificate issuer to use. Usually you would configure this value as `letsencrypt-staging` or `letsencrypt-prod` on your root `*.tf` files.	`string`	`"selfsigned-issuer"`	no
enable_service_monitor	Enable Prometheus ServiceMonitor in the Helm chart.	`bool`	`false`	no
helm_values	Helm chart value overrides. They should be passed as a list of HCL structures.	`any`	`[]`	no
replicas	Number of keycloak pods to be deployed.	`number`	`1`	no
app_autosync	Automated sync options for the Argo CD Application resource.	`object({ allow_empty = optional(bool) prune = optional(bool) self_heal = optional(bool) })`	`{ "allow_empty": false, "prune": true, "self_heal": true }`	no
dependency_ids	IDs of the other modules on which this module depends on.	`map(string)`	`{}`	no
database	Keycloak external database server configuration.	`object({ host = string username = string password = string })`	`null`	no
enable_custom_theme	Enable the Modern GitOps custom login theme.	`bool`	`true`	no
theme_config	Configuration for the custom Keycloak theme loaded from a Git repository.	`object({ name = optional(string, "modern-gitops") init_container_image = optional(string, "alpine/git") repository_url = optional(string, "https://github.com/GersonRS/keycloak-templates.git") repository_branch = optional(string, "main") repository_path = optional(string, "themes/modern-gitops") })`	`{}`	no
gateway_name	Name of the Istio Gateway resource to attach HTTPRoutes to.	`string`	`"istio-gateway"`	no
gateway_namespace	Namespace where the Istio Gateway resource is deployed.	`string`	`"istio-ingress"`	no

project_source_repo

Repository allowed to be scraped in this AppProject.

string

"https://github.com/GersonRS/modern-gitops-stack-module-keycloak.git"

namespace

Namespace where the applications’s Kubernetes resources should be created. Namespace will be created in case it doesn’t exist.

string

"management"

argocd_namespace

Namespace used by Argo CD where the Application and AppProject resources should be created.

string

"argocd"

cluster_name

Name given to the cluster. Value used for the ingress' URL of the application.

string

n/a

yes

base_domain

Base domain of the cluster. Value used for the ingress' URL of the application.

string

n/a

yes

subdomain

Subdomain of the cluster. Value used for the ingress' URL of the application.

string

"apps"

argocd_project

Name of the Argo CD AppProject where the Application should be created. If not set, the Application will be created in a new AppProject only for this Application.

string

null

argocd_labels

Labels to attach to the Argo CD Application resource.

map(string)

{}

destination_cluster

Destination cluster where the application should be deployed.

string

"in-cluster"

target_revision

Override of target revision of the application chart.

string

"v2.8.0"

cluster_issuer

SSL certificate issuer to use. Usually you would configure this value as letsencrypt-staging or letsencrypt-prod on your root *.tf files.

string

"selfsigned-issuer"

enable_service_monitor

Enable Prometheus ServiceMonitor in the Helm chart.

bool

false

helm_values

Helm chart value overrides. They should be passed as a list of HCL structures.

any

[]

replicas

Number of keycloak pods to be deployed.

number

1

app_autosync

Automated sync options for the Argo CD Application resource.

object({
    allow_empty = optional(bool)
    prune       = optional(bool)
    self_heal   = optional(bool)
  })

{
  "allow_empty": false,
  "prune": true,
  "self_heal": true
}

dependency_ids

IDs of the other modules on which this module depends on.

map(string)

{}

database

Keycloak external database server configuration.

object({
    host     = string
    username = string
    password = string
  })

null

enable_custom_theme

Enable the Modern GitOps custom login theme.

bool

true

theme_config

Configuration for the custom Keycloak theme loaded from a Git repository.

object({
    name                 = optional(string, "modern-gitops")
    init_container_image = optional(string, "alpine/git")
    repository_url       = optional(string, "https://github.com/GersonRS/keycloak-templates.git")
    repository_branch    = optional(string, "main")
    repository_path      = optional(string, "themes/modern-gitops")
  })

{}

gateway_name

Name of the Istio Gateway resource to attach HTTPRoutes to.

string

"istio-gateway"

gateway_namespace

Namespace where the Istio Gateway resource is deployed.

string

"istio-ingress"

= Outputs

Name	Description
id	ID to pass other modules in order to refer to this module as a dependency.
admin_credentials	Credentials for the administrator user of the master realm created on deployment.

Name

Description

ID to pass other modules in order to refer to this module as a dependency.

admin_credentials

Credentials for the administrator user of the master realm created on deployment.