Development & Testing

This guide provides instructions for developers who want to work with the Polaris Helm chart locally, including setting up a local Kubernetes cluster, building from source, and running tests.

Local Development with Minikube🔗

Prerequisites🔗

• Minikube installed
• Helm 3.x or 4.x installed
• kubectl installed

Starting Minikube🔗

Start a local Minikube cluster:

minikube start

Installing from the Official Repository🔗

Add the official Polaris Helm repository and install the chart:

helm repo add polaris https://downloads.apache.org/polaris/helm-chart
helm repo update
kubectl create namespace polaris
helm install polaris polaris/polaris --namespace polaris

Verify the installation:

helm test polaris --namespace polaris

Building and Installing from Source🔗

This section assumes you have cloned the Polaris Git repository and set up prerequisites to build the project. See the Install Dependencies guide for details.

Building Container Images🔗

Start Minikube and configure Docker to use Minikube’s Docker daemon:

minikube start
eval $(minikube docker-env)

Build the container images. The Polaris server image is required, the admin tool image is optional (useful for bootstrapping realms if necessary, see below):

./gradlew \
  :polaris-server:assemble \
  :polaris-server:quarkusAppPartsBuild --rerun \
  :polaris-admin:assemble \
  :polaris-admin:quarkusAppPartsBuild --rerun \
  -Dquarkus.container-image.build=true

Alternatively, you can use Make to start Minikube and build the images:

make minikube-start-cluster
make build
make minikube-load-images

Creating the Namespace and Fixtures🔗

Create the namespace and deploy fixtures:

kubectl create namespace polaris
kubectl apply --namespace polaris -f helm/polaris/ci/fixtures/

The fixtures deploy a PostgreSQL instance and a MongoDB instance that can be used for testing purposes. If you plan to test with persistence backends, wait for the database pods to be ready:

kubectl wait --namespace polaris --for=condition=ready pod --selector=app.kubernetes.io/name=postgres --timeout=120s
kubectl wait --namespace polaris --for=condition=ready pod --selector=app.kubernetes.io/name=mongodb --timeout=120s

Alternatively, you can use Make to deploy the fixtures:

make helm-fixtures

Installing the Chart Manually🔗

Install the chart from the local source, using either the values.yaml file, or any of the values files in helm/polaris/ci/. Example:

# Non-persistent backend
helm upgrade --install --namespace polaris polaris helm/polaris

# Persistent backend
helm upgrade --install --namespace polaris \
  --values helm/polaris/ci/persistence-values.yaml \
  polaris helm/polaris

Bootstrapping Realms for Development🔗

When doing adhoc testing with a persistent backend, you may want to bootstrap all the realms using the admin tool. For more information, see the Admin Tool guide.

Example for the PostgreSQL backend:

kubectl run polaris-bootstrap \
  -n polaris \
  --image=apache/polaris-admin-tool:latest \
  --restart=Never \
  --rm -it \
  --env="polaris.persistence.type=relational-jdbc" \
  --env="quarkus.datasource.username=$(kubectl get secret polaris-persistence -n polaris -o jsonpath='{.data.username}' | base64 --decode)" \
  --env="quarkus.datasource.password=$(kubectl get secret polaris-persistence -n polaris -o jsonpath='{.data.password}' | base64 --decode)" \
  --env="quarkus.datasource.jdbc.url=$(kubectl get secret polaris-persistence -n polaris -o jsonpath='{.data.jdbcUrl}' | base64 --decode)" \
  -- \
  bootstrap -r POLARIS -c POLARIS,root,s3cr3t

Example for the NoSQL (MongoDB) backend:

kubectl run polaris-bootstrap \
  -n polaris \
  --image=apache/polaris-admin-tool:latest \
  --restart=Never \
  --rm -it \
  --env="polaris.persistence.type=nosql" \
  --env="polaris.persistence.nosql.backend=MongoDb" \
  --env="quarkus.mongodb.database=polaris" \
  --env="quarkus.mongodb.connection-string=$(kubectl get secret polaris-nosql-persistence -n polaris -o jsonpath='{.data.connectionString}' | base64 --decode)" \
  -- \
  bootstrap -r POLARIS -c POLARIS,root,s3cr3t

Both commands above bootstrap a realm named POLARIS with root password: s3cr3t.

Running Chart Tests🔗

Prerequisites🔗

Install the required tools:

brew install chart-testing
brew install yamllint
make helm-install-plugins

The following tools will be installed:

• Helm Unit Test
• Helm JSON Schema
• Chart Testing
• yamllint

Unit Tests🔗

Helm unit tests do not require a Kubernetes cluster. Run them from the Polaris repo root:

make helm-unittest

Linting🔗

Lint the chart using the Chart Testing tool:

make helm-lint

Making Changes to Documentation or Schema🔗

If you make changes to the Helm chart’s values.yaml file, you need to regenerate the documentation and schema. Run from the Polaris repo root:

make helm-schema-generate helm-doc-generate

Alternatively, you can run:

make helm

This will run all Helm-related targets, including unit tests, linting, schema generation, and documentation generation (it will not run integration tests though).

Integration Tests🔗

Integration tests are tests executed with the ct install tool. They require a Kubernetes cluster with fixtures deployed, as explained in the Installing the Chart Manually section above.

The simplest way to run the integration tests is to use Make:

make helm-integration-test

The above command will build and load the images into Minikube, deploy the fixtures, and run all ct install tests.

Cleanup🔗

Uninstall the chart, remove resources and delete the namespace:

helm uninstall --namespace polaris polaris
kubectl delete namespace polaris --wait=true --ignore-not-found

The stop Minikube if desired:

minikube stop

Alternatively, you can use Make to perform the cleanup:

make helm-fixtures-cleanup
make minikube-stop-cluster
make minikube-cleanup # will delete the Minikube cluster