Skip to content
This repository has been archived by the owner on Sep 16, 2024. It is now read-only.

Configuration Management API

Jump to bottom
rjrudin edited this page Dec 16, 2019 · 6 revisions

The MarkLogic Configuration Management API - CMA - provides a mechanism for creating and updating many resources in a single request to MarkLogic. This can make deployments significantly faster, as potentially dozens of requests can be combined into a single request.

Supported resource types

CMA usage was first introduced in version 3.8.0 of ml-app-deployer, where it was used to speed up the creation of forests. Support for amps and privileges was added in 3.11.0. Support for databases, protected paths, query rolesets, roles, servers, and users was added in 3.15.0.

The 3.15.0 release also defaults to using CMA for all supported resource types except servers. This support has been tested extensively, but if you run into any problems with it, you can turn off CMA usage completely by setting the "mlDeployWithCma" property to "false" (and please file an issue too).

CMA and the MarkLogic version you're using

The 3.15.0 release and higher should be used with MarkLogic 9.0-9 or higher. This is due to some bugs in CMA pertaining to users in versions of MarkLogic prior to 9.0-9. If you're not yet on 9.0-9, you should disable deploying users with CMA via the "mlDeployUsersWithCma" property.

Depending on how your databases and roles are configured, you may also run into issues with CMA on versions of MarkLogic prior to 9.0-9. If so, you can use "mlDeployDatabasesWithCma" and "mlDeployRolesWithCma" to turn off CMA usage for databases and roles.

Note that, as shown in the table below, mlDeployWithCma can be set to false to turn off all CMA usage.

CMA and XML resource files

If you're defining your resource files in XML, you may run into issues when using the CMA. The reason for that is that when ml-app-deployer submits a request to the CMA endpoint, it does so using a JSON payload. Thus, if you've defined your resources in XML, each resource must be converted into JSON so it can be included in the CMA request. That conversion depends on a set of Java classes in ml-app-deployer that supports unmarshalling XML into instances of those Java classes and then marshalling them out to JSON. But those Java classes are not tightly bound to the latest schema of the Manage API - i.e. at any point, there may be gaps with those classes and what the Manage API supports.

Thus, if you're using XML resource files, consider one of the following two options:

  1. Disable CMA usage, either via mlDeployWithCma=false or disabling it for the resource(s) that you're defining in XML
  2. Convert your XML resource files to JSON

And if you do run into an issue with XML resource files when using CMA, please submit a bug in this project with the contents of the XML file.

Combined requests

Version 3.15.0 also introduces the concept of combining certain resource types into a single CMA request for further performance gains. In 3.15.0, the following combined requests are submitted:

  • Privileges, protected paths, query rolesets, roles, and users are all combined into a single request and submitted
  • Databases and forests created via properties are submitted in a single request (custom forests are still submitted separately, along with sub-databases and their forests)

A note about roles - before roles are submitted, ml-app-deployer will check each role to see if it refers to itself (via permissions) and does not exist in MarkLogic yet. Each such role will first be created in a separate request, as otherwise, the combined CMA request will fail to create the role correctly.

Properties

The table below lists all properties available for configuring CMA usage.

Property Description
mlDeployWithCma New in 3.15.0 - controls whether CMA is used for any resource types. This property is applied before all other "*WithCma" properties, such that you could set it to false but still enable certain resource types to use CMA. Defaults to false (as servers are not deployed with CMA by default).
mlCombineCmaRequests New in 3.15.0 - controls whether certain resource types (listed above) will be combined into requests for better performance. Defaults to true.
mlDeployAmpsWithCma New in 3.11.0 - deploy amps via CMA. In 3.15.0, defaults to true; before that, defaults to false.
mlDeployDatabasesWithCma New in 3.15.0 - deploy databases (excluding sub-databases) via CMA. Defaults to true.
mlDeployForestsWithCma New in 3.11.0 (replaces mlOptimizeWithCma) - deploy forests via CMA. Note that prior to 3.15.0, forests for the default content database are excluded. In 3.15.0, defaults to true; before that, defaults to false.
mlDeployPrivilegesWithCma New in 3.11.0 - deploy privileges via CMA. In 3.15.0, defaults to true; before that, defaults to false.
mlDeployProtectedPathsWithCma New in 3.15.0 - deploy protected paths via CMA. Defaults to true.
mlDeployQueryRolesetsWithCma New in 3.15.0 - deploy query rolesets via CMA. Defaults to true.
mlDeployRolesWithCma New in 3.15.0 - deploy roles via CMA. Defaults to true.
mlDeployServersWithCma New in 3.15.0 - deploy servers via CMA. Defaults to false, as testing hasn't shown this to always help with performance, and certain changes to servers will fail via CMA as well.
mlDeployUsersWithCma New in 3.15.0 - deploy users via CMA. Defaults to true.
mlOptimizeWithCma New in 3.8.0, but deprecated in 3.11.0 - when using ML 9.0-5 or greater, you can set this to true to optimize the creation of forests via a CMA (Configuration Management API) package. Defaults to false.
Clone this wiki locally