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.

External Requirements

curl

Minimum required version is 7.71.0.

We were forced to use a null_resource in order to wait for a working Keycloak deployment. This resource runs a local command which uses curl to test if the Keycloak interface is up and running. Because of some flags that were only introduced on more recent versions of curl, you will need to have installed at least the version 7.71.0.

Requirements

The following requirements are needed by this module:

Providers

The following providers are used by this module:

Modules

No modules.

Resources

The following resources are used by this module:

Required Inputs

The following input variables are required:

argocd_namespace

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

Type: string

base_domain

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

Type: string

cluster_name

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

Type: string

Optional Inputs

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

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
}

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: "ca-issuer"

database

Description: Keycloak external database server configuration.

Type:

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

Default: null

dependency_ids

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

Type: map(string)

Default: {}

helm_values

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

Type: any

Default: []

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: "keycloak"

target_revision

Description: Override of target revision of the application chart.

Type: string

Default: "v1.0.0-alpha.1"

Outputs

The following outputs are exported:

admin_credentials

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

id

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

Reference in table format

Show tables

= Requirements

Name Version

argocd

~> 4

kubernetes

~> 2

null

~> 3

random

~> 3

utils

~> 1

= Providers

Name Version

argocd

~> 4

kubernetes

~> 2

null

~> 3

random

~> 3

utils

~> 1

= 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

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

argocd_namespace

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

string

n/a

yes

base_domain

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

string

n/a

yes

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

"ca-issuer"

no

cluster_name

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

string

n/a

yes

database

Keycloak external database server configuration.

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

null

no

dependency_ids

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

map(string)

{}

no

helm_values

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

any

[]

no

namespace

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

string

"keycloak"

no

target_revision

Override of target revision of the application chart.

string

"v1.0.0-alpha.1"

no

= Outputs

Name Description

admin_credentials

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

id

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