Using the Manual cloud with Juju

The purpose of the Manual cloud is to cater to the situation where you have machines (of any nature) at your disposal and you want to create a backing cloud out of them. If this collection of machines is composed solely of bare metal you might opt for a MAAS cloud but note that such machines would also require IPMI hardware and a MAAS infrastructure. The Manual cloud can therefore both make use of a collection of disparate hardware as well as of machines of varying natures (bare metal or virtual), all without any extra overhead/infrastructure.


With any other cloud, the Juju client can trigger the creation of a backing machine (e.g. a cloud instance) as they become necessary. In addition, the client can also cause charms to be deployed automatically onto those newly-created machines. However, with a Manual cloud the machines must pre-exist and they must also be specifically targeted during charm deployment.

Note: A MAAS cloud must also have pre-existing backing machines. However, Juju, by default, can deploy charms onto those machines, or add a machine to its pool of managed machines, without any extra effort.


The following conditions must be met:

  • At least two machines are needed (one for the controller and one to deploy charms to).
  • The machines must have Ubuntu (or CentOS) installed.
  • The machines must be contactable over SSH (either by password or public key) using a user account with root privileges. On Ubuntu, sudo rights will suffice if this provides root access.
  • The machines must be able to ping each other.


A Manual cloud is initiated through the use of the add-cloud command. In this step you specify an arbitrary cloud name, the intended controller (IP address or hostname), and what user account the Juju client will attempt to contact over SSH.

As usual, a controller is created with the bootstrap command and refers to the cloud name.

Your collection of machines (minus the controller machine) must be added to Juju by means of the add-machine command. A machine is specified by means of its IP address.

Important: A Manual cloud requires at least one machine to be added.

Finally, to deploy a charm the deploy command is used as normal. However, a machine must be targeted. This is accomplished with the --to option in conjunction with the machine ID.

Adding a Manual cloud

Use the interactive add-cloud command to add your Manual cloud to Juju's list of clouds. You will need to supply a name you wish to call your cloud, the IP address (or hostname) for the machine you intend to use as a controller, and what remote user account to connect to over SSH (prepend 'user@' to the address/hostname).

juju add-cloud

Example user session:

Cloud Types

Select cloud type: manual

Enter a name for your manual cloud: mymanual

Enter the controller's hostname or IP address: noah@

Cloud "mymanual" successfully added
You may bootstrap with 'juju bootstrap mymanual'

We've called the new cloud 'mymanual', used an IP address of for the intended controller, and a user account of 'noah' to connect to. Since the 'root' user was not used, the machine is probably running Ubuntu.

Now confirm the successful addition of the cloud:

juju clouds

Here is a partial output:

Cloud        Regions  Default          Type        Description
mymanual           0                   manual 

Adding credentials

Credentials should already have been set up via SSH. Nothing to do!

Creating a controller

You are now ready to create a Juju controller for cloud 'mymanual':

juju bootstrap mymanual manual-controller

Above, the name given to the new controller is 'manual-controller'. The machine that will be allocated to run the controller on is the one specified during the add-cloud step. In our example it is the machine with address

For a detailed explanation and examples of the bootstrap command see the Creating a controller page.

Adding machines to a Manual cloud

To add the machine with an IP address (and user) of bob@ to the 'default' model in the Manual cloud (whose controller was named 'manual-controller'):

juju add-machine ssh:bob@

Unless you're using passphraseless public key authentication, you may be prompted for a password a few times. The process takes a couple of minutes.

Once the command has returned, you can check that the machine is available:

juju machines

Sample output:

Machine  State    DNS          Inst id             Series  AZ  Message
0        started  manual:  xenial      Manually provisioned machine

Deploying a charm in a Manual cloud

To deploy WordPress onto the machine we need to declare the ID (of '0') of the machine:

juju deploy wordpress --to 0

See Deploying to specific machines for more information on targeting certain machines.

Additional Manual cloud notes

The following notes are pertinent to the Manual cloud:

  • Juju machines are always managed on a per-model basis. With a Manual cloud the add-machine process will need to be repeated if the model hosting those machines is destroyed.
  • To improve the performance of provisioning newly-added machines consider running an APT proxy or an APT mirror. See Offline mode strategies.

Additional CentOS notes

One of the requirements for the Manual cloud is that SSH is running on the participating machines, but for CentOS this may not be the case. To install SSH run the following commands as the root user on the CentOS system:

yum install sudo openssh-server redhat-lsb-core
systemctl start sshd

Since you will be connecting to the root account during the add-machine step, also ensure that there is a root password set on the CentOS machine.

Next steps

A controller is created with two models - the 'controller' model, which should be reserved for Juju's internal operations, and a model named 'default', which can be used for deploying user workloads.

See these pages for ideas on what to do next:

© 2018 Canonical Ltd. Ubuntu and Canonical are registered trademarks of Canonical Ltd.