
In this guide, we will go over the steps you will want to consider when moving from one Flex Package Composition to another. For example, we recommend that most Enterprise installations start with the Balanced
Flex Package composition as defined here: Deployment Flexibility. Let’s say that after some time, you find that it would be beneficial to scale out a piece of it independently as it needs to have its own lifecycle. This is the scenario that we will be describing in this tutorial, as illustrated by the diagram below:
Many that are new to Broadleaf assume that moving from one Flex Package composition to another as being a "migration project" that might require significant application re-factoring or data migration. However, as long as you follow recommended microservice design and extension patterns, we believe that moving from one Flex Package to another is really an exercise of maintaining different deployment configurations.
That is - you can still be working with the same codebase, but will just need to maintain separate build configurations and properties to support deploying a different package.
In fact, our MicroservicesDemo
Starter Project is structured in a way that demonstrates how you can set up a single project which can be deployed in 3 example Flex Package Configurations: Min Deployment
, Balanced
, and Granular
. Internally, our developers like to run Min
+ Indexer
locally for development purposes, but will deploy the same codebase as a Balanced
configuration to all other upstream environments.
Given that Broadleaf is a microservices framework that can be extended with your own customizations, one big assumption that should be followed when doing so is making sure that any extensions or customizations do not cross bounded contexts.
Bounded Contexts in Broadleaf’s Microservice ecosystem are represented as the Resource Tier Services
such as Catalog
, Pricing
, Customer
, Offer
, etc… where each utilizes its own data store for persistence.
Here’s as an example of an anti-pattern to watch out for: If you have an application that includes both the catalog
and offer
dependencies in the same deployable application, you should not create any hard dependencies between the two services. This would include directly calling each of these services APIs or creating new domains that cross boundaries (e.g. a Product-Offer Cross Reference that ties a product and offer together). Instead, you should use a messaging channel or leverage one of the Composite Tier Services
to orchestrate communication across contexts (even if they are in the same deployable application).
Following these guidelines allows you to more easily move from one Flex Package composition to another.
Taking our example of splitting out Pricing
from the Balanced - Browse Flex Package
, the first thing you will want to do is remove your Pricing
dependency from the Browse
pom.xml
.
Note
|
If you are working with our MicroservicesDemo starter project, you will see a library dependency called demo-pricing-services in flexpackages/balanced/browse/pom.xml which can be removed.
|
Removing this, will allow us to build a Spring Boot application that does not include the pricing dependency.
Next, you’re going to want to look at your Spring application context configurations.
Notice that in the Balanced - application-default.yml
configuration, there are properties to configure Broadleaf’s Pricing
service. You can spot it, as Broadleaf employs a Service Prefix
properties convention to easily spot which configurations apply to which service.
For example:
broadleaf:
pricing:
liquibase:
change-log: 'classpath:/db/changelog/pricing.flexdemo.postgresql.changelog-master.yaml'
liquibase-schema: public
default-schema: pricing
delegating:
schema: pricing
delegate-ref: composite
Since we are removing the pricing depedency, we can also remove any configuration that enables it.
Since we are moving a service out of the Balanced - Browse Flex Package
certain compositional services may be still configured to point to it as if it were still inside the Balanced - Browse
package. For example: Cart Operations can be configured to set up the endpoints of where and how to call the Pricing
Service like:
broadleaf:
catalogbrowse:
pricingprovider:
url: 'https://localhost:9447'
Since we are no longer serving the Pricing Services API endpoints under the Browse
deployment which by default listens on port 9447
, we’ll want to change this to point to the correct URL that the new Pricing
service is going to be listening on.
Tip
|
If using the MicroservicesDemo Starter Project, the Granular pricing service is set up to listen on port 8448
|
In our example, we want to deploy a granular Pricing
Service. Luckily, the way our MicroservicesDemo
starter project is set up, there is already configuration set up to deploy Pricing
services indivdually using the localdev
Spring Profile.
You will notice that under the maven structure in the project: services/pricing
contains a fully executable Spring Boot application that can be run by itself (or built into a jar that is included in the Balanced - Browse
application).
Tip
|
you can run Pricing by itself by going here cd /services/pricing and doing something like: ../../mvnw spring-boot:run -Dspring-boot.run.profiles=localdev
|
Finally, Broadleaf’s Reference Architecture employs a Gateway in front of these backend services to route requests from a client to the appropriate place. Since we’re splitting Pricing
service outside of the Balanced - Browse Flex Package
, we need to make sure that the request goes to the right place as illustrated in the diagram below:
Since Spring Cloud Gateway routes are all configurable via Spring Application properties, this can all be changed using ENV
runtime properties meaning that you don’t necessarily have to rebuild your application with new context files just to change an existing route.
For example, running this configuration locally using docker-compose
, all you need to do is change the flexpackages/balanced/docker/.env
file
from:
BROADLEAF_GATEWAY_PROXYURLS_PRICING=https://host.docker.internal:9447
to
BROADLEAF_GATEWAY_PROXYURLS_PRICING=https://host.docker.internal:8448
Tip
|
When deploying to kubernetes, you can pass in the same ENV overrides to the default helm charts as well. |