Staging and Promotion

Asset Promotion

API Gateway assets are critical to keep a business running. In order to facilitate the migration of assets smoothly across different API Gateway instances and stages, API Gateway supports the movement of assets such as APIs, policies, applications, packages, plans, approval configurations on through staging and promotion, and export and import capabilities.

API Gateway supports staging and promotion of assets. In a typical enterprise-level, solutions are separated according to the different stages of Software Development Lifecycle (SDLC) such as development, quality assurance (QA), and production stages. As each organization builds APIs for easy consumption and monetization, continuous integration (CI) and continuous delivery (CD) is an integral part of the solution. CI is a development practice that requires developers to integrate code into a shared repository several times a day and CD is a software engineering approach in which teams produce software in short cycles, ensuring that the software can be reliably released at any time. Development of assets starts at the development stage and once the assets are developed, they are promoted to the QA stage for testing, after testing of the assets is complete, the assets are promoted to the deployment stage.

API Gateway provides tools and features to automate your CI and CD practices. Modifications made to the APIs, policies, and other assets can be efficiently delivered to the application developers with speed and agility. For example, When you publish new applications, the API definitions change. These changes are to be propagated to application developers. The API provider has to update the associated documentation for the API or application. In most cases this process is a tedious manual exercise. You can use API Gateway staging and promotion to address such cases to automate API and policy management that makes deployment faster, introduces continuous innovation with speed and agility. This ensures that new updates and capabilities are automatically, efficiently, and securely delivered to their developers and partners, in a timely fashion and without manual intervention.

API Gateway provides the staging and promotion feature to automate the CI and CD practices. Modifications made to the APIs, policies, and other assets can be efficiently delivered to the application developers with speed and agility.

Staging and promotion allows you to:

When you have three stages namely Dev, QA, and Prod, you can promote assets in the given sequence. That is, you can promote assets from stage 1 to stage 2, and from there to stage 3.

To promote assets from first stage, you create aliases of those assets that you want to promote to the second stage and promote them. Similarly, from the second stage you create aliases of assets that you want to promote to the third stage and promote them. The following illustration shows the flow:

Assets can have aliases that are associated to a target stage and aliases without a target stage. When you promote to a target stage, the aliases associated to the particular target stage are promoted to the target stage. If an asset has no alias that is created for the target stage, then aliases that are not associated are included in the promotion.

Stages

The fundamental phases of assets starts with requirements or needs at the development stage and once the assets are developed, they are promoted to the QA stage for testing, after testing of the assets is complete, the assets are promoted to the production stage.

An asset’s overall lifecycle can be split across two or more API Gateway instances. For example, assets that are in the development and test phases of their lifecycle can be maintained in one instance and assets that are deployed (that is, in production) can be maintained in a separate instance.

When the asset’s lifecycle is split across multiple API Gateway instances, each participating instance is referred to as a stage. A stage definition in API Gateway describes an API Gateway instance by its name and configuration information.

Note: Software AG recommends you to have API Gateway instances across stages to be completely independent. For example, the API Gateway instances from the Development stage and the API Gateway instances from the QA stage must not share any resources in common such as databases.

Promotions

Promotion refers to moving API Gateway assets from the source stage to one or more target stages. For example, you might want to promote assets you have developed on servers in a Development stage (the source API Gateway instance) to servers in a QA or Production stage (the target API Gateway instance). When you promote an asset from one stage to another, the asset’s metadata is copied from the source instance to the target instance. For the list of assets and configuration settings that can be promoted, see Assets that can be exported and imported.

Assets that are dependencies for the asset are also promoted. The required dependencies of an asset are always promoted with the asset. However, you can choose which optional dependencies are promoted at the time of promoting the asset. For example, at the time of promoting an API, the policies and aliases used by the API are always promoted. However, you can choose which dependent applications are promoted as applications an optional dependency for APIs. You can choose to promote all or no application, or select specific applications that you want to included with the API in the promotion.

