devops-stack-module-keycloak

A DevOps 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 DevOps Stack):

module "keycloak" {
  source = "git::https://github.com/camptocamp/devops-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

Important

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/camptocamp/devops-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 (>= 5)

• kubernetes (>= 2)

• null (>= 3)

• random (>= 3)

• utils (>= 1)

Providers

The following providers are used by this module:

• random (>= 3)

• utils (>= 1)

• argocd (>= 5)

• kubernetes (>= 2)

• null (>= 3)

Resources

The following resources are used by this module:

• argocd_application.operator (resource)

• argocd_application.this (resource)

• argocd_project.this (resource)

• null_resource.dependencies (resource)

• null_resource.this (resource)

• null_resource.wait_for_keycloak (resource)

• random_password.db_password (resource)

• kubernetes_secret.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):

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.1.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"

helm_values

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

Type: any

Default: []

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({
    vendor   = string
    host     = string
    username = string
    password = string
  })

Default: null

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	>= 5
kubernetes	>= 2
null	>= 3
random	>= 3
utils	>= 1

= Providers

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

= Resources

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

= Inputs

Name	Description	Type	Default	Required
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
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.1.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
helm_values	Helm chart value overrides. They should be passed as a list of HCL structures.	any	[]	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({ vendor = string host = string username = string password = string })	null	no

= 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.