Managing Choreo Connect¶
WSO2 API Controller (apictl) can be used as a developer CLI tool for Choreo Connect. It enables interacting with one or more Choreo Connect environments without having to perform the following tasks via the WSO2 API Manager (WSO2 API-M).
- Deploy an API
- View the list of deployed APIs
- Undeploy an API
Info
Before you begin
-
Download the Choreo Connect distribution from the GitHub release page's and follow the Quick Start Guide attached with the release.
-
Make sure the apictl is downloaded and initialized, if not follow the steps in Download and Initialize the apictl. Following the guide upto Check the version of the apictl will be sufficient to continue.
-
Remember to add the cert of Choreo Connect into
/home/<your-pc-username>/.wso2apictl/certs
to communicate via https (to avoid having to use insecure mode with -k or --insecure). Click here for more information.
Add a Choreo Connect Environment¶
A Choreo Connect here refers to the entire cluster which includes all three components: adapter, router and enforcer. By adding a Choreo Connect environment, the URL to the adapter will be stored in a configuration file, and therefore enables login.
Once you have added a Choreo Connect environment, and logged in, other commands such as apictl mg deploy api
can be used by only specifying an environment. This allows you to use such commands without entering the Choreo Connect adapter URL, username, and password every time.
-
Command
apictl mg add env <environment-name> --adapter <adapter-url>
Info
Flags:
- Mandatory :
--adapter
or-a
: The Choreo Connect adapter host url with port
Example
apictl mg add env prod --adapter https://localhost:9443
- Mandatory :
Log in to a Choreo Connect Environment¶
Log in will get an access token from the Choreo Connect adapter and store it for further commands.
-
Command
apictl mg login <environment-name>
apictl mg login <environment-name> -u <username>
apictl mg login <environment-name> -u <username> -p <password>
Tip
If you run
apictl mg login <environment-name>
you are prompted to provide both the username and the password. If you runapictl mg login <environment-name> --username <username>
, you are prompted to provide the password. If you include the flag--password-stdin
, you can provide the password in a file as well. For an example,cat <file-with-the-password> | apictl mg login <environment-name> -u <username> --password-stdin
Info
Flags:
- Optional :
--username
or-u
: Username for login
--password
or-p
: Password for login
--password-stdin
: Get password from stdin
Example
apictl mg login dev
apictl mg login dev -u admin
apictl mg login dev -u admin -p admin
cat ~/.mypassword | apictl mg login dev -u admin --password-stdin
-
Response
Successfully logged into Choreo Connect Adapter in environment: <environment-name>
Successfully logged into Choreo Connect Adapter in environment: dev
Warning
Using
--password
in CTL is not secure. Instead, you can use--password-stdin
to include password file or provide the password when prompted. - Optional :
Deploy an API¶
In order to deploy, let us first create an API project. Follow the steps in Initialize an API Project to create an API project using apictl.
An API project can be deployed to a Choreo Connect using the following commands.
-
Command
apictl mg deploy api -e <environment-name> -f <api-project-file-path>
apictl mg deploy api ---environment <environment-name> --file <api-project-file-path>
Tip
In an API project, the API name and the API version given in the
api.yaml
will be taken as the name and version of the API once deployed.Tip
When trying to deploy, if an API with the same name, version, virtual host combination already exists in the Choreo Connect adapter, an error response will be given saying that the API already exists.
In order to override the existing API or deploy an API without considering whether it already exists or not, include the flag
--override
or its shorthand-o
to the same command above. For an example,apictl mg deploy api -e dev -f petstore -o
Info
Flags:
-
Mandatory :
-e
,--environment
: Choreo Connect adapter environment to add the API
-f
,--file
: Filepath of the apictl project to be deployed -
Optional :
-o
,--override
: Whether to deploy an API irrespective of its existence. Overrides when exists.
--skip-cleanup
: Whether to keep all temporary files created during the deploy process
Example
apictl mg deploy api -e dev -f petstore
apictl mg deploy api --environment dev --file petstore
apictl mg deploy api -e dev -f petstore --override
apictl mg deploy api -e dev -f petstore -o --skip-cleanup
-
-
Response
Successfully deployed API to Choreo Connect.
Unable to deploy API. API already exists. Status: Conflict 409
Successfully deployed/updated the API in Choreo Connect.
List Deployed APIs¶
This command can be used to list the deployed APIs on a given Choreo Connect adapter environment.
-
Command
!!! tip By default, the number of APIs listed will be limited to 25. To increase or decrease the limit set the flagapictl mg get apis -e <environment-name>
--limit
or its shorthand flag-l
. For an example,apictl mg get apis -e dev --limit 100
Tip
Currently, these APIs can be filtered by API type. The supported types are http and ws (web socket). Use the flag
--query
or its shorthand flag-q
to filter APIs.apictl mg get apis -e dev --query type:http
Info
Flags:
-
Mandatory :
-e
,--environment
: Choreo Connect adapter environment to list the APIs from -
Optional :
-l
,--limit
: Maximum number of APIs to return
-q
,--query
: Query to filter the APIs
Example
apictl mg get apis -e dev
apictl mg get apis -q type:http --environment dev --limit 100
apictl mg get apis -q type:ws -e dev -l 10
-
-
Response
Limit flag not set. Set to default: 25 APIs total: 2 received: 2 NAME VERSION TYPE CONTEXT GATEWAY_ENVS SwaggerPetstore 1.0.5 HTTP /v2 [Production and Sandbox] SwaggerPetstore1 1.0.5 WS /v2 [Production and Sandbox]
Undeploy an API¶
This command can be used to remove an API from the Choreo Connect.
-
Command
apictl mg undeploy api -e <environment-name> -n <api-name> -v <api-version>
apictl mg undeploy api -e <environment-name> -n <api-name> -v <api-version> --vhost <vhost>
Info
Flags:
-
Mandatory :
-e
,--environment
: Choreo Connect adapter environment to undeploy the API from
-n
,--name
: API name
-v
,--version
: API version -
Optional :
-t
,--vhost
: Virtual host the API belongs to
Example
apictl mg undeploy api -e dev -n petstore -v 0.0.1
apictl mg undeploy api --name SwaggerPetstore --version 0.0.1 -e dev
apictl mg undeploy api -n petstore -v 0.0.1 -e dev --vhost www.pets.com
- Response
API undeployed from Choreo Connect successfully!
-
Log out from a Choreo Connect Environment¶
This command can be used to logout from a Choreo Connect adapter environment. Once this command is executed, the access token of the Choreo Connect adapter will be erased from apictl.
-
Command
apictl mg logout <environment-name>
Example
apictl mg logout dev
- Response
Logged out from Choreo Connect Adapter in environment: <environment-name>
Logged out from Choreo Connect Adapter in environment: dev
Remove a Choreo Connect Environment¶
This command can be used to remove a Choreo Connect environment from apictl. Once this command is executed, it will delete the adapter URL and its access token first, and then remove the Choreo Connect environment from apictl.
-
Command
apictl remove env <environment-name>
Example
apictl remove env dev
-
Response
Successfully removed environment '<environment-name>'
Successfully removed environment 'dev'