4.15.07.00 - Apigee Edge for Private Cloud release notes

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

On Tuesday, September 8, 2015, we released a major Feature Release of Apigee Edge for Private Cloud.

Since the previous Edge for Private Cloud quarterly release (4.15.04.00), the following releases have occurred and are included in this quarterly release:

• Cloud: 15.04.15, 15.04.29, 15.05.27, 15.06.10, and 15.06.24
• Private Cloud: 4.15.04.01

Which Edge versions can you upgrade to 4.15.07.00

Depending on your current version of Edge, you can either:

• Directly upgrade to 4.15.07.00
• Incrementally upgrade, meaning you have to upgrade from your current version to another version of Edge, and then upgrade to 4.15.07.00.

For more information, see Which Edge for Private Cloud versions can you upgrade to 4.15.07.00.

Before upgrading from version 4.15.01.x or from a prior version

1. Check the Cassandra SSTable version:
   1. Change directory to /<install-root>/apigee4/data/cassandra/data.
   2. Run a find command,
      > find . -name *-ic-*
      The results should return a set of .db files if you are running Cassandra 1.2 SSTable.
   3. Run this find command:
      > find . -name *-hf-*
      The results should be empty, meaning no .db files are in the hf format. If you see no files in the hf format, then you are done and can upgrade to 4.15.07.00.
      
      The hf format is for Cassandra 1.0 SSTables. If you have any *.db files in the hf format, then you have to upgrade SSTable as described in the rest of this procedure.
2. If you find any *.db files in the hf format, then upgrade SSTable by running the following command on every Cassandra node until you have upgraded all Cassandra nodes:
   > /<install-root>/apigee4/share/apache-cassandra/bin/nodetool -h localhost upgradesstables -a
3. Repeat Step 1 to check that all the *.db files are in the ic format for Cassandra 1.2 version.
4. Repeat Steps 1 through 3 on every Cassandra node in your Edge installation.
5. Upgrade to Edge 4.15.07.00.
6. After the 4.15.07.00 upgrade, check the *.db files to make sure they have all been upgraded to the C* 2.0 style sstable:
   > cd /<install-root>/apigee4/data/cassandra/data
   > find . -name *-jb-*
   This command should return a set of .db files if you are running Cassandra 2.0.

New features and enhancements

Following are the new features and enhancements in this release.

Installation and upgrade

Selective component upgrade and uninstall

The apigee-upgrade.sh and apigee-uninstall.sh scripts now let you select the Edge components to upgrade or uninstall. Previously, it upgraded or uninstalled all components on the node. (OPDK-1377, OPDK-1175)

Upgrade rollback

If the apigee-upgrade.sh fails during an upgrade, you can now use the apigee-rollback.sh script to roll back the upgrade. After fixing any upgrade issues, you can retry the upgrade. (OPDK-1275)

Shortened installer script options

The install scripts no longer take the long form of options, such as --help. They now only take single letter options, such as -h. (OPDK-1356)

SmartDocs installation

When installing SmartDocs with the setup-smartdocs.sh script, you are prompted to enter the organization, environment, and virtual host, which ensures that SmartDocs is installed in the expected location. Previously, those values were hard-coded in the script. (OPDK-1310)

Running update-cass-pwd-in-config.sh without prompts

The update-cass-pwd-in-config.sh script can run without prompts if you set the ENABLE_CASS_AUTH, CASS_USERNAME, and CASS_PASSWORD environment variables. (OPDK-1309)

Edge Platform

Following are the new Edge platform features included in this release.

OpenJDK 1.7 supported by Edge Private Cloud

This release of Edge supports Oracle JDK 1.7 and OpenJDK 7, and removed support for JDK 1.6. (OPDK-1187)

OS support

Apigee Edge for Private Cloud has expanded its operating system support to include Red Hat Enterprise Linux 6.6 & 7.0 (64-bit), CentOS 6.5, 6.6, & 7.0 (64-bit), and Oracle Linux 6.5.

Cassandra 2.0.15 included in OPDK 15.07

This release installs Cassandra 2.0.15. If you are upgrading for a previous release, your version of Cassandra will be updated. (OPDK-1197)

SHA2 support for OAuth token hashing

To better protect OAuth tokens in the event of a database security breach, Edge supports SHA2 algorithms for hashing OAuth tokens (in addition to SHA1). With new orgainzation-level properties, you can enable and configure hashing for new tokens as well as retain legacy hashing on any tokens that existed prior to this new feature. Previously in Edge for Private Cloud, a property called hash.oauth.tokens.enabled in the keymanagement.properties file (on your management server and message processors) enabled automatic SHA1 hashing of OAuth tokens. This property is now deprecated.

