Deploying Keycloak On GKE With HTTPS A Comprehensive Guide

Jul 12, 2025 by Jeany 59 views

Deploying Keycloak on Google Kubernetes Engine (GKE) with HTTPS using Ingress

Setting up Keycloak, a leading open-source identity and access management solution, on Google Kubernetes Engine (GKE) can be a complex task, especially for those new to Kubernetes and cloud environments. A common challenge encountered during this process is the "Https is Required" error when trying to access Keycloak via HTTP. This article provides a comprehensive guide to deploying Keycloak on GKE with HTTPS enabled using Ingress, ensuring a secure and accessible setup. We will walk through the necessary steps, from configuring your GKE cluster and installing Helm to deploying Keycloak and setting up Ingress with TLS.

Prerequisites

Before we begin, ensure you have the following prerequisites in place:

A Google Cloud Platform (GCP) account with billing enabled.
A GKE cluster up and running. If you don't have one, you can create one using the GCP Console or the gcloud command-line tool.
The kubectl command-line tool installed and configured to connect to your GKE cluster.
Helm, the Kubernetes package manager, installed on your local machine.
A domain name and a TLS certificate for that domain. You can obtain a certificate from a Certificate Authority (CA) like Let's Encrypt.

Step 1: Setting up Your GKE Cluster

First, you'll need a running GKE cluster. If you don't have one already, you can create a new cluster using the Google Cloud Console or the gcloud command-line tool. For example, to create a new cluster named keycloak-cluster in the us-central1 region, you can use the following command:

gcloud container clusters create keycloak-cluster \
    --region us-central1 \
    --machine-type n1-standard-1 \
    --num-nodes 3

This command creates a cluster with three nodes using the n1-standard-1 machine type. Adjust the machine type and number of nodes based on your requirements. Once the cluster is created, you need to configure kubectl to connect to your cluster. You can do this using the following command:

gcloud container clusters get-credentials keycloak-cluster --region us-central1

This command retrieves the necessary credentials and updates your kubectl configuration. You can verify that kubectl is configured correctly by running:

kubectl get nodes

This should display the nodes in your cluster. Ensuring your cluster is properly set up is crucial for a successful Keycloak deployment. A well-configured cluster provides the foundation for a stable and scalable Keycloak instance. It is also essential to consider the networking aspects of your cluster, such as VPC settings and firewall rules, to ensure secure communication between your Keycloak deployment and other services. Moreover, you should regularly update your cluster's version to benefit from the latest security patches and features. Properly setting up and maintaining your GKE cluster is the first step towards a robust Keycloak deployment. The choice of machine types and the number of nodes should be based on your expected load and resource requirements. For production environments, it is recommended to use more robust machine types and a higher number of nodes to ensure high availability and performance.

Step 2: Installing Helm

Helm is a package manager for Kubernetes, which simplifies the deployment and management of applications. We will use Helm to deploy Keycloak. If you haven't already installed Helm, you can download the latest version from the official Helm website or use a package manager like brew on macOS. Once Helm is installed, you need to initialize it in your cluster. For Helm 3, this is done automatically when you run your first helm command. To add the Keycloak Helm repository, use the following commands:

helm repo add codecentric https://codecentric.github.io/helm-charts
helm repo update

This adds the Codecentric Helm repository, which contains the Keycloak chart, and updates your local Helm repository cache. Helm simplifies the deployment process by packaging all the necessary Kubernetes resources into a single chart. Using Helm, you can easily deploy and manage complex applications like Keycloak with a single command. The Helm chart for Keycloak includes all the required Kubernetes resources, such as Deployments, Services, and Ingress, making the deployment process straightforward. It is also important to keep your Helm installation up to date to benefit from the latest features and bug fixes. Helm charts are a convenient way to manage Kubernetes applications, allowing you to define, install, and upgrade even the most complex application. Helm also provides a rollback mechanism, which allows you to easily revert to a previous version of your application if something goes wrong during an upgrade. This makes Helm an invaluable tool for managing applications in a Kubernetes environment.

Step 3: Deploying Keycloak with Helm

Now that Helm is set up, we can deploy Keycloak. We will deploy Keycloak with a PostgreSQL database for persistence. First, create a values.yaml file to customize the Keycloak deployment. This file will contain the configuration values for the Keycloak Helm chart. Here's an example values.yaml file:

