Skip to main content

Linking Components

The Pergola Component structure​

Every part of an application that runs independently should be a Pergola Component. The Components of your Project form your application stack. For example: a web frontend, an API service and a database backend can form a web application with persistent data and an API for programmatic access to it.

In parts this is mandatory, e.g. when you have a web app and a regularly executed background job. The web server of the web app is a daemon that runs all the time, while the background job starts and finishes on a regular basis. As this is managed on the Component level in Pergola, you have to split these into separate Components.

The separation of web frontends and API services, on the other hand, is not mandatory, especially if they share the same framework or codebase, but is considered best practice. It allows for individual performance tuning and cost optimization via resource assignments and scaling as well as better monitoring.

Having an application with multiple Components, it is necessary to define their interdependencies and their communication channels.

Allow access to a Component​

As Pergola protects all Components from external network traffic by default, you need to publish the ports your application's Component serves in the Project Manifest explicitly. This is done by specifying a ports property in your pergola.yaml:

[...]
  ports:
  - 8080

In this example, traffic to port 8080 is allowed so that the Component can receive requests. It could be a web service hosting an HTTP API on port 8080.

For reference, please see Ports in Project Manifest.

note

Configuration within the Project Manifest is independent of your application's code by design. You need to make sure that your app actually serves these ports as well. See inbound requests to a Component for further details.

Reference another Component​

To call another Component the network address of that Component must be known. Pergola provides this information as a 'component reference' at runtime.

You can reference any Component of your application by assigning the Component reference to an environment variable. This is done within the env property in pergola.yaml, by referencing the other Component's name via the component-ref:

[...]
  env:
  - name: API_HOST
    component-ref: my-api-backend

This assumes, that you have a Component that is named my-api-backend. And you need to make sure that your application uses the environment variable API_HOST to connect to the API backend.

For reference, please see Project Manifest.

Examples​

To link a web app to a database, you need to publish the port of the database Component and reference it within the web app Component.

components:
- name: my-webapp-component
[...]
  env:
  - name: DB_HOST
    component-ref: my-database-component
  - name: DB_PORT
    value: "27017"

[...]

- name: my-database-component 
[...]
  ports:
  - 27017

Of course, you have to make sure to use the environment variable DB_HOST and DB_PORT in your code and the according DB driver to connect to the database (MongoDB in this example).

A fully functional pergola.yaml could look like:

version: v1

components:
- name: my-webapp-component
  docker:
    file: Dockerfile
  env:
  - name: DB_HOST
    component-ref: my-database-component
  - name: DB_PORT
    value: "27017"
  - name: DB_USER
    config-ref: mongo_initdb_root_username
  - name: DB_PWD
    config-ref: mongo_initdb_root_password
  ingresses:
  - host: mywebapp
  ports:
  - 8080

- name: my-database-component
  docker:
    image: mongo:7.0.11
  ports:
  - 27017
  env:
  - name: MONGO_INITDB_ROOT_USERNAME
    config-ref: mongo_initdb_root_username
  - name: MONGO_INITDB_ROOT_PASSWORD
    config-ref: mongo_initdb_root_password
  resources:
    cpu: 500m
    memory: 2Gi
  storage:
  - name: mongostorage
    path: /data/db
    size: 20Gi

Further Reading​