Community

MarkLogic 10 and Data Hub 5.0

Latest MarkLogic releases provide a smarter, simpler, and more secure way to integrate data.

Read Blog →

Company

Stay On Top Of Everything MarkLogic

Be the first to know! News, product information, and events delivered straight to your inbox.

Sign Me Up →

 
Knowledgebase:
Configuration Management API(CMA) details
21 July 2020 11:42 PM

Introduction

Marklogic Server persists its configuration in XML files (for example, databases.xml, hosts.xml, etc.), copies of which exist on each node of a cluster. While you could use the Admin UI to manage an individual cluster's configuration, at scale and over multiple environments, the best practice is to build a source-control managed script that uses MarkLogic's configuration management APIs - specifically Configuration Management API (CMA) and REST Management API (RMA).

What is RMA?

RMA (REST Management API- /manage/v2) provides the ability to easily capture detailed information about MarkLogic Server objects and processes such as hosts, databases, forests, application servers, and groups from any tool that can make a RESTful call.

You can read more about the MarkLogic REST Management API at - http://docs.marklogic.com/REST/management.

What is CMA?

Configuration Management API (CMA) is a new, higher-level interface built on top of the REST Management API (RMA). CMA is intended to more easily integrate with downstream tooling like MarkLogic's ml-gradle, Ops Director, and Java API, as well as third party options like node.js, bash, and curl.

Customers will typically want to package up configurations to manage the deployment of applications into development, test, and production environments. CMA makes it easier to set up complex MarkLogic features such as replication and failover across these different environments by providing common 'canned' scenarios.

You can read more about the MarkLogic Configuration Management API at - http://docs.marklogic.com/REST/configuration-management-api

How to invoke CMA?

Customer can create and apply configurations in three ways:

1. REST Management API: manage/v3: REST endpoint for generating and applying configurations.

Please refer to http://docs.marklogic.com/REST/configuration-management-api

For example: 

1.1 http://host:8002/manage/v3?format=json : This will return the configuration data in json format. If we change the format to xml, we will get the configurations in xml format.

1.2 http://host:8002/manage/v3?format=zip: This will return package.zip. This archive contains the configuration files (database, forest hosts..etc), README, and ml-gradle property/build files. README from the zip file has the details about how to install ml-gradle and apply the configurations to the other instances.

2. XQuery: cma.xqy --- XQuery library for generating and applying configurations.

Please refer to https://docs.marklogic.com/cma for more details.

cma:apply-config Apply a named configuration, overriding parameters and setting options.
cma:generate-config Retrieve an individual resource, set of resources, or full cluster configuration; generate a configuration from scenarios.

For example:

xquery version "1.0-ml";
import module namespace cma="http://marklogic.com/manage/config"
   at "/MarkLogic/cma.xqy";
cma:apply-config($zip)

3. JavaScript: cma.sjs --- JavaScript library for generating and applying configurations.

Please refer to https://docs.marklogic.com/js/cma for more details.

Function name Description
cma.applyConfig Apply a named configuration, overriding parameters and setting options.
cma.generateConfig Retrieve an individual resource, set of resources, or full cluster configuration; generate a configuration from scenarios.

For example, to create a REST server:

// Create a REST server.
'use strict';

var cma = require('/MarkLogic/cma.sjs');

var json = {
    "config": [{
    "forest":[{"forest-name":"mydb1-f1"},{"forest-name":"mymodulesdb-f1"}],
        "database": [{
                "database-name": "myDb",
        "forest":["mydb1-f1"]
            },
            {
                "database-name": "myModulesDb",
        "forest":["mymodulesdb1-f1"]
            }
        ],
        "server": [{
            "server-name": "restapiServer",
            "server-type": "http",
      "group-name":"Default",
            "root": "/",
            "port": "8900",
      "url-rewriter": "/MarkLogic/rest-api/8000-rewriter.xml",
            "content-database": "myDb",
            "modules-database": "myModulesDb"
        }]
    }]
};
 
cma.applyConfig(json);

Takeaways

  • Use source controlled scripts exercising MarkLogic's Configuration Management API to reliably and consistently manage configuration changes across your environments.
  • Avoid a single monolithic configuration script. The best practice here is to modularize your configuration changes in the form of multiple scripts. If you have multiple databases and configurations, one recommendation would be to maintain the scripts per database. It is easier to maintain and also apply these changes to the instance.
  • Depending on your configuration requirements, you may find your script needing to make calls to both the higher level Configuration Management API as well as the lower level REST Management API. If you have performance issues with CMA/RMA Rest api's, you can even call the Javascript/X-Query api directly from your code.

(1 vote(s))
Helpful
Not helpful

Comments (0)