Keycloak Deployment on EKS

5 min readOct 8, 2024

In this guide, we will go through the step-by-step process of installing and configuring Keycloak on a Kubernetes cluster using an Ingress controller and connecting Keycloak to an existing AWS RDS MySQL database.

Keycloak is an open-source identity and access management solution. Here, we will deploy it on Kubernetes and use AWS RDS as the backing database.

Prerequisites:

A Kubernetes cluster is up and running.
AWS RDS MySQL database already created and configured.
ALB Ingress controller set up in your Kubernetes cluster.
Domain name and TLS certificate available for Keycloak Ingress (optional but recommended for production).

Step 1: Namespace Creation

We will first create a namespace where all the Keycloak resources will be placed.

apiVersion: v1
kind: Namespace
metadata:
  name: keycloak


$ kubectl apply -f namespace.yaml

Step 2: Create Secrets for Database Credentials

Instead of hardcoding sensitive data such as the database credentials in the deployment file, we will store the credentials in Kubernetes secrets. This approach ensures better security for your deployment.

Create the Kubernetes Secret for the RDS Database:

kubectl create secret generic keycloak-db-secret \
  --namespace=keycloak \
  --from-literal=db-username='your-db-username' \
  --from-literal=db-password='your-db-password' \
  --from-literal=db-name='your-database-name' \
  --from-literal=db-host='your-rds-endpoint'

Step 2: Keycloak Deployment

In the following deployment, YAML will set up a Keycloak instance on Kubernetes. We are using the official Keycloak image and connecting it to an RDS MySQL database.

Keycloak Deployment YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: keycloak
  namespace: keycloak
  labels:
    app: keycloak
spec:
  replicas: 1
  selector:
    matchLabels:
      app: keycloak
  template:
    metadata:
      labels:
        app: keycloak
    spec:
      containers:
      - name: keycloak
        image: quay.io/keycloak/keycloak:25.0.0
        args: ["start-dev"]
        env:
        - name: KEYCLOAK_ADMIN
          value: "admin"
        - name: KEYCLOAK_ADMIN_PASSWORD
          value: "your_admin_password"
        - name: DB_VENDOR
          value: mysql
        - name: DB_ADDR
          valueFrom:
            secretKeyRef:
              name: keycloak-db-secret
              key: db-host
        - name: DB_USERNAME
          valueFrom:
            secretKeyRef:
              name: keycloak-db-secret
              key: db-username
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: keycloak-db-secret
              key: db-password
        - name: DB_DATABASE
          valueFrom:
            secretKeyRef:
              name: keycloak-db-secret
              key: db-name
        - name: DB_PORT
          value: "3306"
        - name: KC_PROXY
          value: "edge"
        ports:
        - name: http
          containerPort: 8080
        readinessProbe:
          httpGet:
            path: /realms/master
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 3

In this deployment:

We are using quay.io/keycloak/keycloak:20.0.3 image.
The environment variables are configured to point to your RDS MySQL instance (replace placeholders like your-rds-endpoint with your actual values).
The Keycloak admin username and password are defined in the environment variables.

Apply the Deployment:

kubectl apply -f deployment.yaml

Step 3: Keycloak Service

We will now expose the Keycloak deployment as a service. For this guide, we are using a NodePort service type.

apiVersion: v1
kind: Service
metadata:
  name: keycloak
  namespace: keycloak
  labels:
    app: keycloak
spec:
  ports:
  - name: http
    port: 8080
    targetPort: 8080
  selector:
    app: keycloak
  type: NodePort


$kubectl apply -f service.yaml

This will create a NodePort service that exposes Keycloak on the port 8080.

Step 4: Ingress Configuration

We will create an Ingress resource to expose Keycloak externally via an Application Load Balancer (ALB) in AWS. Ensure that you have installed the ALB Ingress Controller in your Kubernetes cluster.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  namespace: keycloak
  name: ingress-keycloak
  annotations:
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/target-type: instance
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTP": 8080}, {"HTTPS": 443}]'
    alb.ingress.kubernetes.io/certificate-arn: "<YOUR-CERTIFICATE-ARN>"
spec:
  ingressClassName: alb
  tls:
    - hosts:
      - keycloak.yourdomain.com
  rules:
  - host: keycloak.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: keycloak
            port:
              number: 8080

In this Ingress configuration:

We are setting up an internet-facing ALB (Application Load Balancer).
TLS is enabled using an AWS Certificate Manager certificate (replace <YOUR-CERTIFICATE-ARN> with your actual ARN).
The domain is set as keycloak.yourdomain.com, which should point to the ALB.

Apply the Ingress:

kubectl apply -f ingress.yaml

Once applied, the ALB Ingress Controller will create an ALB and associate it with your domain.

Adding ALB’s DNS name to Route53:

To make the Keycloak Admin Dashboard accessible via a custom DNS name, add the ALB’s DNS name as a DNS record in Route 53.

Follow these steps in the AWS Management Console:

Go to AWS Management Console and open the Route53 console.

Go to “Route53” and select the hosted zone where you want to add the DNS record for the ALB.
Click on “Create Record Set.”
Configure the following settings:

Name: Enter the desired subdomain or domain name for the ALB (e.g., “keycloak.yourdomain.com”).
Type: Choose “CNAME.”
Alias: Set this to “No.”
Value: Enter the ALB’s DNS name you retrieved earlier (e.g., “cluster-alb-<account-id>.us-west-2.elb.amazonaws.com”).
TTL (Seconds): Optionally, set the Time To Live (TTL) for the DNS record.

4. Click “Create” to add the DNS record.

After creating the DNS record, Once the changes have propagated, users can access the keycloak Admin Dashboard using the custom DNS name.

Step 5: Verify the Setup

After deploying Keycloak and the Ingress, you should be able to access Keycloak at http://keycloak.yourdomain.com (or https:// if you’ve configured TLS).
Use the admin credentials defined deployment.yaml to log into the Keycloak admin console.
Verify that Keycloak is connected to your RDS database by checking if the data is persisted in your MySQL instance.

Conclusion

You have successfully deployed and configured Keycloak on Kubernetes, securely connected it to an AWS RDS MySQL database using Kubernetes secrets, and exposed it externally using an AWS Application Load Balancer (ALB). With this setup, you now have a scalable and production-ready identity and access management solution.

Keycloak can now be integrated with any application to provide a robust and flexible authentication mechanism, offering support for modern standards like OAuth2, OpenID Connect, and SAML. Whether you are building a new application or integrating with existing services, Keycloak enables you to manage authentication, authorization, and user identity with ease.

Using this setup, you can:

Integrate Keycloak with microservices running in your Kubernetes cluster for centralized authentication.
Configure Single Sign-On (SSO) for multiple applications.
Leverage the RDS-backed persistence to store and manage users, roles, and authentication data efficiently.
Take advantage of Kubernetes and ALB scalability to handle increasing loads for enterprise applications.

This Keycloak setup on Kubernetes, combined with AWS resources, ensures a highly available and fault-tolerant environment for managing user authentication and authorization.

I hope that you find this article and my experience helpful, and thanks for taking the time to read my article.

If you have any questions or feedback, feel free to comment.

About The Author
Suraj Solanki
Senior DevOps Engineer
LinkedIn: https://www.linkedin.com/in/suraj-solanki
Topmate: https://topmate.io/suraj_solanki