conjure-up is a thin layer spanning a few different underlying technologies - Juju, MAAS, and LXD.

conjure-up provides you with a streamlined, turnkey solution. In order to provide that streamlined approach, conjure-up makes use of processing scripts. These scripts are executed at 3 different times in the deployment, just after a Juju bootstrap, just before a Juju deploy, and right after a Juju deploy.

Processing scripts give you the flexibility to alter LXD profiles in order to expose additional network interfaces to Neutron services, import images into Glance once the service is available, or notifying the Deployment status screen that your solution is ready and can be viewed at a specific URL.

With these powerful concepts you can package up the solution that can then be provided to coworkers who can easily deploy your solutions in any Public Cloud, MAAS, or LXD.

Getting Started

Hardware Requirements

Public Cloud

For Public Cloud deployments hardware requirements(constraints) are handled by the Spell authors and will automatically be allocated during deploy.

Localhost

For localhost deployments the following setup is recommended:

  • 2 cores

  • 16G RAM

  • 32G Swap

  • 250G SSD with a seperate block device for ZFS. Our recommendation for that device is 100G.

Configure LXD/ZFS

If you plan on using the localhost provider a properly configured network bridge is required and optionally(but highly recommended) configuring ZFS. Skip if you plan on using any other public cloud.

$ sudo lxd init

LXD will go through a series of questions including the setup of ZFS and a network bridge. Make sure to utilize your seperate block device for the ZFS pool here.

There may be times where conjure-up will error out due to not finding a suitable lxdbr0 bridge device. Since LXD is socket activated you may need to run lxc finger and re-try conjure-up installation.
For best results make sure to allocate at least a 100G ZFS pool size.

Installing conjure-up

We are currently in a pre-release phase. In order to help test conjure-up we ask that you install from the PPA until otherwise noted:

$ sudo apt-add-repository ppa:conjure-up/next

Juju is one of the underlying technologies used and is also currently in beta. Please use their PPA until otherwise noted:

$ sudo apt-add-repository ppa:juju/devel

Finally, update your apt cache and install necessary packages:

$ sudo apt update
$ sudo apt install conjure-up

Summon a Spell

To deploy solutions such as OpenStack you will summon a spell:

$ conjure-up openstack

To see a list of all available spells run:

$ conjure-up
Several remote locations are supported please see Advanced Spell Summoning for further details.

Uninstalling

conjure-up uses Juju under the hood and to remove a deployment requires the use of juju help commands.

You’ll need to be familiar with Juju controllers and models

The basics of removing a deployed spell are as follows:

# Deploy openstack
$ conjure-up openstack

# List Juju information
$ juju controllers
CONTROLLER  MODEL    USER         CLOUD/REGION
teddy*      default  admin@local  localhost/localhost

$ juju models
MODEL       OWNER        STATUS     LAST CONNECTION
controller  admin@local  available  never connected
default*    admin@local  available  just now

# Remove the default model is houses our OpenStack deployment
$ juju destroy-model default

# Or destroy the entire environment and start over
$ juju kill-controller teddy

Spell Walkthrough

Follow through our screenshot walkthrough of deploying The Canonical Distribution of Kubernetes, Enterprise Kubernetes, anywhere.

Spell Selection

Initially, you will be provided with a list of available spells that can be deployed. For this walkthrough we will select Canonical Kubernetes.

Once a Spell is selected you can view its README at any time by pressing R
spell selection
Figure 1: Spell selection

Cloud Selection

Next, a list of publicly supported clouds will be presented.

cloud selection
Figure 2: Cloud selection

Application List

Once a cloud is selected you will be presented with a list of applications that make up the Canonical Kubernetes deployment. This screen allows you to deploy each application individually or make additional configuration changes to the selected application (covered in Application Configuration).

application list
Figure 3: Application list

Application Configuration

In the configuration screen for the application you have the ability to configure certain aspects prior to deployment. For example, in Figure 4 you can increase the amount of units to deploy of Elasticsearch.

application config
Figure 4: Application Config

Bootstrap

Once the applications are deployed and if no previously bootstrapped cloud exist you will be presented with a wait screen that gives you the status of the current bootstrap.

If an existing cloud is already bootstrapped you will not see this view.
bootstrap wait
Figure 5: Bootstrap Wait Screen

Deployment Status

After the bootstrap process is complete the applications will begin their deployment tasks. This includes installing the necessary bits onto the allocated machines, setting their relations between the applications, and verifying that each application starts successfully. You’ll notice that once the applications are ready they will have a green checkmark beside them.

deploy status
Figure 6: Deployment Status Screen

Additional Application Tasks

This is the real benefit of conjure-up. These additional steps encapsulate the operational tasks to perform to your deployment in order to start using your big software. In Figure 7 you’ll notice that this walks you through downloading the required kubectl tool to work with your new cluster. Additionally, it’ll contact your cluster and grab the necessary information to display for you on the Summary.