postgresql:
  enabled: true
keycloak:
  ingress:
    enabled: true
    className: "nginx" # Use your Ingress controller class name
    hostname: keycloak.example.com # Replace with your domain
    tls:
      enabled: true
      secretName: keycloak-tls # Name of the TLS secret
  extraInitContainers:
    - name: fix-permissions
      image: busybox
      command: ["sh", "-c", "chown -R 1000:1000 /opt/jboss/keycloak/standalone/data"]
      securityContext:
        runAsUser: 0
      volumeMounts:
        - name: keycloak-data
          mountPath: /opt/jboss/keycloak/standalone/data
persistence:
  enabled: true
  size: 10Gi

Replace keycloak.example.com with your domain name and ensure that the className matches your Ingress controller class name (e.g., nginx, traefik, or gce). This configuration enables Ingress, sets the hostname, enables TLS, and specifies the secret name for the TLS certificate. The extraInitContainers section is added to fix permissions issues that may arise with Keycloak's data directory. This ensures that Keycloak has the necessary permissions to write to its data directory. To deploy Keycloak, use the following command:

helm install keycloak codecentric/keycloak -f values.yaml

This command installs Keycloak using the Codecentric Helm chart and the configurations specified in the values.yaml file. The deployment process may take a few minutes. You can monitor the progress using kubectl: Deploying Keycloak with Helm streamlines the process and allows for easy customization through the values.yaml file. The values.yaml file is a powerful tool for configuring Keycloak to meet your specific requirements. By customizing the values in this file, you can control various aspects of the deployment, such as the database settings, resource limits, and security configurations. It's essential to review and understand each setting in the values.yaml file to ensure that Keycloak is deployed correctly and securely. Moreover, you can use Helm's templating capabilities to further customize the deployment process, such as dynamically generating configuration files based on environment variables. This allows for greater flexibility and control over your Keycloak deployment. The deployment process might require some adjustments based on your specific environment and needs.

kubectl get pods

Step 4: Creating a TLS Secret

To enable HTTPS, you need to create a TLS secret in Kubernetes. This secret will contain your TLS certificate and private key. You can create a TLS secret using kubectl: The creation of a TLS secret is a critical step in enabling HTTPS for your Keycloak deployment. Without a valid TLS certificate, your Keycloak instance will not be able to serve traffic over HTTPS, which is essential for security. When creating the TLS secret, ensure that you provide the correct certificate and private key files. The certificate should be in PEM format, and the private key should match the certificate. It's also crucial to protect your TLS secret from unauthorized access. Kubernetes Secrets are stored in etcd, which is the Kubernetes backend storage, and are not encrypted by default. Therefore, it's recommended to enable encryption at rest for your Secrets to protect them from unauthorized access. Additionally, you should regularly rotate your TLS certificates to maintain a high level of security.

kubectl create secret tls keycloak-tls \
    --key path/to/your/key.pem \
    --cert path/to/your/cert.pem

Replace path/to/your/key.pem and path/to/your/cert.pem with the paths to your private key and certificate files, respectively. Ensure that the secret name (keycloak-tls) matches the secretName specified in your values.yaml file. This step is crucial for enabling HTTPS access to Keycloak.

Step 5: Setting up Ingress

Ingress is a Kubernetes resource that manages external access to the services in a cluster, typically via HTTP and HTTPS. To set up Ingress for Keycloak, you need to have an Ingress controller running in your cluster. If you don't have one, you can install one using Helm. For example, to install the Nginx Ingress controller, use the following commands:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install ingress-nginx ingress-nginx/ingress-nginx \
    --set controller.service.type=LoadBalancer

This installs the Nginx Ingress controller and exposes it as a LoadBalancer service. Once the Ingress controller is running, Kubernetes Ingress is essential for routing external traffic to your Keycloak service. An Ingress controller is responsible for implementing the Ingress rules defined in your Ingress resource. There are several Ingress controllers available, such as Nginx, Traefik, and HAProxy, each with its own features and configuration options. When choosing an Ingress controller, consider factors such as performance, scalability, and ease of configuration. The Ingress controller you choose should also be compatible with your GKE environment and your specific requirements. For example, if you need advanced features such as traffic shaping or rate limiting, you might choose an Ingress controller that supports these features. It's also essential to configure your Ingress controller correctly to ensure that traffic is routed properly to your Keycloak service. This includes setting up DNS records, configuring TLS certificates, and defining Ingress rules.

