Migrating Apps to Different Environments¶
WSO2 API Controller, apictl allows you to maintain multiple environments running on the same WSO2 API-M version. This feature allows you to import and export applications between your environments. For example, if you have an application running in the development environment, you can import it and export it to the production environment. Thereby, applications do not have to be created from scratch in different environments.
Info
Before you begin
-
Make sure WSO2 API CTL Tool is initialized and running, if not follow the instructions in Download and Initialize the CTL Tool.
-
Make sure to add an environment before you start working with the following CTL commands, because all applications need to be imported or exported to/from a specific environment.
For more information, see Add an Environment.
Tip
- Only the following types of users are allowed to export and import applications.
- A user with the
admin
role. - A user with a role having
apim:app_import_export
Admin REST API scope withAPI Subscribe
permission.
- A user with the
- Refer Creating Custom Users to Perform API Controller Operations for more information.
Manage the application lifecycle¶
The lifecycle of an application could be defined as the stages of an application between the development and production environments. The feature facilitates to manage the application life cycle by allowing the user to migrate the applications within desired environments. The user should have admin permissions in order to use this.
Export an application¶
You can export an application in the Developer Portal and download it as a zipped file.
-
Log in to the API Manager in exporting the environment by following the instructions in Login to an Environment.
Tip
If you are already logged-in and your logged-in credentials and the 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. -
Run any of the following CTL commands to export an existing application as a
.zip
archive.-
Command
apictl export-app -n <application-name> -o <owner> -e <environment> -k
apictl export-app --name <application-name> --owner <owner> --environment <environment> --insecure
apictl export-app --name <application-name> --owner <owner> --environment <environment> --withKeys=<with-keys> --insecure
Info
Flags:
- Required :
--name
or-n
: Name of the application to be exported
--owner
or-o
: Owner of the application to be exported
--environment
or-e
: Environment to which the application should be exported - Optional :
--withKeys
: Export keys for the application
Example
apictl export-app -n SampleApp -o admin -e dev -k
apictl export-app --name SampleApp --owner SampleUser --environment dev -k
apictl export-app --name SampleApp --owner SampleUser --environment dev --withKeys=true -k
- Required :
-
Response
Successfully exported Application! Find the exported Application at /Users/kim/.wso2apictl/exported/apps/dev/admin_SampleApp.zip
-
The exported application zipped file will be as follows:
<exported-Application>.zip
└── <Application-Name>.json
Import an application¶
You can import an application to your environment as a zipped application. When you import an application as a zipped file, a new application is created within the target environment.
-
Log in to the API Manager in exporting the environment by following the instructions in Login to an Environment.
Tip
If you are already logged-in and your logged-in credentials and the keys already are 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. -
Run any of the following CTL commands to import an existing application as a
.zip
archive.-
Command
apictl import-app -f <file> -e <environment> -k
apictl import-app --file <file> --environment <environment> -k
apictl import-app -f <file> -e <environment> -s=<skip-subscriptions> -o <owner> --skipKeys=<skip-keys> -k
apictl import-app --file <file> --environment <environment> --skipSubscriptions=<skip-subscriptions> --skipKeys=<skip-keys> --preserveOwner=<preserve-owner> --update=<update> --insecure
Info
Flags:
- Required :
--file
or-f
: The file path of the exported application.
--environment
or-e
: Environment to which the application should be imported. - Optional :
--owner
or-o
: Name of the target owner of the application as desired by the importer
--preserveOwner
: Preserves application owner. Defaultfalse
.
--skipSubscriptions
or-s
: Skip subscriptions of the application. Defaultfalse
.
--skipKeys
: Skip importing keys of application Defaultfalse
.
--update
: Update application or create new. Defaultfalse
.
Example
apictl import-app -f dev/admin_SampleApp.zip -e production
apictl import-app --file dev/admin_SampleApp.zip --environment production
apictl import-app -f dev/admin_SampleApp.zip -e production -o admin --skipSubscriptions=true --skipKeys=true
apictl import-app -f dev/admin_SampleApp.zip -e production --preserveOwner=true
apictl import-app -f dev/admin_SampleApp.zip -e production --update=true
Tip
If your file path is
/Users/kim/.wso2apictl/exported/apps/dev/admin_SampleApp.zip.
, then you need to enterdev/admin_SampleApp.zip
as the value for--file
flag. - Required :
-
Response
ZipFilePath: /Users/kim/.wso2apictl/exported/apps/dev/admin_SampleApp.zip Completed importing the Application 'dev/admin_SampleApp.zip' Succesfully imported Application!
Note
Skipping subscriptions/keys while importing application
You can opt to skip importing the subscriptions of the application by defining--skipSubscriptions
or-s
flag. This parameter is set tofalse
by default.
You can opt to skip importing the keys (client credentials of the OAuth App) of the application by defining--skipKeys
. This parameter is set tofalse
by default.
Changing/Preserving Owner while Importing Application
The owner of the imported application can be specified by providing a username of a valid user based on your preference. The application importer can set the preferred owner’s username as the value of the--owner
or-o
flag.
You can also import the application by preserving the application owner’s information, from the previous environment. The application importer can add the--preserveOwner
flag in order to define that this flag is set to true. This parameter is set to false by default. Therefore, the default value is used when you do not define this flag. If you import the application without specifying any of the optional flags, you will be added as the owner of the application in the imported environment.
If both the--owner
and the--preserveOwner
flags are set, then the--owner
flag gets higher priority over the--preserveOwner
flag. -
Import applications in a single-tenant environment¶
There are three options to import applications in a single-tenant environment.
-
Application A in environment 1 is migrated to environment 2. Some APIs may not be available in environment 2 (API B in this case) and the relevant subscriptions are not added in such cases (skipped).
-
A different owner can be specified while importing an application to environment 2, without preserving the original user of environment 1.
- The original owner of the application can be preserved when the application is imported to environment 2 by adding the
--preserveOwner
flag.
Import applications in a multi-tenant environment¶
In a situation where an application has API subscriptions in different tenant domains, such subscriptions are added if the relevant APIs with the target tier, are available in the importing environment. Note that the provider of the API may not be the same in the importing environment.
Top