Anypoint Platform Upgrade to Latest Software Guide
|
The upgrade to the November 2017 or "Crowd" release changes the existing Anypoint Platform APIs, which affects continuous integration and continuous development (CI/CD) pipelines built against the API Manager API and autodiscovery. See the APIs in API Manager - Post-Upgrade and CI/CD Changes to Make sections. A high-level overview is in the CI/CD Architecture section. Note: After the upgrade and before classifying your APIs into environments, test your APIs, Notebooks, and Portals. After APIs are classified, your organization cannot roll back if you encounter upgrade related issues. Portal URLs are updated, so update these links accordingly. |
Complete an Upgrade to the November Release
Anypoint Platform provides these steps to complete the upgrade to the November 2017 Anypoint Platform software release:
-
Group your APIs. (Optional, recommended)
-
Request a time to upgrade using the green banner that lets you access the self-service upgrade portal. Only the organization owner can schedule the upgrade. If you do not see a banner, contact your Customer Success Manager to coordinate steps to upgrade.
-
After the upgrade, we recommend you classify APIs to your environments. (Optional, recommended).
| Before the classification step, test your APIs, Notebooks, and Portals. After APIs are classified, your organization cannot roll back in the event you encounter upgrade-related issues. |
Why Group your APIs?
Create a group of API versions in API Manager before the upgrade to provide access for your API developers and consumers to the master portal of your API, and for ease of use of environments to which you can deploy your APIs.
The new version of the platform supports moving APIs between environments, so you won’t need the name of the environment in the API name or version. Prior to the release, you may have stored the name of the environment in the name of the API.
For example, you may have had "Staging" or "Prod" in the API name or version to indicate use in those environments:
Orders API - v1 - Dev
Orders API - v2 - Staging
Orders API - v1 Prod - v1
By removing any reference to environments like "Dev" or "Stg" or "Prod" before the upgrade, you avoid having to change the API or version names as you promote the API instances through environments after upgrading.
Note: If you use Business Groups instead of environments to group your APIs, API grouping is not needed or recommended.
You will be able to see the original API names in API Manager after the upgrade. Therefore, you will be able to easily account for any new names you created. API autodiscovery and API Manager platform APIs have changed, so be sure to review them below before creating new APIs. APIs created before upgrade continue to work with the old autodiscovery XML references.
Notes:
-
If you do not perform the grouping step, you may find extraneous API projects and a degraded platform experience for consumers.
-
After you add one or more APIs to an API group (New API Name in the API Grouping screen), you cannot ungroup the APIs. However you can change the group for each API individually to a different API group, by changing an API name or API version name.
Group Your APIs
Note: Read the previous Complete an Upgrade to the November Release and Why Group your APIs? for vital roll back and business group information.
We recommend completing the grouping of your APIs before scheduling your upgrade to remove the name of the environment (dev, stg, etc.), and clean up API names or versions. After the upgrade, you can promote or "classify" an API version into an environment.
-
Log into Anypoint Platform and go to API Manager.
-
To the right of each API in API Manager you should see a message that reads Prepare To Group.
-
Click Prepare To Group. In the popup, API Manager lists the Current API Name and Current API Version. Add an API to a new group by choosing an API name to use for all versions, or use an existing API name to add it to an existing group of API versions. The idea is that you select one portal to represent the API (i.e. a canonical version). However, consumers may download the specifications of any version in the group from the portal in the new Exchange.
-
Click Edit to change the New API Name, New API Version, or to include the API portal to represent the API in Exchange.
Important: Only one API portal can be migrated per group of APIs.
-
Specify a New API Name. This can be any string of ASCII characters.
-
Specify a New API Version Name. This can be any string of ASCII characters.
Note: If you have two or more identical version names in one API group for example, two versions named "v1" in an API group, you can distinguish them after the upgrade by the Exchange asset ID. The Exchange asset versions share the major number (1.x.x) but differ in the patch number (1.0.0 and 1.0.1). The latest is the one that has the "Select RAML" checkbox checked in the grouping step, otherwise a version’s creation date determines the numbering.
Avoid storing the environment name in the API Name or Version Name if possible. After the upgrade, classify your APIs to the appropriate environment from the new API Manager.
Schedule Platform Upgrade
Schedule the upgrade for your Anypoint Platform organization by accessing the self service portal and following the steps.
The upgrade is triggered automatically at the time you schedule in the self-service portal. Access this portal from the green banner in the Anypoint Platform login. The estimated upgrade time is 15 minutes to upgrade 50 API versions.
During this stage, API design projects and API portals are moved into their appropriate new home. API specifications and API portals are stored and versioned in Anypoint Exchange, and new projects are created for them in Anypoint Design Center. SOAP APIs or APIs without specifications are moved to Exchange only and not added to Design Center.
After this process completes, the user who scheduled the upgrade receives an email confirming a successful upgrade. In case MuleSoft encounters issues, MuleSoft automatically rolls back an upgraded account to its previous experience. You can contact MuleSoft Customer Support with any questions on resolving these errors.
Post-Upgrade: Classify APIs into Environments
After the upgrade, all APIs are listed in an environment called the Unclassified environment. From here, you can classify APIs into your appropriate environments.
For the environments you classify APIs into, there is a new access control which is explained here: Grant Permission to Access Environments. Existing API Manager roles/permissions continue to work in the Unclassified environment, and the APIs section in Access Management is applicable to unclassified APIs.
Even though API Manager supports tracking APIs by both organization and environment credentials, MuleSoft recommends using environment credentials as the permissions associated to them are more restrictive. But, you need to restart Mule Runtime after changing credentials, which can cause downtime.
| The names of APIs you see in the Unclassified environment reflect the original API names you had prior to grouping your APIs. This is so that you can easily determine the environment for each API. |
-
Update the server where the API or API proxy is running. (Optional: only needed if you would like to use environment credentials for API tracking. You can still continue to use organization credentials that don’t require any changes on Mule runtime configuration.)
-
Classify the API into the suggested environment.
Using credentials from one environment does not allow:
-
Tracking APIs from different environment
-
Tracking APIs from different organizations
|
In the Pre-Crowd version of API Manager, all API Analytics dashboards were organization-wide. In Crowd, each dashboard links to a particular environment. |
For more information see To Classify APIs.
FAQ on Upgrades
How do I reschedule my upgrade?
Click Cancel booking in your Booking confirmed email. You can reschedule your upgrade by accessing the calendar view at the bottom of the self service upgrade portal and selecting a new upgrade date and time (7 days advance notice is required).
What is the API grouping step about?
Group your APIs so they are organized on one or multiple API portals. Group API versions of the same API and that share the same specification standard (for example WSDL, RAML). Each group shares a single portal page in Exchange. If you have multiple versions in the API, click the checkbox in the grouping popup to select the portal and associated RAML to be the master portal for the API. In Exchange, the specification for any version on your API can be downloaded for your API consumers.
Is there any downtime?
There is no downtime during the API grouping or the automated migration. We do, however, advise not to use API Manager during the upgrade process to prevent any data inconsistency. After the upgrade, classification of APIs into environments may cause downtime due to proxy restart.
Do API policies, client IDs, and secrets remain in effect during the upgrade?
Yes, API policies remain in effect during the upgrade. You should not have to change these settings whether on-premises or in the cloud. After the upgrade, it’s not required to change those properties, existing ones will continue to work. Regardless of the deployment target, you need to provide a clientID and clientSecret.
How do I cancel my upgrade?
After you accepted the calendar invitation sent to you, open the email with subject "Your booking confirmation". Click Cancel booking and click Cancel this booking in the window that opens. Once you cancel, a confirmation email is sent. For help, email crowd@mulesoft.com. When you are ready to select a new time, log back into the platform to schedule the upgrade.
How can I test the upgrade before scheduling the upgrade for my Anypoint org?
Our general recommendation is to create a trial account. This will be created as an upgraded account. Therefore, request your Customer Success Manager to convert the account to pre-upgrade with self-service upgrade scheduling for the trial account. Create dummy APIs for your testing purposes. Schedule an upgrade for the trial account using the instructions you will see when logging in after the trial account is converted to "pre-Crowd".
Who should I contact for questions during the process?
Open a case in the support portal.
Do I need to start using environment credentials for my APIs?
It’s optional to switch to environment clientID and clientSecret instead of org level credentials.
After the upgrade, how does API usability change?
After the upgrade is complete, APIs stored in API Manager before the upgrade are moved as follows:
| Before the Upgrade | Afterwards | Description |
|---|---|---|
API Manager: |
Design Center: |
All RAML files from API Manager automatically appear as an API Specification Project within Design Center. This project is visible to everyone within a business group. |
API Manager: |
Anypoint Exchange: |
API Portals are available for access through Anypoint Exchange, instead of API Manager. |
API Manager: |
API Manager: |
APIs stored in the API Manager move to the Unclassified Environment. API providers need to classify each API to the appropriate environment. |
Can I bulk classify APIs into a specific environment after the upgrade?
No.
What is the "Unclassified" Environment?
After the migration completes, all APIs appear in the Unclassified Environment. All APIs that haven’t been classified into a real environment can be managed from here. This environment has the same user interface and permissions model as the pre-upgrade API Manager.
All APIs in the Unclassified environment can be classified into a real environment by following the process described in this document. If API grouping information was provided before the migration, that information is used as the API name and version of the API being classified in the target environment.
Is API classification mandatory before deploying to existing applications?
No, you can continue to work in the unclassified environment and deploy to existing applications.
Is there a rollback available?
Yes. If you have problems with the new experience of Anypoint Platform, you can open a support ticket from MuleSoft Support and we will execute a rollback. Note: Rollback is only available if no APIs were classified. We recommend to request rollback within 24-48 hours. New changes after the upgrade will not be carried over with a rollback.
New and Changed Features
API Manager API (v2.x) leverages environments and API Autodiscovery.
Environments and Permissions
-
All APIs created using the pre-upgrade version of API Manager appear in the "Unclassified" Environment after the upgrade.
-
Exchange: Assign a user to at least the Exchange Viewers role to allow the user access to all Exchange assets within the business group in which you have assigned the permission. The Portals Viewer role has been deprecated.
-
APIs in the Unclassified environment can be classified into their corresponding environment. Once an API is classified and is then promoted, it results in a new API instance.
-
The user permissions model is now action-based and set for users at the environment level, which is aligned to the rest of the Management Center. Administrators should set environment-level permissions for all users after the upgrade.
-
Default environment-level admin roles are available. The permission model in the Unclassified environment works in the same way as API Manager permission model worked before the upgrade. Assigned permissions for APIs in the Unclassified environment also remain untouched during the upgrade process.
Autodiscovery for New API Instances
Auto-discovery changes apply to new API instances of existing or new APIs. Autodiscovery for existing API instances remains unchanged and you can leave the configuration as is.
-
To configure the Autodiscovery element for new API instances, retrieve the necessary values from the API and the UI:
-
name=”groupId:{{groupId}}:assetId:{{assetId}}” -
version=”{{version}}:{{instanceId}}”
-
-
-
Auto-discovery changes only apply to the newly created APIs and its instances The existing APIs remain unaffected even after the upgrade. New auto-discovery changes only apply to the newly created APIs and its instances.
-
-
API Manager API (v2.x) is available to leverage all new API Manager capabilities.
-
User permissions model has changed to be action-based at the environment level. (See To Grant Permission to Access Environments.)
NOTE: Permissions are now aligned with the rest of the Management Center. After the upgrade, administrators should set environment-level permissions for all users. Default environment-level admin roles are available. The permission model in the Unclassified environment works in the same way as the API Manager permission model worked before the upgrade. Assigned permissions for APIs in the Unclassified environment also remain untouched during the upgrade process.
API Designer
-
To make changes to a RAML of a running or published API, users need to republish any specifications in Exchange that have versions.
-
Design Center projects do not have tags like old API Manager projects.
-
API sync from Studio 6 and 7 only supports pull only.
API Portals in Exchange
-
External links from the navigation panel are grouped under the Helpful links section in Exchange.
-
Invisible pages are deprecated and replaced with draft functionality of Exchange. All invisible pages become draft after the upgrade is complete.
-
Branding at the API portal level is deprecated and replaced with global branding control. This means that all API portal pages inherit global styles.
-
To update an API specification available in Exchange or used by an API proxy in API Manager, users need to publish a new version of API specification to Exchange using API designer.
-
Internal API consumers can see all API endpoints and versions through an API portal they have access to. Existing API Manager controls permissions per API version.
-
Onboarding of external users of API Public Portals onboarding has been simplified and there’s no need to invite external users for them to be able to consume APIs and request API keys.
-
When APIs are migrated to Exchange, Exchange calls REST Connect to generate connectors for Mule 4 and Mule 3. Because REST Connect only supports RAML v1.0, owners for API specifications based on RAML v0.8 receive an email notification with a message that the connector creation has failed. They can still use Design Center to open and edit these API specifications, but these specifications cannot be used as a connector in Design Center, Studio 6, and Studio 7.
APIs in API Manager - Post-Upgrade
-
APIs utilizing an autodiscovery element now leverage API Manager.
-
API promotion to environments is a new feature that you can introduce as a step in your CI/CD pipeline.
-
Because the November release upgrade moves all portals and RAMLs, the old API cannot be used to modify, create, or delete them after the upgrade.
-
The pre-upgrade API Manager API can be used with APIs in the Unclassified environment with some restrictions (see below). There are also new environment-aware APIs, which also support the Unclassified environment, that you may start using (see the new API Manager API portal and the Proxies xAPI portal).
-
The following resources for managing RAMLs return 400. Use Design Center APIs instead.
/organizations/{organizationId}/apis/{apiId}/versions/{apiVersionId}/addRootRaml /organizations/{organizationId}/apis/{apiId}/versions/{apiVersionId}/files/* -
The following resources for managing portals (including permission setting) return 400. Use Exchange APIs instead.
/organizations/{organizationId}/apis/{apiId}/portals /organizations/{organizationId}/apis/{apiId}/versions/{apiVersionId}/portal/* /organizations/{organizationId}/portals/* organizations/{organizationId}/public/* -
API creation needs to be done in Exchange first, thus creation of an API from API Manager API returns a 400 response.
-
-
APIs exported before the upgrade cannot be imported after upgrade.
CI/CD Changes to Make
The Anypoint Platform APIs section of this doc has links to the API documentation so you can update your pipeline per any of the below criteria:
-
CI/CD pipelines need to be reconstructed to accommodate the environments you plan to use for your APIs. See the How to build your CI/CD pipeline for the full API lifecycle blog post.
-
If you call API Manager APIs to apply API management or policies, review the API Manager API and refactor your pipeline as needed.
-
If publishing to Exchange, review the new Exchange Maven Facade API and refactor as needed.
-
If you apply Policies, SLAs, etc., review API Manager API and refactor as needed.
Anypoint Platform APIs (November 2017 Release)
The following is a list of platform APIs that orchestrate the API deployment and management CI/CD automation. See the MuleSoft Developer Portal to find all the available Anypoint Platform APIs.
| Component | API Portal Before 17/Nov/2017 | Exchange Portal 17/Nov/2017 and Later |
|---|---|---|
All Platform Portals |
||
Access Management |
||
CloudHub |
The CloudHub Public API enables you to access application management services for applications deployed to CloudHub. |
|
API Platform / API Manager |
The API Manager API enables you to manage an API by applying policies, setting SLAs, configuring alerts for your API instances, and promoting API instances. The API Platform API exposes the management capabilities of the Anypoint Platform for APIs, enabling them to be used by external sites. |
|
Anypoint Runtime Manager (ARM) |
||
Exchange |
This API basically focuses on assets and portals. It allows doing a lot of operations on different organizations according to the permissions that each user has in Anypoint. Exchange Graph Service (API Reference) - v1 The Exchange Graph API lets you query Exchange assets filtering by multiple criteria and returning only the information you need. To try the Graph API, Click the Docs button in the top-right corner. Exchange Maven Facade (Maven Facade) - v1 The Exchange Maven Facade API lets you interact with Exchange using the Maven client to publish and consume Exchange assets as Maven dependencies. You can use the Exchange Maven Facade API for Mule applications, templates, examples, connectors or policies. RAML API specifications are not supported, use the Design Center xAPI to publish those assets. |
|
Proxies |
N/A |
The Proxies XAPI allows you to download or deploy proxies into Runtime Manager. Proxies API v1 |
CI/CD Architecture
The following diagram gives an overview of the CI/CD (continuous integration and delivery) process.
When working with large teams and multiple applications, the manual process for testing and deployment is challenging and teams should consider using a Continuous Integration and Deployment server like Jenkins.
Continuous Integration
The need for continuous integration (CI) for a project is very important. By using Maven as your build tool, you can create a build that gets triggered on every project change, and run all its unit and functional tests automatically.
The advantages of continuous integration are:
-
Early notification of issues in the software development lifecycle.
-
Ensures code gets fully tested before release.
-
Successfully tested branches ensure better success when merging to the master branch.
A continuous integration system:
-
Listens for new commits to a project’s source code management system. The CI watches many branches for new commits. You can use either polling to find new commits, or the management system can trigger events that inform your program of commits.
-
Pulls the newest branch into a centralized server.
-
Creates build jobs on a centralized server.
-
Runs configurable unit and integration tests on the code base to compile, test, package, and deploy the project in a sandbox to ensure the project works correctly.
-
Stores artifacts in a repository.
-
Displays the results of each build.
-
Deploys passing builds to production.
Prepare Applications for a CI/CD Server
-
Use a source code repository, such as GitHub or BitBucket.
-
Add the following configurations to each Maven pom.xml of each application:
-
Mule Maven plugin for CloudHub, ARM, and Standalone deployment.
-
Mule Maven plugin for MUnit.
-
-
If using a Jenkins pipeline, add the Jenkins files to the Mule project.