The following table lists the required and optional dependencies of assets that are supported by promotion management.

Asset Dependencies (Required) Dependencies (Optional)
APIs Policies, Aliases Applications
Applications APIs
Packages APIs, Plans, Policies, Subscriptions
Plans Policies
Subscriptions Packages, Plans Applications
Teams Group
Approval configurations Access profiles
Configuration > Keystore Keystore, Truststore
Email destination Trust store
Service Registry Keystore, Truststore
Custom destinations Keystore, Truststore, Aliases

Note: Till API Gateway version 10.3, promotion management supported only the simple and endpoint types of aliases. Starting from API Gateway version 10.4, all types of aliases are supported.

Promoting Assets Using Promotion Management API

The promotion management capabilities allows for moving assets from lower to higher environments. For details, see Asset Promotion.

API Gatewayenables continuous integration (CI) and continuous delivery (CD) practices to be used for development, deployment, and promotion of the APIs, applications, other related assets, and for supporting the use of DevOps tooling. There are different ways in which API Gateway enables continuous integration (CI) and continuous delivery (CD).

The promotion management REST APIs allow for automation for CI/CD. For detail about the promotion management API, see Promotion Management.

DevOps Use Case using Promotion Management APIs

This example explains a sample DevOps use case using the promotion management APIs. You can promote API Gateway assets from one stage to the other using API Gateway specific scripts provided in GitHub. You can use the continuous integration tools like Jenkins and Azure to deploy user-created assets that reside on source API Gateway instance or repositories to a target API Gateway instance. For example, you might want to deploy assets you have developed on an API Gateway instance in a development environment (the source) to an API Gateway instance in a test or production environment (the target).

The high level steps to achieve this are as follows and are depicted in the illustration:

1.Create a stage-specific API Gateway environment.

2.Develop APIs.

3.Test the APIs.

Promoting Assets from API Gateway User Interface

Pre-requisites:

Promoting assets from one (source) stage to another (target) stage includes the following high-level steps:

  1. Authorization server promotion: Promote Authorization server in one of the following ways:

    • Export the authorization server from one environment and import it into another, if you want to use the same authorization server across multiple environments.

    • Create the authorization server with the same name as in the current environment, if you want to use a different authorization server instance.

    Proceed to the next step once the authorization server is ready.

  2. Select assets for promotion: During this step, you search for assets by using a keyword and by performing a type search that sorts and filters the results.

    • Search using a keyword: You can search for all assets whose string attributes (asset name, description, and so on) contain a certain keyword (character string).

    • Search using a Type: You can search for assets on the basis of types.
      You may use the Search by type filter to restrict the types on which the search is conducted. In the Search by type panel, API Gateway shows you a list of supported asset types.

    • Search by team: You can search for assets assigned to team(s). Click the team(s) to view the assets that are assigned to the selected team(s).

    • Search using two keywords: You can provide more than one keyword by separating the keywords using a pipe symbol (|). For example, to search for assets whose names contain pet and test, you can provide pet|test in the search field.

    • Search using wild card characters: You can use wild card characters in your search keyword. For example, to list all assets that start with graph, you can provide graph*.

  3. Optionally select assets’ dependencies for promotion: During this step, you specify whether the dependencies (for example, a list of applications that are registered for an API, subscriptions for a package, and so on) of the selected assets will be included for the promotion.

    Note: As groups and users are part of the team, if you want to promote the Groups and Users (optional dependencies) of the team that the selected asset belongs to, you have to set the enableTeamWork extended setting to true. Only then the Groups and Users sections appear.

  4. Select the stages to promote: During this step, you specify one or more target stages to which you want to promote the selected assets and their dependencies.

  5. Configure the promotion details: During this step, you provide the promotion-specific information.

  6. Ensure that you are promoting the assets from an lower version of API Gateway to a higher version of API Gateway. You cannot promote assets from a higher version to a lower version of API Gateway. For example, if you are using API Gateway v10.11, you can promote the assets from this version to v10,15 and other higher versions. You cannot promote assets back to the v10.7, v10.5, and so on.

To promote assets

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Select Promotions.
    The Search page appears.

  3. Click Promote.

  4. In the Search by keyword text box, type the keyword to search for assets. You can use one or more wildcards to specify the keywords.
    API Gateway returns the assets that match the specified keyword.

  5. In the Search by type drop-down list, select the required type(s). Select the All check box to search across all asset types.
    API Gateway returns the assets that match the selected type(s). The number of search results is displayed in the results area, for example, Showing 10 results. If no results are found, the results area is displays a blank page.

  6. Optional. Select the Include admin configurations check box if you want to include administrative configurations in the promotion.
    API Gateway displays the administrative configurations that are supported for promotion. For the list of assets and configuration settings that can be promoted, see Promotions.

    Important: Before you configure API Gateway to promote an administrative configuration, make sure that the corresponding administrative settings are already configured in API Gateway. For example, to include the Load balancer configuration in the asset promotion set, the required Load balancer URLs should be configured.

  7. Select the assets and the administrative configurations that you want to promote.

  8. Click Next.
    The Assets and dependencies page appears.

  9. Select the referenced assets that you want to promote.

  10. Click Next.
    The Stages page appears.

  11. Select the target stages to that you want to promote the assets, dependencies, and administrative configurations.

  12. Click Next.
    The Promote page appears.

  13. Provide the following information:

    Field Description
    Name Mandatory. Name of the promotion.
    Description Description of the promotion.
    Overwrites assets except alias that already exist on the selected target stages If you set this field to True, all the assets except for aliases are overwritten.
    Overwrites aliases that already exist on the selected target stages. If you set this field to True, even the aliases are overwritten.
    Fix missing version Select the check box to fix the API version history. The discrepancy between the asset versions in the source and target stages, if any, are fixed.
    For example, consider that you have created an API and have five versions of the API from 1 to 5, in the source. If you select versions 1,2,4, and, 5 for promotion to the target, and if this check box is not selected, versions 1 and 2 are linked separately and versions 4 and 5 are linked separately. However, if you select this check box, version 2 is linked to version 4 and hence all versions 1,2,4, and 5 are now linked in the target.

    Note: The Overwrite assets if exists on selected stages option allows you to overwrite assets that exist on the target stages. If you do not want to overwrite assets in the target stages, clear this check box.

  14. Click Promote.
    The selected assets, dependencies, and administrative configurations are promoted to the selected stages.

    The Stage-specific promotion status page displays the status of the asset promotion in each of the selected stages. The available values are:

    • Success

    • Failure

    The page also displays the reason if the promotion fails.

Viewing Promotion List and Promotion Details

The Promotions tab displays a list of the available asset promotions in API Gateway. The asset promotions are listed alphabetically by name.

In addition, you can examine the details of an asset promotion history, repromote assets to the configured stages, and delete the promotion history from API Gateway database in the Promotions tab.

To view the promotion list and promotion details

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Select Promotions.
    The Promotions tab displays a list of available asset promotions. This tab provides the following information about each promotion:

    Column Description
    Name Name of the promotion.
    Description Description of the promotion.
    Promoted by Name of the user who initiated the asset promotion.
    Promotion time The time at which the asset promotion occurred.
    Status The status report on the asset promotion.
  3. Examine the Report link in the Status column and check for any errors that occurred during the asset promotion.
    The Promotion status report displays the following information:

    Column Description
    Asset type Name of the asset type that was promoted from the source instance.
    Name Name of the asset that was promoted from the source instance.
    Status The status of the asset promotion.
    Comments A descriptive comment on the asset promotion status.
  4. Click the required promotion whose details you want to examine.
    The Promote page appears.

Repromoting Assets

Pre-requisites:

You must have the Manage promotions functional privilege assigned to perform this task.

If you have made recent changes to an asset’s information, you can repromote the updated asset to the already promoted target stages.

If you need to update an asset, for example, you need to correct an attribute setting, modify the asset’s description, that has already been promoted to a target stage, you can simply make the change directly to the asset in the source target and then repromote the updated asset to the target stage just as you did with the previous version of the asset. In a multi-stage environment, you will need to repromote the updated assets in each of the participating API Gateway instances.

To repromote assets

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Select Promotions.
    The Promotions tab displays a list of available promotion histories in API Gateway.

  3. Click the Repromote icon for the required assets’ promotion history.
    The Stages page appears.

  4. Select the target stages to that you want to repromote the assets, dependencies, and administrative configurations.

  5. Click Next.
    The Promote page appears.

  6. Provide the following information:

    Field Description
    Name Mandatory. Name of the promotion.
    Description Description of the promotion.

    Note: The Overwrite assets if exists on selected stages option allows you to overwrite assets that exist on the target stages. If you do not want to overwrite assets in the target stages, clear this check box.

  7. Click Promote.
    The selected assets, dependencies, and administrative configurations are repromoted to the selected stages. The Stage-specific promotion status page displays the status of the asset repromotion in each of the selected stages. The available values are:

    • Success

    • Failure

    The page also displays the reason if the repromotion fails.

Adding a Stage

Pre-requisites:

You must have the Manage promotions functional privilege assigned to perform this task.

API Gateway can contain one or more stages. You define a stage to represent the asset’s lifecycle such as development, test, and production.

To add a stage

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Click Add Stage.

  3. Provide the following information in the Basic information section:

    Field Description
    Name Mandatory. Name of the stage.
    Note: A stage name must be unique within API Gateway.
    Description Description of the stage.
  4. Provide the following information in the Technical information section:

    Field Description
    Stage URL Mandatory. The URL of the host machine where the stage is deployed on an API Gateway installation.
    The Stage URL value is specified in the format, <scheme>://<host>:<port>. The scheme is http or https. The host is the host name of the machine on which the target API Gateway instance is running. The port is the port number of the target API Gateway instance.
    Username Mandatory. The username of a registered API Gateway user who has the Manage promotions or Manage assets functional privilege in the target API Gateway instance.
    Password Mandatory. A valid password of the API Gateway user identified by the attribute Username.
    Keystore alias The alias of the keystore containing the private key that is used for performing asset promotion from one (source) stage to another (target) stage.
    The Keystore alias field contains a list of the available keystore aliases in API Gateway. If there are no configured keystore aliases, this field lists the default Integration Server keystore, DEFAULT\_IS\_KEYSTORE.
    Note: This field is required when the Stage URL scheme is set to https
    Key alias (signing) The alias of the private key that is stored in the keystore specified by the keystore alias.
    The Key alias field contains a list of the available aliases in the selected keystore. If there are no configured keystores, this field is empty.
    Note: This field is required when the Stage URL scheme is set to https
  5. Click Save.

    The stage gets created and is displayed in the stages list on the Promotion Management > Stages screen. You can click Test to test the configuration before saving the details for creating a stage.

The stages tab displays a list of available stages in API Gateway. In addition to viewing the list of stages, you can also examine, modify the basic or the technical information of a stage at any time and delete a stage in the stages tab to remove it from API Gateway permanently.

Manage Rollbacks

Rollback is the process of restoring the asset’s metadata in the target API Gateway instance to a previous state.

You might need to rollback assets to revert any promotional data changes being made in the target API Gateway instance.

Rollback Asset Promotions

Pre-requisites:

You must have the Manage promotions functional privilege assigned to perform this task.

You can rollback an asset promotion that is already available in the target stage at any time.

To rollback asset promotion

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Select Rollbacks.
    The Rollbacks tab displays a list of available promotion histories.

  3. Click the Rollback icon for the promotion history that you want to rollback.

  4. Click Yes in the confirmation dialog.

Viewing Rollback List and Rollback Details

The Rollbacks tab displays a list of the available asset promotion rollbacks in API Gateway. The rollbacks are listed alphabetically by name.

In addition, you can also examine the details of a rollback, and delete the rollback history in the Rollbacks tab.

To view the rollback list and rollback details

  1. Expand the menu options icon icon, in the title bar, and select Promotion management.

  2. Select Rollbacks.
    The Rollbacks tab displays a list of available asset promotion rollbacks.

    This tab provides the following information about each rollback:

    Column Description
    Name Name of the rollback.
    Promotion time The time at which the asset was promoted.
    Rollback time The time at which the asset promotion was rolled back.
    Status The status report on the rollback operation.
  3. Examine the Report link in the Status column and check for any errors that occurred during the rollback process.
    The Promotion status report displays the following information:

    Column Description
    Asset Type Name of the asset type that was promoted from the source instance.
    Asset Name Name of the asset that was promoted from the source instance.

Exporting and Importing Assets and Configurations

API Gateway supports the import and export of the assets that you create or configure in API Gateway. You can import archives of APIs, global policies, and other related assets that you have exported and re-create them in API Gateway. This enables you to easily export and archive the assets; and when required, import them to a different instance of API Gateway or redeploy them on the same instance.

Each artifact in an archive is associated with a universally unique identifier (UUID) that is unique across all API Gateway installations. When importing an archive, the UUID helps in determining whether the corresponding artifact is already available in API Gateway. You can configure whether you want to overwrite the existing artifact or keep the available artifact during the import process.

Note:

Note: Do not attempt to modify and import an archive file because import of modified archive files is not supported.You can export archives from an earlier version to a later version of API Gateway. However, you can not import from a later version to an earlier version. For example, you can not import an 10.5 asset into a 10.3 API Gateway.
You can also export and import assets using the API Gateway REST APIs. For more information, see API Gateway Archive.

When you export an asset, the dependent assets are also exported. If any of the exported assets contain secure strings, the user credential information (passwords) associated with the assets is also exported. When you import this exported asset, API Gateway enforces conditions to check the order of import and the dependency evaluation between assets, and the dependent assets along with the user credential data are imported. For example, if you import an API, API Gateway checks and ensures that all associated policies and aliases are imported along with any passwords, if present, before importing the API.

The Overwrite option available for all the assets allows you to decide whether the asset should be imported if an existing version of the asset already exists in the target instance. In scenarios where you select to overwrite the asset in the target instance, API Gateway also checks for any associated passwords and applies the overwrite accordingly. There is no separate overwrite option for the passwords during import. The password uses the overwrite option of the asset it is associated with. For example, if you are importing an alias with a password, the overwrite option provided for the alias is applied for the password as well. If set to true, the password is overwritten if it is already exists in the system.

Functional Privileges

The Export or Import assets and Purge and Archive events category on the Access profile details page has the available import and export privileges. You must assign the following functional privileges for the required permissions:

Accessing the Export and Import commands in the API Gateway user interface

The export command is either a button with the label Export, or the icon icon. You can export multiple items within lists, such as APIs in the API page, by using the export command in the list menu.

You can import assets using the user menu (icon) > Import command.

Assets that can be exported and imported

Path to Page/Tab Assets that can be exported and imported
APIs APIs
Policies > Threat protection Global denial of service
Denial of service by IP
Rules
Mobile device and apps
Alert settings
Policies > Global policies Global policies
Policies > Policy templates Policy templates
Applications Applications
Packages > Packages Packages
Packages > Plans Plans
User menu () > Administration > General
  • Extended settings
  • API fault
  • Approval configuration
  • URL Aliases
  • Custom content-types
  • Callback processor settings
User menu () > Administration > Security
  • Keystore/Truststore
  • SAML issuer
  • Custom assertions
  • Kerberos
  • JWT/OAuth/OpenID
  • Providers
User menu () > Administration > Destinations
  • API Gateway
  • API Portal (only the Event configurations are exported)
  • Elasticsearch (properties on both tabs—Elasticsearch communication and Events—are exported)
  • Email (properties on both tabs—Email configuration and Templates—are exported)
User menu () > Administration > Service registries
  • Service registry
User menu () > Administration > Aliases
  • Aliases

Dependencies

Some API Gateway assets use other assets. For example, APIs uses policies, aliases, and other assets. As the configuration of an asset is incomplete without the assets it uses, the export features includes the assets that are used by the asset that you export.

The following table shows the asset dependencies of each type of asset:

Asset Dependencies (Required) Dependencies (Optional)
APIs Policies, Aliases Applications, Application registrations
Applications APIs, Application registrations
Packages APIs, Plans, Policies, Subscriptions
Plans Policies
Subscriptions Packages, Plans Applications
Teams Group
Approval configurations Access profiles
Configuration > Keystore Keystore, Truststore
Email destination Trust store
Service Registry Keystore, Truststore
Custom destinations Keystore, Truststore, Aliases

Importing Asset and Configuration Archives

Importing an exported archive enables you to import the required assets to a different instance of API Gateway or redeploy them on the same instance. For information about the import/export process, see Exporting and Importing Assets and Configurations.

To import the exported files

  1. Expand the menu options icon icon, in the title bar, and select Import.

  2. Provide the following information:

    Parameter Description
    Select archive file Click Browse to select a file or ZIP format file.
    Overwrite Select an overwrite option:
    • None: If you do not want to overwrite matching objects that exist on the server. Import will fail for the object in the archive if a matching object/asset already exists on the server.
    • All: If you want to overwrite any matching asset that exists on the server. If a match is not found, then a new asset is created.
    • Custom: If you want to select the specific types of assets that will be overwritten on the server if a match is found. If a matching asset exists on the server for an asset type that is not selected in the Custom overwrite list, the import operation fails.

    If a duplicate asset is found for any asset type that is not selected in the Custom overwrite list, the import fails.

    Note: Some types of assets have dependencies on other asset types. For example, APIs have a dependency on policies, aliases, and applications. Some of the dependencies are required, while others are optional. The required dependencies are always included in the archive when you export the asset. You should consider your requirements and select the assets that need to be overwritten in the Custom list.
    API version history Select this option Fix missing versions to fix the API version history.
    On selecting this option, the APi versions are newly linked according to the system version of the APIs.

    Note: API Gateway supports backward compatibility for API Gateway 10.1 version or higher when importing the archives of APIs. In addition, the compatibility of archives across API Gateway fix levels is also maintained. For example, you can import the archives created from lower fix levels of API Gateway into higher fix levels.
    The import of an archive created from a higher fix level of API Gateway into a lower fix level can be rejected if the higher fix level’s configurations are not supported by the lower fix level.

  3. Click Import.
    The Import report displays the following information:

    Parameter Description
    Type The asset type.
    Successful The number of successful imports for each artifact type.
    Unsuccessful The number of unsuccessful imports for each artifact type.
    Replaced The number of instances replaced for each artifact type.
    Warning The number of warnings displayed during the import of each artifact type. API Gateway displays warning messages when the import is successful but some additional information is required.
  4. Click Download the detail report here > to download the detail report.
    The detail report displays the following information about the imported artifact:

    Parameter Description
    Name The name of the artifact imported.
    Type The artifact type.
    Status The status of the imported artifact. The available values are:
    • Success
    • Replaced
    • Warning
    • Failure
    Explanation The reason if the import fails or if a warning occurs.

If you want to take a backup of an API that you want to overwrite during import, you can set the parameter enableImportBackup as true under Administration > General > Extended Settings section. For more information about this extended setting, see Configuring Extended Settings.

If an API import fails, one of the reasons might be that a configuration that is required by the API is not set up correctly on API Gateway. If something happens unexpectedly while the import is in progress, API Gateway discontinues the import and restores the existing API. This is necessary as parts of the existing API such as policies may already have been overwritten.