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:

1minikube start

Installing from the Official Repository🔗

Add the official Polaris Helm repository and install the chart:

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

Verify the installation:

1helm 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:

1minikube start
2eval $(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):

1./gradlew \
2  :polaris-server:assemble \
3  :polaris-server:quarkusAppPartsBuild --rerun \
4  :polaris-admin:assemble \
5  :polaris-admin:quarkusAppPartsBuild --rerun \
6  -Dquarkus.container-image.build=true

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

1make minikube-start-cluster
2make build
3make minikube-load-images

Creating the Namespace and Fixtures🔗

Create the namespace and deploy fixtures:

1kubectl create namespace polaris
2kubectl 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:

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

Alternatively, you can use Make to deploy the fixtures:

1make 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:

1# Non-persistent backend
2helm upgrade --install --namespace polaris polaris helm/polaris
3
4# Persistent backend
5helm upgrade --install --namespace polaris \
6  --values helm/polaris/ci/persistence-values.yaml \
7  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:

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

Example for the NoSQL (MongoDB) backend:

 1kubectl run polaris-bootstrap \
 2  -n polaris \
 3  --image=apache/polaris-admin-tool:latest \
 4  --restart=Never \
 5  --rm -it \
 6  --env="polaris.persistence.type=nosql" \
 7  --env="polaris.persistence.nosql.backend=MongoDb" \
 8  --env="quarkus.mongodb.database=polaris" \
 9  --env="quarkus.mongodb.connection-string=$(kubectl get secret polaris-nosql-persistence -n polaris -o jsonpath='{.data.connectionString}' | base64 --decode)" \
10  -- \
11  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:

1brew install chart-testing
2brew install yamllint
3make 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:

1make helm-unittest

Linting🔗

Lint the chart using the Chart Testing tool:

1make 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:

1make helm-schema-generate helm-doc-generate

Alternatively, you can run:

1make 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:

1make 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:

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

The stop Minikube if desired:

1minikube stop

Alternatively, you can use Make to perform the cleanup:

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