Automate Build and Deployment with Cadence¶
Overview¶
Use the optional BuildStreaM cadence workflow to periodically reconcile the RPM repositories referenced by a designated catalog and, after successful reconciliation, build and deploy the resulting images in one GitLab pipeline.
When enabled, the playbook watcher waits for the configured interval, verifies
that no other pipeline is running, and runs catalog-scoped RPM reconciliation.
Repository resynchronization must complete successfully, irrespective of
whether package additions or removals are detected. After a successful
reconciliation, BuildStreaM increments
catalog.version, commits and pushes cadence_catalog_rhel.json, and GitLab
runs these stages:
initialization
-> parse-catalog
-> configure-local-repository
-> build-images
-> deploy
-> restart
-> validate
-> summary
The deploy, restart, and validation stages use the image-group identifier created by the same pipeline execution. The existing build-only and deploy-only pipelines remain independently available.
Note
Cadence configuration is stored in build_stream_config.yml, not in the
catalog JSON. cadence_catalog_rhel.json contains the catalog input whose
committed changes select the unified cadence pipeline.
Prerequisites¶
- Deploy BuildStreaM and its managed GitLab project. See BuildStreaM.
- Verify that
omnia_postgres.service,omnia_build_stream.service, andplaybook-watcher.serviceare active on the OIM. - Verify that
cadence_catalog_rhel.jsonexists at the root of the managed GitLab project. - Configure every RPM repository referenced by the cadence catalog and verify that its upstream source is reachable from the OIM.
- Complete the Image Build Manager inputs and
input/orchestrator/pxe_mapping_file.csvin the managed GitLab project. - Wait for operations that use the same catalog, repository, image, or target nodes to finish before enabling cadence.
Procedure¶
-
On the OIM, open the staged BuildStreaM configuration:
$OMNIA_DATA_PATH/build_stream/input/$OMNIA_PROJECT_NAME/build_stream_config.ymlThe default project is
project_default. -
Configure the
cadencemapping:cadence: # Enable or disable cadence polling for periodic package synchronization # Accepted values: true | false # Default: false enabled: true # Polling interval for cadence syncs in days # Accepted values: integer >= 1 (1 day minimum) # Default: 7 (7 days) interval_days: 7 # Timeout for repo sync playbook execution in seconds # Default: 3600 (1 hour) sync_timeout_seconds: 3600 # Poll interval while waiting for sync result in seconds # Default: 10 sync_poll_interval_seconds: 10Use the following constraints:
Parameter Constraint Default enabledBoolean falseinterval_daysInteger greater than or equal to 17sync_timeout_secondsInteger greater than or equal to 603600sync_poll_interval_secondsInteger from 1through30010 -
Validate the configuration:
Run on: OIM hostcd <OMNIA_SOURCE_PATH>/src/main ./omnia.sh --run build_stream --tags validate -
Allow the watcher to run automatically. The first reconciliation begins after
interval_days. -
To run the unified pipeline manually without waiting for reconciliation:
- In the managed GitLab project, navigate to Build > Pipelines.
- Click New pipeline.
- Add the variable
PIPELINE_TYPEwith the valuecadence. - Click Run pipeline.
A manual cadence pipeline uses the current
cadence_catalog_rhel.jsonand starts the unified lifecycle directly. Starting the pipeline manually bypasses periodic repository reconciliation.
Verification¶
-
Verify the watcher service and confirm that the cadence timer started:
Run on: OIM hostsystemctl status playbook-watcher.service journalctl -u playbook-watcher.service --no-pagerThe journal reports the configured interval when the timer starts.
-
After an automatic reconciliation, inspect:
$OMNIA_DATA_PATH/repo_manager/output/$OMNIA_PROJECT_NAME/repo_resync_status.ymlConfirm that
overall_statusandorphan_cleanuparesuccess. Every repository must report successful synchronization and cleanup, zerostale_packages_remaining, and nonnegative integer package counters. The resynchronization must succeed whether or not the counters report package additions or removals. -
For a successful reconciliation, confirm that:
cadence_catalog_rhel.jsonhas a newcatalog.versionand a cadence Git commit on the configured branch.- GitLab displays all eight cadence stages.
- The pipeline summary reports the
JOB_IDand compositeIMAGE_GROUP_IDused for the execution. - The target nodes restart with the newly built image and the validation stage succeeds.
Next steps¶
- Review the Catalog JSON reference.
- Use Cleanup Operations to remove image groups that are no longer required.
Troubleshooting¶
- The timer does not start: Confirm that
cadence.enabledistrue, the staged configuration is valid, andplaybook-watcher.serviceis active. - The first cycle has not run: The watcher waits for the complete
interval_daysvalue before its first cycle. - Cadence Pipeline is not triggered periodically: If RPM reconciliation via repo_resync.yml fails, there will be no cadence pipeline invoked.
- The cycle is suppressed: An active pipeline causes cadence to skip that cycle. Allow the pipeline to finish and wait for the next interval.
- The reconciliation result is rejected: Correct any failed aggregate or repository status, failed orphan cleanup, nonzero stale-package count, or invalid package counter in the Repository Manager workflow.
- A pipeline stage reports a missing identifier: Review the
initializationandparse-catalogjobs. Dependent stages do not run without theirJOB_IDandIMAGE_GROUP_IDartifacts. - The unified pipeline fails: Open the failed GitLab job and correct the
reported build, deployment, restart, or validation problem. Catalog-mode
cadence builds do not create a
*_prevS3 rollback copy. - For additional issues, see BuildStreaM Issues.
