How to configure Juju for offline usage

See also:

There are three Juju entities to take into account when configuring Juju in a network-restricted environment. Each one of these may require specific treatment depending on the backing cloud type and in what manner the local network is restricted. These are:

  • the client,
  • the controller, and
  • the machines,

where the client is the Juju client from whence juju commands are invoked; the controller is the Juju machine acting as controller; and the machines are the Juju workload machines that get created during charm deployment.

These entities interact in the following way: the client is responsible for creating the controller and then manages the controller through its API. The controller, in turn, is responsible for accessing and passing all needed resources to the machines.

Recall that a Juju agent (jujud) runs on each machine (and unit) and acts as an intermediary between the machine/unit and the controller.


Network criteria

Here we examine what network access is needed to various internet-based resources for the aforementioned three entities in order to satisfy base requirements as well as requirements arising from local implementation decisions.

Any unsatisfied network criteria will need to be overcome by a combination of new local services (see Offline mode strategies) and the appropriate Juju configuration changes (covered below).

Internet-based resources

  • cloud provider The client requires access to the backing cloud in order to create a controller. Most public clouds have a RESTful API that operates over TCP port 443. A special case is the localhost cloud, in which the client talks to the local LXD daemon.

    Depending on the provider chosen and the network design the controller may require access to the provider.

  • Official Ubuntu cloud images.

    • Required when using the localhost cloud, by the client in order to create a controller and by the controller when creating further machines.

    • The machines require access if they will themselves be hosting LXD containers.


    • Where Juju agents are stored online. It is therefore required by the client in order to pass an agent to the newly-created controller and then later required by the controller itself in order to pass agents to any subsequently-created machines.

    • Used to map Juju series to cloud images. Required by the client for all cloud providers. The exception is the MAAS cloud, which maintains its own registry of images.

  • The Ubuntu package archive.

    Required by the controller and the machines. Used for providing software needed to set up the controller (e.g. juju-mongodb) as well as package management (e.g. updates). In addition, charms deployed on the machines typically call for packages to be installed.

  • Ubuntu security package updates.

    Recommended for the controller and the machines. Note that all security updates eventually end up in the Ubuntu package archive via the ‘-updates’ pocket.

  • The Charm Store. Required by the controller so that charms can be deployed on the machines.

    See Deploying charms offline for how to manage charms locally.

  • charm-specific resources Some charms require auxiliary site support (for pulling down resources). Popular sites include and Therefore, the machines may need access to these.

The following table summarizes the above information. An X designates either a hard requirement or a requirement based on local factors (see the footnotes). Remember that when using the localhost cloud, the controller resides on the same host as the client, in the form of a LXD container.

resource client controller machines
cloud provider X X [3] X [1] X [4] X [5] X X X X X X X [2] X
charm-specific resources X

[1]: Required for the localhost cloud only. [2]: Not needed if option --no-gui is used with the bootstrap command. See Access the dashboard. [3]: May be needed, depending on provider and network design. [4]: Required for the localhost cloud only. [5]: Required if the machines will host LXD containers.

The above table does not take into account the packaging needs (e.g. package updates) of the client host system.

Offline configuration methods

The client is made aware of proxy settings via the shell that it is running under (e.g. Bash). This is done by exporting the relevant environment variables:

  • http_proxy
  • https_proxy
  • no_proxy

Both the controller and the machines are configured at the model level, therefore both these entities can be configured together. Keep in mind, however, that the controller is configured via the ‘controller’ model and the machines are configured via whatever model that will eventually contain them. This information is passed during the controller creation process since the controller needs to download Ubuntu packages in order to provision itself.

Juju has the following offline-related model configuration settings at its disposal:

  • agent-metadata-url
  • apt-ftp-proxy
  • apt-http-proxy
  • apt-https-proxy
  • apt-mirror
  • container-image-metadata-url
  • ftp-proxy
  • http-proxy
  • https-proxy
  • image-metadata-url
  • juju-ftp-proxy
  • juju-http-proxy
  • juju-https-proxy
  • juju-no-proxy
  • snap-http-proxy
  • snap-https-proxy
  • snap-store-assertions
  • snap-store-proxy

The method for configuring models while using the bootstrap command is done with either the --config option or the --model-default option. The latter is a more powerful choice since it applies to all existing and future models whereas --config only affects the ‘controller’ and ‘default’ models.

Read Configuring models for details on how a model can be configured.


To set an HTTP proxy for the client, whose URL is given by $PROXY_HTTP:

export http_proxy=$PROXY_HTTP

To configure all models to use an APT mirror, whose URL is given by $MIRROR_APT, while creating an AWS-based controller:

juju bootstrap --model-default apt-mirror=$MIRROR_APT aws

To have all models of a localhost cloud use local resources for both Juju agent binaries and cloud images, whose URLs are given by $LOCAL_AGENTS and $LOCAL_IMAGES, respectively:

juju bootstrap \
    --model-default agent-metadata-url=$LOCAL_AGENTS \
    --model-default image-metadata-url=$LOCAL_IMAGES \

Last updated 1 year, 9 months ago. Help improve this document in the forum.