Introduction

Scenario

In this tutorial, we will look at how one could leverage the multi-tenancy feature from Kill Bill. The scenario we will describe, is one where we would like to provide 'Subscription As A Service' (SaaS) in the cloud (AWS). The tutorial will skip all the operational good practices such as redundancy of instances, firewalls, load balancers and focus instead on the Kill Bill specifics. Also, note that when deploying in the cloud where instances can come and go, the configuration of the bus and notifications queues need to be understood.

We will assume that we only need one plugin to make the payments, and as an example we will use the Stripe plugin.

Users and Roles

Let’s start by defining some users and roles:

The user setting up the Subscription As A Service in the cloud, is called superadmin, and will have all the privileges to configure the tenants and setup the roles associated with the other users.

The admin user associated to each tenant will be called admin_X where X is the name of the tenant.

Let’s take the case of a small yoga studio that wants to use our Subscription As A Service to provide subscriptions to its users: The name of the merchant is Shakti, and so we will create a user called admin_shakti for the tenant shakti.
The admin_shakti user will have full privileges for its Shakti tenant and will not see any of the other tenants.

Of course, for our own purpose of providing the service, we will also create a very first tenant to invoice our merchants (e.g the Shakti business). That tenant will be called saas ('Subscription As A Service'), and the associated admin user will be called admin_saas.

Also, for sake of simplicity, we will setup Kill Bill to use a static Shiro configuration file to configure the various admin users/roles. In real life, it would be more practical to rely on LDAP rather than static configuration, or use the Database configuration approach to avoid having to restart Kill Bill when creating new users/roles. The LDAP configuration is supported by Shiro but we will not describe the steps in that tutorial to keep it simple.

Kill Bill Multi-tenant Deployment

Overview of AWS Deployment Steps

In order to install Kill Bill on AWS you can use our docker images and rely on the aws from docker-machine. Alternatively you can setup things by hand, for instance by following the following steps.

The important piece is that=, the port 8080 should be publicly available for Kill Bill (in that simple setup with no firewall) and the port 3000 should be publicly available for KAUI.

Notes:

We are using the version VERSION for killbill and kaui below to avoid having to update the documentation each time we release. We do suggest you use the latest version as shown in the download page.

The deployment will consist in separate instances:

One instance for killbill, where we will deploy the docker image killbill/killbill:latest

One instance to configure the admin UI (KAUI) where we will deploy the deocker image killbill/kaui:latest

Finally RDS instance

For the Kill Bill Deployment, the killbill database schema will need to include:

Configuration Files

Since we want to realy on the static shiro.ini file, we need to make sure such a file exists and is available. Fortunately, there is config variable, KILLBILL_SHIRO_RESOURCE_PATH, that we can pass to our docker image, to take of that.

Starting the Kill Bill Instance

Again, here we will be reusing the same instances we configured in the http://killbill.io/tutorials/aws/ [aws tutorial], and start first pull and and then run the docker containers in these EC2 instances:

Finally, since we run the analytics plugin, we need to configure the analytics tables.
There is a script that can be run to configure the analytics tables with all the existing views and reports.
The script needs to be run from the analytics repo, and it will both hit some endpoints on the running instance of killbill and also create some views through mysql client.
If your RDS instance is not visible to the public world, you have two options

Clone the repo on the killbill ec2 zone and run the script from there (but that might require installing git, …​)

Clone the repo on your local machine and create a tunnel (this is the option we will highlight below):

Saas Setup

Creating the tenants and configuring allowed users

KAUI has been enhanced with new admin screens, that are described in the Multi-tenancy screens section of that documentation.

The first step is to login as superadmin to have the rights to create new tenants and configure all allowed users.

Starting on the /admin_tenants screen, click to Configure a New Tenant to create the 2 tenants saas and shakti; for e.g for shakti we would enter:

Name : shakti

API Key: some_key_fort_shakti

API Secret: some_secret_for_shakti

Click on the Create tenant to also create the tenant in Kill Bill.

At this point, the tenant exists in Kill Bill and is known from KAUI as well.

We can then configure the allowed users. KAUI needs to know who can access which tenant, and this information is kept in the KAUI database.
It really means that any user known from Kill Bill (shiro.ini) will be able to make API calls against any tenant provided the user specifies the correct tenant api_key and api_secret, so the security resides behind keeping those keys secret.
On the screen /admin_allowed_users, click on Add a new Allowed User; for e.g for the shakti administrator we would enter:

Name : admin_shakti # This has to match the shiro.ini configuration

Description : Admin user for tenant shakti

Then you will be prompted to select the tenant this users has access to. In our example of admin_shakti, we will select the available tenant shakti from the list that we previously configured.

Obviously for the user superadmin we would add the two tenants saas and shakti.

When all the users and tenants have been configured, you can try to logout, and login as a specific user (for e.g admin_shakti).
If the user has only access to one tenant, the process of login-in will directly assign that tenant and all subsequent operations will be made against that tenant.
If the user has more than one tenant, the user will be prompted to chose which tenant to use right after the login screen.

Configuring each tenant

Both Kill Bill and KAUI have been improved to now support uploading per tenant configuration:

The UI offers new screens to upload all these new configs

The plugins get notified when such config occurs so they can take action if needed

In multi-node scenario, there is a mechanism to make sure all nodes will be notified and refresh their view

The following per-tenant configuration can now be uploaded:

Per Tenant Versioned Catalog: Each new upload will create a new version of the catalog

Per Tenant Overdue Config: Each new upload will overwrite the previous version of the overdue.xml associated with this tenant

Per Tenant Invoice Template: Each new upload will overwrite the previous version of the invoice template associated with this tenant

Per Tenant Invoice Translation: Each new upload will overwrite the previous version of the invoice translation associated with this tenant

Per Tenant Catalog Translation: Each new upload will overwrite the previous version of the catalog translation associated with this tenant

Per Tenant Plugin Translation: Each new upload will overwrite the previous version of the config associated with this tenant and this specific plugin

Let’s do some basic configuration for the tenant 'shakti'. We will upload a catalog and then a specific configuration for the stripe plugin. You can login as superadmin or admin_shakti since both these users have the right to access that tenant. From the screen /admin_tenants/ chose the shakti tenant.

Then, let’s start with the stripe plugin: Create a valid config and then use the Plugin Config section of the page to specify the plugin name killbill-stripe and then upload the yml shown below: