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

>= 5

>= 2

>= 3

>= 3

>= 1

= Providers

Name Version

>= 3

>= 3

>= 1

>= 5

>= 2

= Resources

Name Type

resource

resource

resource

resource

resource

resource

resource

data source

data source

= Inputs

Name Description Type Default Required

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

string

n/a

yes

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

string

n/a

yes

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

string

"apps"

no

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

Labels to attach to the Argo CD Application resource.

map(string)

{}

no

Destination cluster where the application should be deployed.

string

"in-cluster"

no

Override of target revision of the application chart.

string

"v3.1.0"

no

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 chart value overrides. They should be passed as a list of HCL structures.

any

[]

no

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

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

map(string)

{}

no

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.

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