Components
What are Components?
Each individually running part of an application in Pergola is a Component. Components can be based on individually developed application code as well as databases, message queues or services. E.g. a web application could consistent of a frontend, a REST API and a database.
Each Component has its own runtime environment, its own lifecycle and its own computing resources like CPUs, memory and storage.
Component overview
Pergola shows detailed information about all Components per Stage.
Navigate to your Project on the start page or under the 'Projects' navigation and click on the Stage you want to see your Components for:
The example above shows a flawlessly running application with three Components. If any issues were present, this view would be the starting point for problem detection and analysis.
See Component Monitoring for operations and monitoring procedures on the Component level.
How are Components defined?
Components are defined in the Project Manifest. This could look like:
components:
- name: my-webapp-component
docker:
file: Dockerfile
ports:
- 8080
ingresses:
- host: mywebapp
[...]
- name: my-database-component
docker:
image: postgres:16
ports:
- 5432
[...]
For a deep dive, consider reading the Pergolize your app tutorial.
Permanently running Components
Permanently running Components are the most common type. They are up and running and serve all the time, aka daemons. Web servers, microservices, queue endpoints and databases are examples for permanently running Components.
In the example above, both todo-app and todo-db are permanently running Components.
Such Components have at least one instance running, and can be scaled to multiple instances. They are scaled automatically by Pergola, controlled via the scaling configuration in the Manifest.
Scheduled Components
Scheduled Components only run at certain points in time. They are mainly used for background/side jobs. Regular data updates, AI model training, email report generation and housekeeping are examples for such jobs running as scheduled Components.
A scheduled Component is created by providing a cron expression to define the points in time, that it will be started:
scheduled: "0 2 * * *"
Please refer to the scheduling configuration in the Manifest and to the Scheduled Components tutorial.
Triggered Components
Triggered Components are used for background jobs, but unlike scheduled Components they do not run regularly. Instead, they are started at events. Structural updates to data stores, processing of incoming images and clean up after irregular shutdowns are examples for such jobs running as triggered Components.
A triggered Component is created by providing a trigger expression to define the starting event:
scheduled: "@release"
Please refer to the scheduling configuration in the Manifest and to the Scheduled Components tutorial.
Start and stop Components
Pergola allows you to start and stop individual Components on a given Stage manually. The behaviour varies by Component type and is discussed below.
Please use these features with utmost care, especially in production Stages.
Stop a Component
Stopping a Component has a standard behaviour to shut down everything (all instances) as gracefully as possible. By using the kill switch, you can enforce immediate shut down.
Stopping behaviour by Component type:
| Type | Standard Behaviour | Behaviour with kill |
|---|---|---|
| Permanently running | Stop all running instances gracefully (SIGTERM) | Stop all running instances immediately (SIGKILL) |
| Scheduled | Do not start the Component any more (at the next scheduled point in time); any potentially running instances will still run to completion | Additionally, stop running instances immediately |
| @release trigger | Stop all running instances gracefully | Stop running instance immediately |
Start a Component
Starting a Component has a standard behaviour similar to the startup during a Release, each instance of that Component is started as soon as all required resources, like storage, are ready. For scheduled Components, the scheduling gets enabled only, and you can choose whether it should also run immediatly or not with the now switch.
| Type | Standard Behaviour | Behaviour with now |
|---|---|---|
| Permanently running | Start instances according to scaling directive | not applicable |
| Scheduled | The Component will run in the future, at the next scheduled point in time | Additionally, run the Component immediately |
| @release trigger | Run the Component right now (once) | not applicable |
Restart a Component
Restarting a Component only applies to permanently running Components. It has a standard behaviour similar to rolling update during a Release.
| Type | Behaviour |
|---|---|
| Permanently running | Instance by instance, stop gracefully and restart new instances while obeying the scaling directive |
Example in Web UI
Navigate to your Project on the start page or under the 'Projects' navigation and click on the Stage to find the Component Overview ( see above ).
In the following example, it shows a running Stage with three Components. For each Component, there are buttons to start, stop and restart the Component.
Depending on the Component type, a popup dialog will let you choose to stop a Component immediately:
Or will let you choose to run a scheduled Component immediately.
Example in CLI
Assume you have these three Components:
- web-server
- data-migration, scheduled
@release - daily-backup, scheduled regularly, e.g.
0 0 * * *
Stop the Component web-server gracefully:
pergola stop component web-server -p myproject -s prod
Stop the Component web-server immediately:
pergola stop component web-server -p myproject -s prod --kill
Stop the Component data-migration:
pergola stop component data-migration -p myproject -s staging
Deactivate the scheduling for Component daily-backup:
pergola stop component daily-backup -p myproject -s prod
This will deactivate the scheduling only. Any potentially running instances will run to completion.
Deactivate the scheduling and stop any potentially running instances of the Component daily-backup immediately:
pergola stop component daily-backup -p myproject -s prod --kill
Start the Component web-server:
pergola start component web-server -p myproject -s prod
Run the Component data-migration now:
pergola start component data-migration -p myproject -s staging
As this Component is scheduled @release, it will run immediately.
Resume scheduling for Component daily-backup:
pergola start component daily-backup -p myproject -s prod
This will not run the Component immediately, but will activate the scheduling for the next run.
Resume scheduling for Component daily-backup and run now:
pergola start component daily-backup -p myproject -s prod --now
This will re-enable the scheduling and run the Component immediately.