Adding FusionAuth to Kubernetes

FusionAuth is a platform for adding authentication and authorization to your apps. It’s practically a plug-and-play platform, allowing you to focus on your own app development and leave the security aspects to the security experts. In November 2021, FusionAuth announced that their product can now be run in a Kubernetes environment. Let’s take a look at how to do that. Our goal here is to get a simple Kubernetes setup running on your own development machine and deploy FusionAuth to a container.


First, you will want to get your system up to speed with a development setup for Kubernetes; for this, we’ll use Minikube. For this example I’m using Ubuntu Linux; here are the overall steps for getting Minikube set up in this environment:

  1. Install Docker Engine
  2. Install the kubectl command
  3. Install Helm
  4. Install Minikube

Once everything is installed, you can start Minikube by typing:

minikube start

Minikube will take a couple of minutes to pull down the necessary images to run.

Installing the Database

Our next steps will be to install a PostgreSQL container, which will hold the data for FusionAuth.

To install PostgreSQL, we’re going to use Bitnami’s repo by adding it like so:

helm repo add bitnami

Now we’ll use Helm to install PostgreSQL. Type:

helm install mypostgres bitnami/postgresql --set postgresqlPassword=abc123

For this example, we’re assigning the password abc123 to the PostgreSQL login. Remember, we’re just doing a practice run on Minikube, so in an actual production environment, you’ll want to make it much more secure!

You can check the progress by repeatedly typing:

kubectl get pods -o wide

until the Ready column in the output shows 1/1 and the Status column shows Running, like so:

NAME                      READY   STATUS    RESTARTS   AGE   IP           NODE
mypostgres-postgresql-0   1/1     Running   0          89s   minikube

(I’ve truncated the output as it actually includes more information than this.)

Installing FusionAuth

FusionAuth has their own chart that we can obtain through Helm. First, add FusionAuth’s own repo like so:

helm repo add fusionauth

But before we can install FusionAuth, the chart needs specific values that you supply through a YAML file. Type the following to pull down a starter file:

curl -o fusionauth.yaml

Now, open fusionauth.yaml in your favorite editor.  In the “database” section, set

protocol: postgresql
host: "mypostgres-postgresql"
user: "postgres"
password: "abc123"

Note that the protocol’s value of postgresql should not have double quotes around it. The other values do. In the database/root section, set the user and password again to postgres and abc123, respectively.

And finally, under the “search” section, set engine to database, without double quotes:

engine: database

Save the file and exit the editor. Now you can install FusionAuth, using the values in this YAML file, by typing the following:

helm install my-release fusionauth/fusionauth -f fusionauth.yaml

This will launch FusionAuth. It might take a minute or two to start. As before, enter

kubectl get pods -o wide

several times and watch for the Ready column to be 1/1 and Status to be Running. Note that it might take two or three minutes to be ready.

That’s it; the database and FusionAuth are now installed and running. Now, you’ll need to do a port forward so you can try it out by typing:

kubectl port-forward svc/my-release-fusionauth 9011:9011

Next, open your browser and go to http://localhost:9011. You should see the setup screen.

You can now follow the instructions for configuring and using FusionAuth.

Next Steps

For a full deployment, the above steps should generally work outside of Minikube. Additionally, when you deploy your app into Kubernetes, it will all be packaged neatly alongside FusionAuth, allowing for a self-contained ecosystem. However, you have a couple of options. You can, if you prefer, use MySQL instead of PostgreSQL. To do so, you’ll change the database protocol in fusionauth.yaml to mysql. You will also need to determine the host name of the database container and use that in the YAML file. Finally, you may or may not want to include Elasticsearch. If your app will have thousands of users or more, you’ll likely want to use Elasticsearch as it provides much better performance than PostgreSQL or MySQL alone.