OpenStack

In Juju, OpenStack is a machine cloud and works as described below.

Note

This reference assumes basic familiarity with Juju. If you are new to Juju, start with the Tutorial, then use this page together with the generic materials it links to.

Requirements

An OpenStack version that supports:

  • Compute v2 (Nova).

  • Network v2 (Neutron) (optional, but required for Queens or newer).

  • Volume v2 (Cinder) (optional).

  • Identity v2 or v3 (Keystone).

Concepts

The following table shows how OpenStack abstractions map to Juju concepts:

OpenStack

Juju

Project/Tenant

Scope for a model (roughly)

Nova instance

machine

Process on an instance

unit

Group of units for one workload

application

Cinder volume

storage

Neutron network/subnet

Network spaces and placement targets (roughly)

The cloud

See also: Cloud, Juju | Manage clouds, Terraform Provider for Juju | Manage clouds

As for all machine clouds, the cloud is registered in Juju via a cloud definition, stored in clouds.yaml on the client (on Linux: ~/.local/share/juju/clouds.yaml) and following this schema:

clouds:
  <cloud-name>:  # User-defined name
    type: openstack
    auth-types:
      - <auth-type>                # See Authentication types below
    endpoint: <keystone-api-url>  # Keystone API endpoint
    regions:
      <region-name>:
        endpoint: <endpoint>       # Region-specific endpoint (if different)
    config:                        # Optional: model config defaults
      <config-key>: <value>        # See Configuration keys below

Tip

Source the OpenStack RC file (source <path to file>) before running juju add-cloud in interactive mode – Juju will detect values from preset OpenStack environment variables and suggest them as defaults.

Credentials

See also: Credential, Juju | Manage credentials, Terraform Provider for Juju | Manage credentials

As for all machine clouds, credentials are stored in credentials.yaml on the client and follow this schema:

credentials:
  <your-openstack-cloud>  # Cloud name as defined above
    <credential-name>:             # User-defined credential name
      auth-type: <auth-type>       # userpass (see Authentication types below)
      <attribute>: <value>         # Auth-type-specific attributes (see below)

Important

If you want to use environment variables (recommended): Source the OpenStack RC file. Run juju add-credential and accept the suggested defaults.

Authentication types

OpenStack supports the following authentication types:

userpass

Attributes:

  • username: The username to authenticate with (required).

  • password: The password for the specified username (required).

  • tenant-name: The OpenStack tenant name (optional).

  • tenant-id: The OpenStack tenant ID (optional).

  • version: The OpenStack identity version (optional).

  • domain-name: The OpenStack domain name (optional).

  • project-domain-name: The OpenStack project domain name (optional).

  • user-domain-name: The OpenStack user domain name (optional).

Controllers

See also: Controller, Juju | Manage controllers, Terraform Provider for Juju | Manage controllers

Bootstrap behavior

Creates a controller instance on OpenStack. Requires simplestreams metadata to locate appropriate machine images. If metadata is available locally, pass it via juju bootstrap ... --metadata-source <path to metadata simplestreams>.

See more: How to manage Simplestreams metadata

Special bootstrap considerations:

  • Multiple private networks: Specify the network for instances to boot from via juju bootstrap ... --model-default network=<network uuid or name>.

  • Floating IP access: If instances must be accessed via floating IPs, pass allocate-public-ip=true as a bootstrap constraint.

Resources created at bootstrap

The controller runs on a Nova instance provisioned using the same mechanisms as workload machines – see Resources created per machine for the full per-machine resource model. Controller-specific differences are noted below.

Compute

  • Nova instance: Ubuntu LTS compute instance. Flavor selected based on hardware constraints.

  • Instance metadata: Tagged with juju-is-controller: true, juju-controller-uuid, and juju-model-uuid.

Networking

  • Security groups:

    • Model-wide group: juju-<controller-uuid>-<model-uuid>. Ingress rules (self-referencing):

      • TCP ports 1–65535 (IPv4 and IPv6)

      • UDP ports 1–65535 (IPv4 and IPv6)

      • ICMP (IPv4 and IPv6)

    • Machine or global group (no initial rules; added via open-ports):

      • firewall-mode=instance (default): juju-<controller-uuid>-<model-uuid>-<machine-id>

      • firewall-mode=global: juju-<controller-uuid>-<model-uuid>-global

    • Optionally the OpenStack default security group if use-default-secgroup=true.

    • All groups tagged with juju-controller=<controller-uuid> and juju-model=<model-uuid>.

  • Network attachments: Connected to configured internal networks from model config.

  • Neutron ports (if space-aware networking): Pre-created with fixed IPs before instance boot.

  • Floating IP (optional): Allocated from external network if allocate-public-ip=true.

