Upgrade considerations on native Kubernetes
Review the supported versions, requirements, and limitations for upgrading API Connect on Kubernetes.
- Supported upgrade paths
- Ensuring compatibility with Drupal 10 for Developer Portal customizations
- Exporting analytics data before upgrading from a version prior to 10.0.5.0
- Validating an API definition file with the API Dev Tools Swagger Parser
- x-ibm-gateway-cors-allow-credentials-when-no-cors-policy API property is deprecated
Supported upgrade paths
|Upgrade from:||How to upgrade to 10.0.5.3|
||Complete the procedure in Upgrading subsystems on native Kubernetes in this 10.0.5 documentation..|
|Older versions of 10.0.x:
||Complete 2 upgrades:
|Older versions of 10.0.1.x:
||Complete 2 upgrades:
||Complete 3 upgrades:
|2018 FP20 and higher||Complete the procedure in Upgrading from 2018 on native Kubernetes in this documentation.|
Ensuring compatibility with Drupal 10 for Developer Portal customizations
Review the Guidelines on upgrading your Developer Portal from Drupal 9 to Drupal 10 to ensure that any customizations to the Developer Portal are compatible with Drupal 10.
In API Connect 10.0.5.3, the Developer Portal moved from Drupal 9 to Drupal 10 (this upgrade also requires PHP 8.1). The upgrade tooling will update your Developer Portal sites; however, if you have any custom modules or themes, it is your responsibility to ensure their compatibility with Drupal 10 and PHP 8.1 before starting the upgrade.
Exporting analytics data before upgrading from a version prior to 10.0.5.0
If upgrading from v10.0.4-ifix3, or upgrading from v10.0.1.7-eus (or higher): Upgrading to 10.0.5.x from an earlier version will result in the deletion of existing analytics data. If you want to retain your analytics data then you must export it before starting the upgrade. For instructions on exporting data, see Additional considerations for upgrading analytics from a version prior to 10.0.5.0
Validating an API definition file with the API Dev Tools Swagger Parser
From IBM API Connect Version 10.0.3.0 or later, SwaggerDoc (OpenAPI 2.0) and OpenAPI 3.0 documents that form API definition files are now validated at stage or publish time by the API Dev Tools Swagger Parser. Before upgrading, you should ensure that your existing API definition files can be parsed and are considered valid by the Swagger Parser tool. Note that any API definitions that are already staged or published are not impacted, but would undergo Swagger Parser validation again should they be re-staged or re-published in the future.
- Download and install the
swagger-parser-clitool (see https://www.npmjs.com/package/swagger-cli). This tool includes a
validatecommand that can validate local API definition files against the SwaggerDoc (OpenAPI 2.0) and OpenAPI 3.0 schemas, in both JSON and YAML formats.
- Use the browser-based Swagger Parser Validator available at https://apitools.dev/swagger-parser/online/; this accepts a URL to existing files available online, or can accept text copied and pasted into the tool, in both JSON and YAML formats. It can likewise validate against the SwaggerDoc (OpenAPI 2.0) and OpenAPI 3.0 schemas.
apic validatetoolkit CLI command.
paths, the following error is reported:
[object Object] is not a valid Swagger API definition
infosection is missing the required
versionproperty, the following error is reported:
Swagger schema validation failed. Missing required property: version at #/info JSON_OBJECT_VALIDATION_FAILED
$refproperties) that do not resolve to an existing reference within the document (known as de-referencing), this is also be flagged as an error. For example, if a document contains the following as a reference:
schema: $ref: '#/definitions/Pet'
#/definitions/Pet) must exist in the same document, at the given path (
definitionssection in this example), similar to the following:
If the local reference is not found within the document, the following de-referencing error is reported:
definitions: Pet: type: object required: - name properties: id: type: integer format: int64
Token "Pet" does not exist.
x-ibm-gateway-cors-allow-credentials-when-no-cors-policy API property is
In v2018, when cross-origin resource sharing (CORS) is enabled for an API, every response to a CORS request contains the header:
Inclusion of Access-Control-Allow-Credentials (ACAC) does not provide optimal security, so starting with v2018.4.1.17, an API property can be set to prevent this header from being returned:
Name: x-ibm-gateway-cors-allow-credentials-when-no-cors-policy Collection: * Value (string): off
Collection property refers to a specific Catalog to which a property value
applies. The "
*" value means the value applies to all catalogs. You can either
* or a Catalog (collection) name.
The property can also be set by using the DataPower CLI:
api-definition myAPI property x-ibm-gateway-cors-allow-credentials-when-no-cors-policy * off exit
Important: The value of this property must be exactly the string
(case-sensitive) in order to remove the header.
- Enabling CORS support for an API
- OpenAPI 3.0 editor: Setting API properties
- OpenAPI 2.0 editor: Setting API properties
In API Connect 10.0.3.0 or later, the
x-ibm-gateway-cors-allow-credentials-when-no-cors-policy property works, but only
for API definitions which do NOT contain a cors-policy. You cannot define both this property and a
CORS Policy on the same API definition.
This property is deprecated in v10: a warning will be written to the log for every CORS request received by an API whose definition contains this property.
For v10, the recommended way to ensure the ACAC header does not appear in CORS responses is to add a CORS policy to the API definition. In v10, any API definition which has a cors-policy defined will NOT return the ACAC header by default . Note that it is possible in the CORS policy rules to explicitly return the ACAC header for some or all origins.
If you move your configuration from Version 2018 to 10.0.3.0 or later, and have this custom property defined in your API definitions, you will not see any change in behavior, other than new warnings in the log. This property will remove the ACAC header for any API definition where it appears.
If, when you move your configuration from Version 2018 to Version 10, you want to have the ACAC header present in the CORS responses, you can leave the API definitions as-is (without the new property defined) and the ACAC header will be returned, as long as a cors-policy is not added to the API definition. Note also that even with a CORS policy defined for an API, the ACAC header can be returned if desired by explicitly allowing it in the rules of the CORS policy.
Note that the
in an API definition:
- Will cause a commit-time error in v10 if a cors-policy is also present in the same API definition
- Will NOT work in v10 or v2018 to turn ON the ACAC header; it can ONLY be used to turn OFF the
- In v2018, ACAC is on by default
- In v10, without cors-policy, ACAC is on by default
- In v10, with cors-policy, ACAC can be turned on for specific origins via rules in cors-policy
Upgrading to v10.0.5.3 (or later) from an earlier 10.05.x release.
Additional features related to inter-subsystem communication were added in v10.0.5.3. To enable and configure these features see: Optional post-upgrade steps for upgrade to 10.0.5.3 (or later) from earlier 10.0.5 release.