Terraform has become an indispensable tool for managing infrastructure as code (IaC) in many software teams. It enables us to define and provision cloud resources in a consistent, predictable manner, ensuring that infrastructure remains in the same state across all environments.
One popular use case for Terraform is setting up and managing Keycloak. However, while setting up Keycloak with Terraform is powerful, bundling both the setup and configuration of Keycloak in the same Terraform codebase can introduce certain risks, so be careful!
In this blog, we’ll walk through setting up Keycloak using Terraform (very, very simple use case) and explore the dangers of combining setup and configuration in the same code. We’ll also discuss alternative approaches to managing Keycloak configurations and explore the latest survey on Keycloak realm management tools.
What Is Terraform and Why Use It?
Terraform, developed by HashiCorp, is an open-source tool used to manage infrastructure through code. It allows you to describe your infrastructure in configuration files that Terraform processes and turns into APIs for interacting with service providers like AWS, Azure, GCP, or even tools like Keycloak.
In my daily work, I rely on Terraform to manage the lifecycle of cloud resources. Whether it’s provisioning new EC2 instances, configuring VPCs, or managing Kubernetes clusters, Terraform allows me to ensure that all environments remain consistent. This consistency is critical for compliance frameworks like SOC 2, where auditing and ensuring infrastructure changes are tracked is necessary. Terraform also removes the need for engineers to log into cloud consoles manually, reducing human error and ensuring that all changes are deliberate and auditable.
Setting Up Keycloak with Terraform
Using the Terraform provider for Keycloak allows you to automate the provisioning of Keycloak realms, clients, users, and more. See the provider as the black box that will manage all the interaction with the actual Keycloak APIs. You would use the same strategy if you needed to provision other API based resources.
Here’s a basic example of how to get started:
Step 1: Install the Keycloak Terraform Provider
To install the Keycloak provider, you can add the following block to your main.tf file:
provider "keycloak" {
client_id = "admin-cli"
client_secret = "your-secret"
realm = "master"
base_url = "https://my-super-cool-keycloak-cluster.skycloak.io"
}You probably noticed that a client id and secret are used. When using providers, you will need to provide an authentication method that will be used to authenticate with the APIs. In this instance, we use the admin-cli client to make the necessary change in the master realm. Remember this is an example. In another blog post, we will see how to use a service account to achieve a more secure result.
Step 2: Create a Keycloak Realm
The next step is to create a new realm in Keycloak. This can be done using the following code:
resource "keycloak_realm" "my_realm" {
realm = "my-realm"
enabled = true
}Step 3: Add Clients and Users
Once the realm is created, you can configure clients, roles, and users:
resource "keycloak_openid_client" "my_client" {
realm_id = keycloak_realm.my_realm.id
client_id = "my-client"
enabled = true
direct_access_grants_enabled = true
}Notice here that we reference the realm that was previously created. Terraform will understand the relationship and make sure the realm is created before creating this resource.
The Danger of Combining Setup and Configuration
While Terraform is great for provisioning Keycloak, bundling both the setup (e.g., creating the Keycloak cluster) and configuration (e.g., client, realms, specific roles, permissions) in the same codebase can be problematic:
1. Complexity Increases Over Time
As your Keycloak setup grows, managing both setup and configuration in the same repository becomes increasingly difficult to maintain. This can make troubleshooting issues more challenging and add unnecessary complexity.
In a recent event, a client was locked out of her environment while trying to upgrade their keycloak cluster. In the same Terraform code base, other resources depended on Keycloak for auth and the clients and permissions were also depending the cluster. During the upgrade, the cluster went down, and the remaining of the script could not run.
2. Configuration Drift
By combining setup and configuration, there’s a risk that minor configuration changes could accidentally alter the underlying setup. For example, changing a client configuration could inadvertently lead to changes in how realms are provisioned.
3. Security Risks
Sensitive configuration data, such as client secrets, might be exposed unintentionally if all aspects of setup and configuration are handled together.
4. Difficulties with Auditing and Compliance
From a compliance standpoint (e.g., SOC 2), separating infrastructure setup from application configuration makes it easier to audit and track changes. Bundling them together increases the complexity of audits and makes it harder to pinpoint where changes were made.
Alternatives for Managing Keycloak Configurations
1. Separate Repositories for Setup and Configuration
A more manageable approach is to split your infrastructure setup and configuration management into separate repositories. You could use one repository purely for setting up the Keycloak infrastructure and another to manage the configuration using the Keycloak Terraform provider.
2. Pulumi for Configuration Management
Pulumi is an alternative to Terraform that allows you to write infrastructure code using popular programming languages like Go, TypeScript, and Python. However, to maintain consistency across teams, I prefer sticking to one infrastructure-as-code tool, such as Terraform, to ensure standardization across projects.
3. Keycloak Realm Management Tools
Keycloak recently released a survey of the most popular tools used to configure realms. According to the results, the Terraform provider for Keycloak is the most popular, with 51% of respondents using it (Reference). Other tools, such as Keycloak-Config-CLI and custom-built solutions, were also popular but less commonly used.
Conclusion
Terraform provides an excellent way to manage the lifecycle of your Keycloak setup, from creating realms to configuring clients and users. However, combining setup and configuration in the same Terraform codebase introduces risks such as complexity, security vulnerabilities, and configuration drift. To mitigate these risks, consider using separate repositories for setup and configuration or exploring other tools like Pulumi.
By keeping infrastructure-as-code consistent, you can avoid manual interventions, ensure compliance with frameworks like SOC 2, and maintain auditability across all environments.
In a follow up blog post, I will show you a full example of a terraform code base used to maintain realms, clients and others for a Keycloak cluster.