// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
= Code Deployment

When working with Ignite, you may need to deploy user code to nodes. For example, you may need the code used in link:compute/compute[Distributed Computing].

In Ignite 3, when you deploy user code to the cluster, it is saved as a *deployment unit*. Deployment units have a unique ID and are immutable. When you need to update code version, you will need to deploy a new unit.

All interactions with deployment units are performed by using REST API. REST endpoints are available for deploying units, undeploying units, and checking deployment unit statuses either on node or across the whole cluster.

== Deploying New Unit

To create a new deployment unit, send a request to the `/management/v1/deployment/units/{unitId}/{unitVersion}` endpoint. You can deploy code to one node, and it will be propagated to the cluster as necessary, but generally it is better to provide the list of all nodes when deploying user code.

Below is the list of parameters for the endpoint:

[width="100%",cols="1,1,3",opts="header"]
|===

|Parameter|Type|Description

|unitId|path|*Required* Unique unit ID. If a deployment unit with this ID does not exist, it is created. Otherwise, a new version is created instead.
|unitVersion|path|*Required* Unique version of the deployment unit. If a deployment unit with the specified UI and version already exists, HTTP 409 "Conflict" response is returned.
|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.

|===

== Getting Unit Information

Deployment unit information is available via multiple endpoints:

=== Getting Specific Unit Information

The `/management/v1/deployment/node/units/{unitId}` and `/management/v1/deployment/cluster/units/{unitId}` endpoints provide information about the deployment unit specified in the request, for the node or across the cluster respectively.

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

[width="100%",cols="1,1,3a",opts="header"]
|===

|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.
|===


=== Getting Information for All Units

The `/management/v1/deployment/node/units` and `/management/v1/deployment/cluster/units` endpoints provide information about all deployments unit, for the node or across the cluster respectively. Optionally, you can search for only deployment units in a specific status.


[width="100%",cols="1,1,3a",opts="header"]
|===

|Parameter|Type|Description

|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, send a request to the `/management/v1/deployment/units/{unitId}/{unitVersion}` endpoint. 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.

[width="100%",cols="1,1,3",opts="header"]
|===

|Parameter|Type|Description

|unitId|path|*Required* Unique unit ID of the deployment unit to delete.
|unitVersion|path|*Required* Unique version of the deployment unit to delete.

|===