Migrate from Azure Sphere (Legacy) to Azure Sphere (Integrated)
On 27 September 2027, Azure Sphere will retire its Legacy service interfaces, Azure Sphere (Legacy) API (also known as PAPI), and Azure Sphere CLI (also known as azsphere). All Azure Sphere (Legacy) users must migrate to Azure Sphere (Integrated) before this date. Azure Sphere (Integrated) is native to the Azure platform, and provides a like-for-like replacement of the Azure Sphere (Legacy) interface. Azure Sphere (Integrated) also offers offers significant improvements in security (Azure RBAC integration), usability (Azure Portal integration), and observability/alerting (Azure Monitor integration). For more information, see this blog.
This article is designed to help Azure Sphere administrators and engineering teams understand and plan for migration. We have designed the migration process to allow you to manage your Azure Sphere devices in both Azure Sphere (Integrated) and Azure Sphere (Legacy) as needed throughout the migration project. In addition, your Legacy-based scripts, automation, and interfaces, can operate uninterrupted while your engineering team builds and tests updated versions based on Azure Sphere (Integrated).
The migration process can be broken down into the following areas of work:
- Integrating the Legacy tenant into an Azure Sphere catalog in Azure portal
- Migrating interactive user workflows
- Migrating automated processes and interfaces
Integrating your Azure Sphere (Legacy) tenant to an Azure Sphere catalog
This first step in the migration process must be completed before any other work can begin. The Integrate feature in Azure portal prepares your Azure Sphere (Legacy) tenant to be managed in the Azure environment where it becomes an Azure Sphere catalog. The tenant and its resources remain the same with the exception that you can now also access and manage them via Azure’s user interfaces including the Azure portal, the Azure Sphere extension for Azure CLI, and Azure Sphere for PowerShell.
The Integrate process performs two steps:
- It assigns an Azure resource ID to each resource in the tenant, allowing the resource to be managed by the Azure Resource Manager.
- It maps the Legacy tenant user access roles to user access roles managed by Azure Roles Based Access Control (RBAC). When the suggested access role mappings are displayed during the integrate process, you can accept, modify, or reject them. After the integration step is complete, you can modify user access at any time.
Typically, the integration step only takes a few minutes, and once completed, any user that was granted access during the integration can immediately begin managing the new Azure Sphere catalog in any of Azure’s user interfaces. No existing workflow is blocked by the Integrate process, and we recommend that you do it soon so that you can start exploring the new Azure Sphere (Integrated) interfaces and benefits. Once it is complete, you can begin the rest of your migration work.
Migrating interactive user workflows
Interactive workflows are ones where an individual uses the “azsphere” CLI (or uses a script which in turn uses “azsphere” CLI) to perform a task. Such interactive workflows may occur as part of manufacturing (e.g. claiming new devices into your tenant), operations (e.g., managing certificates related to your tenant), or developer use cases (e.g., setting up a developer device to not receive over-the-air updates).
When planning the migration of your workflows, you need to consider training users, updating internal documentation, and, in cases where scripts are used interactively, updating those scripts. You may also consider taking advantage of two key improvements in Azure Sphere (Integrated): Azure Sphere’s streamlined interface in Azure portal, and Azure’s robust user access management in Azure Role Based Access Control (RBAC).
It’s important to consider whether a particular user workflow is better accomplished in a web interface rather than a CLI. Azure Sphere (Integrated) allows you to manage the catalog in Azure Portal, and for many interactive user workflows, Portal offers a richer and simpler user experience. For example, in Azure portal you can simultaneously upload and deploy images in a single step, as shown below.
Second, consider how you can restrict user access more effectively. Azure Sphere (Integrated) supports Azure Role Based Access Control (RBAC) which enables far more robust and fine-grained user access than Azure Sphere (Legacy).
It is a least-permissions model designed to grant an individual user access to only those resources required for their job, as well as permission to perform only the user actions necessary for their job. For example, in an Azure Sphere catalog, you can allow a user to view the Production device group, and to create new deployments in that device group, but specifically prevent them from moving devices in and out of the device group, or from viewing other device groups in the catalog.
If you have not used Azure RBAC before, we recommend learning more about basic Azure RBAC concepts like scope and resource hierarchy because they are key to understanding impacts of applying a specific RBAC role permission to a catalog versus to a catalog’s child resource like a device group.
To help, we have provided an Example RBAC configuration for multiple business users that illustrates some best practices for RBAC for Azure Sphere. The sample highlights permissions tailored to common business user needs, including software engineers producing applications for Azure Sphere devices, OT technicians managing production Azure Sphere device fleets, and manufacturers who build Azure Sphere devices.
Removing user access to the Azure Sphere (Legacy) tenant
Once a workflow is migrated and your users are using Azure Sphere (Integrated) full time, we strongly recommend removing each user’s permissions from the Legacy tenant to eliminate unintended access. Otherwise, a user can sidestep the fine-grained access controls that you configured in Azure RBAC by continuing to use Legacy. Removing Legacy user access will also help you ensure that those users can successfully perform all of their required tasks in Azure Sphere (Integrated), and will be unaffected by Legacy retirement.
Users working on converting or testing automated processes may need to retain their Legacy tenant access privileges for a longer period of time.
Migrating automated processes and interfaces
In addition to migrating interactive workflows, if your organization has built automated processes that use Azure Sphere (Legacy) scripts, or user interfaces based on the Azure Sphere (Legacy) API, you will need to rework those to use Azure Sphere (Integrated). To make the migration process as easy as possible, you can actively develop and test updated automation while your production Legacy-based automation runs uninterrupted. Care is needed when testing commands that cannot be reversed, such as claiming a device to a catalog where you do not want it to reside long term.
For each interface you build on the Azure Sphere (Integrated) API, you must create a Microsoft Entra access token that will allow the interface to access the API endpoint. For information about access tokens and calling the Azure REST APIs, please refer to Azure REST API reference documentation.
After you deploy the updated automated processes and interfaces to production, you should remove Azure Sphere (Legacy) access for the service principals used to authenticate your old Legacy-based automation and interfaces. Removing all service principal access ensures that all your automated processes are fully migrated, and will be unaffected by Legacy retirement.
Shutting down remaining access to the Legacy tenant
The final step in the migration process is to remove any remaining Azure Sphere (Legacy) access. Today, Azure Sphere (Legacy) tenants require at least one active Legacy Administrator account, even if the tenant has been integrated into Azure portal. We are working on a feature that will allow you to delete that last Legacy tenant Administrator account, but it is not available at this time. When we release this feature, we will announce its availability on Azure Update.
Taking advantage of features available in Azure Sphere (Integrated)
While not required in order to use Azure Sphere (Integrated), we highly recommend that as part of your migration plan you explore and take advantage of the other powerful Azure services now available for Azure Sphere.
One of the most powerful is Azure Monitor. Azure Monitor offers a variety of fleet monitoring features such as collection of performance metrics and diagnostic data, and querying events in activity logs from both Azure Sphere devices and the Azure Sphere security service.
Using Azure Monitor data, you can correlate device fleet health with events happening on the Azure Sphere security service, such as release of a new app update. You can also configure alerts on critical events, such as the upcoming expiration of your Azure Sphere tenant certificate. For details, see Monitoring Azure Sphere fleet and device health.
Getting started and finding help
It’s easy to get started just by integrating your Azure Sphere (Legacy) tant into an Azure Sphere (Integrated) catalog and starting to explore working with Azure Sphere in Azure CLI or Azure Portal. Azure Sphere (Legacy) is fully supported until the 27 September 2027 retirement date. All migration activities must be completed by that date. If you have questions about migration or need technical assistance, you can find answers from community experts on Microsoft Q&A, or you can contact AZSPPGSUP@microsoft.com.