Skip to content

Latest commit

 

History

History
437 lines (311 loc) · 26.6 KB

index-portalfx-extension-onboarding.md

File metadata and controls

437 lines (311 loc) · 26.6 KB
Raw

Onboarding

Welcome to the Azure portal! We're excited to have you to join the family.

Most services consist of 3 components:

  • Marketing content on azure.com or other website
  • Management APIs exposed via Azure Resource Manager (ARM) or Microsoft Graph
  • Management UI in the Azure portal and/or other tools/websites, like Visual Studio

The Azure onboarding process is streamlined to optimize the delivery of high quality experiences based on hundreds of hours of usability testing that meet Microsoft Common Engineering Criteria (CEC) and compliance requirements. Do not start designing UI or management APIs until after you've started the onboarding process to ensure you're following the latest patterns and practices. This will better optimize your time and avoid throw-away work by avoiding usability issues caused by anti-patterns and inconsistencies that block usability, performance, etc.

  1. Onboarding kickoff (Stakeholders: Leon Welicki, Adam Abdelhamed)

    Setup a meeting to discuss the following:

    • Is your service targeting public Azure, on-prem, or both?
    • Service name
    • VP, PM, and engineering owners
    • Timelines (preview, GA)
    • Summary of the service and target scenarios

  2. Business model review (Stakeholders: Brian Hillger’s team, Stacey Ellingson

  3. Management APIs in ARM/Graph

    All services using Azure Billing must be exposed via Azure Resource Manager (ARM), the replacement for RDFE (Red Dog Front End). Other services can use either ARM or Microsoft Graph. Typically, services that integrate deeply with Office 365 use Graph. All others are encouraged to use ARM.

    The Azure portal SDK doesn't require any specific back-end, but does provide extra support for ARM-based resources. Please submit a partner request for additional built-in support for standard Graph or ARM APIs.

    For Azure Resource Manager (ARM) (Stakeholder: Ryan Jones):

  4. CSS (Support) (Stakeholders: Wes Penner, CEGRM)

    Start CSS onboarding at least 3mos before public preview to ensure your customers can use Azure support.

  5. Azure.com (Stakeholders: Elena Salaks, Guy Burstein)

    All new services should be listed in azure.com. This isn't a requirement for onboarding the portal, but service categorization is the same between the azure.com Products menu, portal Services menu, and the Azure Marketplace. The long-term goal is for all 3 to be the exact same, where services aren't listed in the portal unless they're also on azure.com.

    Plan ahead for all the outbound communication, blogging, and marketing work to publicize your services as it goes out to customers, in particular if your release time needs to be aligned with the Azure events and conferences. For preview release, this could be an optional requirement, but for GA, your localized azure.com content and service updates plan are exit criteria that will require the stakeholders to sign off.

    For more information about azure.com onboarding, see http://acomdocs.azurewebsites.net.

  6. Common Engineering Criteria (CEC) (Stakeholder: Duke Kamstra)

    The Microsoft Common Engineering Criteria (CEC) program was designed to establish a set of engineering requirements across all products. Meeting these requirements is critical to the success of Azure. Every extension is required to be listed in the CEC Scorecard. Onboard your service to the CEC Scorecard using the CEC Fundamental Portal (CFP):

    1. Add your service to ServiceTree: https://servicetree.msftcloudes.com
    2. Request your service be "Active"
    3. If not in C+E, go to Dependencies to define a depndency on the CEC Scorecard service (C+E services are automatically added)
    4. Complete metadata in ServiceTree to enable the automation for various KPIs
    5. Complete the requirements for each release stage: https://cecfundamentals

  7. Internationalization (Stakeholder: Lynne Dong)

    Nearly 70% of Azure users are from outside of the United States. It’s important to make Azure a globalized product, and there are a few requirements under the "Internationalization" criteria you need acour service is required to support the same set of languages as the Portal for GA. Learn more about internationalization requirements.

  8. Azure Compliance (Stakeholders: Azure Compliance team)

    Compliance criteria and practices are defined in Quality Essentials throughout our development cycle. These ensure services meet the Trusted Cloud commitments outlined in the Microsoft Azure Trust Center for our customers. There are mandatory procedures as Preview and GA requirement, and to be revisited for every release cycle. QE provides the UI access to manage the release policies and procedures for each compliance. The tool can be installed from http://qe.

    QE tracks the following:

    • Accessibility
    • Global readiness
    • Global trade compliance
    • License terms
    • Open source software
    • Privacy
    • Security Development Lifecycle (SDL)
    • Software integrity

    Some of the procedures such as Accessibility, GB Certificate, Privacy, and Security are also measured in the CEC Scorecard and exit criteria for management review and tracking. These requirements apply to both the portal fx and extensions. Since Fx provides the common infrastructure and UI controls that govern the data handling and UX, hence some of the compliance work for extensions would be identical across in Ibiza, and rationally be mitigated by the Framework. For example, Accessibility support on keyboard navigation and screen reader recognition, as well as the regional format and text support to meet globalization requirement are implemented at the controls that Framework distributed.  Same for Security threat modeling, extension authentication to ARM, postMessage/RPC layer and UserSettings, etc. are handled by Framework. To minimize the duplicate efforts on those items Fx provides some level of "blueprint" documentation you can use as a reference for compliance procedures. You are still responsible to go through the tools and submit the results for approval before shipping your extension. Contact Amit Modi for any questions about Fx coverage.

    Policy Fx coverage
    Accessibility Generic control supports on keyboard, focus handling, touch, screen reader, high contrast, and theming
    Global Readiness Localizability, regional format, text support, China GB standard
    Privacy User settings data handling, encryption, and authentication
    SDL Threat modeling

  9. Build your portal extension! (see below)

Portal extension

Ready to write your first Azure portal extension? Here are a few resources to get you started:  

  1. Download the SDK

  2. Read the docs

    Our doc site provides the technical details while you are building your extension. The Getting Started section will guide you through how it works, build the extension, as well as the debugging tips during your code development.

  3. View the samples

    The Fx team runs a battery of tests using samples that are available as part of the downloaded SDK as well as available from the DOGFOOD (DF) environment. Browse through the samples to explore live examples of APIs.

  4. Setup a UX feasibility review

    Before starting to build your extension, please setup time to review your design and ensure your desired outcome is feasible.

  5. Join the right groups:

  6. Ask questions on //stackoverflow

    Join the community in https://stackoverflow.microsoft.com and let us know if you have any questions. (Don't forget to tag questions with "ibiza" or related tag.)

  7. Side-load your extension for local testing

    Side-loading allows you to test and debug your extension locally against any environment. This is the preferred method of testing.

  8. Marketplace integration

    At a high level, each icon you see in the Azure Portal Marketplace is referred to as a Gallery item. Gallery items take the form of a file with the .azpkg extension. You can think of this file as a zip which contains all assets for your gallery item: icons, screenshots, descriptions.

    PROD: The Marketplace team accepts fully finished .azkpg files from your team and performs upload to Production Click to request 1store onboarding your gallery package.

    DOGFOOD: Use AzureGallery.exe to upload items to DOGFOOD using the following command:

AzureGallery.exe upload -p ..\path\to\package.azpkg -h [optional hide key]

In order to use the gallery loader you will need to set some values in the AzureGallery.exe.config file for details see AzureGallery.exe docs. For dev/test scenarios see Test In Prod

  1. Register your extension

    Once your service name is finalized, request to have your extension registered in all environments. Once deployed to DOGFOOD (aka DF), contact the Fx team to request that it be enabled (if applicable). Your extension will be enabled in production once all exit criteria have been met.

    Extension names must use standard extension name format: Company_BrandOrSuite_ProductOrComponent  (e.g. Contoso_Azure_{extension} or Microsoft_Azure_{extension}). Set the extension name in extension.pdl as follows:

<Extension Name="Company_BrandOrSuite_ProductOrComponent" Preview="true">

Extension URLs must use a standard CNAME pattern. Create CNAMEs using Microsoft's DNS (use any Azure property as the identity).

Environment URL
DOGFOOD df.{extension}.onecloud-ext.azure-test.net
PROD main.{extension}.ext.azure.com
BLACKFOREST main.{extension}.ext.microsoftazure.de
FAIRFAX main.{extension}.ext.azure.us
MOONCAKE main.{extension}.ext.azure.cn

Use a wildcard SSL cert for each environment to simplify maintenance (e.g. *.{extension}.onecloud-ext.azure-test.net or *.{extension}.ext.azure.com). If your team is building separate, independent extensions, you can also use {extension}.{team}.ext.azure.com and create a wildcard SSL cert for *.{team}.ext.azure.com to simplify overall management. Internal teams can create SSL certs for DF using http://ssladmin. Production certs must follow your organizations PROD cert process -- do not use SSL Admin for production certs.

NOTE : Registering an extension in Portal requires deployment so it can take almost 10 days. Please plan accordingly.

Request to register your extension (internal only) and email the work item id to ibizafxpm. You'll automatically be notified when the configuration change is pushed to PROD. External teams can submit their request via email.

  1. Exit criteria + quality metrics

    Every extension must meet required [exit criteria / quality metrics before it will be enabled.

For any other questions, don’t hesitate to ask us on https://stackoverflow.microsoft.com.

## Exit criteria & quality metrics

In order to meet customer expectations and continue to increase customer satisfaction, the following quality metrics are tracked for every extension:

  1. Performance
  2. Reliability
  3. Usability
  4. Accessibility
  5. Feature adoption

Performance (Stakeholder: Sean Watson)

All blades must meet the required blade reveal time of <4 seconds for the 80th percentile before being enabled in PROD. Extensions must be enabled in MPAC to start tracking performance. Resource and Create blades are tracked explicitly. All other blades are rolled up into Weighted Experience Score (WxP), which must be >80. WxP determines the percentage of blade usage that meets the performance bar.

Blade reveal time is the time it takes for all the parts above to fold to call revealContent() (load 1st level data) or to resolve onInputSet() promises, whichever is earlier.

MPAC and PROD performance is included in weekly status emails and each team is expected to investigate regressions.

See also:

Reliability (Stakeholder: Sean Watson)

Every extension, blade, and part must meet the reliability SLA. Extension, resource blade, and Create blade reliability metrics must be met before your extension will be enabled in PROD. Extensions must be enabled in MPAC to start tracking reliability.

MPAC and PROD reliability is included in weekly status emails and each team is expected to investigate regressions.

See also:

Usability (Stakeholder: Angela Moulden)

Each service must define the critical, P0 scenarios for their business. These scenarios must be usability tested to ensure 80% success rates and an experience score of 80 (based on a short survey). Usability must be measured by testing at least 10 participants.

Accessibility (Stakeholder: Paymon Parsadmehr)

Similar to the usability bar, every service must meet the Microsoft standards for accessibility.

Feature adoption

All extensions are required to complete the following before being enabled in PROD. None are required to be enabled in MPAC. Track status on the feature adoption sign-off dashboard (doesn't include menu blade for services [as opposed to resources], deployment success rates, Create dropdowns/PCv3, or Browse menu placement).

  1. Menu blade (aka resource menu; Stakeholders: Sean Watson, Edison Park)

    All services must implement the menu blade instead of the Settings pattern. ARM resources should opt in to the resource menu for a simpler, streamlined menu.

    Every service must include the following menu items:

    • Resource health -- Check the health of any resource from the resource blade via settings (Stakeholder: Bernardo Alfredo Munoz)
    • Troubleshoot -- Have a Troubleshoot link in the resource menu to surface self-help solutions on common issues (Stakeholder: AzSFAdoption)
    • Create support request -- Be able to create a support request from the menu (Stakeholder: Ganga Narayanan)

    See also:

  2. Create success (Stakeholder: Paymon Parsadmehr)

    Every Create blade must meet the create success rate standard. For latest numbers see Power BI. If create workflow success drops 5% over a rolling 24h period with 50+ creates, a sev 2 incident will be filed. This covers every error that causes Creates to fail after the user clicks the Create button. Extensions/RPs are responsible for validating all inputs to ensure the user cannot click the create button unless that create will be successful. Services that use template deployment must opt in to RP registration checks, deployment validation, and required permission checks to avoid common errors.

    See also:

  3. Activity logs (Stakeholder: Rajesh Ramabathiran)

    Activity/event/operation/audit logs must be available from the menu for all services. Subscription-based resources (not just tracked resources) get this for free when implementing the resource menu. All other services are required to add the equivalent experience for their service.

  4. Create blades (Stakeholder: Michael Flanakin, Paymon Parsadmehr)

    All Create blades must be a single blade. Do not use wizards or picker blades. Use form sections and dropdowns. Subscription-based resources must use the built-in subscription, resource group, location, and pricing dropdowns; especially in Create blades. These each cover common scenarios that will save time and avoid deployment failures.

    See also:

  5. PCv3 (Stakeholder: Paymon Parsadmehr)

    Use Parameter Collector v3, especially for Create blades. Do not use v1 or v2 anywhere. The newer version has improved APIs, performance, and telemetry.

    See also:

  6. Automation options from Create (Stakeholder: Paymon Parsadmehr)

    Every service should expose a way to get scripts to automate provisioning. Automation options should include CLI, PowerShell, .NET, Java, Node, Python, Ruby, PHP, and REST (in that order). Tracked resources that use the built-in template deployment API are opted in by default.

  7. Browse menu placement (Stakeholder: Edison Park)

    All services must be added to a specific category in the Browse/Services menu (under favorites on the left). Categorization will be the same as it is for azure.com’s products menu. The Fx team needs to know what asset types will be added to ensure your service is placed in the correct categories. (Asset type names are defined in extension PDL.)

    See also:

The following features are required for all subscription-based resources:

  1. Deployment validation (Stakeholder: Paymon Parsadmehr)

    The following validation must be included:

    • Opt in to RP registration checks on the subscription dropdown
    • Specify required permissions on the resource group dropdown
    • Opt in to deployment validation

    See also:

  2. Resource move (Stakeholder: Edison Park)

    Being able to move your resource from one subscription or resource group to another.

    See also:

  3. Create from Browse (Stakeholder: Edison Park)

    Have an "Add" command in the Browse blade for that resource.

    See also:

  4. Context menu commands in Browse (Stakeholder: Edison Park)

    Within the Browse blade, your resource specific commands should be available on right-click or when the user clicks on the "...".

    Have an "Add" command in the Browse blade for that resource.

    See also:

  5. Show all resource properties in the Browse column chooser

    Within the Browse blade, you should have all your resource specific columns available in the column chooser to allow users to see data they need.

    See also:

  6. Export template / RP schema

    ARM RPs must provide a schema for all tracked and nested resource types to ensure they support the export template capability. Export template is enabled by default from the resource menu.

    See also: