Provision Service
For Helix Control-M to run and monitor jobs on your application host, you must have an Agent installed. The Provision service allows you access to the full cycle of Agent setup when provisioning a new Agent. In addition, you can use the Provision service to deploy application plug-ins or integration plug-ins to the Agent during provisioning. A group of images is provided in the repository, including two types of images—Agent images (for the various operating systems), and plug-in images (for various Control-M plug-ins).
-
To use the Provision service, ensure that you successfully installed the Control-M Automation CLI on the same machine where you plan to install the Agent. See Setting Up the API.
-
Before you perform setup or install for the first time, you must set the Java environment variable, which points to an external Java installation. See Setting the Java Environment Variable.
-
If the host on which you want to provision an Agent uses a proxy server, ensure that the HTTP_PROXY and HTTPS_PROXY environment variables are defined. Values for these variables are in the format {protocol}://{host}:{port}. For example, http://172.19.0.169:3128 or https://server.com:3128. For authentication to the proxy, include logon credentials, as in the following example:
HTTP_PROXY= http://username:password@proxy.example.com:1234If you want to opt out of proxying on specific hosts or particular destination ports, you can use the NO_PROXY environment variable, set with a comma-separated list of hosts. For example, NO_PROXY=hostname.example.com,10.1.0.0/16,172.30.0.0/16:443
Provision a New Control-M/Agent and Deploy Plug-ins
The following API commands enable you to provision Agents and deploy plug-ins:
-
provision images: Gets a list of available images.
-
provision image: Prepares the file system for the installation of an Agent.
-
provision saas:agent::setup: Registers an Agent and connects it with a Server.
-
provision saas::install: Runs all phases of image installation (including both image and setup).
-
provision agent::update: Downloads and installs the latest version of Control-M/Agent and any installed plug-ins to the Agent machine.
-
provision image::remove: Uninstalls an image from the user account without unregistering it.
-
provision agent::uninstall: Uninstalls an image from the user account and unregisters it.
For the installation of an Agent, you can choose between the following options:
-
Run the image and setup commands separately. This is useful when your architecture requires dynamic installation and setup of Agents. In this scenario, you use the image command to prepare your image (such as a VM image, a Docker image, or an AWS AMI) with the Agent inside it. Then, when required, you use the setup command to dynamically perform Agent setup and register it to the Server.
-
Run the install command to perform all installation phases. This option is useful in a more static architecture, where there is no distinction between building an image and instantiation.
To provision a plug-in on an Agent, run just the image command.
To prepare for provisioning, you must obtain the installation packages (for the Agent, application plug-ins, or integration plug-ins) that are referenced within the images.For more information, see Control-M Automation API Provisioning.
provision images
The provision images command enables you to get a list of the images that are available on the server for a specific OS. Returns a list of image names.
CLI Syntax
ctm provision images <os> [-s version=all|latest|<numeric_string>]
The following table describes the provision images command parameters.
Parameter |
Description |
---|---|
<os> |
Determines one of the following operating systems:
|
-s version |
Filters the returned list of images by version. You can set this filter to one of the following values:
Default: Latest |
Here is an example of a request for a list of
> ctm provision images Linux
[
"AWS_plugin.Linux",
"Agent_Amazon.Linux",
"Agent_CentOs.Linux",
"Agent_Oracle.Linux",
"Agent_RedHat.Linux",
"Agent_Suse.Linux",
"Agent_Ubuntu.Linux",
"Application_Integrator_plugin.Linux",
"Azure_plugin.Linux",
"Databases_plugin.Linux",
"Hadoop_plugin.Linux",
"Informatica_plugin.Linux",
"MFT_plugin.Linux",
"SAP_plugin.Linux"
]
If annotation is enabled for the Configuration Management category in Control-M, you must also provide an annotation to justify your action. For more information, see Annotation Input.
REST API Syntax
Example using cURL:
os=Linux
curl -H "x-api-key: $token" $endpoint/provision/images/$os?version=9.0.20.080
provision image
Downloads an image and installs it into the current user account.
For a plug-in, use just this command.
For an Agent, after running this command you must still register the Agent on the server using the setup command.
This functionality is supported only through the CLI, and cannot be called through a REST API command.
ctm provision image <image>
The following table describes the provision image command parameters.
Parameter |
Description |
---|---|
<image> |
Determines which image to You do not need to include the OS extension in the name of the image. For example, you can specify Agent, rather than Agent.Linux. The operating system is detected automatically. |
To verify that plug-in provisioning was successful, ensure that the relevant product code was added to the installed-versions.txt file located in the Agent home directory:
Plug-in |
Product Code |
---|---|
Application Integrator |
DRAIT.9.0.20.080 |
AWS |
DRAMZ.9.0.20.080 |
Azure |
DRAZR.9.0.20.080 |
Databases |
DRMQL.9.0.20.080 |
Hadoop |
DRCBD.9.0.20.080 |
Informatica |
DRINF.9.0.20.080 |
Managed File Transfer (MFT) |
DRAFP.9.0.20.080 |
SAP |
DRRMC.9.0.20.080 |
provision saas:agent::setup
The provision saas:agent::setup command enables you to register an agent and connects it with a Control-M environment.
This functionality is supported only through the CLI, and cannot be called through a REST API command.
ctm provision saas:agent::setup <agentTagName> [name]
The following table describes the provision saas:agent::setup command parameters.
Parameter |
Description |
---|---|
<agentTagName> |
The name of the agent tag associated with the agent authorization token. For information about generating a token, see Generating an Agent Token. |
[name] |
A name or alias for the agent, for display in the list of agents in the Helix Control-M user interface. The default (if not specified) is hostname-user. |
To verify that the agent was registered successfully, ensure that the relevant product code, DRKAI.9.0.20.080, was added to the installed-versions.txt file located in the Agent home directory.
provision saas::install
The provision saas::install command enables you to perform all phases of image installation. For an agent, this includes both image and setup.
This functionality is supported only through the CLI, and cannot be called through a REST API command.
ctm provision saas::install <image> <agentTagName> [name]
The following table describes the provision saas::install command parameters.
Parameter |
Description |
---|---|
<image> |
Determines which image to install You do not need to include the OS extension in the name of the image. For example, you can specify Agent, rather than Agent.Linux. The operating system is detected automatically. |
<agentTagName> |
Defines the name of the agent tag associated with the agent authorization token. For information about generating a token, see Generating an Agent Token. |
[name] |
Defines a name or alias for the agent, for display in the list of agents in the Helix Control-M user interface. The default (if not specified) is hostname-user. |
To verify that an agent was installed successfully, ensure that the relevant product code, DRKAI.9.0.20.080, was added to the installed-versions.txt file located in the Agent home directory.
provision agent::update
The provision agent::update command enables you to download and install the latest version of Control-M/Agent and any installed plug-ins to the agent machine that runs the command.
-
This functionality is supported only through the CLI, and cannot be called through a REST API command.
-
To run this command, the current version of Control-M/Agent must be 9.0.20.280 or higher.
-
If Control-M MFT or Control-M for SAP is installed on the Agent, you must stop the Agent before running this API command and start it afterward. To avoid Agent downtime, you can create a host group and include multiple Agents with the same plug-in within the host group. After you shut down one Agent, jobs are routed to another Agent in the host group.
ctm provision agent::update [instanceName]
To skip confirmation messages during installation, add -y after the command.
The following table describes the provision agent::update command parameter.
Parameter |
Description |
---|---|
[instanceName] |
(Windows only) Specifies which Agent instance to update. If not specified, the Default installation is updated. Use this parameter if your environment has multiple Agents. |
provision image::remove
The provision image::remove command enables you to uninstall an image from this user account without unregistering it in Control-M.
This functionality is supported only through the CLI, and cannot be called through a REST API command.
ctm provision image::remove
provision agent::uninstall
The provision agent::uninstall command enables you to uninstall an image from this user account and unregisters it from the Server.
This functionality is supported only through the CLI, and cannot be called through a REST API command.
ctm provision agent::uninstall