Running in Cluster Mode

Overview

The Curity Identity Server is built to scale. With its unique configuration system, the Curity cluster scales linerarly with no internode dependencies.

The Curity cluster consists of an admin node and one or more runtime nodes. Every runtime node within the cluster will register at the admin node and receive updates regarding the configuration in a secure manner. The runtime nodes maintain a local copy of the configuration and continue to operate even in case the connection to the admin node breaks or the admin node goes down. It's recommended to setup a configuration secret which will make sure that any sensitive data in the configuration is secured even at rest.

Enabling Cluster Mode

To run the Curity Identity Server in cluster mode you need a cluster configuration. There are three different ways to create this configuration:

1. Run Curity locally and download one from the Admin UI
2. Use the CLI: request environments environment generate-cluster host ADMIN_HOSTNAME_OR_IP
3. Download and unpack Curity and run the <idsvr_home>/bin/genclust -c ADMIN_HOSTNAME_OR_IP command

Where ADMIN_HOSTNAME_OR_IP is the hostname or IP address of your admin node.

The cluster configuration basically tells every node how to communicate with the admin node, i.e. the IP or hostname and port of the registration endpoint of the admin node and the cluster key used for securing the connection. Therefore this configuration must be shared with each node during the initialization otherwise the node will not be able to join the cluster i.e. register at the admin. However, as mentioned above, if the node has a local copy of the configuration it will still be operable.

<config xmlns="http://tail-f.com/ns/config/1.0">
  <environments xmlns="https://curity.se/ns/conf/base">
    <environment>
      <cluster>
        <keystore>.v:S.RjNrUEhZdnRqWnxnQEM6Fl.....3tPAgmbxWKILmz1wwwxr1dJFCeWCY=</keystore>
        <host>idsvr-admin.company.local</host>
        <port>6789</port>
        <admin-listening-host>0.0.0.0</admin-listening-host>
      </cluster>
    </environment>
  </environments>
</config>

There is technically no need for an admin node in the cluster since the runtime nodes will be able to serve requests even if they cannot contact an admin node as long as they have a working local configuration. It is though strongly recommended to use an admin node because it ensures that all nodes have the same configuration and will be able to receive updates if required.

Joining the Cluster

There are two things to consider when deploying a new runtime node:

1. The node must have a valid cluster configuration.
2. The node must be assigned a service role.

During startup, the Curity Identity Server will always try to load the last configuration. If it cannot find any previous configuration, it will load configuration files from $IDSVR_HOME/etc/init. Put the cluster configuration into this folder during initialization. You may also put a complete configuration into this folder to minimize the load for the first update from admin node.

The service role is the template that specifies settings like which endpoints the node will expose. It implies which part of the configuration will be loaded by the node. For example, you may configure two different roles, one for issuing internal tokens and one for nodes that are exposed to the internet. The following command will setup a runtime node called node1 and assign a role called internal.

$ ${IDSVR_HOME}/bin/idsvr --service-role internal --service-name node1 --no-admin

In case the role is not (yet) configured, the runtime node will stay idle until it receives a suitable configuration update from the admin node. The runtime node will automatically register at the admin if it found a valid cluster configuration during startup and pull for any configuration updates. The node has hereby joined the cluster successfully.

Docker, Kubernetes and Helm

There are many different ways to deploy the Curity Identity Server. For example, you may use Docker containers and Docker Compose as described in the tutorial Clustering with Docker Compose.

You may use Kubernetes for your cluster as well. Curity provides a Helm chart that allows you to quickly and easily setup a cluster. With a single command and some configuration parameters you can install and update a cluster using Helm, add or remove nodes in an easy manner. Check out the tutorial Install the Curity Identity Server with Helm.