Deploying on Kubernetes (K8s)

Open Zaak supports deploying on Kubernetes as a first-class citizen, embracing the Cloud Native principles.

Note

This section assumes you are familiar with Kubernetes. If this is not the case, we advise you to read up on K8s first and come back to this documentation later.

This documentation is aimed at DevOps engineers.

Requirements

We recommend deploying on Haven-compliant clusters. The Open Zaak and Haven teams have coordinates the relevant infrastructure specification aspects.

Don’t panic if your cluster is not compliant (yet), as your cluster will likely still be capable of hosting Open Zaak.

Features and their requirements:

  • A PostgreSQL database (10, 11 and 12 are actively tested in CI) with the following extensions:

    • pg_trgm

    • postgis

  • Load balancing over multiple replicas is supported using Deployment resources

  • Fully stateless deployments without volumes are possible if and only if you do not use the Documents API backed by the local file system (the default). You can achieve this by using the CMIS-adapter or by using a Documents API from another vendor.

  • If you use the Documents API backed by the local file-system, you need a ReadWriteMany-capable persistent volume solution, even with a single replica.

Topology

Traffic from the ingress will enter Open Zaak at one or multiple NGINX reverse proxies. NGINX performs one of two possible tasks:

  • pass the request to the Open Zaak application or

  • send the binary data of uploaded files to the client

NGINX exists to serve uploaded files in a secure and performant way.

All other requests are passed to the Open Zaak application containers.

The application containers communicate with a PostgreSQL database, which must be provisioned upfront. Additionally, Redis is used for caching purposes.

Deployment tooling - Ansible

The Open Zaak organization maintains an Ansible collection which supports deploying on Kubernetes using the open_zaak_k8s role.

Note

We assume knowledge of Ansible playbooks in the rest of this section.

A sample deployment is included in the Open Zaak repository, pinned on the most recent stable Open Zaak version.

Get a copy of the deployment configuration

You can either clone the https://github.com/open-zaak/open-zaak repository, or download and extract the latest ZIP: https://github.com/open-zaak/open-zaak/archive/main.zip

Install dependencies

Note

Next to Ansible itself, we need some additional dependencies to interact with K8s clusters. These are Python libraries you need to install. The requirements are specified in the sample deployment directory.

First, navigate to the correct directory. In the folder where you placed the copy of the repository, change into the deployment directory:

(env) [user@host]$ cd /path/to/open-zaak/deployment/

Install the required dependencies with pip:

(env) [user@host]$ pip install -r requirements.txt

Next, install the Ansible playbook dependencies:

(env) [user@host]$ cd kubernetes
(env) [user@host]$ ansible-galaxy collection install -r requirements.yml

Deploying the applications

Open Zaak ships with a sample playbook for the applications, apps.yml, which

  • installs Open Zaak

  • installs Open Notificaties

You can run the Ansible-playbooks as-is (with some configuration through variables), or use them as inspiration for manual deployment.

For a list of all the available variables, check the collection roles.

Configuring Open Zaak

To deploy Open Zaak, some variables need to be set (in vars/open-zaak.yml):

You might want to tweak environment variables in order to provision a superuser.

Configuring Open Notificaties

To deploy Open Notificaties, some variables need to be set (in vars/open-notificaties.yml):

Deployment tooling - Helm

If you’re familiar with or prefer Helm, there are community-provided Helm charts for Open Zaak and Open Notificaties.

Note

These charts are contributed by the community on a best-effort basis. The Technical Steering Group takes no responsibility for the quality or up-to-date being of these charts.

Next steps

You may want to customize the logging setup. The default setup should be sufficient to get started though.

To be able to work with Open Zaak, a couple of things have to be configured first, see Open Zaak configuration for more details.

Updating an Open Zaak installation - Ansible

Make sure you have the deployment tooling installed - see Deployment tooling - Ansible for more details.

If you have an existing environment (from the installation), make sure to update it:

# fetch the updates from Github
[user@host]$ git fetch origin

# checkout the tag of the version you wish to update to, e.g. 1.0.0
[user@host]$ git checkout X.Y.z

# activate the virtualenv
[user@host]$ source env/bin/activate

# ensure all (correct versions of the) dependencies are installed
(env) [user@host]$ pip install -r requirements.txt

Open Zaak deployment code defines variables to specify the Docker image tag to use. This is synchronized with the git tag you’re checking out.

Warning

Make sure you are aware of possible breaking changes or manual interventions by reading the Changelog!

Next, to perform the upgrade, you run the apps.yml playbook just like with the installation:

(env) [user@host]$ ./deploy.sh apps.yml

Note

In the Kubernetes deployment setup, Open Zaak makes use of multiple replicas by default, and is set up to perform rolling releases. This means that the old version stays live until all new versions are running without errors.

We make use of health checks and liveness probes to achieve this.

This does mean that there’s a brief window where clients may hit the old or new version at the same time - usually this shouldn’t pose a problem.