Code Deployment

When working with GridGain, you may need to deploy user code to cluster nodes so that it can be executed across the cluster, as shown in the Distributed Computing section.

In GridGain 9 the code is deployed as an immutable deployment unit with a unique ID and version.

You can manage deployment units using either CLI commands or the REST API. Both methods provide the same functionality for deploying, listing, and undeploying code.

Deploy New Unit

Deploying a new unit requires specifying a unique string ID for the code and a version number.

Deploy via CLI

When deploying a new unit, use cluster unit deploy command with unit’s ID and set the following options:

Parameter Description

Parameter	Description
version	Required Deployment unit version in `x.y.z` format. If a unit with the same name and version already exists, a `Unit already exists` error will be thrown.
path	Required Path to the deployment unit file or directory. It is recommended to use an absolute path.
nodes	Defines the target nodes for deployment. Use `ALL` to deploy to every node immediately, `MAJORITY` to deploy to enough nodes for a management group majority (with remaining nodes updated later), or list specific node names (comma-separated) for immediate deployment to those nodes.

version

Required Deployment unit version in x.y.z format. If a unit with the same name and version already exists, a Unit already exists error will be thrown.

path

Required Path to the deployment unit file or directory. It is recommended to use an absolute path.

nodes

Defines the target nodes for deployment. Use ALL to deploy to every node immediately, MAJORITY to deploy to enough nodes for a management group majority (with remaining nodes updated later), or list specific node names (comma-separated) for immediate deployment to those nodes.

For example, to deploy to the majority of nodes use the following command:

cluster unit deploy test-unit --version 1.0.0 --path $ABSOLUTE_PATH_TO_CODE_UNIT --nodes MAJORITY

Here $ABSOLUTE_PATH_TO_CODE_UNIT refers to the absolute path to the code unit file or directory.

Deploy via REST

To deploy a new unit via the REST API, send a POST request to the /management/v1/deployment/units/{unitId}/{unitVersion} endpoint with the following parameters:

Parameter Type Description

Parameter	Type	Description
unitId	path	Required Unique unit ID. If a deployment unit with this ID does not exist, it is created.
unitVersion	path	Required Unique version of the deployment unit. If a deployment unit with the specified ID and version already exists, HTTP 409 "Conflict" response is returned.
unitContent	file (multipart)	Required JAR file to deploy, provided as a file upload via multipart/form-data.
deployMode	query	Defines how many nodes the unit will be deployed to. If set to `MAJORITY`, the unit will be deployed to enough nodes to form cluster management group majority. If set to `ALL`, the unit will be deployed to all nodes. Cannot be used with the `initialNodes` parameter.
initialNodes	query	The list of names of specific nodes to deploy the unit to. Cannot be used with the `deployMode` parameter.

unitId

path

Required Unique unit ID. If a deployment unit with this ID does not exist, it is created.

unitVersion

path

Required Unique version of the deployment unit. If a deployment unit with the specified ID and version already exists, HTTP 409 "Conflict" response is returned.

unitContent

file (multipart)

Required JAR file to deploy, provided as a file upload via multipart/form-data.

deployMode

query

Defines how many nodes the unit will be deployed to. If set to MAJORITY, the unit will be deployed to enough nodes to form cluster management group majority. If set to ALL, the unit will be deployed to all nodes. Cannot be used with the initialNodes parameter.

initialNodes

query

The list of names of specific nodes to deploy the unit to. Cannot be used with the deployMode parameter.

For example, you can deploy a new unit to specific nodes in your local cluster as follows:

curl -X POST 'http://localhost:10300/management/v1/deployment/units/unit/1.0.0?initialNodes=node1,node2' \
  -H "Content-Type: multipart/form-data" \
  -F "unitContent=@/path/to/your/unit.jar"

You can target nodes using either the deployMode or initialNodes parameter. These options serve the same purpose as the similar CLI parameters, ensuring the unit propagates as needed.
For additional details see the corresponding API documentation.

Getting Unit Information

This section explains how get all deployments on the cluster or on a specific node, view unit details such as status and version, and search or filter deployments by these attributes.