If you previously used the hash.oauth.tokens.enabled property to enable SHA1 hashing, the upgrade script for this release automatically generates the new org-level properties for you. To verify after upgrade, do a GET as a system administrator with this API: https://{host}:{port}/v1/o/{your_org}.

• For information on enabling token hashing in your organization with the new properties, see "Hashing Tokens in the database" in the Requesting access tokens topic.
• For information on bulk hashing existing tokens, see the Edge for Private Cloud Operations Guide. (APIRT-1389)

Flat directory structure for log files

You can configure Edge to store log files in a flat directory structure by setting a new enable.flat.directory.structure property to true in the message-logging.properties file. For more information, see Message Logging policy. (APIRT-1394)

Environment cache performance

For better in-memory cache management and utilization, the "Maximum Elements in Memory" settings on environment cache resources has been deprecated. The total elements present across all cache resources (including the default cache) depends on the total memory allocated to the cache. By default, the total memory allocated for in-memory caching on a given message processor is 40% of the total memory available, determined by the cache property settings in your message processor cache.properties file. Elements will be evicted from in-memory cache only when there is insufficient cache memory or the elements expire.

To revert back to the old behavior of using the "Maximum Elements in Memory" property for cache management, set the property overrideMaxElementsInCacheResource=false in the cache.properties file. (APIRT-1140)

API Services

Following are the new API Services features included in this release.

New Proxy Editor as default

The new API proxy editor is enabled by default in the management UI. The new editor includes many usability improvements, including more comprehensive views of conditional flows and endpoints on the Overview page, all configuration on the Develop page, more intuitive adding of conditional flows, endpoints, and policies, more complete XML views rather than small snippets, search that crawls filenames and text, and more. (MGMT-2279)

New Delete OAuth v2.0 Info policy

A new "Delete OAuth v2.0 Info" policy lets you delete OAuth v2 access tokens and authorization codes. The policy replaces the functionality previously provided by the management API. For more information, see Delete OAuthV2 Info policy. (MGMT-2257)

New Delete OAuth v1.0 Info policy

A new "Delete OAuth v1.0 Info" policy lets you delete OAuth v1.0 request tokens, access tokens, and verifier codes. The policy replaces the functionality previously provided by the management API. For more information, see Delete OAuth V1 Info policy. (APIRT-1351)

Access Control policy

The Access Control policy has been enhanced to allow finer-grained evaluation of IP addresses for allowlisting and denylisting when IP addresses are contained in the X-FORWARDED-FOR HTTP header.

With multiple IP address checking enabled on the header (contact Support to set the feature.enableMultipleXForwardCheckForACL), a new <ValidateBasedOn> element in the policy lets you check against the first IP, the last IP, or all IPs in the header. For more information, see Access Control policy.

New entities in Access Entity policy

The Access Entity policy provides access to the following new entities: consumerkey-scopes, authorizationcode, requesttoken, and verifier. For more information, see Access Entity policy.

Statistics Collector policy: automatic conversion of statistics name to lowercase

When creating a custom analytics collection in the API proxy editor (Develop page > Tools > Custom Analytics Collection), the collector variable (statistic) "Name" must be lowercase. If you enter the name with uppercase letters, the tool automatically converts the Statistic name to lowercase in the Statistics Collector policy. (MGMT-740)

Removal of Classic Trace in API proxy editor

The newest version of Trace functionality in the API proxy editor has moved from beta to general availability. Access to "classic trace" with the "Access the classic version of trace" link is no longer available.

Apigee Community access from management UI Help menu

You can access the Apigee Community from the management UI Help menu.

Error Messages in the management UI

Following are error message enhancements in the management UI:

• The management UI used to group and display all error messages on the UI for the entire login session unless you dismissed them. With this update, the error messages are cleared automatically when you navigate away from the page on which they occurred. (MGMT-2254)
• The management UI no longer suppresses duplicate error messages. (MGMT-2242)

UI performance and error enhancements

General enhancements were made to different areas of the management UI, including page display performance and error message cleanup.

Role hyperlinks on Organization Users page in the management UI

On the Organization Users page in the management UI (Admin > Organization Users), role names are now hyperlinked, letting you quickly navigate to role pages. (MGMT-1055)

New target variables in message flow

New variables in message flows provide more complete URL information for target endpoints and target servers:

• TargetEndpoint: request.url replaces target.basepath.with.query.
• TargetServer: loadbalancing.targetserver replaces targetserver.name. Also, target.basepath is populated only when the <Path> element is used in the TargetEndpoint's HTTPTargetConnection <LoadBalancer> element.

Server Name Indication (SNI) support

