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

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:

Providers

The following providers are used by this module:

Resources

The following resources are used by this module:

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):

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: "v3.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

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

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