Skip to content

Level 4: Add a Rest API/Gateway

Before going through this guide, ensure you went through the level 3 : Add an Operator.

This tutorial explains how to add a Rest API/Gateway to your existing platform on an operator environment. The Rest API Gateway provides an endpoint design to Punchplatform features but also to Elasticsearch clusters.


Configure the Rest API Gateway

Edit first the punchplatform-deployment.settings file :


To get more details on each subsection, please read the punchplatform-deployment.settings documentation.

Then edit the file. The following configuration demonstrate a basic configuration for a Rest API Gateway communicating with a 3 nodes Elasticsearch cluster. We also consider that the same cluster is used for data and metrics :

      "mycluster": {
        "tenant": "mytenant",
        "servers": {
          "server1": {
            "inet_address": "",
            "port": 4000
        "elasticsearch": {
          "data_cluster": {
            "hosts":["server1:9200", "server2:9200", "server3:9200"]
          "metric_cluster": {
            "hosts": ["server1:9200", "server2:9200", "server3:9200"],
            "index": "gateway-logs"
        "services": {
          "extraction": {
            "formats": ["csv", "json"]
          "registry": {
            "type": "s3",
            "settings": {
              "address": "http://server1:9000",
              "access_key": "bob",
              "secret_key": "bobpassword",
              "bucket": "punch"
        "reporters": [
            "type": "elasticsearch",
            "cluster_name": "es_metrics"


To get more details on each subsection, please read the documentation.


Since the Rest API Gateway can start Unix sub-processes for channel management and PML executions (among other features), it needs an operator environment and a zookeeper cluster accessible on each Gateway's deployed server to work.

You will also need to download your configuration on each server.
From the deployer machine, upload your configuration to the zookeeper cluster with : -pf -zkn <zookeeper_cluser_name>

Then, on each Rest API Gateway's server, download the configuration with : -pf

To check if your server has a proper operator environment, execute this command :

You should get this result :

        PUNCHPLATFORM_VERSION           = "punchplatform-operator-environment-6.0.0"
# confs                                                            
        PUNCHPLATFORM_CONF_DIR          = "/home/vagrant/pp-conf"
        PUNCHPLATFORM_CONF_URL          = "localhost:2181/punchplatform-primary"
        PUNCHPLATFORM_CONF_FILE         = "/home/vagrant/pp-conf/"

# install                                                          
        PUNCHPLATFORM_INSTALL_DIR       = "/data/opt/punchplatform-operator-environment-6.0.0"
        PUNCHPLATFORM_LOG_DIR           = "/home/vagrant/logs"

# and much more ...

Check and Generate Your Configurations

First execute this command on your deployer machine :

$ --generate-inventory

This command generates a complete set of so-called inventories from your two configuration files.
If that succeeds, you can proceed.


From the deployer, make sure you can access your target server using ssh. Depending on your ssh configuration this may require a ssh password. Simply execute the following command. --deploy -Kk --tags gateway

Check your deployment

From any machine which can connect to your Rest API Gateway's cluster, you can test your deployment with :

curl -v GET server1:4000/v1/mytenant/es/es_search/_cat/indices

You can also check the state of each server by connecting to it with ssh and use systemd :

sudo systemctl status gateway-mytenant


The Rest API Gateway cluster's supervision can be done through :

  • systemd
  • Kibana

Through systemd supervision, you can check the Gateway's application logs using journalctl. This way provides you the highest log details to supervise the application running :

sudo journalctl -lf -u gateway-mytenant --no-pager


To obtain more details in application's logs, you can also change the log level by editing the file /data/opt/punchplatform-operator-environment-6.0.0/bin/log4j2.xml

For Kibana supervision, each Gateway's server is logging into :

  • platform-logs index by default
  • Inside index_name configured in your gateway's reporter configuration