Skip to content

Latest commit

 

History

History
 
 

kpm

README.adoc

KPM: the Kill Bill Package Manager

KPM Installation

Pre-built binaries (recommended)

kpm

On Linux and MacOS, you can use the pre-built binaries. KPM self-contained builds are available on Maven Central with coordinates org.kill-bill.billing.installer:kpm.

Download the .tar.gz package matching your architecture (Linux and MacOS only).

Note that this installation method assumes /bin/bash to be available on your system.

Through Rubygems

kpm

On Windows, you can install KPM via RubyGems.org. For this, you need to first install Ruby 2.x.x. We recommend installing Ruby 2.7.7.

Ruby can be installed via RubyInstaller. Once installed, you can run the following command to install KPM:

gem install kpm

Note: KPM is not tested with Ruby 3.x.x or later versions.

KPM Commands

Kill Bill installation

kpm install Using A kpm.yml File

KPM also lets you specify a configuration file, kpm.yml, to describe what should be installed. For example:

killbill:
  version: 0.20.12
  plugins:
    java:
      - name: analytics

This instructs kpm to:

  • Download Kill Bill version 0.20.12

  • Setup the Analytics (Java) plugin (you would still need to manually install the plugin DDL file)

To start the installation:

kpm install kpm.yml

Here is a more advanced example, specifying a custom Nexus repository and non-standard deployment directories:

killbill:
  version: 0.20.12
  nexus:
    ssl_verify: false
    url: http://nexus.acme
    repository: public-all
  plugins:
    java:
      - name: analytics
      - name: acme:custom
        artifact_id: custom-plugin
        version: 0.0.1-SNAPSHOT
  plugins_dir: /var/tmp/bundles
  webapp_path: /var/lib/tomcat/webapps/ROOT.war

Artifacts Downloads

You can download specific artifacts with the following commands:

  • kpm pull_kaui_war <version>: downloads the Kaui war

  • kpm pull_kb_server_war <version>: downloads the Kill Bill war

  • kpm install_java_plugin plugin-key <kb-version>: downloads a Java plugin identified by plugin-key

  • kpm install_ruby_plugin plugin-key <kb-version>: downloads a Ruby plugin identified by plugin-key

  • kpm pull_defaultbundles <kb-version>: downloads the default Kill Bill OSGI bundles

This is especially useful when scripting deployments.

Note: previous plugin versions aren’t cleaned up by default to facilitate rollbacks. If your deployment is stateful, unused, old plugin versions will slow the Kill Bill startup time. To cleanup these entries, use kpm cleanup which will delete all non-default plugin versions, or kpm uninstall.

kpm uninstall

kpm uninstall plugin-key will uninstall a plugin identified by plugin-key (all versions are uninstalled by default).

kpm migrations

kpm migrations is used to download database migration files when upgrading Kill Bill or plugins. See our database migrations guief for more details.

Operations

kpm inspect

The command kpm inspect can be used to see which plugins have been installed:

kpm inspect --destination=/var/tmp/bundles
_______________________________________________________________________________________________________________________________________________________
|          PLUGIN NAME |  PLUGIN KEY | TYPE |                          GROUP ID |        ARTIFACT ID | PACKAGING | VERSIONS sha1=[], def=(*), del=(x) |
_______________________________________________________________________________________________________________________________________________________
| killbill-cybersource | cybersource | ruby | org.kill-bill.billing.plugin.ruby | cybersource-plugin |    tar.gz |                 4.0.2[e0901f..](*) |
|                adyen |   dev:adyen | java |                               ??? |                ??? |       ??? |                      0.3.2[???](*) |
_______________________________________________________________________________________________________________________________________________________

Note: GROUP ID, ARTIFACT ID, PACKAGING and SHA1 can be missing (???) when installing plugins which aren’t hosted in a Nexus repository. This isn’t an issue.

kpm system

The command kpm system is a superset of the inspect command. In addition to plugins information, the command will return details about the Kill Bill and Kaui installation, Java and Ruby environment, details about the OS, CPU, Memory and disks, entropy available, etc.

Note: for non-standard deployments, you will need to tell KPM the location of the Kill Bill and Kaui webapp (see kpm help system).

kpm diagnostic

The command kpm diagnostic is a superset of the system command. It will connect to your Kill Bill instance to gather tenant configuration information and account data (if a specific account is specified) and will gather all log files.

You will need to instruct KPM how to connect to your Kill Bill instance (see kpm help diagnostic).

kpm account

kpm account exports all account data from a running system and re-imports it in another Kill Bill installation. This is an advanced command and is usually run as part of kpm agnostic.

kpm tenant_config