steps config
Figure 7: Steps Configuration

Summary

Finally, the summary screen presents you with all the information necessary to access and start using your big software. In Figure 8 we provide you with how to access and use your kubectl binary along with the Kubernetes cluster-info and how to access the Kibana dashboard for viewing things such as Filebeat and Topbeat.

summary
Figure 8: Summary

Pressing Q will return you back to the shell with your deployment left intact.

Advanced Spell Summoning

conjure-up includes several spells in addition to supporting summoning spells from several remote repositories and from a local directory on your filesystem.

GitHub/BitBucket

Not quite ready to push your spell to the charm registry? That’s ok, simply push your spell to GitHub and conjure-up can deploy from there:

$ conjure-up battlemidget/ghost

This would pull from GitHub repo https://github.com/battlemidget/ghost

Remote Web Server

conjure-up will also support downloading directly from a webserver. For example, if you have your spell zipped up and stored at http://example.com/my-conjure-spell.zip you could install it like so:

$ conjure-up http://example.com/my-conjure-spell.zip

Local Filesystem

Passing in either the directory path of the spell or if the current working directory is a spell:

$ conjure-up ~/spells/openstack/openstack-novalxd

Or from cwd

$ ~/spells/openstack/openstack-novalxd> conjure-up .

Running in Headless Mode

conjure-up is meant to be a teaching tool in addition to a full blown application deployment tool. By Default conjure-up will walk you through the entire deployment process and help you understand what it is you are deploying.

Where this doesn’t make sense is if you are wanting to deploy your application in an automated fashion. For example, integrating the deployment with a Jenkins CI server.

For these cases conjure-up provides a headless mode.

To deploy in a headless mode you’ll need to have credentials defined if deploying to a Public Cloud or make sure LXD is configured if deploying to Localhost.

To deploy OpenStack to a Localhost provider:

$ conjure-up openstack-novalxd localhost

If we want to deploy to a cloud like AWS:

$ conjure-up canonical-kubernetes aws
Keep in mind you’ll need to have credentials defined, see Juju credentials for more details.

Customizing headless mode

Post deployment actions are exposed to the environment via environment variables. Some actions may require you to input data depending on what is required. An example would be input the path of your public ssh key so that your OpenStack deployment can make those available to the compute nodes.

To see what environment variables you can set prior to running a headless mode install, run the following:

$ conjure-up --show-env openstack-novalxd localhost
Available environment variables:

+--------------+-------------------+---------------------------------------------------------+
| ENV          | DEFAULT           |                                                         |
+--------------+-------------------+---------------------------------------------------------+
| SSHPUBLICKEY | ~/.ssh/id_rsa.pub | Import SSH keypairs into OpenStack. This allows you to  |
|              |                   | access the newly deployed instances via SSH with your   |
|              |                   | current user. If you are not sure about the location of |
|              |                   | a ssh key leave it as is and we will create one         |
|              |                   | automatically.                                          |
+--------------+-------------------+---------------------------------------------------------+

See http://conjure-up.io/docs/en/users/#running-in-headless-mode for more
information on using these variables to further customize your deployment.

In order to change it from it’s default of ~/.ssh/id_rsa.pub you would simply do:

$ SSHPUBLICKEY=/home/bob/my-ssh-key.pub conjure-up openstack-novalxd localhost

Troubleshoot

Logging

conjure-up logs are written to journald by default. Viewing those logs can be done with:

$ journalctl |grep conjure-up

You can also increase the logging by enabling the debug flag:

$ conjure-up -d

Unicode

If the system running conjure-up does not have its locale defined to UTF-8 a failure will occur similar to:

UnicodeDecodeError: 'ascii' codec can't decode byte 0xe2 in position 2201: ordinal not in range(128)

To fix you will need to set your locale accordingly, for example:

$ locale
LANG=en_US.UTF-8
LANGUAGE=en_US
LC_CTYPE="en_US.UTF-8"
LC_NUMERIC="en_US.UTF-8"
LC_TIME="en_US.UTF-8"
LC_COLLATE="en_US.UTF-8"
LC_MONETARY="en_US.UTF-8"
LC_MESSAGES="en_US.UTF-8"
LC_PAPER="en_US.UTF-8"
LC_NAME="en_US.UTF-8"
LC_ADDRESS="en_US.UTF-8"
LC_TELEPHONE="en_US.UTF-8"
LC_MEASUREMENT="en_US.UTF-8"
LC_IDENTIFICATION="en_US.UTF-8"
LC_ALL=

Common Spell Problems

OpenStack Base for MAAS

config-changed error for neutron-gateway

This error can happen if you’ve not set your bridge-mappings and data-port during the Application List portion of the deployment.

Please see the Neutron Gateway charm documentation under Port Configuration for more information.