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 config 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 

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 run apictl 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.

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

    apictl mg get apis -e <environment-name>
    !!! tip By default, the number of APIs listed will be limited to 25. To increase or decrease the limit set the flag --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'
Top