Create a deployment

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

To deploy your applications from the cloud, you upload the application images to your Azure Sphere tenant and create a deployment to distribute the images to Azure Sphere devices. To create a deployment, you must be signed in to Azure Sphere and you must have the Administrator role. In addition, your devices must be prepared to receive cloud deployments.

Note

Each component in a deployment must have a unique GUID. If you base your application on an Azure Sphere sample, remember to create a unique GUID for your application before creating a deployment to avoid possible conflicts.

Prepare the devices

Before your devices can receive applications from the cloud, they must have a product and belong to a device group, and cannot have the AppDevelopment capability installed.

If you haven't already created a product for your devices, you need to do so before you can create a deployment. To create a product:

azsphere product create --name <product-name>

Replace <product-name> with a name for your product, such as DW100. See azsphere product for more information on this command.

Deployments target device groups, so you'll also need to assign your devices to a device group that enables cloud updates before they can receive your deployed applications. By default, each product has five device groups: Production, Field Test, Development, Field Test OS Evaluation, and Production OS Evaluation. You can use one of these device groups or create your own. To find out whether a device group accepts cloud updates, use azsphere device-group show.

The devices must also be prepared for cloud loading, which means that they do not have the appDevelopment capability. When shipped from the factory, devices do not have this capability. However, if you've used a device for application development, you've probably added this capability with the azsphere device enable-development command (called azsphere device prep-debug in earlier preview releases of the SDK).

To remove the capability, use azsphere device enable-cloud-test:

azsphere device enable-cloud-test --device-group <device-group-ID> or '<product-name>/<device-group-name>'

The --device-group parameter identifies the device group. The device group ID supplies a GUID, which uniquely identifies the device group across all products. Alternatively, you can use the product name and device group name pair in the <product-name>/<device-group-name> format. This pair of names uniquely identifies a device group for a particular product. For more information, see deployment create.

Create a deployment for a device group

Deployments can contain both applications and board configurations, and both are handled the same way when you create a deployment. Deployments are sets of images to be distributed to all devices within a device group. Each deployment is linked to a specific device group within a specific product. You must include either the product name and the device group name (as the following example shows) or the device group ID when you create the deployment.

To create a deployment:

  1. Upload the image package:

    azsphere image add --image <path-to-image>  --regional-data-boundary <value>
    
  2. Create a new deployment for a device group:

    azsphere device-group deployment create --device-group <device-group-ID> --images <image-ID>
    

    or

    azsphere device-group deployment create '<product-name>/<device-group-name>' --images <image-ID>
    

To provide multiple values for --images enter a list of values separated by spaces.

The --device-group parameter identifies the device group. The device group ID supplies a GUID, which uniquely identifies the device group across all products. Alternatively, you can use the product name and device group name pair in the <product-name>/<device-group-name> format. This pair of names uniquely identifies a device group for a particular product.

The --images parameter provides the image ID of the image package file for the application. The image is uploaded to your current tenant.

The --regional-data-boundary parameter specifies the regional data boundary for this image. Allowed values are EU and None. The default value is None. If no value is specified the default value will be used.

For example:

azsphere image add --image my-app.imagepackage --regional-data-boundary "None"
azsphere device-group deployment create --device-group "DW100/Field Test" --images e3769536-dc4b-48d9-afd4-22ed321ba4bc

Rules for a valid deployment

To be valid, a deployment must follow these rules:

  • The total size of the deployment must be less than 1 MiB.
  • The deployment can have no more than one board configuration file.

Update a deployment

To update a deployment, use the azsphere image add and azsphere device-group deployment create commands again, as described in the previous section, and specify the path to the updated application file.