Skip to content

Backplane integration

Subsystem integration with the Backplane is carried out automatically by the integration tool (available here).

Testing integration

Prerequisites

Run integrator

A docker image of the integrator (single non-interactive) is provided to test the integration during subsystem development.

docker login registry.gitlab.com
docker run --pull always -v /path/to/backplane:/backplane -v /path/to/spec.json:/serviceName.json registry.gitlab.com/i3-market/code/backplane/service-integration-manager:latest /serviceName.json

docker run --pull always \
    -v /path/to/backplane:/backplane \ // <- Backplane volume
    -v /path/to/spec.json:/serviceName.json \ // <- Specification volume
    registry.gitlab.com/i3-market/code/backplane/service-integration-manager:latest \
    /serviceName.json // <- Parameter
Note that 3 parts of the command have to be changed:

  • Backplane volume (string after first -v)
    Change the first part (/path/to/backplane) with the actual path to backplane project (e.g. C:/Development/i3Market/backplane:/backplane)

  • Specification volume (string after second -v)
    Change the first part (/path/to/spec.json) with the actual path to the OAS file (e.g. C:/Development/i3Market/specs/greeter.json) Change the filename of the second part (serviceName in /serviceName.json) with the name of the service (e.g. /greeter.json)

  • Parameter (last string)
    Change with the second part of the specification volume (e.g. /greeter.json)

Example:

docker login registry.gitlab.com
docker run --pull always -v C:/Development/i3Market/backplane:/backplane -v C:/Development/i3Market/specs/greeter.json:/greeter.json registry.gitlab.com/i3-market/code/backplane/service-integration-manager:latest /greeter.json

Integration deployment

To integrate a subsystem with the Backplane API, you have to upload the OpenApi Specification of your subsystem to the Backplane Subsystems OAS repository.
This OAS file must be named accordingly to the service name (preferably in camel case), since the filename will be used to determine the name of the integrated service. For example, for the Auditable Accounting service, the OAS should be named auditableAccounting.json.

Every time the Backplane Subsystems OAS repository is updated, either with a new specification or an update of an existing one, the Backplane deployment process is triggered. Because of this, we encourage subsystem developers to test that the integration works fine before uploading the specification to the repository.
After the deployment process, a new instance of the Backplane with all the changes in the subsystems will be available.

You can find the instructions to test the integration above.

Do not upload any integration file generated by the integration tool during testing to the Backplane repository

Server election

As you may have notice, the OAS definitions include a servers property, that is being used by the Backplane to properly redirect the requests. This property can also be an array, in case the service is deployed in multiple nodes and/or environments.

For example, in the following definition we have 3 different servers tagged with either nodes or docker-compose tags.

{
  "servers": [
    {
      "url": "https://example1.i3-market.eu:3001",
      "x-tags": ["nodes"]
    },
    {
      "url": "https://example2.i3-market.eu:3001",
      "x-tags": ["nodes"]
    },
    {
      "url": "https://example:3001",
      "x-tags": ["docker-compose"]
    }
  ]
}
Notice, using the x-tags allows us filtering the nodes to consider at backplane runtime with the environment variable SERVER_FILTER_TAGS.

Example Docker-compose deployment

When running the backplane with the environment variable SERVER_FILTER_TAGS=docker-compose. It will choose the last definition to redirect all queries (https://example:3001).

In case more than one server matches the filter and DISABLE_SERVER_OPTIMIZER=false, an election process will be executed. Electing the first one passing the DNS Resolution Test and priorizing servers located in the same node, using PUBLIC_URI environment variable as reference.

Note

In case after running the DNS resolution test, more than server is elected, it will follow the priority order stated in the OAS file, being the first defined the most priority one.

Secured endpoints

In case your definition includes some secure endpoints, a given security section has to be included in your OAS definition. Please refer to the backplane authentication section

Troubleshooting

This integrator is being developed, and, while it is stable now, it may break if faced with some corner cases. Although the integrator may not fail and finish normally, if you see some errors in the generated files or some weird stuff happens (for example the integrator logs lists fewer endpoints than expected), it will probably be the integrator's fault. If you come across any problem, don't hesitate to contact us at:

Last update: 2022-09-28
Created: 2022-04-06
Back to top