CloudStack setup guide
Connect FluxBilling to Apache CloudStack: API keys, plugin settings, products, the IPv4 add-on, what customers can do, billing lifecycle and troubleshooting.
The CloudStack plugin connects FluxBilling to the API of your Apache CloudStack management server, so you can sell cloud servers from your CloudStack zones as FluxBilling products. FluxBilling takes the order, sends the invoice and collects the payment. When the invoice is paid, the plugin deploys the server in CloudStack, and the customer manages it from the FluxBilling client area. The plugin is free and is listed in the plugin marketplace of every FluxBilling panel. Your CloudStack installation stays as it is.
This guide covers plugin version 1.0.0. It walks through the setup in the order you do it, then explains what happens to a server over its life and what to check when something does not work.
Who supports this integration. The plugin is built and maintained by FluxBilling. If something does not work, contact FluxBilling support at contact@fluxbilling.app or through fluxbilling.app/contact. Questions about CloudStack itself, its zones or its hypervisors go to your CloudStack administrator or the Apache CloudStack community.
What you need before you start
- A working CloudStack cloud with at least one enabled zone. In FluxBilling, each zone is a location your customers can choose. The web console needs CloudStack 4.18 or newer. Setting the customer's own password on password-enabled templates needs 4.19 or newer; older versions generate a password instead.
- A compute offering (CloudStack calls it a service offering) for each plan you want to sell. It sets the CPU and RAM of the server.
- Templates that are ready in the zones you sell. Linux templates need cloud-init: the plugin uses it to set the hostname and root password and to allow root SSH login. Templates with CloudStack's password feature switched on get their password from CloudStack instead. See CloudStack's guide to password management in templates.
- A guest network in each zone the server can join. You can let CloudStack pick the zone's default network, or choose networks on the product.
- An API key and secret key for a CloudStack user that may deploy, stop, start, destroy and expunge virtual machines for the account that will own them (see step 1).
- Network access from your FluxBilling panel to the CloudStack API, usually the management server on port 8080 over plain HTTP, or your HTTPS address in front of it. A private address and a self-signed certificate are accepted.
Step 1: Create an API key pair in CloudStack
CloudStack identifies an API caller by its API key and checks a signature made with the secret key. The plugin signs every request with your secret key. The secret key itself is never sent.
- Log in to the CloudStack UI as an administrator.
- Open Accounts, open the account, then the user FluxBilling should act as. We recommend a separate user for FluxBilling, so you can replace its keys without touching anything else.
- Use Generate Keys on that user, then copy the API Key and Secret Key shown on the user's page.
CloudStack explains the key pair and how API access can be restricted in Roles, Accounts, Users, and Domains, and how signed requests work in the programmer's guide. If your cloud disables API key access for some users, accounts or domains, make sure it is allowed for this user.
Use a root administrator's key pair unless you know your role allows everything below. Two things need more than a normal user: deploying servers into another account (the Domain ID and Account settings), and expunging a server straight away when a service is terminated.
| Command | Used for |
|---|---|
listServiceOfferings, listZones, listTemplates, listNetworks, listDiskOfferings | Filling the lists in the product editor, on the order form and in the reinstall dialog |
deployVirtualMachine, queryAsyncJobResult | Creating the server and waiting for CloudStack's job to finish |
listVirtualMachines, listVolumes | Server details, power state and usage figures |
addIpToNic | Extra IPv4 addresses ordered as an add-on |
startVirtualMachine, stopVirtualMachine, rebootVirtualMachine | Power actions, suspension and unsuspension |
createConsoleEndpoint | The web console link |
restoreVirtualMachine, updateVirtualMachine, resetPasswordForVirtualMachine | Reinstalling and setting a new root password |
scaleVirtualMachine, changeServiceForVirtualMachine, resizeVolume | Plan changes |
destroyVirtualMachine, expungeVirtualMachine | Termination |
Step 2: Install the plugin
- In the FluxBilling admin panel, open Settings (the gear icon in the top bar).
- Under Integrations, open Marketplace. Stay on the Browse tab.
- Open the CloudStack Provider card and click Get for Free.
FluxBilling confirms with Plugin "CloudStack Provider" installed and ready to use. The plugin is switched on straight away and appears under Settings → Integrations → Plugins as CloudStack Provider, marked Active.
Step 3: Connect it to CloudStack
- Open Settings → Integrations → Plugins.
- On the CloudStack Provider card, click Configure.
- Fill in the fields below and click Save Configuration.
| Field | What to enter |
|---|---|
| API URL (required) | The full API address, ending in /client/api. For example https://cloud.example.com/client/api, or http://192.0.2.10:8080/client/api for the management server's own port. |
| API Key (required) | The API key from step 1. |
| Secret Key (required) | The secret key from step 1. It signs every request and is never sent. |
| Domain ID | Optional. The UUID of a CloudStack domain. Together with Account, new servers are created in that account instead of the API key's own account. |
| Account | Optional. The name of the account that owns the servers. Only used together with Domain ID. |
| Project ID | Optional. The UUID of a CloudStack project. New servers are created in that project instead of an account. |
| OS Image Filter | Which templates FluxBilling lists: All usable (executable), Featured, Own templates (self), Community or All (root admin). The same filter applies to the product editor, the order form and the reinstall dialog. |
| Keep destroyed machines | Off: terminating a service expunges the server and its volumes at once. On (Destroy without expunging): the server is destroyed but stays recoverable by a CloudStack administrator until the cloud's own expunge delay has passed. |