you need to create an Ingress resource to route traffic to Keycloak. The Ingress resource defines how external traffic should be routed to your services. Here's an example Ingress resource:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: keycloak-ingress
  annotations:
    kubernetes.io/ingress.class: "nginx" # Use your Ingress controller class
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/use-forwarded-headers: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
spec:
  tls:
    - hosts:
        - keycloak.example.com # Replace with your domain
      secretName: keycloak-tls # Name of the TLS secret
  rules:
    - host: keycloak.example.com # Replace with your domain
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: keycloak
                port:
                  number: 8080

Replace keycloak.example.com with your domain name and ensure that the secretName matches the name of your TLS secret. Save this resource to a file (e.g., keycloak-ingress.yaml) and apply it using kubectl:

kubectl apply -f keycloak-ingress.yaml

This creates an Ingress resource that routes traffic to the Keycloak service on port 8080. The annotations ensure that the Ingress controller uses the TLS secret for HTTPS and redirects HTTP traffic to HTTPS. The annotations also configure the Ingress controller to use forwarded headers and set the proxy body size. Applying the Ingress resource effectively exposes your Keycloak service to the outside world. Once the Ingress resource is applied, the Ingress controller will start routing traffic to your Keycloak service based on the rules defined in the Ingress resource. It's important to monitor the Ingress controller to ensure that it is functioning correctly. You can use kubectl to check the status of the Ingress controller and the Ingress resource. If you encounter any issues, such as traffic not being routed correctly, you can examine the Ingress controller logs to identify the cause of the problem. The Ingress resource allows for fine-grained control over how traffic is routed to your services. You can define multiple rules to route traffic based on hostnames, paths, and other criteria.

Step 6: Configuring DNS

To access Keycloak using your domain name, you need to configure your DNS settings to point to the Ingress controller. This involves creating an A record that maps your domain to the external IP address of the Ingress controller. You can find the external IP address of the Ingress controller by running:

kubectl get service ingress-nginx-controller -n ingress-nginx -o wide

This command displays the services in the ingress-nginx namespace and shows the external IP address of the ingress-nginx-controller service. Go to your domain registrar's website and create an A record that points your domain (e.g., keycloak.example.com) to this IP address. Configuring DNS correctly ensures that your domain name resolves to the external IP address of your Ingress controller. Without proper DNS configuration, users will not be able to access your Keycloak instance using your domain name. When configuring DNS, ensure that you create an A record that points your domain to the external IP address of your Ingress controller. It's also essential to set the Time-To-Live (TTL) value appropriately. The TTL value determines how long DNS resolvers cache the DNS record. A lower TTL value allows for faster updates, but it can also increase the load on your DNS servers. A higher TTL value reduces the load on your DNS servers but can delay updates. It may take some time for the DNS changes to propagate, so be patient and allow some time for the changes to take effect. You can use online tools such as dig or nslookup to verify that your DNS records are configured correctly.

Step 7: Accessing Keycloak

Once the DNS configuration is complete, you can access Keycloak using your domain name (e.g., https://keycloak.example.com). Your browser should redirect you to the Keycloak login page. If you are still encountering the "Https is Required" error, ensure that your Ingress resource is configured correctly and that the TLS secret is valid. Double-check that the ssl-redirect annotation is set to true in your Ingress resource. You may also need to clear your browser cache or try accessing Keycloak in incognito mode. Accessing Keycloak via HTTPS is crucial for ensuring secure communication between your clients and the Keycloak server. HTTPS encrypts the data transmitted between the client and the server, protecting it from eavesdropping and tampering. If you are still encountering issues, you can examine the logs of your Ingress controller and Keycloak pods to identify the cause of the problem. The logs can provide valuable information about errors and warnings that may be preventing Keycloak from functioning correctly. Additionally, you can use Kubernetes' debugging tools, such as kubectl logs and kubectl describe, to further investigate the issue. If everything is configured correctly, you should be able to access Keycloak securely using your domain name. This ensures that all communication with Keycloak is encrypted and protected.