Access Keys:
Skip to content (Access Key - 0)
Cancel    
Cancel   
 

Runtime Policy Management

Nov 12, 2013 19:06

Robin Pille

Aug 01, 2014 11:25

Mulesoft Current Mule Documentation

Runtime Policy Management

Mulesoft Documentation Page

Contents

Runtime Policy Management 

Deprecated Version

You've landed on a page for a deprecated version of the Anypoint Platform for APIs. If you are currently using this version, please migrate to the current version of the platform.

See Applying Runtime Policies for information relevant to the current platform.

API Manager offers runtime policies that can require or restrict specific behaviors within an application. You can apply policies to service versions or to specific endpoints to ensure that all service calls automatically comply with a policy. Service owners or administrators (organization owners) may apply policies to their services in API Manager at any time without interrupting consumers. API Manager applies special tags called characteristics to a service version to provide visibility about what policies are in effect.

 Contents

Creating a Policy from a Template

Follow the steps below to create a policy using one of the policy templates available in API Manager:

  1. Click the Policies icon along the top navigation bar.
  2. Click Add Policy in the upper right corner of the page.




  3. Select the policy template that you wish to use from the list of available templates, then click Next Step.

     What if the policy template I need isn't listed?

    If you want to create a policy that isn't covered by the templates listed here, scroll to the end of the list and click the "Suggest a New Policy" link. You can also contact MuleSoft professional services and ask for a custom policy template for your organization.

  4. On the Configure Policy screen, modify the policy Name to help users in your organization distinguish this policy from other policies which may be created from the same template.
  5. Enter Notes about your policy. API Manager displays the text you enter here next to the name of your policy in the policy list.

     

  6. Depending on which template you have selected, the template may require additional configuration. 
  7. When finished, click Finish

You have now created a policy and made it available to be applied to service versions or endpoints in your organization. To apply the policy and thus enforce it on service versions or endpoints, you must continue with the steps below.

 

Applying a Policy

To apply a policy to a service version or endpoint, you must be the service's owner or an administrator. (Learn more about account types and user roles.)

To apply the policy, navigate to the service's main screen, then complete the procedure below.

If you want to apply a policy to an entire service version:

  1. Click the version menu (the three horizontal lines in the far upper right corner of the screen).
  2. Select Manage policies.



  3. In the pop-up dialog, select the desired policy or policies to apply. Only policies that have previously been created via the Policies icon on the top navigation bar will be available in this drop-down list. For more information about any of the policies, click More Info... (Don't see the policy you need? Go ahead and create it yourself.)




  4. When finished, click Close
  5. The policy is now in effect. Upon screen refresh, the policy characteristic(s) contributed by your policy now appears in the Version Information panel. All users will be able to see the characteristic(s).

If you want to apply a policy to a specific endpoint:

  1. Click the Endpoints tab.
  2. Click the Manage policies icon next to the endpoint to which you want to apply a policy.



  3. In the pop-up dialog, select the desired policy or policies to apply. Only policies that have previously been created via the Policies icon on the top navigation bar will be available in this drop-down list. For more information about any of the policies, click More Info... (Don't see the policy you need? Go ahead and create it yourself.)
  4. When finished, click Close
  5. The policy is now in effect. Upon screen refresh, the policy characteristic(s) contributed by your policy now appears in the Version Information panel with an asterisk after the characteristic to indicate that it applies only to certain endpoints. All users will be able to see the characteristic(s). 

API Manager will prevent you from applying conflicting policies. If you have a throttling policy applied at the service version level, you will not be able to apply a throttling policy at the endpoint level as well, and vice versa.

 

Removing Policies

To remove a policy from a service version or endpoint, you must be the service's owner or an administrator.

  1. Navigate to the service's main screen.
  2. Open the Manage policies pop-up window for either service version or a specific endpoint:
    1. To open the window for a version, click the version menu (the three horizontal lines in the far upper right corner of the screen), then click Manage policies.
    2. To open the window for a specific endpoint, click the Manage policies icon next to that endpoint.
  3. Click Remove next to the policy you wish to unapply.

 

Deleting Policies

To delete a policy from API Manager, you must be that policy's creator or an administrator (organization owner).

Delete policies with caution! This action cannot be undone.

Policies currently applied to one or more service versions or endpoints have an  label. Note that deleting a policy that is in use will automatically unapply it from all service versions and endpoints to which it has been applied. If other policies are dependent upon the policy that you are deleting, those policies will also be removed from the affected service versions and endpoints.

To delete a policy:

  1. Click the Policies icon on the top navigation bar.
  2. Scroll to find the policy you wish to delete, then click the trash icon next to the policy you wish to remove from API Manager.

 

Best Practices

Applying Policies in API Manager vs Hardcoding

While you can always hardcode governance policies directly into your service, you now have the option of skipping the hardcoding and, instead, applying it via API Manager. In API Manager, you can apply or unapply policies as needed at runtime without requiring any retooling of the service or, in most cases, the consumers. If you hardcode your governance policies into your service, you must take the service offline, adjust the code, then redeploy it in order to make a change to the hardcoded policy. To avoid service interruption for hardcoded adjustments, use API Manager to apply policies to services.

Applying Policies to Services Already in Use

While many policies require no specific configuration of the service call, some policies require that a consumer's service call include specific information and/or be formatted in a particular way. If such a policy is applied after consumers are already using a service, the service owner should warn all consumers of the upcoming policy change before applying it. This warning gives consumer owners the time to reconfigure their service calls to meet the new specifications. Otherwise, consumers that do not meet the requirements of a new policy may have their service calls rejected.

Documentation

It's a good idea to document your policies as part of your service version documentation and keep this documentation up to date if policies change.

All other users, unless they are a service owner or an administrator, cannot view details about the policies you have applied to your service. Other users can only see what policy characteristics are applied to a service. (See details about characteristics in this summary table of policy templates). However, in the case of some policies, users will need additional information about how to satisfy the requirements of the policy. Thus, users will rely on the service description, release notes, and any supporting documentation for information about how to properly format a service call to comply with any runtime policies. 

Example

For example, the contract enforcement policy employs a contract key expression to validate contracts IDs passed via a message header. Any consumer application needs to pass their contract ID on a header keyed to the same property name as expected by the configuration of this policy. The default property name provided on the policy template is X-Anypoint-ContractKey. Whether you keep this default or customize it to a different property name when you create your contract enforcement policy, you should tell potential consumers of any services using this policy:

  1. what the property name is, and 
  2. that this property is expected by the inbound endpoints of your service. 

Provide this information clearly in your release notes or service description and update it if you make changes to the policies. 

For more information and an example of how to pass the contract key when using a dynamic lookup, see Service Lookup Endpoint Reference.

Furthermore, if a policy has been applied to some endpoints and not to others, the characteristic will have an asterisk after it to indicate this, but additional documentation is needed to tell users which endpoints have which policies applied. Include links to external documentation in the release notes for each service version or in the Description field in the main screen for your service. Or, upload your documentation as an artifact.



Go Further