Edge supports the use of Server Name Indication southbound (from message processor to target endpoints). If you want to use SNI, contact Apigee Support.

Java 1.7 is required.

With SNI, which is an extension of TLS/SSL, multiple HTTPS targets can be served off the same IP address and port without requiring all those targets to use the same certificate.

No Edge-specific configuration is required. If your environment is configured for southbound SNI (Edge cloud is by default), Edge supports it.

Edge automatically extracts the hostname from the request URL and adds it to the SSL handshake request. For example, if the target host is https://example.com/request/path, then Edge adds the server_name extension as shown below:

For more information on SNI, see http://en.wikipedia.org/wiki/Server_Name_Indication.

"Signature Algorithm" in the SSL Certificates details

A new "Signature Algorithm" field has been added to SSL certificate details, viewable in the management UI (Admin > SSL Certificates) and the management API (Get Cert Details from a Keystore or Truststore). The field shows either "sha1WithRSAEncryption" or "sha256WithRSAEncryption", depending on the type of hashing algorithm used to generate the certificate.

Showing SSL certificates that are near expiration

The SSL Certificates page in the management UI (Admin > SSL Certificates) indicates when SSL certificates are expiring within 10, 15, 30, or 90 days, depending on your selection in the new expiration drop-down field.

Threat protection error configuration

By default, Edge throws an HTTP 500 Internal Server Error status code and an ExecutionFailed error if a message doesn't make it past a JSON or XML Threat Protection policy. You can change that error behavior with a new organization-level property. When setting org property features.isPolicyHttpStatusEnabled to true, the following behavior occurs:

• Request: With a threat protection policy attached to any request flow, invalid messages return a 400 status code, along with a corresponding policy error message.
• Response: With a threat protection policy attached to any response flow, invalid messages still return a 500 status code, and one of the corresponding policy error messages is thrown (rather than just ExecutionFailed).

Cloud customers must contact Apigee Support to set the organization property. This feature will be available to Edge Private Cloud customers at the next Private Cloud quarterly release.

Updated schemas for endpoints, proxies, and other entities

Reference schemas have been updated for non-policy entities such as TargetEndpoint, ProxyEndpoint, APIProxy, and many others. See https://github.com/apigee/api-platform-samples/tree/master/schemas. (APIRT-1249)

Developer Services

Following are the Developer Services new features included in this release.

SmartDocs general availability

SmartDocs is graduating from beta to general availability. Updates and new features include:

• Support for Swagger 2.0, including import by file or URL, including support for custom-named security objects.
• Visual design improvements in the templates that generate SmartDocs.
• Usability and workflow enhancements in the Developer Portal, available through the Content > SmartDocs menu in Drupal.
• What has been known as "Custom Token" authentication is now called "API Key".
• Authentication "security" objects defined at the revision level.
• Configuration of client authentication at the template level. New revisions no longer reset any preconfigured SmartDocs client credentials.

For more feature descriptions, see this blog post.

For SmartDocs documentation, see Using SmartDocs to document APIs.

Developer app name displayed in the management UI

Developer apps in Edge have both an internal Name that doesn't change and a Display Name that you can change. On a Developer App page in the management UI (Publish > Developer Apps > app name), the app internal "Name" is displayed along with the "Display Name", making it easier to visually identify apps by their internal names for troubleshooting and API management.

Analytics Services

Following are the new Analytics Services features included in this release.

Preserved data time limit

When generating analytics reports with the management UI or API, data older than six months from the current date is not accessible by default. If you want to access data older than six months, contact Apigee Support.

Classic version of custom reports being removed from the management UI

The optional classic version of custom analytics reports is no longer available in the management UI.

Developer Engagement widget performance

The funnel widget on main analytics dashboard (Developer Engagement section) has been enhanced to provide better performance.

Monetization

Following are the new monetization features included in this release.

Rate plan email notifications

A new Rate Plan email notification type lets you notify developers when they reach a certain transaction or dollar limit in the volume-banded or bundle rate plans they've purchased. For details, see Set up notifications using notification templates.

Synchronization of Recurring Fee and Aggregation Basis periods

In a rate plan, there were potentially two different time periods in effect:

• Recurring Fee period, configured on the Fees tab of a rate plan, that determined when developers were charged a recurring fee.
• Aggregation Basis period, defined on the rate card for Volume Banded or Bundles plans, that determined when bundle use was reset for developers.

Those two periods are now synchronized. When both a non-zero recurring fee and a Volume Banded or Bundle rate card exist in a rate plan, the recurring fee period is used for both. For example, if a monthly recurring fee exists, then rate card bundles are also reset monthly (by default at the beginning of the month).

