Provision Service
The Provision service allows you access to the full cycle of Agent setup when you provision a new Agent. In addition, you can use the Provision service to deploy application plug-ins or integration plug-ins to the Agent during the provision process. The repository contains a group of images, including Agent images for the various operating systems and plug-in images for various Control-M plug-ins.
-
You must install an Agent for Helix Control-M to run and monitor jobs on your application host.
-
If you run the Provision service, ensure that Control-M Automation API CLI is successfully installed on the same host where you plan to install the Agent. See Setting Up the API.
-
Before the initial setup or installation, you must set the Java environment variable that points to an external Java installation. See Setting the Java Environment Variable.
-
If you provision an Agent on a host that uses a proxy server, ensure that the HTTP_PROXY and HTTPS_PROXY environment variables are defined. The values for these variables are in the following format:
{protocol}://{host}:{port}
-
http://172.19.0.169:3128
-
https://server.com:3128
You must include logon credentials for authentication to the proxy.
HTTP_PROXY= http://username:password@proxy.example.com:1234
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.
NO_PROXY=hostname.example.com,10.1.0.0/16,172.30.0.0/16:443
-
Provision a New Control-M/Agent and 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 host.
-
provision image::remove: Uninstalls an image from the user account but does not unregister it.
-
provision agent::uninstall: Uninstalls an image from the user account and unregisters it.
You can select one of the following options to install an Agent:
-
Run the image and setup commands separately. This is useful if your architecture requires dynamic installation and Agent setup. In this scenario, run the image command to prepare your image with the Agent inside it. An image can be a VM image, a Docker image, or an AWS AMI. Then, when necessary, run the setup command to dynamically set up the Agent and register it to the Server.
-
Run the install command for all installation phases. This option is useful in a static architecture that has no distinction between building an image and instantiation.
To provision a plug-in on an Agent, run the image command only.
Before you begin the provision process, you must obtain the installation packages for the Agent, application plug-ins, or integration plug-ins 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. The command returns a list of image names.
CLI Syntax
The following shows the CLI syntax for the provision images command:
ctm provision images <os> [-s version=all|latest|<numeric_string>]
The following table describes the provision images command parameters.
Parameter |
Description |
---|---|
os |
Determines the supported operating systems. Valid values:
|
-s version |
(Optional) Filters the returned list of images by version. Valid values:
Default: latest |
The following example shows 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
The following example shows the REST API syntax for the provision images command in cURL:
os=Linux
curl -H "x-api-key: $token" $endpoint/provision/images/$os?version=9.0.20.080
provision image
The provision image command downloads an image and installs it into the current user account.
If the image is a plug-in image, run this command only.
If the image is an Agent image, run this command and then you must register the Agent on the server with the setup command.
This API command is supported only through the CLI and cannot be called through a REST API command.
CLI Syntax
The following shows the CLI syntax for the provision images 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. |
Ensure that the relevant product code is in the installed-versions.txt file located in the Agent home directory to verify that the agent is registered successfully.
The following table shows the plug-in product codes.
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 API command is supported only through the CLI and cannot be called through a REST API command.
CLI Syntax
The following shows the CLI syntax for the provision saas:agent::setup command:
ctm provision saas:agent::setup <agentTagName> [name]
The following table describes the provision saas:agent::setup command parameters.
Parameter |
Description |
---|---|
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 |
(Optional) Defines a name or alias for the agent to appear in the agent list that appears in the Helix Control-M user interface. Default: hostname-user (if not specified) |
Ensure that the relevant product code, DRKAI.9.0.20.080, is in the installed-versions.txt file located in the Agent home directory to verify that the agent is registered successfully.
provision saas::install
The provision saas::install command enables you to implement all phases of image installation. For an agent, this includes both image and setup.
This API command is supported only through the CLI and cannot be called through a REST API command.
CLI Syntax
The following shows the CLI syntax for the provision saas::install 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 to appear in the Agent list in the Helix Control-M user interface. Default: hostname-user (if not specified) |
Ensure that the relevant product code, DRKAI.9.0.20.080, is in the installed-versions.txt file located in the Agent home directory to verify that an agent was installed successfully.
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 host that runs the command.
-
This API command 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 you run 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.
CLI Syntax
The following shows the CLI syntax for the provision agent::update command:
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) Defines which Agent instance to update. If not defined, the Default installation is updated. This parameter is required for environments with multiple Agents. |
provision image::remove
The provision image::remove command enables you to uninstall an image from this user account without its unregistration in Control-M.
This API command is supported only through the CLI and cannot be called through a REST API command.
CLI Syntax
The following shows the CLI syntax for the provision image::remove 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 API command is supported only through the CLI and cannot be called through a REST API command.
CLI Syntax
The following shows the CLI syntax for the provision agent::uninstall command:
ctm provision agent::uninstall