Leave Domain ID, Account and Project ID empty to create every server in the account of the API key's user. All servers sold through the plugin end up in that one place; customers do not get their own CloudStack logins.
The secret fields are stored encrypted. FluxBilling shows Configuration saved successfully when the settings are saved. The dialog has no connection test. The quickest check is step 5: when the Service Offering list in the product editor fills with your CloudStack offerings, FluxBilling can reach CloudStack and the key pair works.
Step 4: Create a category for your CloudStack products
In FluxBilling, the category decides how its products are delivered. Every product in the category is built by the plugin you choose here.
- Open Products, switch to the Categories tab and click Add Category.
- When FluxBilling asks What does this category sell?, choose Plugins. Do not choose VPS: that type is FluxBilling's own KVM module, not CloudStack.
- Enter a Name. The URL slug fills in by itself.
- Under How paid orders are fulfilled, click CloudStack Provider.
- Under Availability, choose Live to show the category on the order page, or Unlisted while you test.
- Click Create Category.

Step 5: Create a product for each plan
- On the Products tab, click Add Product and choose the category from step 4.
- On General, enter the product name and description your customers will see.
- On Configuration, fill in the CloudStack fields described below.
- On Pricing, set the price. Prices, billing cycles, taxes and add-ons all live in FluxBilling. Only the offering, zones, templates, networks and disks come from CloudStack.
- Click Create Product.
| Field | What it does |
|---|---|
| Service Offering (required) | The CloudStack compute offering every server sold with this product gets. It sets the CPU and RAM. The list shows each offering with its vCPUs and memory. |
| Zones Offered (required) | The zones customers can order in. The customer picks one at order; the first is used when they do not. |
| OS Images Offered (required) | The templates customers can choose at checkout. Linux templates need cloud-init; templates with CloudStack's password feature get their password from CloudStack. |
| Guest Networks | Optional. The networks to attach. Each list entry shows its zone; at deploy, only the networks in the chosen zone are used. Leave it empty to let CloudStack pick the zone's default network, which works in basic zones or where the account has a single shared network. |
| Root Disk Size (GB) | Optional. Grows the root disk to this size when the server is deployed. Leave it empty to keep the template's size. |
| Data Disk Offering | Optional. A CloudStack disk offering for an extra data disk. |
| Hostname Template | Optional. When set, FluxBilling generates the hostname and the customer is not asked for one. {{id}} is replaced by the service number, so vps-{{id}}.example.com becomes for example vps-1042.example.com. Leave it empty to let customers enter a hostname. |