If no recurring fee exists, bundles are reset based on the Aggregation Basis defined on the rate card. For example, if a developer starts using a rate card on the 19th of the month, and the Aggregation Basis is every month, then the bundle use is reset a month after the 19th.

Aggregation Basis is being deprecated and will be removed from monetization in a future release. For more information, see Specify rate card plan details.

Custom Attributes in summary revenue reports

Transaction recording policies let you optionally capture custom attribute data from transactions, and you can now include those custom transaction attributes in summary revenue reports. By adding a MINT.SUMMARY_CUSTOM_ATTRIBUTES property to your organization, you can indicate which custom attributes are added to the database tables for use in reports.

Apigee Edge for Private Cloud customers can set the flag with the following API call and System Administrator credentials.

curl -u email:password -X PUT -H "Content-type:application/xml" http://host:8080/v1/o/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isMonetizationEnabled">true</Property>
        <Property name="MINT.SUMMARY_CUSTOM_ATTRIBUTES">[&quot;my_attribute_1&quot;,&quot;my_attribute_2&quot;]</Property>
        <Property name="features.topLevelDevelopersAreCompanies">false</Property>
    </Properties>
</Organization>"

Note that the array of custom attributes in the API call is URL-encoded.

SmartDocs upgrade process

If you've already been using SmartDocs during the beta period, new features and capabilities in the general availability version require that you upgrade SmartDocs in your developer portal.

Any SmartDocs pages that have already been published in your developer portal will continue to work, but you must follow the update process before editing or publishing any changes to existing or new pages.

Keep in mind that while you can render and publish SmartDocs inside your developer portal, SmartDocs are generated from the API model that lives within Apigee's Edge API Management Services. Any changes you make to an API model in Edge will be the same across all your Pantheon environments (similar to how developers exist across Pantheon environments).

To upgrade from SmartDocs beta to general availability

1. Update and test the 15.05.27 release in your dev or test environments on Pantheon.
2. Create a new model to replace any existing API model you have been using.
   • If you have been importing Swagger or WADL documents, import them again into a new revision.
   • If you have been maintaining your API model via the SmartDocs module, export as SmartDocs JSON and import into your new model using file attachment.
3. Set the security properties of the revision of your model. On the Content > SmartDocs > model page, select Security Settings.
   
4. Check any pre-configured authentication in the model settings page (Content > SmartDocs) by clicking Settings in the Operations column.
   
5. Update any custom templates to use v6 of the CSS and JS assets, and make changes to reflect any new object names, such as authSchemes and apiSchema. For information on updating SmartDocs templates, see Using SmartDocs to document APIs.
6. Re-render and publish your model revision.
7. After validating the new documentation, update your production portal to the 15.05.27 release.

If you are an Edge enterprise customer and have questions or concerns about the upgrade process, please email marsh@apigee.com and cnovak@apigee.com. Otherwise, please use the Apigee Community for the best response.

Future feature changes and enhancements

This section previews expected future feature changes and enhancements:

Change to Response Cache policy behavior

Coming in a future release (to be determined), the default behavior of the <ExcludeErrorResponse> element of the Response Cache policy will change.

Current behavior: The element <ExcludeErrorResponse> in the response cache policy is false by default. This means that, by default, responses with any possible HTTP status code (including 3xx) are cached by the Response Cache policy.

Future behavior: The element <ExcludeErrorResponse> in the Response Cache policy will default to true. This means that, by default, only responses with HTTP Status codes 200 to 205 will be cached. To override this behavior and to cache responses for all status codes, you will need to set the element <ExcludeErrorResponse> to true explicitly.

Current workaround: For Private Cloud 4.15.07.00 and older releases, if you want to cache responses only with the Status codes 200 to 205, you must explicitly set the element <ExcludeErrorResponse> to true.

Bugs fixed

The following bugs are fixed in this release.

Known issues

This release has the following known issues.

> source /{install-dir}/apigee4/bin/apigee-env.sh 

> VER=`basename $(find $SHARE_DIR/installer/monetization -name "mint-*.zip") | cut -d "-" -f 2,3,4` 

> sed -i "s/^MONETIZATION_VERSION=.*/MONETIZATION_VERSION=$VER/" /install-dir/apigee4/bin/apigee-env.sh 

> rm /install-dir/apigee4/share/monetization 

************************************** 
In order to complete the monetization upgrade please run: 
sudo /opt/apigee4/share/monetization/schema/migration/MOPDK4.15.04.00/
365-create-notification-condition.sh 
************************************** 

connect.ranges.denied=10.0.0.0/8,192.168.0.0/16,127.0.0.1/32

<install_dir>/apigge4/bin/apigee-service message-processor restart