---
title: "POST /greengrass/v2/deployments"
method: POST
path: "/greengrass/v2/deployments"
---

# POST /greengrass/v2/deployments

`POST /greengrass/v2/deployments`

Creates a continuous deployment for a target, which is a Greengrass core device or group of core devices. When you add a new core device to a group of core devices that has a deployment, IoT Greengrass deploys that group's deployment to the new device.

You can define one deployment for each target. When you create a new deployment for a target that has an existing deployment, you replace the previous deployment. IoT Greengrass applies the new deployment to the target devices.

Every deployment has a revision number that indicates how many deployment revisions you define for a target. Use this operation to create a new revision of an existing deployment.

For more information, see the [Create deployments](https://docs.aws.amazon.com/greengrass/v2/developerguide/create-deployments.html) in the _IoT Greengrass V2 Developer Guide_.

## Request body

- object
  - `targetArn` string, required — The <a href="https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html">ARN</a> of the target IoT thing or thing group. When creating a subdeployment, the targetARN can only be a thing group.
  - `deploymentName` string — The name of the deployment.
  - `components` object — The components to deploy. This is a dictionary, where each key is the name of a component, and each key's value is the version and configuration to deploy for that component.
  - `iotJobConfiguration` object — Contains information about an IoT job configuration.
    - `jobExecutionsRolloutConfig` object — The rollout configuration for the job. This configuration defines the rate at which the job rolls out to the fleet of target devices.
      - `exponentialRate` object — The exponential rate to increase the job rollout rate.
        - `baseRatePerMinute` integer, required — The minimum number of devices that receive a pending job notification, per minute, when the job starts. This parameter defines the initial rollout rate of the job.
        - `incrementFactor` number, double, required — <p>The exponential factor to increase the rollout rate for the job.</p> <p>This parameter supports up to one digit after the decimal (for example, you can specify <code>1.5</code>, but not <code>1.55</code>).</p>
        - `rateIncreaseCriteria` object, required — The criteria to increase the rollout rate for the job.
          - `numberOfNotifiedThings` integer — The number of devices to receive the job notification before the rollout rate increases.
          - `numberOfSucceededThings` integer — The number of devices to successfully run the configuration job before the rollout rate increases.
      - `maximumPerMinute` integer — The maximum number of devices that receive a pending job notification, per minute.
    - `abortConfig` object — The stop configuration for the job. This configuration defines when and how to stop a job rollout.
      - `criteriaList` IoTJobAbortCriteria[], required — The list of criteria that define when and how to cancel the configuration deployment.
        - `failureType` 'FAILED' | 'REJECTED' | 'TIMED_OUT' | 'ALL', required — The type of job deployment failure that can cancel a job.
        - `action` 'CANCEL', required — The action to perform when the criteria are met.
        - `thresholdPercentage` number, double, required — <p>The minimum percentage of <code>failureType</code> failures that occur before the job can cancel.</p> <p>This parameter supports up to two digits after the decimal (for example, you can specify <code>10.9</code> or <code>10.99</code>, but not <code>10.999</code>).</p>
        - `minNumberOfExecutedThings` integer, required — The minimum number of things that receive the configuration before the job can cancel.
    - `timeoutConfig` object — The timeout configuration for the job. This configuration defines the amount of time each device has to complete the job.
      - `inProgressTimeoutInMinutes` integer — <p>The amount of time, in minutes, that devices have to complete the job. The timer starts when the job status is set to <code>IN_PROGRESS</code>. If the job status doesn't change to a terminal state before the time expires, then the job status is set to <code>TIMED_OUT</code>.</p> <p>The timeout interval must be between 1 minute and 7 days (10080 minutes).</p>
  - `deploymentPolicies` object — Contains information about policies that define how a deployment updates components and handles failure.
    - `failureHandlingPolicy` 'ROLLBACK' | 'DO_NOTHING' — <p>The failure handling policy for the configuration deployment. This policy defines what to do if the deployment fails.</p> <p>Default: <code>ROLLBACK</code> </p>
    - `componentUpdatePolicy` object — The component update policy for the configuration deployment. This policy defines when it's safe to deploy the configuration to devices.
      - `timeoutInSeconds` integer — <p>The amount of time in seconds that each component on a device has to report that it's safe to update. If the component waits for longer than this timeout, then the deployment proceeds on the device.</p> <p>Default: <code>60</code> </p>
      - `action` 'NOTIFY_COMPONENTS' | 'SKIP_NOTIFY_COMPONENTS' — <p>Whether or not to notify components and wait for components to become safe to update. Choose from the following options:</p> <ul> <li> <p> <code>NOTIFY_COMPONENTS</code> – The deployment notifies each component before it stops and updates that component. Components can use the <a href="https://docs.aws.amazon.com/greengrass/v2/developerguide/interprocess-communication.html#ipc-operation-subscribetocomponentupdates">SubscribeToComponentUpdates</a> IPC operation to receive these notifications. Then, components can respond with the <a href="https://docs.aws.amazon.com/greengrass/v2/developerguide/interprocess-communication.html#ipc-operation-defercomponentupdate">DeferComponentUpdate</a> IPC operation. For more information, see <a href="https://docs.aws.amazon.com/greengrass/v2/developerguide/create-deployments.html">Create deployments</a> in the <i>IoT Greengrass V2 Developer Guide</i>.</p> </li> <li> <p> <code>SKIP_NOTIFY_COMPONENTS</code> – The deployment doesn't notify components or wait for them to be safe to update.</p> </li> </ul> <p>Default: <code>NOTIFY_COMPONENTS</code> </p>
    - `configurationValidationPolicy` object — The configuration validation policy for the configuration deployment. This policy defines how long each component has to validate its configure updates.
      - `timeoutInSeconds` integer — <p>The amount of time in seconds that a component can validate its configuration updates. If the validation time exceeds this timeout, then the deployment proceeds for the device.</p> <p>Default: <code>30</code> </p>
  - `parentTargetArn` string — The parent deployment's target <a href="https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html">ARN</a> within a subdeployment.
  - `tags` object — A list of key-value pairs that contain metadata for the resource. For more information, see <a href="https://docs.aws.amazon.com/greengrass/v2/developerguide/tag-resources.html">Tag your resources</a> in the <i>IoT Greengrass V2 Developer Guide</i>.
  - `clientToken` string — A unique, case-sensitive identifier that you can provide to ensure that the request is idempotent. Idempotency means that the request is successfully processed only once, even if you send the request multiple times. When a request succeeds, and you specify the same client token for subsequent successful requests, the IoT Greengrass V2 service returns the successful response that it caches from the previous request. IoT Greengrass V2 caches successful responses for idempotent requests for up to 8 hours.

## Response `201`

Success

- CreateDeploymentResponse
  - `deploymentId` string — The ID of the deployment.
  - `iotJobId` string — The ID of the IoT job that applies the deployment to target devices.
  - `iotJobArn` string — The <a href="https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html">ARN</a> of the IoT job that applies the deployment to target devices.

## Other responses

- `480` — ResourceNotFoundException
- `481` — ValidationException
- `482` — AccessDeniedException
- `483` — ThrottlingException
- `484` — InternalServerException
- `485` — ConflictException
- `486` — RequestAlreadyInProgressException

---

[API](https://skmtc.net/aws/apis/greengrassv2.md) · [All operations](https://skmtc.net/aws/apis/greengrassv2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/greengrassv2/versions/f491b1d234d1/schema)