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.

In parts this is mandatory, e.g. when you are having 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 regularly. As this is managed on the Component level in Pergola, you have to split these into separate Components.

Splitting databases from applications or web apps from REST API backends on the other hand is not mandatory, but considered best practice. It enables 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 open the ports in the Project Manifest explicitly. This is done by specifying a ports-property in your pergola.yaml:

[...]
  ports:
  - 80

In this example, traffic to port 80 is allowed to send requests to a web server. It could be a Component hosting a HTTP API.

For reference please see Ports in Project Manifest.

Note: Pergola configuration is independent of your Dockerfile by design. You might have to expose the same ports there as well to make it work.

Reference another Component​

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

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

[...]
  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.

Examples​

To link a web app to a database, you need to reference the database Component in the web app Component and expose the port of the database Component.

components:
- name: my-webapp-component
[...]
  env:
  - name: DB_HOST
    component-ref: my-database-component

[...]

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

Of course, you have to make sure to use the environment variable DB_HOST in your code 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: "27020"
      - name: DB_USER
        config-ref: mongo_initdb_root_username
      - name: DB_PWD
        config-ref: mongo_initdb_root_password
    ingresses:
      - host: myurlpart
    ports:
      - 8080

  - name: my-database-component
    docker:
      image: mongo:4.0.4
    ports:
      - 27020
    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