If a customer's order names a zone or template the product does not offer, the plugin uses the first one in the product's list instead.
Step 6 (optional): Sell more IPv4 addresses
Each server gets the address CloudStack assigns on its default network. To let customers order more IPv4 addresses, up to four in total, create one add-on and attach it to your CloudStack products.
- Open Products, switch to the Options tab and click Add Option.
- Enter an Option Name such as IPv4 addresses.
- Under Slug, choose additional_ips — CloudStack Provider. This is the name the plugin reads. A different slug is not seen by the plugin.
- Leave Spec Service on None (billing only).
- Choose a Pricing Type, then switch on Configurable Options.
- Add one choice per address count. The Value is the total number of IPv4 addresses on the server, from 1 to 4 (
ipv4-2works as well as2). So1means the main address only and2means one extra address. Give each choice its label and price. - Click Create.
- Open each CloudStack product, go to Pricing and use Attach under Plugin expects these options, or select the add-on in the list.
- The extra addresses are added to the server's default network card in CloudStack as secondary IPs. CloudStack picks them from that network. The guest operating system does not configure them by itself: the customer adds them inside the server.
- Values above 4 are treated as 4, and values below 1 as 1.
- If CloudStack cannot add an extra address, for example because the network has none free, the server is still delivered with the addresses it did get. Check Additional IPs on the service page after the first orders with this add-on, and add a missing address in CloudStack.
The add-on takes effect when the server is built. The plugin does not add or remove addresses on an existing server, so customers cannot change the add-on after the build: the service page asks them to open a ticket. You can still change it from the admin panel. FluxBilling then bills the new choice and adds a pending task under Automations as a reminder; add or remove the addresses in CloudStack yourself.
Step 7: Place a test order
Place an order for each product before you sell it, for example from a test client account.
The customer chooses a Location and an Operating System, enters a Hostname (unless the product has a hostname template) and a Root Password. The root password must have at least 8 characters and at least three of: uppercase letter, lowercase letter, number, symbol. Hostnames may contain letters, numbers, hyphens and dots, and each part between the dots must start and end with a letter or number.
What happens when the invoice is paid
With Auto Provisioning switched on (see Billing lifecycle), FluxBilling starts the build as soon as the invoice is paid:
- Checks. The plugin reads the zone and template from the order and checks that the template exists in that zone. It matches the product's guest networks to the zone.
- Guest setup. For Linux templates it prepares cloud-init data that sets the hostname, sets the root password (unless the template uses CloudStack's password feature) and allows root SSH login with a password. Windows templates get no cloud-init data.
- The server. It asks CloudStack to deploy the server with the service offering, template, networks, root disk size and data disk, in the domain, account or project from the settings, and waits about a minute for CloudStack's job to finish. In CloudStack the server is named after the first part of the hostname plus a short part of the FluxBilling service ID, and its display name is the full hostname.
- Extra addresses. If the order includes the IPv4 add-on, it adds the extra addresses to the server's default network card.
- Hand-over. FluxBilling saves the CloudStack server ID, the main IP address and the login on the service and marks it Active. The login is
root(Administratorfor Windows templates) with the customer's root password, or the password CloudStack generated. With the default email templates, the customer gets an email that the server is ready.
If CloudStack takes longer than that, the build is reported as failed and retried. If the deploy job fails and leaves a broken server behind, the plugin removes it. If a build is retried, the plugin first looks for a server it already created for that service in the zone and reuses it, so a retry does not create a second server.
What your customers can do
In the client area, the customer opens the service and gets these controls.
| Control | What it does |
|---|---|
| Start, Stop, Restart | Power actions in CloudStack. Start shows while the server is stopped; Stop and Restart show while it runs and ask for confirmation. |
| Console | Opens a one-time link from CloudStack's console proxy in a new browser tab. Shown while the server runs. Needs CloudStack 4.18 or newer. |
| Reinstall | Erases the root disk and installs the chosen template with a new root password. |
| Reset Password | Sets a new root password on templates with CloudStack's password feature. A running server is restarted to apply it. |
| Server Information | IP address, hostname, operating system, location, status and any additional IP addresses, including IPv6 addresses CloudStack assigned. |
| Resource Usage | CPU, RAM, disk and network traffic as CloudStack reports them, refreshed every 30 seconds. When the hypervisor does not report the guest's free memory, RAM in use shows as 0. |
While a service is suspended, these controls, the server information and the usage figures are hidden, and the customer sees a Service Suspended notice with the reason.
Reinstall
The Reinstall Server? dialog warns that all data is erased, and asks for the Operating System and a New Root Password. The plugin stops the server, rebuilds the root disk from the template and starts it again. On cloud-init templates the new password, the hostname and root SSH login are set through fresh cloud-init data. On password-enabled templates CloudStack sets the password; clouds older than 4.19 generate one, and that one is stored on the service.
Reinstall offers every ready template in the server's zone that the OS Image Filter lets through, not only the ones you selected on the product. If you keep templates in that zone that customers should not install, restrict them in CloudStack or choose a narrower filter.
Reset Password
Reset Password works only on templates with CloudStack's password feature. The plugin stops a running server, sets the new password and starts it again. On other templates the customer sees This OS image cannot change its password in place — reinstall the server to set a new one.
What your staff see
In the admin panel, the service page shows the same server actions, the server information with an extra Cloud state badge (CloudStack's own state of the server, such as Running or Stopped), the resource usage, and an Access Credentials card with the IP address, the user name and the stored root password.
Billing lifecycle
The invoice drives the server. The rules are set under Settings → Billing → Automation:
- Auto Provisioning: deploys the server when the first invoice is paid. When it is off, the paid service waits as Pending until staff provision it.
- Auto Suspension with Suspension Grace: an invoice still unpaid that many days after its due date suspends the service. CloudStack has no suspended state, so the plugin shuts the server down, and forces it off if the guest does not stop. Its disks are kept.
- Paying the overdue invoice unsuspends the service: the server is started again.
- Auto Termination with Termination Grace: a service still suspended for non-payment that many days later is terminated.
Terminating a service destroys the server in CloudStack. With Keep destroyed machines off, it is expunged at once with its volumes and cannot be recovered. With it on, a CloudStack administrator can recover it until the cloud's expunge delay has passed. Termination happens when auto termination runs, when a customer's cancellation takes effect, or when staff terminate the service. A server that no longer exists in CloudStack counts as terminated.
Once an hour, FluxBilling also reads the main IP address, hostname and zone of each active CloudStack service, so a change made in CloudStack shows up on the service.
Plan changes
Customers can only move between products you link on the product's Upgrade Paths tab. When an upgrade or downgrade between two CloudStack products is paid, the plugin moves the server to the new product's service offering:
- First it tries a live change, which works when the offering and template allow dynamic scaling in CloudStack.
- If that is refused, it shuts the server down, changes the offering and starts the server again.
- If the new product sets a larger Root Disk Size (GB) than the server's root disk, the root disk is grown. Disks are never shrunk, so a downgrade keeps the larger disk.
If CloudStack refuses the change, the server is started again on its old offering, the upgrade is marked as failed and the service keeps its current product. Try an upgrade on a test server before you offer upgrades to customers.
Updating the plugin
Open Settings → Integrations → Marketplace, switch to Installed and click Check for Updates. When a new version is available, click Update to v…. Your settings and products are kept.
Troubleshooting
When a build fails, the service stays Pending. The error appears in the Automations menu in the top bar of the admin panel, with the reason and a retry button. FluxBilling tries a failed build again by itself, up to two more times over the next minutes. After that, open the service and click Retry Provisioning. A build started this way does not email the customer, so use Resend Welcome on the service page once it has worked.
Most errors are CloudStack's own error text, passed on as it is. These come from the plugin itself:
| Message or symptom | What to check |
|---|---|
| The Service Offering list in the product editor stays empty | FluxBilling cannot read from CloudStack. Check the API URL, both keys, that API key access is allowed for the user, and any firewall between FluxBilling and the management server. |
| The API endpoint did not answer with JSON (HTTP …) — check the API URL ends in /client/api | The address reaches a web server, but not the CloudStack API. Correct the API URL. |
| The product has no service offering selected (product › Provisioning) | Choose a Service Offering on the product's Configuration tab, then retry. |
| No zone: the product offers none and the order chose none or No OS image: the product offers none and the order chose none | Select at least one zone and one template on the product, then retry. |
| OS image … is not available in zone … | The template is not in the chosen zone, or the OS Image Filter hides it. Copy the template to that zone in CloudStack, or remove the zone or template from the product. |
| None of the networks chosen on the product exist in zone … | The product's guest networks are all in other zones. Add a network of that zone to the product, or leave Guest Networks empty. |
| The deployVirtualMachine job failed, or CloudStack's reason, such as insufficient capacity | CloudStack could not create the server. Check capacity, the offering and the network in that zone, then retry. |
| The web console needs cloud version 4.18 or newer | Your CloudStack version has no console links for API callers. Upgrade CloudStack to use the console. |
| The console proxy returned no link — is the server running? | Start the server, and check that the console proxy is running in that zone. |
| That OS image is not available in this server's zone | The template chosen for a reinstall is not in the server's zone. |
| Reinstall did not run: … | CloudStack refused the rebuild. The server is started again unchanged. |
| Password not changed: … | CloudStack refused the new password. The server is started again with its old password. |
| The plan change failed: … | CloudStack refused the new offering, live and while stopped. The server is started again on its old offering. |
| The plan changed but the root disk was not grown: … | The new offering is in place, but CloudStack refused to grow the root disk. Grow it in CloudStack. |
Limits
- Backups and snapshots are not offered through the plugin.
- Reset Password works only on templates with CloudStack's password feature. On cloud-init templates, the root password is changed by reinstalling.
- The IPv4 add-on is applied only when the server is built. Extra addresses are secondary IPs that the guest has to configure itself.
- IP addresses come from CloudStack's networks. FluxBilling's own IP address management is not involved.
- Hostname, root password and root SSH login are set by cloud-init on Linux templates only. Windows templates get no cloud-init data.
- All servers go to one place in CloudStack: the API key's account, or the domain account or project from the settings. Each FluxBilling panel connects to one CloudStack cloud.
- FluxBilling does not rely on callbacks from CloudStack: it waits for CloudStack's jobs itself. You do not need to set up anything for callbacks.
Apache, Apache CloudStack and CloudStack are trademarks of The Apache Software Foundation. FluxBilling is not affiliated with The Apache Software Foundation.
