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

💡 Tip

Do not use the minikube-load-images target on a shell session where you have already evaluated $(minikube docker-env), or the target won’t be able to load the images into Minikube.

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

⚠️ Warning

The fixtures in helm/polaris/ci/fixtures/ are intended for testing purposes only and are not suitable for production use. Especially, the PostgreSQL and MongoDB instances are configured without encryption or security and should never be deployed as is in production!

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.

📝 Note

The Helm integration tests (see below) do not require bootstrapping realms, as they do not exercise (yet) Polaris REST APIs.

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