kpm tenant_config exports tenant specific data from a running system. This is an advanced command and is usually run as part of kpm agnostic.

kpm cleanup

kpm cleanup which will delete all non-default plugin versions. The --dry-run option can be used to double check first what would be deleted.

Plugins development

kpm info

kpm info lists the libraries to use when writing a plugin for a specific Kill Bill version. It also lists all of the official plugins for that specific version.

Installing Custom Plugins

If you are a developer and either modifying an existing plugin or creating a new plugin, KPM can be used to install the code of your plugin. Before going further, make sure you read the Plugin Development Documentation first.

Let’s assume now that you are modifying the code for the (Java) Adyen plugin. The plugin first needs to be built using the maven-bundle-plugin to produce the OSGI jar under the target directory. Then, this jar can be installed using KPM. We suggest you specify a plugin_key with a namespace dev: to make it clear this is not a released version:

kpm install_java_plugin 'dev:adyen' --from-source-file="<PATH_TO>/adyen-plugin-0.3.2-SNAPSHOT.jar" --version="0.3.2"

Internals

Test required setups

There are 3 suites of tests for KPM (see rake -T):

  • rake test:spec : Fast suite of unit tests

  • rake test:remote:spec : Test suite that relies on maven artifacts

  • rake test:mysql:spec : Test suite that requires an instance of Kill Bill server running and a properly setup database

KPM Unit test

Unit tests don’t require any third party system or configuration.

KPM remote test

Test suite that verifies the following:

  • KPM install command by pulling artifacts from maven repository

  • KPM migration command. This requires setting the TOKEN system property with a valid GITHUB api token.

KPM mysql test

Test suite that requires an instance of mysql running and verifies the following:

  • KPM account command: The account_spec.yml file needs to be modified with correct credentials and user must have correct privileges; also the database schema must not exist. In addition, one must start an instance of a Kill Bill server

Plugin Keys

Plugins are named using their pluginKey (the value for the name entry in the kpm.yml) . The pluginKey is the identifier for the plugin:

  • For plugins maintained by the Kill Bill team, this identifier matches the key in the file based repository of well-known plugins

  • For other plugins, this key is either specified when installing the plugin through api call, or default to the pluginName. For more information, please refer to the Plugin Development guide.

Caching

KPM relies on the kpm.yml file to know what to install, and as it installs the pieces, it keeps track of what was installed so that if it is invoked again, it does not download again the same binaries. The generic logic associated with that file is the following:

  1. When installing a binary (war, jar, tar.gz, …​), KPM will download both the binary and the sha1 from the server, compute the sha1 for the binary and compare the two (verify that binary indeed matches its remote sha1). Then, the binary is installed and sha1.yml file is updated. The sha1 entry in that sha1.yml file will now represent the local sha1 version (note that for tar.gz binaries which have been uncompressed, the local sha1 is not anymore easily recomputable).

  2. When attempting to download again the same binary, KPM will compare the value in the sha1.yml and the one on the remote server and if those match, it will not download the binary again.

There are some non standard scenario that could occur in case of users tampering with the data (or remove server unavailable):

  • Remote sha1 is not available: Binary will be downloaded again (and no sha1 check can be performed)

  • sha1.yml does not exist: Binary will be downloaded again

  • sha1 entry in the sha1.yml exists but has the special value SKIP : Binary will not be downloaded again

  • Binary does not exist on the file system (or has been replaced with something else): KPM will ignore. Note that correct way to remove plugins is to use the KPM uninstall command.

Notes:

  • You can override that behavior with the --force-download switch

  • When --force-download is specified (false by default), network access to a Nexus instance is required. Otherwise, downloads are idempotent even if no outbound networking is allowed (on initial download, the Nexus metadata is cached in the sha1.yml file which is re-used on subsequent installation if no outbound networking is allowed — by default, KPM will try to get the latest metadata from Nexus though)

GitHub Packages

Starting with version 0.9.0, experimental support for GitHub packages has been added:

kpm install_java_plugin acme:plugin \
        --overrides url:https://maven.pkg.github.com/acme/plugin token:<TOKEN> \
        --group-id com.acme \
        --artifact-id plugin \
        --version 0.0.1

Replace TOKEN with a GitHub personal access token.

Cloudsmith

Starting with version 0.10.0, experimental support for Cloudsmith has been added:

kpm pull_kb_server_war 0.22.21-SNAPSHOT \
        --overrides url:https://dl.cloudsmith.io/<TOKEN>/<ORG>/<REPO>/maven \
        --group-id org.kill-bill.billing \
        --artifact-id killbill-profiles-killbill

Replace TOKEN with a Cloudsmith entitlement token, and specify the right ORG and REPO.