FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
  • 5-Minute Setup Guide
  • Release Notes
  • Core Concepts
    • Overview
    • Users
    • Roles
    • Groups
    • Entity Management
    • Registrations
    • Applications
    • Tenants
    • Identity Providers
    • Key Master
    • SCIM
    • Search
    • Authentication and Authorization
    • Integration Points
    • Localization and Internationalization
    • Editions and Features
    • Roadmap
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Licensing
    • Monitoring
    • Proxy Setup
    • Securing
    • Technical Support
    • Troubleshooting
    • Upgrading
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Tutorial
  • APIs
    • Overview
    • Authentication
    • Errors
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Kafka
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM EnterpriseUser
      • SCIM Group
      • SCIM Service Provider Config.
      • SCIM User
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • Webhooks
  • Client Libraries
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • Node
    • OpenAPI
    • PHP
    • Python
    • Ruby
    • Typescript
  • Themes
    • Overview
    • Examples
    • Helpers
    • Localization
    • Template Variables
  • Email & Templates
    • Overview
    • Configure Email
    • Email Templates
    • Email Variables
    • Message Templates
  • Events & Webhooks
    • Overview
    • Writing a Webhook
    • Securing Webhooks
    • Events
      • Overview
      • Audit Log Create
      • Event Log Create
      • JWT Public Key Update
      • JWT Refresh
      • JWT Refresh Token Revoke
      • Kickstart Success
      • User Action
      • User Bulk Create
      • User Create
      • User Create Complete
      • User Deactivate
      • User Delete
      • User Delete Complete
      • User Email Update
      • User Email Verified
      • User IdP Link
      • User IdP Unlink
      • User Login Failed
      • User Login Id Duplicate Create
      • User Login Id Duplicate Update
      • User Login New Device
      • User Login Success
      • User Login Suspicious
      • User Password Breach
      • User Password Reset Send
      • User Password Reset Start
      • User Password Reset Success
      • User Password Update
      • User Reactivate
      • User Registration Create
      • User Registration Create Complete
      • User Registration Delete
      • User Registration Delete Complete
      • User Registration Update
      • User Registration Update Complete
      • User Registration Verified
      • User Two Factor Method Add
      • User Two Factor Method Remove
      • User Update
      • User Update Complete
  • Example Apps
    • Overview
    • Dart
    • Go
    • Java
    • JavaScript
    • .NET Core
    • PHP
    • Python
    • Ruby
  • Lambdas
    • Overview
    • Apple Reconcile
    • Client Cred. JWT Populate
    • Epic Games Reconcile
    • External JWT Reconcile
    • Facebook Reconcile
    • Google Reconcile
    • HYPR Reconcile
    • JWT Populate
    • LDAP Connector Reconcile
    • LinkedIn Reconcile
    • Nintendo Reconcile
    • OpenID Connect Reconcile
    • SAML v2 Populate
    • SAML v2 Reconcile
    • SCIM Group Req. Converter
    • SCIM Group Resp. Converter
    • SCIM User Req. Converter
    • SCIM User Resp. Converter
    • Sony PSN Reconcile
    • Steam Reconcile
    • Twitch Reconcile
    • Twitter Reconcile
    • Xbox Reconcile
  • Identity Providers
    • Overview
    • Apple
    • Epic Games
    • External JWT
      • Overview
      • Example
    • Facebook
    • Google
    • HYPR
    • LinkedIn
    • Nintendo
    • OpenID Connect
      • Overview
      • Azure AD
      • Discord
      • Github
    • Sony PlayStation Network
    • Steam
    • Twitch
    • Twitter
    • SAML v2
      • Overview
      • ADFS
    • SAML v2 IdP Initiated
      • Overview
      • Okta
    • Xbox
  • Messengers
    • Overview
    • Generic Messenger
    • Kafka Messenger
    • Twilio Messenger
  • Connectors
    • Overview
    • Generic Connector
    • LDAP Connector
    • FusionAuth Connector
  • Self Service Account Mgmt
    • Overview
    • Updating User Data & Password
    • Add Two-Factor Authenticator
    • Add Two-Factor Email
    • Add Two-Factor SMS
    • Customizing
    • Troubleshooting
  • Advanced Threat Detection
    • Overview
  • Integrations
    • Overview
    • CleanSpeak
    • Kafka
    • Twilio
  • OpenID Connect & OAuth 2.0
    • Overview
    • Endpoints
    • Tokens
  • SAML v2 IdP
    • Overview
    • Google
    • Zendesk
  • Plugins
    • Plugins
    • Writing a Plugin
    • Custom Password Hashing
  • Guides
    • Overview
    • Advanced Registration Forms
    • Breached Password Detection
    • Multi-Factor Authentication
    • Multi-Tenant
    • Passwordless
    • Securing Your APIs
    • Silent Mode
    • Single Sign-on
  • Tutorials
    • Overview
    • User Control & Gating
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
    • Setup Wizard & First Login
    • Register/Login a User
    • Start and Stop FusionAuth
    • Authentication Tokens
    • Key Rotation
    • JSON Web Tokens
    • Prometheus Setup
    • Switch Search Engines
    • Two Factor (pre 1.26)
  • Reference
    • CORS
    • Configuration
    • Data Types
    • Known Limitations
    • Password Hashes

    Local Kubernetes Cluster Setup With minikube

    Overview

    Having the capability to deploy applications in a local Kubernetes environment allows engineers to quickly develop, test, and demo without the operational overhead of a full-blown cluster. This is precisely what minikube is designed for by creating a single-node cluster within a virtual machine.

    This guide will show you how to install and configure minikube and then install FusionAuth, including the required PostgreSQL database and Elasticsearch, on your minikube cluster.

    Figure 1 shows an example of the minikube configuration that you will create. The cluster will consist of three Replica Sets, one for each deployment of Elasticsearch, Postgresql, and FusionAuth. Each will have one Pod, with the exception of Elasticsearch which will have three. You could scale it down to one pod, but for simplicity, you will use the default settings for the Elasticsearch chart. Each deployment exposes a Service which exposes each application as a network service. Finally, you will use an Ingress Controller of type Load Balancer that allows external traffic, or in this case, traffic from localhost to the cluster.

    fa minikube
    Figure 1. Example Kubernetes configuration in minikube

    Requirements

    Before you begin, you will need to have the following installed.

    • Docker Desktop - The virtual machine environment you will use to run minikube.

    • helm - Package manager used for installing and managing Kubernetes applications. In this guide, you will be using a Helm chart to install FusionAuth, a Postgresql database, and Elasticsearch cluster. For more information, see Installing Helm.

    • kubectl - Command line tool that interacts with the Kubernetes API server and is useful for managing Kubernetes clusters. Before proceeding, follow the installation documentation that corresponds to your platform found here.

    Install minikube

    Navigate to minikube start and complete step one by selecting the options that apply to your local machine.

    For example, if you are running on macOS with x86-64 architecture, Homebrew is a popular installer type:

    Install minikube
    brew install minikube

    Start minikube

    Since you will be deploying multiple applications, you will want to start minikube using some additional resource considerations.

    Before proceeding, make sure Docker Desktop has sufficient resources allocated. These settings can be found in Docker Desktop by navigating to Preferences and then clicking on Resources in the side menu bar. You need to have at least as much memory allocated to Docker Desktop as you give to minikube below.

    Start minikube by additionally specifying cpus and memory.

    Start minikube
    minikube start --cpus 4 --memory 5g

    This minikube setting is a general recommendation that has been tested for this guide based on resource requirements of FusionAuth, Postgresql, and Elasticsearch.

    When the command finishes, it will configure kubectl to point to the minikube cluster. You can confirm this by checking the status:

    Get minikube status
    minikube status
    
    minikube
    type: Control Plane
    host: Running
    kubelet: Running
    apiserver: Running
    kubeconfig: Configured

    Or by running the kubectl command to view pods running on the cluster. Use the -A or --all-namespaces to list all pods deployed to the cluster. Since you have not deployed anything yet, only pods in the kube-system namespace will be returned:

    Get all pods deployed on the cluster
    kubectl get pods -A
    
    NAMESPACE     NAME                               READY   STATUS    RESTARTS       AGE
    kube-system   coredns-78fcd69978-tr4jt           1/1     Running   0              9m38s
    kube-system   etcd-minikube                      1/1     Running   0              9m53s
    kube-system   kube-apiserver-minikube            1/1     Running   0              9m51s
    kube-system   kube-controller-manager-minikube   1/1     Running   0              9m54s
    kube-system   kube-proxy-2h8b2                   1/1     Running   0              9m38s
    kube-system   kube-scheduler-minikube            1/1     Running   0              9m51s
    kube-system   storage-provisioner                1/1     Running   1 (9m8s ago)   9m50s

    Deploy Postgresql

    Start by adding the bitnami helm repository that contains the Postgresql chart:

    Add PostgreSQL chart repository
    helm repo add bitnami https://charts.bitnami.com/bitnami

    To list all of the Helm repositories that you have added, execute this command:

    List chart repositories
    helm repo list

    The resulting output will display the chart you just added and any other helm charts that you may have added previously.

    Output
    NAME      	URL
    bitnami   	https://charts.bitnami.com/bitnami

    Install the chart using the helm command. Set the postgresqlPassword value using the set flag for the postgres user. In this example, the release field is set to pg-minikube:

    Install the postgresql chart
    helm install pg-minikube bitnami/postgresql \
      --set postgresqlPassword=<your-postgresql-password>

    When completed successfully, the output will contain some useful information about your deployment:

    Output of PostgreSQL creation command
    ** Please be patient while the chart is being deployed **
    
    PostgreSQL can be accessed via port 5432 on the following DNS names from within your cluster:
    
        pg-minikube-postgresql.default.svc.cluster.local - Read/Write connection
    
    To get the password for "postgres" run:
    
        export POSTGRES_PASSWORD=$(kubectl get secret --namespace default pg-minikube-postgresql -o jsonpath="{.data.postgresql-password}" | base64 --decode)
    
    To connect to your database run the following command:
    
        kubectl run pg-minikube-postgresql-client --rm --tty -i --restart='Never' --namespace default --image docker.io/bitnami/postgresql:11.13.0-debian-10-r40 --env="PGPASSWORD=$POSTGRES_PASSWORD" --command -- psql --host pg-minikube-postgresql -U postgres -d postgres -p 5432
    
    To connect to your database from outside the cluster execute the following commands:
    
        kubectl port-forward --namespace default svc/pg-minikube-postgresql 5432:5432 &
        PGPASSWORD="$POSTGRES_PASSWORD" psql --host 127.0.0.1 -U postgres -d postgres -p 5432

    When you deploy FusionAuth, you will need to use the DNS name pg-minikube-postgresql.default.svc.cluster.local as seen above and the password that you set in the install command.

    You can test your deployment by attempting to connect to the database following the instructions in the output. You can also verify the pg-minikube-postgresql pod by again retrieving pods with kubectl. The following command requests pods in the default namespace with output (-o) containing additional information such as IP Address:

    Get pods in the default namespace
    kubectl get pods -n default -o wide

    The resulting output will show 1/1 pg-minikube-postgresql pod in a READY state:

    Output
    NAME                       READY   STATUS    RESTARTS   AGE     IP           NODE       NOMINATED NODE   READINESS GATES
    pg-minikube-postgresql-0   1/1     Running   0          8m33s   172.17.0.3   minikube   <none>           <none>

    When a Pod is in a status of READY, it means that it is available to serve requests and should be added to load balancing pools of all matching services. You can read more about Pod lifecycles here.

    You can also retrieve active services on the cluster. A Kubernetes Service exposes applications running on a pod as a network service. The following command will display the new service exposing the Postgresql application with an IP address running on port 5432:

    Get services
    kubectl get services -n default
    
    NAME                              TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
    kubernetes                        ClusterIP   10.96.0.1        <none>        443/TCP    82m
    pg-minikube-postgresql            ClusterIP   10.108.174.128   <none>        5432/TCP   27m
    pg-minikube-postgresql-headless   ClusterIP   None             <none>        5432/TCP   27m

    In addition to the pg-minikube-postgresql service, you will see another service with the name kubernetes. This service is responsible for directing traffic to the Kubernetes API server.

    You also might have noticed the additional postgresql service pg-minikube-postgresql-headless. This is what is known in Kubernetes as a Headless Service. To read more about these types of services, see the official Kubernetes documentation here.

    Deploy Elasticsearch

    Start by adding the Elasticsearch Helm Chart repository by running this command:

    Add Elasticsearch chart repository
    helm repo add elastic https://helm.elastic.co

    You will now have the two charts that you have added in this guide in addition to any other charts you have added if you have used Helm prior to this guide.

    List chart repositories
    helm repo list
    
    NAME      	URL
    bitnami   	https://charts.bitnami.com/bitnami
    elastic   	https://helm.elastic.co

    Before installing, you will need to download a copy of a recommended configuration for minikube virtual machines:

    Download example minikube configuration
    curl -O https://raw.githubusercontent.com/elastic/Helm-charts/master/elasticsearch/examples/minikube/values.yaml

    The contents of this configuration uses a smaller JVM heap, smaller memory per pods requests, and smaller persistent volumes. The values.yaml file you downloaded should look like this:

    Configuration details
    # Permit co-located instances for solitary minikube virtual machines.
    antiAffinity: "soft"
    
    # Shrink default JVM heap.
    esJavaOpts: "-Xmx128m -Xms128m"
    
    # Allocate smaller chunks of memory per pod.
    resources:
      requests:
        cpu: "100m"
        memory: "512M"
      limits:
        cpu: "1000m"
        memory: "512M"
    
    # Request smaller persistent volumes.
    volumeClaimTemplate:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: "standard"
      resources:
        requests:
          storage: 100M

    Now install the Elasticsearch chart using this values.yaml configuration by including the -f flag:

    Install elasticsearch chart
    helm install es-minikube elastic/elasticsearch -f values.yaml

    Be aware, it may take a minute or two for the pods to reach a READY state.

    Confirm your deployment by retrieving active pods in the cluster.

    Get pods
    kubectl get pods -n default -o wide

    The resulting output will show three pods for each elasticsearch node:

    Output
    NAME                         READY   STATUS    RESTARTS   AGE     IP           NODE       NOMINATED NODE   READINESS GATES
    elasticsearch-master-0       1/1     Running   0          7m17s   172.17.0.5   minikube   <none>           <none>
    elasticsearch-master-1       1/1     Running   0          7m17s   172.17.0.4   minikube   <none>           <none>
    elasticsearch-master-2       1/1     Running   0          7m17s   172.17.0.6   minikube   <none>           <none>
    pg-minikube-postgresql-0     1/1     Running   0          39m     172.17.0.3   minikube   <none>           <none>

    Running the kubectl command to get service information again will show that the installed Elasticsearch chart exposes the elasticsearch-master Service running at a dedicated IP address on port 9200:

    Get services
    kubectl get services -n default
    
    NAME                              TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)             AGE
    elasticsearch-master              ClusterIP   10.107.78.6      <none>        9200/TCP,9300/TCP   3m38s
    elasticsearch-master-headless     ClusterIP   None             <none>        9200/TCP,9300/TCP   3m38s
    kubernetes                        ClusterIP   10.96.0.1        <none>        443/TCP             98m
    pg-minikube-postgresql            ClusterIP   10.100.117.198   <none>        5432/TCP            92m
    pg-minikube-postgresql-headless   ClusterIP   None             <none>        5432/TCP            92m

    Kubernetes DNS

    The default installation of minikube enables kube-dns, a Service that automatically assigns dns names to other services in the cluster.

    When you installed Postgresql and Elasticsearch, each service that was created was assigned the following dns names respectively by kube-dns:

    • pg-minikube-postgresql.default.svc.cluster.local

    • elasticsearch-master.default.svc.cluster.local

    You will use these values when deploying FusionAuth.

    For more information on DNS see Kubernetes documentation for DNS for Services and Pods.

    Next Steps

    You now are running all the necessary infrastructure to deploy a containerized application to minikube.

    Next up, Deploy FusionAuth in Kubernetes.

    Feedback

    How helpful was this page?

    See a problem?

    File an issue in our docs repo

    © 2021 FusionAuth
    Subscribe for developer updates