Inter-Service Referencing

A service in one commissioning file describes resources and their relations by referencing resources with each other. In addition to the resources within the same file, one can also reference resources from other services and other files. This is called inter-service referencing.

With inter-service referencing, resources in one service can depend on resources in other services. For example, some Endpoint definitions in one file can belong to a Connection resource that was defined in another service by referencing that Connection in the other service.

When using inter-service referencing to reference e.g. a Connection myConnection in a service with service id serviceB, one needs to refer to that connection by writing !ref serviceB::myConnection. In other words, the resource id must be prefixed with the service id and a double colon, ::. See also service id and resource id.

For more flexibility, the service id is usually not specified directly, but instead a parameter is defined where the respective service id is given at installation time. To use such a parameter, e.g. otherServiceName, one will write !ref '${otherServiceName}::resourceId'.

This is shown in the example with multiple files. In that example, the commissioning file which wants to reference the resources of other services has the parameter machineService, and the inter-service reference is written as !ref '${machineService}::defaultRole'.

Interactions across Referenced Services

Given the flexibility Connectware offers to build advance relationships between services it is important to understand what behaviors are expected in different scenarios.

  • Let’s define services that reference other services Children Services

  • Let’s define a service that is referenced by other services Parent Service

Expected Behaviors

Following are four scenarios and how the services behave in each case:

  1. All services are installed and then enabled in parents/children order

    1. This behaves as any other set of services

    2. Disabling a Parent Service will disable all its Children Services

  2. All services are installed and then enabled in random order

    1. Children Services will wait on Enabling state

    2. Once the Parent Service becomes available they will switch to Enabled

  3. Children Services are installed first without Parent Service present

    1. Trying to enable these services will fail with logs in Service Manger indicating the reason

    2. You will see a log starting with Failed enabling service because: Could not resolve cross-service reference... and some extra details about the unresolvable reference

  4. Parents services are installed first without children presents

    1. No special behavior, once Children Services are added this is the same scenario as cases 1 and 2

Example

The following Service Commissioning Files will be deployed:

  1. A Cybus::Container running a database

    • Service id will be mssqldatabase

  2. A Cybus::Connection connecting to the database

    • Service id will be serviceaconnection

  3. A Cybus::Endpoint using referencing to use that Connection

    • Service id will be servicebendpoint

You can reproduce all the behaviors described above using these Service Commissioning Files.

SQL Database:

description: MSSQL Database
metadata:
  name: MSSQL Database

definitions:
  password: password1234!

resources:
  mssqlDatabase:
    type: Cybus::Container
    properties:
      image: mcr.microsoft.com/mssql/server
      ports:
      - "1433:1433"
      environment:
        ACCEPT_EULA: "Y"
        SA_PASSWORD: !ref password

SQL Connection:

description: MSSQL Connection
metadata:
  name: Service A Connection

parameters:

  ip_host:
    type: string
    title: IP address or hostname where Connectware is installed

definitions:
  port: 1433
  database: master
  username: sa
  password: password1234!

resources:
  mssqlConnection:
    type: Cybus::Connection
    properties:
        protocol: Mssql
        connection:
          host: !ref ip_host
          port: !ref port
          username: !ref username
          password: !ref password
          database: !ref database
          useEncryption: false

SQL Endpoint:

description: Service B
metadata:
  name: Service B Endpoint

parameters:
  mssqlConnectionServiceId:
    type: string
    title: Service id of the MSSQL Connection

resources:
  mssqlVersionB:
    type: Cybus::Endpoint
    properties:
      protocol: Mssql
      connection: !ref '${mssqlConnectionServiceId}::mssqlConnection'
      subscribe:
        query: 'SELECT @@version'
        interval: 1000