The Structure of a CSD

cleroy edited this page Mar 18, 2015 · 6 revisions

A CSD is packaged and distributed as a jar file. The jar is self-contained and encases all the description and logic needed to manage the service type in CM.

Descriptor Files

The following files and directories are treated specially when read by the CSD framework:

  • descriptor/service.sdl
  • descriptor/service.mdl
  • scripts/
  • aux/


At the heart of the CSD is the service descriptor language (SDL) file: descriptor/service.sdl. This is a json file that describes how to manage a service type with the same name as the CSD. This file includes:

  • the service types and associated role types
  • how to start the service/roles
  • parameters for both the service and role types
  • additional commands
  • configuration file generators

The service.sdl file must be located in the descriptor directory. See the Service Descriptor Language Reference for more details.


Service monitoring behavior may be specified in an optional service monitoring descriptor language (MDL) file: descriptor/service.mdl. This is a json file that describes how Cloudera Manager should behave when monitoring a service type with the same name as the CSD. This file includes:

  • new monitored entity types
  • new metrics for the service, roles and monitored entity types.

The service.mdl file is an optional part of a CSD, but it must be located in the descriptor directory if one is specified. See the Service Monitoring Descriptor Language Reference for more details.


This directory contains all the executable scripts that are used to control the underlying service. These scripts are referenced by the service.sdl file through script runners. Scripts can be written in any language that can be executed on the cluster. Bash is often used since it is ubiquitous on Linux distributions. The entire contents of this directory are sent down to the agent's process directory.

See Control Scripts for more details.


A CSD can optionally have an aux directory. Auxiliary files can exist in this directory and, if they do, are also sent down to the agent along with the scripts directory. This can be useful if there are static configuration files, like, that are needed by the service and are not generated by the CSD. Oftentimes substitution variables are added to these static configuration files and then replaced by the control scripts.


The name of the CSD jar must conform to the following format: <name>-<csd-version>-<extra>.jar. For example, a release build of version 1.0 of the Spark CSD is: SPARK-1.0.jar. The <extra> section of the file name is reserved for snapshot builds of the CSD when building with maven. So for example, a snapshot build of the Spark CSD would be: SPARK-1.0-SNAPSHOT.jar. The <extra> is ignored by Cloudera Manager.

Note: when we say version here we mean the CSD version, NOT the underlying service version. For example, version 1.0 of the Spark CSD, SPARK-1.0.jar might control Spark 0.9.