Implementing environment providers

Implementing providers

This document describes how to implement an environment provider for Juju. For the remainder of this document we will use the term "provider" to mean "environment provider", but be aware that there are additional types of providers (e.g. storage providers).

Overview

Providers are the bridge between Juju and the cloud environment in which Juju operates, and provides:

• allocation, deallocation, and querying of machines
• cloud-integrated network management

Aspects of a provider

A provider is made up of several different parts:

• Creation (bootstrapping) and destruction of the environment
• Configuration
• Firewalling
• Instance (machine) creation
• Instance querying

These are encompassed by several interfaces in the Juju codebase:

• environs.EnvironProvider
• environs.Environ
• instance.Instance

Configuration

The first thing you should do when creating a new provider is identify the core configuration required, and then implement the EnvironProvider interface. The EnvironProvider methods are described below.

Environment configuration is encapsulated in environs/config.Config, providing accessors for common configuration attributes. Provider-specific configuration can be obtained through the Config.UnknownAttrs method.

EnvironProvider.PrepareForBootstrap, EnvironProvider.PrepareForCreateEnvironment

These methods "prepare" an environment, which essentially means adding attributes to the provided configuration as required. For most providers, PrepareForCreateEnvironment will be a no-op, simply returning the provided configuration unmodified. Similarly, for most providers the PrepareForBootstrap method will be a call to PrepareForCreateEnvironment followed by a call to Open.

EnvironProvider.Validate

Validate takes two configurations, and reports whether or not they are valid. There are two use-cases for this method:

• "Is this configuration valid in isolation?" In this case, the first argument will be a non-nil configuration, and the second will be nil.
• "Is this configuration valid, given the existing configuration?" In this case, the first argument will be the new configuration, and the second argument the old. You must check for invalid changes to configuration here.

It is also possible for the Validate method to return a modified configuration, which is often used to implement configuration upgrades (i.e. upgrading configuration for older versions of a provider in a newer version). This exists only because we do not have machinery dedicated to upgrading configuration, and should not be used lightly.

EnvironProvider.Open

Open returns an Environ for a given configuration.

EnvironProvider.SecretAttrs

SecretAttrs identifies which configuration attributes are secrets, which may only be shared with servers in the Juju environment, and will be stripped from the environment configuration that is stored in the database. These are typically only the credentials required to connect to the cloud provider.

EnvironProvider.RestrictedConfigAttributes

There is work ongoing to support multiple environments (i.e. separate sets of machines, services, units, etc.) within the same cloud provider. RestrictedConfigAttributes identifies which attributes should not change between multiple environments for the same Juju server, such as the cloud provider credentials.

EnvironProvider.BoilerplateConfig

BoilerplateConfig returns the provider-specific YAML boilerplate that is added to environments.yaml when running juju init. The output should describe the possible configurations and default values.

Creation and destruction of the environment

Instance creation

TODO: tagging TODO: constraint validation TODO: prechecking TODO: distribution