Get Unit Information via CLI

You can list deployment units using unit list command.

Use cluster unit list command to see all deployed units on the cluster.
Use node unit list command to view only the units on the node where the command is executed.
Pass the unit’s ID to the command to get information for the specific unit:
```
cluster unit list test-unit
```
Search units by adding version command options:
```
cluster unit list test-unit --version 1.0.0
```

Or filter by status:

cluster unit list test-unit --status deployed

Parameter Description

Parameter	Description
statuses	Filter units by status. `UPLOADING` - the unit is being deployed to the cluster `DEPLOYED` - the unit is deployed to the cluster and can be used `OBSOLETE` - the command to remove unit has been received, but it is still used in some jobs `REMOVING` - the unit is being removed If not specified, deployment units in all statuses will be returned.

statuses

Filter units by status.

UPLOADING - the unit is being deployed to the cluster
DEPLOYED - the unit is deployed to the cluster and can be used
OBSOLETE - the command to remove unit has been received, but it is still used in some jobs
REMOVING - the unit is being removed

If not specified, deployment units in all statuses will be returned.

Get Unit Information via REST

You can also retrieve deployment unit details via GET requests.

To get information for a specific unit on a node or across the cluster, use /management/v1/deployment/node/units/{unitId} and /management/v1/deployment/cluster/units/{unitId} respectively.
```
curl -X GET 'http://localhost:10300/management/v1/deployment/cluster/units/test-unit/1.0.0'
```
To list all deployment units for the node or across the cluster, use /management/v1/deployment/node/units and /management/v1/deployment/cluster/units respectively.
```
curl -X GET 'http://localhost:10300/management/v1/deployment/cluster/units/'
```

You can further narrow down the search by looking up only deployments with specific versions or statuses.

Parameter Type Description

Parameter	Type	Description
unitId	path	Required Unique unit ID of the deployment unit.
version	query	Unique version of the deployment unit. If not specified, all versions of deployment unit will be returned.
statuses	query	Statuses of the deployment units to return. Possible values: `UPLOADING` - the unit is being deployed to the cluster `DEPLOYED` - the unit is deployed to the cluster and can be used `OBSOLETE` - the command to remove unit has been received, but it is still used in some jobs `REMOVING` - the unit is being removed If not specified, deployment units in all statuses will be returned.

unitId

path

Required Unique unit ID of the deployment unit.

version

query

Unique version of the deployment unit. If not specified, all versions of deployment unit will be returned.

statuses

query

Statuses of the deployment units to return. Possible values:

UPLOADING - the unit is being deployed to the cluster
DEPLOYED - the unit is deployed to the cluster and can be used
OBSOLETE - the command to remove unit has been received, but it is still used in some jobs
REMOVING - the unit is being removed

If not specified, deployment units in all statuses will be returned.

Undeploying Unit

When you no longer need a deployment unit version, you can undeploy it from the cluster.

Undeploy via CLI

Use the cluster unit undeploy command. Provide unit ID and unit version to remove.

cluster unit undeploy test-unit --version 1.0.0

You cannot undeploy all units with the same ID at once, you must remove them by version.
When you undeploy a unit that has multiple versions, the active code rolls back to the next most recent version, determined by the version number.

Undeploy via REST

To undeploy a unit from specific nodes, use a DELETE request to /management/v1/deployment/units/{unitId}/{unitVersion} endpoint.

For instance, to undeploy the same unit from nodes node1 and node2, use the following command:

curl -X DELETE 'http://localhost:10300/management/v1/deployment/units/test-unit/1.0.0?nodes=node1,node2'

When the cluster receives the request, it will delete the specified deployment unit version on all nodes. If the unit is used in a job, it will instead be moved to the OBSOLETE status and removed once it is no longer required.

© 2025 GridGain Systems, Inc. All Rights Reserved. Privacy Policy | Legal Notices. GridGain® is a registered trademark of GridGain Systems, Inc.
Apache, Apache Ignite, the Apache feather and the Apache Ignite logo are either registered trademarks or trademarks of The Apache Software Foundation.

Last updated on Mar 27, 2025