Skip to content

API and CLI Updated 2026-05-27

CLI scaling — changetopology

Use the changetopology CLI method on the Stack Harbor PaaS to script vertical and horizontal scaling of an existing environment.

When you need to change the topology of an existing environment from a script — scale a layer up or down, resize a particular container — the Stack Harbor PaaS CLI exposes the changetopology method. It takes the same payload as createenvironment, except --envName now points to an environment that already exists.

The call

~/jelastic/environment/control/changetopology \
  --envName {env_name} \
  --env '{"engine" : "{engine_type}"}' \
  --nodes '[{"nodeType" : "{node_type}", "count" : {nodes_amount}, "fixedCloudlets" : {cloudlets_amount}, "flexibleCloudlets" : {cloudlets_amount}}, {"nodeType" : "{node_type}", "count" : {nodes_amount}, "fixedCloudlets" : {cloudlets_amount}, "flexibleCloudlets" : {cloudlets_amount}}]'

The set of options matches createenvironment, with one repurposed flag:

  • {env_name} — the existing environment to reshape.
  • {engine_type} — the engine the environment’s instances run on. Required string.
  • {node_type} — the stack identifier for the layer being adjusted (tomcat, mysql, nginx, etc.).
  • {nodes_amount} — target node count for that layer. This is how you drive horizontal scaling.
  • fixedCloudlets / flexibleCloudlets — reserved and dynamic cloudlets for that layer. This is how you drive vertical scaling.

Two axes in one call

Because count and the cloudlet fields are in the same nodes payload, a single changetopology invocation can move along both axes at once — for example, doubling a database layer’s node count and bumping the per-node memory limit. Pass one object per layer you want to change.

Things to know before running it

  • Load balancer required for horizontally scaled application servers. If you’re growing an application-server layer from one node to several, make sure a balancer is already in the topology before the call. If there isn’t one, the platform will add NGINX for you, but it is cleaner to express what you want explicitly.
  • The call is not instantaneous. Reconfiguration can take several minutes depending on the change — stateful scale-out clones the master container, vertical resize may restart the layer.
  • Idempotency. Repeating the call with the same target counts and cloudlet values is safe: the platform reconciles to the requested shape and reports no change when there’s nothing to do.

The CLI covers the rest of the environment lifecycle too:

  • Environment creation and deletion
  • Environment start / stop
  • Environment cloning
  • Environment migration
  • Container redeploy
  • Docker volumes and mount points
  • VCS-based deployment
  • Swapping public IPs
  • Installing JPS solutions

Each of these is documented in its own page; together they let you treat the platform as code.