If you are working on an Azure service and want to expose UI to your customers in the Azure portal then this is the right starting point. The portal has an extension model where each team that builds UI creates and deploys an extension. This process requires a relationship to be established between your team and the central portal team. This document walks you through the process of onboarding your team and starting that relationship.
Onboarding a service, or developing a Portal extension, has three phases: onboarding, development, and deployment. The process is specified in the following image.
There are lots of docs here. We recommend you send mail to ibiza-onboarding@microsoft.com and request a kickoff meeting. Someone from our team will spend 30 minutes walking through the process at a high level. We can point you in the right direction regarding the latest patterns and practices. We can also answer any questions you have. Finally, we can talk about how the relationship between our teams is managed.
Onboarding to Azure all up is a big task that spans many teams. The doc you are reading will help you onboard to the portal, but there are many other teams you will need to work with to get your entire service up and running. These include, but are not limited to the following teams.
NOTE: Contact information for these teams is available here
-
Azure Resource Manager Team
Reach out to this team to onboard your resource provider.
-
Azure Marketing Team
-
Support Team
For integrating with the support system and UX integration.
-
Azure.com team
For a presence on the marketing site.
-
Billing team
To register meters and other billing related activities.
-
AAD onboarding
Reach out to AAD onboarding if the new extension service needs special permissions besides just calling your own resource provider servers. If the extension requires additional built-in support for standard Graph or ARM APIs, submit a partner request at the site located at https://aka.ms/portalfx/uservoice.
-
Azure fundamentals and compliance
The Azure Fundamentals are a set of tenets to which each Azure service is expected to adhere. The Azure Fundamentals program is described in the document located at https://aka.ms/azurefundamentals. The document also identifies the stakeholders and contacts for each of the tenets.
-
Security and privacy reviews
-
Start the CSS onboarding process with the CSS team at least three months previous to public preview. This process may coincide with the following step. For more information about development phases, see top-extensions-developmentPhases.md.
-
Nearly 70% of Azure users are from outside of the United States. Therefore, it is important to make Azure a globalized product. There are a few requirements under the "Internationalization" criteria that your extension is required to support. This is the same set of languages that are supported by Azure Portal for GA. For more information about internationalization requirements, see http://aka.ms/AzureGR. For onboarding localization, please reach out to Bruno Lewin and the Internationalization team at Internationalization team.
-
Decide on a name and URLs for the extension. You may need to contact emailing ibiza-onboarding@microsoft.com to ensure that the name and URL's are unique.
-
Schedule a UX feasibility review with the Ibiza team UX contact by emailing ibiza-onboarding@microsoft.com. Many extensions have been made more successful by setting up early design reviews with the Azure Portal team. Taking the time to review the design gives extension owners an opportunity to understand how they can leverage Azure Portal design patterns, and ensure that the desired outcome is feasible.
While the portal team cannot help directly with all of these factors, see portalfx-extensions-contacts.md for a list of items with which we can assist you.
For less common scenarios, you might need to do a custom deployment. For example, if the extension needs to reach server services using certificate based authentication, then there should be controller code on the server that our hosting service does not support. You should be very sure that a custom hosting solution is the correct solution previous to developing one.
Request the following permissions to stay current on product roadmaps, get news on latest features, and receive invites for ibiza related events.
-
PMs and Developer Leads should join the
ibizapartners PMgroup here. -
Developers should join the
ibizapartners DEVgroup here. -
Developers should join the appropriate group listed on http://aka.ms/standardaccess to get access to portal telemetry. All groups on this page receive access.
-
Developers should join the
Azure Portal Partner Contributors - 19668(19668)group by using this link: https://myaccess. -
PMs, Developers, and Developer Leads should subscribe to the partner request process by joining the
Uservoicegroup at this link: https://aka.ms/portalfx/uservoice. For more information about the partner request process, see top-extensions-partner-request.md. -
PMs, Developers, and Developer Leads should join Stackoverflow Forums that are located at https://stackoverflow.microsoft.com to let us know if you have any questions. Remember to tag questions with supported tags that are monitored by the Ibiza team. All supported tags are documented in portalfx-stackoverflow.md.
-
Developers who want to contribute to the test framework should join groups from the site located at http://aka.ms/azuregithub.
Ask an onboarding question on Stackoverflow.
The development guide located in the main documentation index has all the right pointers.
The development guide located in the main documentation index has all the right pointers.
The Ibiza team provides and operates a common extension hosting service that makes it easy to get your extension into a globally distributed system without having to manage your own infrastructure. For more information see top-extensions-hosting-service.md.
For less common scenarios, you might need to do a custom deployment.
For example, if you need to talk to backend services using certificate-based authentication then you'll need controller code on the server. This is not supported with our hosting service. You should be very sure you require a custom hosting solution before going down this path.
NOTE: The deployment can be configured in such a way that the client portion of the extension uses the hosting service while the custom controller code can be deployed separately. For more information, see top-extensions-custom-deployment.md.
Once the name of the extension is finalized, it is time to register the extension in all environments. This requires a portal deployment and can take time. Our Service Level Agreements are located at top-extensions-svc-lvl-agreements.md. Please plan accordingly.
-
For internal partners, the request to register an extension is a pull request, as specified in top-extensions-publishing.md.
-
External teams can submit their requests by reaching out to the ibizafxpm team with an onboarding request.
-
NOTE: Extension names must use standard extension name format, as in the example located here.
-
NOTE: Extension URLs adhere to the naming requirements located in portalfx-extensions-cnames.md.
-
Show your asset types.
There are three typical release kinds: private preview, public preview, and Global Availability (GA). For the purposes of deployment public preview and GA are the same. The only difference is that the UI may show preview labels and disclaimers where appropriate. For more information about the three kinds of releases, see top-extensions-developmentPhases.md.
For a private preview, the goal is to hide your experience to the general public, but show it to a limited audience. This procedure assumes that the discoverable entry point in the product is the All Services menu, also known as the Browse menu.
Hiding or showing items in the all services menu is controlled by the extension configuration that gets deployed with your extension. The following example shows how to set it up. To do so, you should make a change to hide all your asset types in the environments you wish to stay hidden in. See hiding assets for help with the change.
When in the hidden state, users will not be able to browse to or search for the entry point of the extension. However, you can distribute a special link like the following one that enables the entry point by using a feature flag. https://portal.azure.com?extensionName_hideassettypes=none
A few notes about this path:
- Any user that receives this URL will be able to see your entry point.
- Any users who receives a deep link to blades within your extension will be able to see that experience even without the feature flag
- If the extension is integrated into the Marketplace, then that team has its own way of hiding Marketplace items. Contact 1store@microsoft.com for more details.
You are required to check the quality of your extension. We have standardized ways of measuring reliability and performance at key areas. If you have a private preview then we have already collected this data for you.
There is no blocking exit criteria, which means you do not have to prove that the extension's performance and reliability are in the required range. However, once you ship, the Portal team will monitor the quality of the extension. Extensions that do not meet the required quality bar will be flagged in executive reviews and will be asked to improve their quality as soon as possible.
When you are ready for all users to see your experience, you will enable your entry point as shown in the following example and then deploy your extension.
Azure portal onboarding steps listed below assumes that all new services have completed the onboarding meeting with ibiza-onboarding@microsoft.com team and that you have downloaded the Azure portal SDK to start the development of your extension. If you have not had either the onboarding meeting or have developed the extension, please discuss with the Azure portal team on the requirements.
NOTE: Azure portal Onboarding process is common for all clouds including LX.
-
Before onboarding to Azure portal, please take a moment to understand the different repositories, branches and environments we have in Azure portal and SLAs for onboarding.
-
Azure portal onboarding involves 3 different repositories. Framework, Hosting Services and Alerting.
-
Portal framework and hosting services have Dev, Dogfood and Production Branches. All changes to config files must be raised to Dev branch only.
-
Dogfood config changes can only be applied to Dogfood environment and endpoints that are accessible only by Microsoft employees.
-
Production config changes are applied to RC, Mpac, Preview and Production environments.
-
Once a PR completes in Dev branch, the change gets merged to Dogfood branch automatically.
-
From Dogfood branch, the change is deployed to RC, Mpac and Preview environments.
-
Partners must validate all changes deployed in framework branches of RC or Mpac thoroughly before cherry-picking the commit to Production branch.
-
Partners must cherry-pick Hosting Service changes from Dev Branch to Production of Hosting Service for the hosting service change to be available to use in either Framework environments of RC, Mpac, Preview OR Production.
-
Partners must onboard to all public and sovereign clouds at the same time and update the respective configs.
-
Hide all assets in sovereign clouds if you do not intend to show your experiences in those clouds.
-
By onboarding to Azure portal you agree to keeping your extension up to date regularly with the latest supported SDK. You will recieve IcM alerts ranging from Sev-4 to Sev-2 if you fail to upgrade your SDK before required time limit.
-
Portal SDK has a 120-day backward compatibility and we start firing alerts when the SDK age is 60days. Extension owners are responsible for any outages caused due to an aged SDK that is out of support.
-
IcM Service/Team and feedback email address mentioned in the Portal config must be updated immediately if there is a change in these details or ownership transfer of the service. Failing to update these details will make the service orphaned services.
-
Portal team reserves the right to remove any orphaned services from portal that cause services alerts or failures due to an unsupported SDK version or instability issues for the rest of the portal.
-
Ensure that the users are given advance notice about the deprecation of a feature or service when removing the corresponding experience from Azure portal.
-
Notify users via Azure blog, Azure status updates or email about the intended deprecation plan and provide migration to alternative features or service.
-
Users will continue to see the currently loaded extension version until their browser is refreshed. Hence it is advised that you monitor the telemetry for usage before turning off service or feature.
-
Any alerts configured for you service in the Alerting repository will be removed only after the corresponding configuration changes are fully removed from the extensions config json files and deployed to Production. We also need to wait for stable build before we stop firing the alerts for a deprecated extension.
NOTE: Partner must cherry-pick changes made in both Azure portal framework and hosting services from Dev branch to Production branch for the changes to be deployed to Production/Public clouds. Partners are responsible for completing the PR and cherry-picking the changes from Dev Branch to Production Branch. Portal team does NOT merge these changes automatically
How to cherry-pick manually? More info on publishing
- Open git command prompt and navigate to hosting service folder
- Create a new branch from Production branch
- Run cherry-pick commit_id_from_devbranch_pullrequest
- Resolve any merge conflicts and save changes
- Add the file after saving changes
- Run cherry-pick --continue
- Run git push --set-upstream origin branch_name_created_in_step2
IMPORTANT Partners must ensure PR has the required approvals and all the policies are met and PR is complete. PRs may get delayed due to merge validation expiry or other policy checks. Partners can re-trigger any policy that expired or failed.
-
Understand the deployment schedules and SLAs for Portal framework and Hosting service repositories.
-
Portal team has a process of freezing deployments during special events like //build //Ignite //Inspire etc. Any changes to Production branch will NOT be honored during this freeze time. Please plan your Preview/Release of your service accordingly.
-
Portal team does an automatic merge from Dogfood branch to Mpac and Mpac to Production during special events like conferences. During all other times, partners MUST always cherry-pick the changes from Dev branch to Production branch for the respective changes to go live.
-
National cloud deployments take 2 weeks more than Production branch.
-
Always work with Azure portal onboarding contact about your release dates before you commit timelines to release the product or any Marketing communications.
-
All exceptions to bypass SLAs and fasttrack deployments will require Partner level approval on both sides. All exception during major events will require VP level approval.
Note : Step 1 and Step 2 below are sequential and required to complete the Portal onboarding. Step 3 is optional unless the onboarding service requires dedicated tokens.
To use the Extension Hosting Service after you have developed your extension, you will have to onboard onto the Extension Hosting service separately. You will have to follow the steps in this document to have your extension to be ready for deploying onto the hosting service. The reason we have the steps below is to let you do these things in parallel. Developers should join the Azure Portal Partner Contributors - 19668(19668) group by using this link: https://myaccess.
- Create storage account for each environment eg: Dogfood, Prod, Mooncake, Fairfax and BlackForest
- Create a container under the storage account with anonymous read access
- Upload the config.json and the generated zip file from your build.
NOTE: You can make changes to hosting service configuration and raise a pull request for a self-service onboarding to hosting service
- Create a new branch in the hosting service repository based on the dev branch
- Update the hosting service configuration for appropriate environment(eg: config.dogfood.json, config.prod.json, config.ff.json, config.mc.json, config.bf.json, config.usnat.json, config.ussec.json) by editing and adding a new line for the extension route prefix entry in the "hostExtensionConfigs" section as shown below.
- Commit and Create a pull request to the Dev Branch.
- Create a hosting service onboarding workitem and this to the pull request.
- Send email to ibiza-onboarding@microsoft.com with the workitem details and pull request id to get the approval.
- Once the hosting service PR for Dev branch is completed, parnters MUST cherry-pick this commit from Dev branch to Production branch of hosting services.
Note: Incorrect or insufficient information in the workitem could delay the onboarding process.
- Check Hosting Service API Diagnostics log for Dogfood or Production or Mooncake or Fairfax or Blackforest in web browser. For LX deployments, partners are required to engage their dedicated LX resource to hit the corresponding LX endpoints to validate.
- Press Ctrl+F to find your extension routeprefix that registered for your service. Eg: storage
- Check Commit Search with the commit id and Hosting Service Release Dashboard.
- Register your extension with Azure portal framework by raising a pull request to the appropriate extension config json. eg: extensions.dogfood.json, extensions.prod.json, extensions.ff.json, extensions.mc.json, extensions.bf.json, extensions.usnat.json, extensions.ussec.json etc,. If you are disabling the extension in the given environment(eg: "flags": "Disabled"), you do not have to increment the extension count.
- Increment the extension count in DeploymentSettingsTestConstants.cs
- Always raise the PR to the Dev branch
- For Prod config chanages, once the PR is approved, please cherry pick the change to Prod after thoroughly testing the portal in MPAC endpoint. Portal team does not auto merge the changes to Production branches
- Always cherry-pick the change from Dev to Prod branch. This is a new change to the cherry-picking process as we will deploy to Mpac by default from Dev branch.
- Here is a sample PR change for dogfood branch.
Note : Dogfood config does not require creating a CNAME entry for extensions as all extensions use the common DNS endpoint. Onboarding to Production config will require the CNAME created with route prefix.
{
"name": "Microsoft_Azure_DemoExtension",
"feedbackEmail": "demoextPMDev@microsoft.com",
"flags": "SupportsPrewarming",
"resourceAccess": [
{
"name": "",
"resource": "https://management.core.windows.net/"
},
{
"name": "self",
"resource": "abcd18b0-9c38-48c9-a847-e1ef3af0602d"
},
{
"name": "graph",
"resource": "https://graph.windows.net/",
"oAuthClientId": "abcd18b0-9c38-48c9-a847-e1ef3af0602d"
},
{
"name": "microsoft.graph",
"resource": "https://graph.microsoft.com/",
"oAuthClientId": "abcd18b0-9c38-48c9-a847-e1ef3af0602d"
}
],
"serviceTreeId": "abcdbde1-a1b3-41da-be44-e3fa76a3ffc6",
"icm": {
"service": "Demo IcM Service",
"team": "Azure Demo UX"
},
"hostingServiceName": "azuredemo"
}
- Hide all assets in your extension code before updating the framework config. By doing this, you can control when the assets can be shown and when you want to go live in Production.
Note : Extension name cannot be changed once onboarding is complete. It will require a new onboarding and redirecting to the new extension.
{
"name": "Microsoft_Azure_DemoExtension",
"feedbackEmail": "demoextPMDev@microsoft.com",
"redirectTo": "Microsoft_Azure_DemoOld",
"serviceTreeId": "abcdb46d-bf43-4fef-a148-0d740e595d62",
"icm": {
"service": "Azure Demo IcM",
"team": "Demo Team"
},
"hostingServiceName": "demoextension"
}
-
Add a comment in the workitem associated with the pull request to get notified of deployment.
-
If the changes are deployed you should find them in the API diagnostics log in respective branches DF, RC, MPAC or PROD. For LX deployments, partners are required to engage their dedicated LX resource to hit the corresponding LX endpoints to validate.
Note : Please DO NOT get the pull request approved, bypassed or completed without hosting service onboarding complete and required DNS entries created.
- Check Commit Search with the commit id and Portal Framework Release Dashboard.
- This onboarding process is only meant for extensions in Azure portal that intend to call backend services like msgraph, keyvault or others.
- If your service only calls ARM, you do not need a separate 1st party app.
- Portal team is required to own the AAD apps if you intend to use them in the extension and need portal to get an OBO(on behalf of) token for the configured audiences in your extension config.
- If you intend to get a self token and exchange with AAD for any audience of your choice, Portal team does not need ownership and this AAD onboarding can be skipped.
NOTE: ARM tokens obtained during portal login are meant only for calling ARM. For all other purposes, please create a 1st party App.
-
Join the Ibiza AAD App Partners security group if you want to create or update your 1st party AAD app.
-
Once the request is approved, you should be part of the security group that has access to the public certificate that is required to be added to the AAD apps in 1st party AAD apps in each environment
-
Register your 1st party AAD app from First Party Portal
-
Send email to [ibiza-onboarding@microsoft.com] to add the authentication certificates to the 1st party AAD app along with the Appid.
-
Go to Provisioning tab and in the "Provide more detail" section, add "This app will be used by Azure portal extension to call graph and other backend services".
-
Go to the Owners tab and use redmond\ibizaaadapppartners as the Owners Security Group
IMPORTANT NOTE: Partners are responsible for making sure the AAD app has all the required permissions and pre-authorization to access intended resources.
| Link | Description |
|---|---|
| Getting Started | How To: Getting started with Azure portal SDK |
| Architecture | Azure portal architecture |
| Authentication in Azure portal | How To: Azure portal authentication |
| Azure portal Release Pipeline | Check Framework Service release pipeline |
| Hosting Service Release Pipeline | Check Hosting Service release pipeline |
| Check Framework Commits | Check commit status for Framework |
| Check Hosting Service Commits | Check commit status for Hosting Service |
| Simonp-Sites Commits | Alternative tool for framework commit status |
| Simonp-Sites Pipeline | Alternative tool for pipeline |
| Simonp-Sites Environments | Alternative tool for environments |
You can ask developer community questions on Stackoverflow with the tag ibiza-onboarding or use the following for specific areas of Ibiza.