Storage

  • Root disk: Local ephemeral disk or Cinder boot volume based on root-disk-source constraint.

Models

See also: Model, Juju | Manage models, Terraform Provider for Juju | Manage models

Configuration keys

OpenStack supports the following cloud-specific model configuration keys:

Networking

  • external-network: The network label or UUID to create floating IP addresses on when multiple external networks exist. Type: string. Default: "".

  • use-openstack-gbp: Whether to use Neutron’s Group-Based Policy. Type: bool. Default: false.

  • policy-target-group: The UUID of Policy Target Group to use for Policy Targets created. Type: string. Default: "".

  • use-default-secgroup: Whether new machine instances should have the “default” OpenStack security group assigned in addition to Juju-defined security groups. Type: bool. Default: false.

  • network: The network label or UUID to bring machines up on when multiple networks exist. Type: string. Default: "".

Machines

See also: Machine, Juju | Manage machines, Terraform Provider for Juju | Manage machines

Constraints

OpenStack supports the following constraints:

Note

The constraints instance-type and [mem, root-disk, cores] are mutually exclusive.

Compute

Networking

Storage

Placement directives

OpenStack supports the following placement directives:

Resources created per machine

Applies to all machines, including controller machines. Controller-specific differences are documented in Resources created at bootstrap.

Compute

  • Nova instance: Compute instance with name juju-<model-uuid>-<machine-id>. Flavor selected based on constraints.

  • Root disk: Local ephemeral disk (default) or Cinder boot volume if root-disk-source=volume.

  • Additional Cinder volumes (optional): Created when storage specified via storage constraints.

Networking

  • Security groups:

    • Model-wide group: juju-<controller-uuid>-<model-uuid>

    • Machine-specific group (firewall-mode=instance, default): juju-<controller-uuid>-<model-uuid>-<machine-id>

    • Global group (firewall-mode=global): juju-<controller-uuid>-<model-uuid>-global

  • Network attachments: Connected to configured internal networks. Multiple NICs if multiple networks configured.

  • Neutron ports (if space-aware networking): Pre-created ports with fixed IPs for each subnet/space.

  • Floating IP (optional): Allocated from external network if allocate-public-ip=true constraint.

Metadata tags: juju-model-uuid, juju-controller-uuid, juju-machine-id, juju-units-deployed.

Networking behavior

  • Network selection: Uses networks configured via network model config. If not specified, attaches to all available internal networks.

  • Spaces: OpenStack supports multiple network devices. Supplying multiple space constraints or endpoint bindings will provision machines with NICs in subnets representing the union of specified spaces. Creates dedicated Neutron ports per subnet/space. Ports pre-allocated with fixed IPs before boot.

  • Security groups: Per-model group allows internal traffic. Machine or global group allows user-defined port rules via open-ports.

  • Floating IPs: Allocated from external network specified in external-network config. Attempts to place in same availability zone as instance. Reuses unassigned IPs when available.

  • Port security: Respects port_security_enabled network attribute. Skips security group creation if port security disabled.

Storage behavior

See also: cinder for the Cinder storage provider configuration options.

  • Root disk: Local ephemeral disk by default. Use root-disk-source=volume constraint to boot from a Cinder volume instead.

  • Additional volumes: Cinder block volumes created on demand when storage is specified via storage constraints.

  • AZ constraint: Availability zone is matched to the instance’s AZ when possible.

  • Device path: Auto-assigned by OpenStack.

Storage

See also: Storage, Juju | Manage storage

Storage providers

In addition to generic storage providers, OpenStack provides the following cloud-specific storage providers:

cinder

Type: Cinder block volumes

Tagging: Volumes tagged with juju-model-uuid, juju-controller-uuid, juju-storage-instance, juju-storage-owner. Volume names follow the pattern juju-<model-uuid>-<volume-tag>.

Configuration options:

  • volume-type: The volume type. Value is the name of any volume type registered with Cinder.