Consolidate-packages bal tool

May 22, 2025 ยท View on GitHub

Ballerina inherently supports microservices-style deployments, which are well-suited for microservice orchestration platforms like Kubernetes. However, many enterprise users deploy on VMs or Docker, where managing each service as a separate process increases complexity and resource overhead. This tool aims to provide a solution tailored to such scenarios by enabling consolidated deployments.

Usage

Create or update a consolidator package

Create a new package and add the consolidate-packages tool entry as shown in the below example into the Ballerina.toml with the services required to consolidate. You can add/remove services as needed by updating the values provided for the options.services array. The tool will be automatically pulled during the package build.

[package]
org = "myorg"
name = "myApp"
version = "0.1.0"

[[tool.consolidate-packages]]
id = "consolidateSvc"
options.services = ["myorg/svc1", "myorg/svc2"]

Services required for consolidation can be from Ballerina Central, local repository, or both. In addition to the tool entries above, add a dependency entry for locally published packages as shown below:

[[dependency]]
org = "myorg"
name = "svc1"
version = "1.1.0"
repository = "local"

Using the CLI tool

Alternatively, the consolidate-packages CLI tool can be installed to create and modify the consolidator package. This is typically useful in CI/CD pipelines.

An example is shown below.

Installation

Execute the command below to pull the tool.

bal tool pull consolidate-packages
Creating a new consolidator package
$ bal consolidate-packages new --package-path=myApp myorg/svc1,myorg/svc2

To create a consolidated package with local packages,

$ bal consolidate-packages new --package-path hotel-app myorg/order_service,myorg/payment_service --repository=local
Adding new services to an existing package

Execute the command below to from the package root directory.

$ bal consolidate-packages add myorg/svc3,myorg/svc4

To add local packages,

$ cd hotel-app
$ bal consolidate-packages add myorg/customer_service,myorg/menu_service --repository=local
Removing services from an existing package

Execute the command below to from the package root directory.

$ bal consolidate-packages remove myorg/svc2,myorg/svc3

Building from the Source

Setting Up the Prerequisites

  1. OpenJDK 21 (Adopt OpenJDK or any other OpenJDK distribution)

    Info: You can also use Oracle JDK. Set the JAVA_HOME environment variable to the pathname of the directory into which you installed JDK.

  2. Export GitHub Personal access token with read package permissions as follows,

    export packageUser=<Username>
export packagePAT=<Personal access token>

Building the Source

Execute the commands below to build from the source.

  1. To build the library:

     ./gradlew clean build

  2. To run tests:

     ./gradlew clean test

  3. To build the module without the checks (including tests):

     ./gradlew clean build -x check

  4. To publish to maven local:

     ./gradlew clean build publishToMavenLocal

  5. Publish the generated artifacts to the Ballerina local repository:

     ./gradlew clean build -PpublishToLocalCentral=true

  6. Publish the generated artifacts to the Ballerina central repository:

     ./gradlew clean build -PpublishToCentral=true

Contributing to Ballerina

As an open-source project, Ballerina welcomes contributions from the community.

You can also check for open issues that interest you. We look forward to receiving your contributions.

For more information, go to the contribution guidelines.

Code of Conduct

All contributors are encouraged to read the Ballerina Code of Conduct.