Kubernetes

Get started with Keycloak on Kubernetes.

Before you start

Make sure your machine or container platform can provide sufficient memory and CPU for your desired usage of Keycloak. See Concepts for sizing CPU and memory resources for more on how to get started with production sizing.

Make sure you have Minikube installed, ideally with the Ingress addon enabled.

To check if you have the Ingress addon enabled, enter the following command:

minikube addons list

If the Ingress addon is not enabled, enter the following command to enable it:

minikube addons enable ingress

Start Keycloak

The Keycloak QuickStarts repository includes some example files to help deploy Keycloak to Kubernetes.

As a first step, create the Keycloak statefulset and service by entering the following command:

kubectl create -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/refs/heads/main/kubernetes/keycloak.yaml

This command starts Keycloak on Kubernetes and creates an initial admin user with the username admin and password admin.

If you will eventually want more than one server replica, please see the Scaling guide.

Access Keycloak with Ingress addon enabled

Now create an Ingress for Keycloak by entering the following command:

wget -q -O - https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/refs/heads/main/kubernetes/keycloak-ingress.yaml | \
sed "s/KEYCLOAK_HOST/keycloak.$(minikube ip).nip.io/" | \
kubectl create -f -

If wget and sed are not available, download the file and manually edit the file replacing KEYCLOAK_HOST with keycloak.<minikube ip address>.nip.io.

Enter the following command to see the Keycloak URLs:

KEYCLOAK_URL=https://keycloak.$(minikube ip).nip.io &&
echo "" &&
echo "Keycloak:                 $KEYCLOAK_URL" &&
echo "Keycloak Admin Console:   $KEYCLOAK_URL/admin" &&
echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
echo ""

Access Keycloak without Ingress

If the Ingress addon is not enabled, enter the following command in a separate shell:

minikube tunnel

You can now access Keycloak from the following URL:

KEYCLOAK_URL=http://$(minikube ip):$(kubectl get services/keycloak -o go-template='{{(index .spec.ports 0).nodePort}}') &&
echo "" &&
echo "Keycloak:                 $KEYCLOAK_URL" &&
echo "Keycloak Admin Console:   $KEYCLOAK_URL/admin" &&
echo "Keycloak Account Console: $KEYCLOAK_URL/realms/myrealm/account" &&
echo ""

Remember these URLs. You need them as you follow the instructions in this guide. The URL for the Account Console does not work yet as you need to create the realm first.

Log in to the Admin Console

  1. Go to the Keycloak Admin Console.

  2. Log in with the username and password you created earlier.

Create a realm

A realm in Keycloak is equivalent to a tenant. Each realm allows an administrator to create isolated groups of applications and users. Initially, Keycloak includes a single realm, called master. Use this realm only for managing Keycloak and not for managing any applications.

Use these steps to create the first realm.

  1. Open the Keycloak Admin Console.

  2. Click Create Realm next to Current realm.

  3. Enter myrealm in the Realm name field.

  4. Click Create.

Add realm
Figure 1. Add realm

Create a user

Initially, the realm has no users. Use these steps to create a user:

  1. Verify that you are still in the myrealm realm, which is next to Current realm.

  2. Click Users in the left-hand menu.

  3. Click Create new user.

  4. Fill in the form with the following values:

    • Username: myuser

    • First name: any first name

    • Last name: any last name

  5. Click Create.

Create user
Figure 2. Create user

This user needs a password to log in. To set the initial password:

  1. Click Credentials at the top of the page.

  2. Fill in the Set password form with a password.

  3. Toggle Temporary to Off so that the user does not need to update this password at the first login.

Set password
Figure 3. Set password

Log in to the Account Console

You can now log in to the Account Console to verify this user is configured correctly.

  1. Open the Keycloak Account Console.

  2. Log in with myuser and the password you created earlier.

As a user in the Account Console, you can manage your account including modifying your profile, adding two-factor authentication, and including identity provider accounts.

Keycloak Account Console

Secure the first application

To secure the first application, you start by registering the application with your Keycloak instance:

  1. Open the Keycloak Admin Console.

  2. Click myrealm next to Current realm.

  3. Click Clients.

  4. Click Create client

  5. Fill in the form with the following values:

    • Client type: OpenID Connect

    • Client ID: myclient

      Add client
      Figure 4. Add client

  6. Click Next

  7. Confirm that Standard flow is enabled.

  8. Click Next.

  9. Make these changes under Login settings.

    • Set Valid redirect URIs to https://www.keycloak.org/app/*

    • Set Web origins to https://www.keycloak.org

  10. Click Save.

Update client
Figure 5. Update client

To confirm the client was created successfully, you can use the SPA testing application on the Keycloak website.

  1. Open https://www.keycloak.org/app/.

  2. Change Keycloak URL to the URL of your Keycloak instance.

  3. Click Save.

  4. Click Sign in to authenticate to this application using the Keycloak server you started earlier.

Taking the next step

Before you run Keycloak in production, consider the following actions:

  • Switch to a production ready database such as PostgreSQL.

  • Configure SSL with your own certificates.

  • Switch the admin password to a more secure password.

For more information, see the server guides.

On this page
Edit this guide