Enhanced Environment Configuration (Since 1.7.7-GA)

Most commonly, Spring Cloud Config will be backed by a GIT repository, although many other backing sources are supported. See https://docs.spring.io/spring-cloud-config/docs/current/reference/html/#_environment_repository for a comprehensive list of supported environment repositories.

General Requirements:

Broadleaf’s config server images come with additional spring profiles that allow the full lifecycle of environment acquisition and refresh to be demonstrated locally without requiring a remote GIT repository. The docker-compose setup for the config server should be edited as follows:

This will cause the config server to load a property file from its classpath that specifies broadleaf.cart.validation.cart.maxNumberOfUniqueCartItems to have a value of 9. If your implementation uses this validation, you should be able to launch your application (presumably on your local dev computer) and see the system prevent you at runtime from adding more than 9 items to your cart.

The setup so far has not taken security into account. The security related to config server falls primarily into 3 areas:

Securing the installation starts with activating the secure spring profile on the container via the SPRING_PROFILES_ACTIVE environment variable. However, some additional setup is needed to fulfill the requirements of enacting this profile.

To speak to the secured installation, the client side configuration must also be updated. Building on the bootstrap.yml example from above:

The uri has changed to an https url, and we have included the username and password for the config server authentication.

If the opinionated Broadleaf config server Docker images available do not meet your needs, or you require additional code customization measures to achieve a specialized goal, it is possible to start from a template project, customize, and build your own Docker image. Each of the 4 broker types Broadleaf supports out-of-the-box has a zip assembly of the original source for the project available from Broadleaf maven repository. Each can be downloaded at one of the following locations (requires registered client maven repository credentials):

Each project, when unzipped, can be edited to add/change dependencies, customize code or Spring behavior, etc…​ A New Docker image can be created by executing the following command in the root directory of the project. This image will be deployed to your local Docker registry and is suitable for local testing.

If you generate a new image as part of CI (or other), including the -Pdocker profile and registry url (and omitting the buildLocalDockerOnly system property) will cause an appropriate Docker image to be deployed to your target docker registry during a maven deploy or release (as long as the process is properly authenticated to the remote docker registry).

When the application Spring environment is refreshed, any properties accessed from the environment directly, as well as properties accessed from @ConfigurationProperties annotated beans, are immediately updated with the latest values. However, other components controlled by Spring are not automatically refreshed (unless annotated with @RefreshScope). This means other components leveraging environment properties at initialization, but not during normal request flows, will not benefit from the environment refresh (since they no longer user the properties post-initialization). This represents a subset of the available environment properties in the system. For example, the property controlling connection pool size is only used during connection pool creation, and not thereafter. It is useful to note this limitation when considering what properties will actually be refreshed in a discernible way upon change. On the other hand, upon application restart, all components will be initialized with the latest. Therefore, restarting the application is one strategy to realize configuration update without having to re-deploy the application.

Broadleaf does not employ @RefreshScope in the framework on any beans. It is hard to predict the consequences of the destroy/initialize bean lifecycle on the runtime performance of the application. For example, some beans control resources like async thread pools that take some amount of time to shutdown. And, since all request threads that need to access the API of the refreshing component will block until it finishes initialization, there is a possibility of negative resource suffocation consequences, like Tomcat server request thread or DB connection pool starvation.

In the event a property is only used during bean initialization, and is required for behavior change at runtime refresh, there are several strategies that can be employed:

(1) is always preferable to (2).

The feature requires a Broadleaf Microservices implementation leveraging at least version 1.4.13-GA of the broadleaf-common-extension library. Note, this is included as part of the 1.7.7-GA release train. However, earlier release trains >= 1.7.5-GA can explicitly declare the broadleaf-common-extension dependency at version 1.4.13-GA to realize the feature without upgrading overall to 1.7.7-GA.

The feature is disabled by default. Enable the @ConfigurationProperties annotated bean proxy behavior by setting the property com.broadleafcommerce.environment.property.discrimination.enabled to true.

The application of the proxy behavior is further limited by inclusion/exclusion filters. Out-of-the-box, Broadleaf only includes Broadleaf scoped @ConfigurationProperties beans (ignoring Spring and other third party library configuration beans). To turn off the default Broadleaf scoping and include everything, set the com.broadleafcommerce.environment.property.discrimination.broadleaf.filters.enabled property to false. Most of the time, this is not necessary and the implementation can register additional inclusions/exclusions by adding new filter beans (see below).

Discrimination requires the DiscriminatedPropertyContext be set. In cases where this is not set, discrimination will not be active and the undiscriminated property will be returned (even if the @ConfigurationProperties bean has been proxied). The most notable flow where this will occur is during async message consumption, since tenant information is currently not set here. For message driven flows that require tenant property discrimination, extension of Broadleaf to modify the message creation and consumption is currently required. Generally, this pattern would be followed:

It is often useful to visualize the properties actually discriminated in a request flow at runtime. This can be used as part of troubleshooting @ConfigurationProperties bean proxy behavior, or as part of determining if a discrminated property is being used. Setting the com.broadleafcommerce.environment.property.discrimination.report.count.enabled property to true will enable reporting of all discriminated properties resolved during a request thread, and will do so at the end of the request lifecycle in the standard application log. A sample of the output looks like this: