Release Notes for Red Hat 3scale API Management 2.11 On-premises

Red Hat 3scale API Management 2.11

Document intended for use with Red Hat 3scale API Management 2.11

Red Hat Customer Content Services


This document informs users about the latest and Technology Preview features, as well as resolved issues, associated documentation, and known issues in Red Hat 3scale API Management 2.11


This document is intended for use with Red Hat 3scale API Management 2.11 and related patch releases.

Chapter 1. Red Hat 3scale API Management 2.11.1 - Patch release

This document is intended for use with Red Hat 3scale API Management 2.11.1 On-premises.

1.1. New features

Red Hat 3scale API Management 2.11.1 provides the following new features:

  • Support for Red Hat 3scale API Management on IBM Power Systems. For more details, see Support for IBM Power Systems.
  • APIcast operator handling proxy environment variables through the Custom Resource Definition (Jira 7573).
  • Support for the addition of external Lua dependencies for custom policies (Jira 7488).
  • Enhancements to the Admin Portal interface:

    • Display, selection, and configuration of application plans (Jira 6868)
    • Listing products and backends (Jira 7646)

1.2. Support for IBM Power Systems

These are the supported features for IBM Power Systems:

  • 3scale deployment from operatorHub
  • All Universal Base Images (UBI) 7 and UBI 8 images
  • Self-managed APIcast operators on OpenShift Container Platform (OCP) v4.9
  • Self-managed APIcast on OCP for APIcast v3.11
  • Toolbox images
  • Red Hat Single Sign-On (RH SSO) 7.4

These features are not supported for IBM Power Systems:

  • Self-managed APIcast on Docker on top of RHEL 7 and RHEL 8
  • MSQL 5.7 external
  • PostgreSQL 10.x external
  • RH SSO 7.5
  • Redis HA
  • S3 API compatible file storage - Minio
  • Deployment in disconnected (air-gapped) OCP environment

1.3. Resolved issues

Red Hat 3scale API Management 2.11.1 resolves the following issues:

  • The sign-up form in the Developer Portal is disabled for users authenticated via external Single Sign-On (Jira 7633).
  • Wrong format when retrieving policies_config information through the Account Management API (Jira 7605).
  • Operator pod cannot connect to an external 3scale environment through a proxy (Jira 7761).
  • Issues preventing metrics monitoring directly from 3scale and APIcast operators (Jira 7644 and Jira 7731).

1.4. Known issues

  • Oracle Client Libraries integration for ppc64le requires a workaround (Jira 7953).

1.5. Documentation

Supported configurations

Upgrade guides

Part I. Red Hat 3scale API Management 2.11

This document is intended for use with Red Hat 3scale API Management 2.11 On-premises.

Chapter 2. Compatibility between 3scale and OpenShift Container Platform

3scale 2.11 contains updates that enable it to work with OpenShift Container Platform (OCP) 4.9. If you plan to upgrade to OCP 4.9, you must upgrade 3scale to version 2.11 before you upgrade OCP to version 4.9. Earlier versions of 3scale do not support OCP 4.9. See Migrating 3scale.

If you are using OCP 4.9, you can install and run only version 2.11 of 3scale.

Chapter 3. New features

Red Hat 3scale API Management 2.11 provides the following new features:

  • 3scale toolbox command line interface (CLI) commands that:

  • API providers who are using Braintree can now toggle 3DS on or off (Jira 6860). See Configuring Braintree as a credit card gateway.
  • Support for Redis 6 as an external database (Jira 6492).
  • The length of time that a user can be logged in to 3scale (session length) is now configurable (Jira 693 and Jira 7143).
  • Field definitions can now be set by means of the 3scale API (Jira 4082).
  • API gateway policies:

  • Ability to set the Maintenance Mode Policy (downtime) depending on the subpath, backend, or another condition (Jira 6552).
  • Option to accept/reject request if a policy is not executed in the policy chain (Jira 6705).
  • Configurable Access-Control-Max-Age header in CORS policy (Jira 6556). See CORS Request Handling.
  • APIcast configuration enhancements:

    • Ability to configure proxy_cache_convert_head to determine whether HEAD requests are converted to GET requests before requests are sent upstream (Jira 7016).
    • Ability to configure the APICAST_LOG_LEVEL environment variable on the 3scale operator (Jira 6452).
    • APIcast environment variables are now exposed by custom resource definition (CRD) fields for the APIcast operator (Jira 5496).
    • TLS is now enabled at the pod level with the APIcast operator (Jira 5499).
    • Allow injection of custom policies into the APIcast operator (Jira 7031).
    • Allow injection of custom environment into the APIcast operator (Jira 7033).
    • Ability to configure extended metrics in the APIcast operator (Jira 7272).
  • New option to disable the deployment of Prometheus rules (Jira 7137).
  • Improved 3scale deployment status reporting (Jira 4753).
  • Backend extension that lists application keys in response XML (Jira 7207).
  • Ability to configure Jaeger and OpenTracing environment variables through the 3scale operator (Jira 7267).
  • 3scale customer experience enhancements

    • Improved display of application plans in the application plans index page (Jira 6875).
    • Improved user interface (UI) for selecting the default application plan (Jira 6868).
    • Renewed UI for creating applications (Jira 6876, Jira 6878, Jira 6879).
    • Improved list of backends in the product overview page (Jira 6866).
    • Improved list of products in the backend overview page (Jira 6877).
    • Improved UI for creating backend mapping rules (Jira 6873).

Chapter 4. Technology Preview features


Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see

Red Hat 3scale API Management 2.11 provides the 3scale operator for application capabilities as a Technology Preview feature. The 3scale operator enables the use of custom resources (CRs) to define 3scale tenants, APIs, application plans, limits, metrics and other objects for use in a 3scale installation (Jira 3486). See Using the 3scale operator to configure and provision 3scale.

3scale operator application capabilities added in 3scale 2.11:

  • Reconciliation of product CRs when a backend metric is deleted (Jira 5534).
  • Custom resource definition for managing 3scale developer accounts (Jira 6501).
  • Custom resource definition for managing 3scale developers who are associated with a developer account (Jira 6611).
  • Management of 3scale ActiveDocs by using an ActiveDoc CR (Jira 6584).
  • Management of custom policy definitions by using a CustomPolicyDefinition CR (Jira 6585).
  • Management of OpenAPI documents by using an OpenAPI CR (Jira 4712).
  • Product CRs can now specify OpenID Connect authentication (Jira 5537). See Defining product authentication using OpenID Connect.
  • Product CRs can now specify custom gateway responses and error messages (Jira 5536).
  • Product CRs now support management of the policy chain (Jira 6235).

FULLY SUPPORTED in 3scale 2.11.1: Another Technology Preview feature is the ability to add external dependencies and use them in custom policies (Jira 7488).

Chapter 5. Resolved issues

Red Hat 3scale API Management 2.11 resolves the following issues:

  • Braintree errors are not surfaced in the 3scale Developer Portal (Jira 4963).
  • Fix deprecated Github SSO integration for the developer portal (Jira 4441).
  • System Grafana Dashboards heatmap negative values (Jira 6403).
  • Search does not work for newly created services and backends until these items are indexed the next day (Jira 6205).
  • Changes in product settings cannot be promoted to staging (Jira 6468).
  • Pagination of products and backends shows all pages even when filtering (Jira 6385).
  • Backend API metric not synced to backend as part of the backend_rewrite_storage task (Jira 6491).
  • Not possible to set APIcast pod timezone using the APIcast operator(Jira 6476).
  • APIManager deployment via operator fails when using SealedSecrets (Jira 6635).
  • APIcast not striping standard ports for HTTP/HTTPS requests (Jira 2235).
  • APIcast production pod is failing when deployed using template (Jira 5913).
  • APIcast reports a release candidate version of OpenResty (Jira 6963).
  • Internal error for certain calls in IP Check Policy (Jira 7076).
  • TLS Termination Policy screen displays wrong form given selected options (Jira 6390).
  • Wrong Content-Length header when using payload limits policy (Jira 6736).
  • Importing OpenAPI fails on toolbox container image (Jira 6574).
  • When copying a product from the toolbox CLI, the copied methods lose their description (Jira 6764).
  • Toolbox fails when reimporting an OpenAPI spec (Jira 6906).
  • Toolbox is unable to copy products with more than 500 backends (Jira 5224).
  • Avoid creating stats keys containing the "0" (zero) value (Jira 6652).
  • Fix infrequent exception raised in the backend component (Jira 6783).
  • Empty flash error message showing in the new Account form (Jira 6633).
  • Suppress warn messages on APIcast startup (Jira 5816).
  • Operator backup does not work if pre-existing persistent volume is used (Jira 5677).
  • HEAD requests converted to GET requests (Jira 7023).
  • Fix error message for users logging into the Admin Portal (Jira 6321).
  • Upstream cannot be null error in APIcast logs (Jira 5225).
  • APIcast logs unnecessary warn messages on start up (Jira 5816).
  • APIcast takes a long time to start up when using APICAST_SERVICES_FILTER_BY_URL (Jira 6139).
  • APIcast logs the private API URL instead of the public URL (Jira 6193).
  • Liquid Context Debug policy is not working with APIaaP (Jira 6312).
  • JWT Claim Check Policy does not work with APIaaP backend (Jira 6410).
  • Add APIaaP Routing policy just before APIcast policy (Jira 6428).
  • APIcast is removing the If-Match and If-None-Match headers from requests (Jira 6704).
  • Importing an OAS Spec using the 3scale toolbox fails when only staging-public-base-url is set (Jira 6884).
  • first_traffic and first_daily_traffic events are not updated (Jira 7227).
  • Upstream Mutual TLS (mTLS) between APIcast and the backend API fails when more than a single certificate is used (Jira 7363).
  • APIManager deployed with the operator is not picking up the latest images available (Jira 7435).

Chapter 6. Known issues

Known issues in Red Hat 3scale API Management 2.11:

  • 3scale monitoring with Prometheus and Grafana performs inaccurately when showing values (Jira 6446).
  • Sphinx searches return all records if you search by the name of the class (Jira 6405).
  • The NGINX Filters policy has no effect if you also add the Content Caching policy. The default behavior is that content caching is disabled. If you enable content caching, NGINX returns a 412 response code when it cannot validate a request header even if you specified that header when you added the NGINX Filters policy (Jira 7514).
  • Usernames in 3scale must be 40 characters or fewer. When a username has more than 40 characters, 3scale usually truncates it. Consider this when you do any of the following:

    • Create a developer account.
    • Create a provider account as the master.
    • Add a user to a provider account as the provider or as the master.
    • Add a user to a developer account in the Developer Portal or in the Admin Portal.

    Usernames must be 40 characters or fewer when using Red Hat Single Sign-On to authenticate access to the Admin Portal or Developer Portal.

Chapter 7. Documentation

Supported configurations

Security updates

Upgrade guides

  • Check the procedures to upgrade your 3scale installation from 2.10 to 2.11, for the following deployments:

Chapter 8. Changes in 3scale

This section lists current and future 3scale changes.

8.1. Changed features

  • Internal Redis databases have been upgraded from version 3.2 to version 5.x.

8.2. Deprecated features

  • Support for an APIcast deployment running as a container in RHEL7 and Docker is deprecated. In future releases, 3scale will support only RHEL8. If you are running APIcast self-managed as a container, move to RHEL8 and Podman.

8.3. Removed features

  • Redis 3.2 is no longer supported.

8.4. Future changes

  • When you use Proxy Update, it creates a new APIcast configuration version for the staging environment with the updated settings. It is expected that this will not be the case in future releases. Customers will need to use the new Proxy Config Promote endpoint for this purpose.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Legal Notice

Copyright © 2021 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.