Inter-Service Referencing

Building modular service architecture by referencing resources across service commissioning files.

Inter-service referencing enables resources in one service commissioning file to depend on resources defined in other service commissioning files. This allows you to build modular, reusable services that can be composed together to create complex architectures.

By default, resources within a service commissioning file can only reference other resources in the same file. Inter-service referencing breaks this limitation, allowing you to:

• Create reusable connection definitions that multiple services can share.

• Build modular architectures where services have clear separation of concerns.

• Manage complex deployments by breaking them into smaller, focused components.

Referencing Resources Across Services

To reference a resource in another service:

!ref '${otherServiceName}::resourceId'

Where:

• otherServiceName is the service that contains the target Service ID.

• resourceId is the ID of the resource in the target service.

To reference a resource from another service:

• Do not hardcode the Service ID directly.

• Instead, use a parameter that dynamically provides the correct Service ID at runtime.

parameterName is a parameter that contains the target Service ID resourceId is the ID of the resource in the target service

For example, if you define a parameter named otherServiceName, you can reference a resource in that service as:

!ref '${otherServiceName}::resourceId'

For further details, see Service ID and Resource ID.

Service Dependency Behavior

Connectware enables advanced relationships between services. Understanding how these interdependencies behave at runtime is crucial for correct deployment and maintenance.

• Child services: Services that reference other services.

• Parent services: Services that are referenced by others.

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

   • 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