Skip to content

Latest commit

 

History

History
389 lines (276 loc) · 23.6 KB

index-portalfx-extension-onboarding.md

File metadata and controls

389 lines (276 loc) · 23.6 KB
Raw

Onboarding

Welcome to the Ibiza/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 Ibiza/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.

Azure Onboarding

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

  2. 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):

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

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

  4. 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.

  5. 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

  6. 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.

  7. 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

Ibiza Onboarding

  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

Ibiza Extension Resources

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

  1. Join the right groups:

  2. Download the SDK

  3. 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.

  4. 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.

  5. 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.

  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

  9. Recommended patterns

    The following patterns are recommended for every extension based on customer feedback and usability studies, but are not required:

    • Menu blade

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

      See also:

    • Activity logs (Stakeholder: Rajesh Ramabathiran)

      Activity/event/operation/audit logs should 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 should add the equivalent experience for their service.

    • Create blades

      All Create blades should be a single blade. Do not use wizards or picker blades. Use form sections and dropdowns. Subscription-based resources should 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. The subscription, resource group, and location picker blades have been deprecated.

      Every service should also 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). ARM-based services that use template deployment are opted in by default.

      See also:

    • Browse (resource list) blades

      All Browse blades should have:

      • "Add" command to help customers create new resources quickly
      • Context menu commands in the "..." menu for each row
      • Show all resource properties in the column chooser

      See also:

    • 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:

  10. 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.

  11. 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. Create success
  6. Resource move (ARM subscription-based services only)

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 rate and an 80% experience score (based on a short survey). Usability must be measured by testing with at least 10 participants.

Accessibility (Stakeholder: Paymon Parsadmehr)

Similar to the usability bar, every service must meet the Microsoft standards for accessibility for their critical, P0 scenarios. Teams within C+E should work with the C+E Accessibility team to verify accessibility.

NOTE: Accessibility is a non-blocking requirement today, but it will be blocking in CY2017.

Create success (Stakeholder: Paymon Parsadmehr)

Every Create blade must meet the create success rate. For Create SLA check the Power BI Dashboard. If success drops 5% on 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 Create isn't submitted unless that Create will be successful. This applies to all services, whether using ARM or not.

Services that use ARM template deployment must opt in to RP registration checks, deployment validation, and required permission checks to avoid common issues and help improve your success rates.

NOTE: Create success rates are a non-blocking requirement, but opting into applicable validation is required for preview/GA (for ARM-based services). Any blades with a success rate below 99% will result in sev 2 incidents based on the above logic.

See also:

Resource move (Stakeholder: Edison Park)

ARM-based services must allow customers to move resources between subscriptions and resource groups.

See also: