Migrating Common API Policies to Different Environments

ESB API Controller (apictl) allows you to maintain multiple environments running on the same MWARE ESB version. This allows you to import and export Common API Policies between your environments. For example, if you have a Common API Policy defined in the development environment, you can export it and import it to the production environment. Thereby, Common API Policies do not have to be created from scratch in different environments.

Info

Before you begin

  • Make sure apictl is initialized and setup, if not follow the steps in Download and Initialize the apictl.

  • Make sure to add an environment before you start working with the following apictl commands, because all API Products need to be imported or exported to/from a specific environment.
    For more information, visit Add an Environment.

Tip

A user with Internal/devops role or admin role are allowed to import/export Common API Policies. To create a custom user who can import/export Common API Policies, refer Steps to Create a Custom User who can Perform API Controller Operations.

Export a Common API Policy

  1. Log in to the MWARE ESB in the exporting environment by following steps in Login to an Environment.

    Tip

    If you are already logged-in and your logged-in credentials and keys are already available in the <USER_HOME>/.wso2apictl/keys.json file, you can skip this step.

    Info

    If you skip step 1 and if no keys exist for the environment in the <USER_HOME>/.wso2apictl/keys.json file, you will be prompt to log in to the environment when running the next command.

  2. Run any of the following apictl commands to export a Common API Policy as a .zip archive.

    • Command

      apictl export policy api -n <Common API Policy name> -e <environment>  
      apictl export policy api --name <Common API Policy name> --environment <environment>  
      apictl export policy api --name <Common API Policy name> --environment <environment> --format <Policy Definition file format>

      Info

      Flags:

      • Required :
        --name or -n : Name of the API Product to be exported --version or -v : Version of the common API Policy to be exported
        --environment or -e : Environment from which the API Product should be exported
      • Optional :
        --format : File format of exported policy definition file (JSON or YAML). The default value is YAML.

      Example

      apictl export policy api -n addHeader -e dev
      apictl export policy api -n addHeader -e dev --format JSON

    • Response

      Successfully exported API Policy!
Find the exported API Policies at /Users/benura/.wso2apictl/exported/policies/api/<Environment Name>/<Policy Name>_<Policy Version>.zip
      Successfully exported API Policy!
Find the exported API Policies at /Users/benura/.wso2apictl/exported/policies/api/dev/addHeader_v1.zip

The exported ZIP file has the following structure:

<Common API Policy-name>
├── <Common API Policy-name>.yaml
├── <Common API Policy-name>.j2
├── <Common API Policy-name>.gotmpl

The structure of an exported Common API Policy ZIP file is explained below:

Sub Directory/File Description
Policy-name.yaml Contains all the basic information required for a Common API Policy to be imported to another environment.
Policy-name.yaml Synapse gateway configurations which get applied during the runtime.
Policy-name.gotmpl Choreo Connect gateway configurations which get applied during the runtime.

Import a Common API Policy

You can use the common API Policy archive exported from the previous section (or you can extract it and use the extracted folder) and import it to the MWARE ESB instance in the target environment.

  1. Log in to the MWARE ESB in the importing environment by following steps in Login to an Environment.

    Tip

    If you are already logged-in and your logged-in credentials and keys are already available in the <USER_HOME>/.wso2apictl/keys.json file, you can skip this step.

    Info

    If you skip step 1 and if no keys exist for the environment in the <USER_HOME>/.wso2apictl/keys.json file, you will be prompt to log in to the environment when running the next command.

  2. Run any of the following apictl commands to import a common API Policy.

    • Command 

      apictl import policy api -f <path to Common API Policy directory> -e <environment> 
      apictl import policy api --file <path to Common API Policy directory> --environment <environment>
      apictl import policy api -f  <path to Common API Policy archived file> -e <environment> 
      apictl import policy api --file <path to Common API Policy archived file> --environment <environment>

      Info

      Flags:

      • Required :
        --file or -f : The file path of the common API Policy to import.
        --environment or -e : Environment to which the common API Policy should be imported.

      Example

      apictl import policy api -f ~/addHeader_v1.zip -e production 
      apictl import policy api --file ~/addHeader_v1.zip --environment production
      apictl import policy api -f ~/AddHeader -e production 
      apictl import policy api --file ~/AddHeader --environment production

      Tip

      If your file path is /Users/benura/.wso2apictl/exported/policies/api/dev/addHeader_v1.zip, then you need to enter dev/addHeader_v1.zip as the value for --file or -f flag.

    • Response

      Successfully Imported API Policy.
Top