3scale toolbox

Description

3scale toolbox is a set of tools to help you manage your 3scale product. Using the 3scale API Ruby Client.

Table of contents

• Requirements
• Installation
• Usage
  • Copy service
  • Copy backend
  • Copy product
  • Export/Import product
  • Import from CSV
  • Import from OpenAPI definition
  • Export/Import Application Plan
  • Create, Apply, List, Show, Delete Application plan
  • Create, Apply, List, Delete Metric
  • Create, Apply, List, Delete Method
  • Create, Apply, List, Show, Delete Service
  • Create, Apply, List, Delete ActiveDocs
  • Show, Update, Deploy APIcast proxy settings
  • List, Show, Promote, Export Staging/Production Proxy Configuration
  • Copy Policy Registry
  • Create, Apply, List, Show, Delete, Suspend, Resume Applications
  • Export/Import Product Policy Chain
  • Remotes
• Development
  • Testing
  • Develop your own core command
  • Licenses
• Plugins
• Error Reporting
• Troubleshooting
• Contributing

Requirements

Supported Ruby interpreters

• MRI 3.0

Installation

Install the toolbox:

$ gem install 3scale_toolbox

The 3scale toolbox packaging repo provides packages and installation/deployment steps for the following platforms:

• CentOS/Fedora
• Ubuntu/Debian
• Mac OS X
• Windows
• Docker
• Kubernetes / Openshift

Usage

$ 3scale help
NAME
    3scale - 3scale toolbox

USAGE
    3scale <sub-command> [options]

DESCRIPTION
    3scale toolbox to manage your API from the terminal.

COMMANDS
    account              account super command
    activedocs           activedocs super command
    application          application super command
    application-plan     application-plan super command
    backend              backend super command
    copy                 copy super command
    help                 show help
    import               import super command
    method               method super command
    metric               metric super command
    policies             policies super command
    policy-registry      policy-registry super command
    product              product super command
    proxy                proxy super command
    proxy-config         proxy-config super command
    remote               remotes super command
    service              services super command

OPTIONS
    -c --config-file=<value>      3scale toolbox configuration file (default:
                                  $HOME/.3scalerc.yaml)
       --disable-keep-alive       Disable keep alive HTTP connection mode
    -h --help                     show help for this command
    -k --insecure                 Proceed and operate even for server
                                  connections otherwise considered insecure
    -v --version                  Prints the version of this command
       --verbose                  Verbose mode

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment. Run bundle exec 3scale to use the gem in this directory, ignoring other installed copies of this gem.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Testing

To run all tests run rake.

There are two kinds of tests:

• unit (see spec/unit)

rake spec:unit

• integration (see spec/integration).

rake spec:integration

Integration tests can be run locally or against a real 3scale account. When details of the account are set via environment variables, integration tests are run against the given account. Otherwise, tests are run locally with mocked 3scale clients.

The easiest way to set everything up is it to have a .env file in the root of the project with the following environment variables (set your own values):

ENDPOINT=https://your-domain-admin.3scaledomain
PROVIDER_KEY=abc123
VERIFY_SSL=true (by default true)

Develop Core Command

Very simple core command to list existing services. Helps to illustrate basic command code structure and helper methods to deal with remotes.

$ cat lib/3scale_toolbox/commands/service_list_command.rb
module ThreeScaleToolbox
  module Commands
    class ServiceListCommand < Cri::CommandRunner
      include ThreeScaleToolbox::Command

      def self.command
        Cri::Command.define do
          name        'service_list'
          usage       'service_list <3scale_remote>'
          summary     'service list'
          description 'list available services'
          param       :remote
          runner ServiceListCommand
        end
      end

      def run
        puts threescale_client(arguments[:remote]).list_services
      end
    end
  end
end

A few things worth highlighting:

• Your module must include the ThreeScaleToolbox::Command module. It allows your command to be added to the toobox command tree.
• You must implement the command module function and return an instance of Cri::Command from cri
• threescale_client helper method returns 3scale API client instance. All the process remote parsing, fetching from the remote list and client instantiation is done out of the box.

Then register the core command in lib/3scale_toolbox/commands.rb

--- a/lib/3scale_toolbox/commands.rb
+++ b/lib/3scale_toolbox/commands.rb
@@ -4,6 +4,7 @@ require '3scale_toolbox/commands/copy_command'
 require '3scale_toolbox/commands/import_command'
 require '3scale_toolbox/commands/remote_command'
+require '3scale_toolbox/commands/service_list_command'

 module ThreeScaleToolbox
   module Commands
@@ -12,7 +13,8 @@ module ThreeScaleToolbox
       ThreeScaleToolbox::Commands::CopyCommand,
       ThreeScaleToolbox::Commands::ImportCommand,
-      ThreeScaleToolbox::Commands::RemoteCommand::RemoteCommand
+      ThreeScaleToolbox::Commands::RemoteCommand::RemoteCommand,
+      ThreeScaleToolbox::Commands::ServiceListCommand
     ].freeze
   end
 end

Running the new core command:

$ 3scale service_list my-3scale-instance
{ ... }

Licenses

It is a requirement that we include a file describing all the licenses used in the product, so that users can examine it.

Run rake license_finder:check to check licenses when dependencies change.

Run rake license_finder:report > licenses.xml to update licenses file.

Plugins

As of 3scale Toolbox 0.5.0, 3scale Toolbox will load plugins installed in gems or $LOAD_PATH. Plugins are discovered via Gem::find_files then loaded. Install, uninstall and update plugins using tools like RubyGems and/or Bundler.

Make your own plugin

Troubleshooting

• SSL errors: If you run into SSL issues with the toolbox, you can take actions to resolve them.

Contributing

If you are interested in contributing to 3scale Toolbox, please refer to instructions available here