Resource Linking¶

An API parameter of resource type can be used to link any resource with another resource to enforce creating a linked resource before creating a parent resource.

To understand, let's imagine if you have 2 resources and B is linked to A, then your users have to create A first, then B. In order to create B, they have to specify an instance of A that they want to link. You can also create a multi-level linkage and for your users to create a top-level resource, they have to follow the bottoms-up creation.

Note

To see the difference between resource linking and resource dependency, please see here

As an example, if you are creating a PostgreSQL SaaS such that you also want to allow proxy in front of their databases. Now, it makes no sense to create a proxy with no database to point to.

To model this, you may create two service components (or resources):

Database resource
Proxy resource

And, then link Proxy resource with the Database resource. By doing that, Omnistrate will automatically link them and allow your users to specify a database instance before they can create a proxy instance.

Here is an example with PGAdmin as a proxy resource and PostgreSQL as a database resource.

version: "3"
services:
  Proxy:
    image: omnistrate/pgadmin4:7.5
    ports:
      - 80:80
    volumes:
      - ./data:/var/lib/pgadmin
    x-omnistrate-capabilities:
      httpReverseProxy:
        targetPort: 80
    environment:
      - DB_ENDPOINT= Writer
      - SECURITY_CONTEXT_FS_GROUP=0
      - SECURITY_CONTEXT_USER_ID=0
      - SECURITY_CONTEXT_GROUP_ID=0
      - [email protected]
      - PGADMIN_SERVER_JSON_FILE=/tmp/servers.json
      - PGADMIN_DEFAULT_PASSWORD=abc123
      - DB_USERNAME=root
    x-omnistrate-api-params:
      - key: database
        description: backend database
        name: database
        type: Resource
        export: false
        required: true
        modifiable: false
 Database:
    image: 'bitnami/postgresql:latest'
    ports:
      - 5432:5432
    volumes:
      - ./data:/var/lib/postgresql/data
    environment:
      - POSTGRESQL_PASSWORD=abc123
      - POSTGRESQL_DATABASE=testdb
      - POSTGRESQL_USERNAME=root
      - POSTGRESQL_POSTGRES_PASSWORD=rootpassword12345
      - POSTGRESQL_PGAUDIT_LOG=READ,WRITE
      - POSTGRESQL_LOG_HOSTNAME=true
      - POSTGRESQL_REPLICATION_MODE=master
      - POSTGRESQL_REPLICATION_USER=repl_user
      - POSTGRESQL_REPLICATION_PASSWORD=repl_password
      - POSTGRESQL_DATA_DIR=/var/lib/postgresql/data/dbdata
      - SECURITY_CONTEXT_USER_ID=1001
      - SECURITY_CONTEXT_FS_GROUP=1001
      - SECURITY_CONTEXT_GROUP_ID=0

Assuming, you marked both the resources as external, your customers will be able to independently create an instance of database resource without any obligation to create a proxy resource, or configure any of the database instances to proxy instance.

Note that your customers won't be able to create proxy instance without creating an instance of database resource because creation of proxy resource requires an instance of database instance.

Resource Linking vs Resource Dependency¶

Dependencies allows you to specify DAG and how different service components are dependent on each other. Resource linking is used to link two resources such that you can enforce creation of linked resource before creation a parent resource

To better understand, let's imagine if you have 2 resources and B is linked to A, then your users have to create A first, then B. In order to create B, they have to specify an instance of A that they want to link. You can also create a multi-level linkage and for your users to create a top-level resource, they have to follow the bottoms-up creation by first creating the leaf resource in the DAG all the way up-to parent resource.

In the dependency model, if you have B as a dependency to A, your users can directly create the parent resource A and Omnistrate will automatically detect the dependency, create B (aka all the dependencies) behind the scenes and use that to create A. Depending on the experience, you want to offer to your customers, you may want to choose one vs. the other.

As an example, lets say you want to build a Database SaaS with Master and Replica. For linked resource, your customers will have to create Master instance and then add Replicas by passing the instance of Master instance during the creation of Replica instance(s). On the other hand, with dependency, you can offer a Cluster like experience and encapsulate both Master and Replica behind the Cluster resource. Now, your users can just the Cluster resource and Omnistrate will automatically create Master and Replica resources behind the scenes. There is no right or wrong and purely a function of what experience you want to offer.