How to manage metadata

When Juju creates a controller it needs two critical pieces of information:

  • VM image metadata: The UUID of the image to use when spawning a new machine (instance).
  • Agent binary metadata: The URL from which to download the correct Juju agent.

This “metadata” is stored in a JSON format called Simplestreams. It is built-in for most clouds Juju is aware of but needs to be configured if you’re setting up your own cloud.

This document shows how to manage this metadata in Juju.

See also: Plugin juju-metadata


Generate metadata

For cloud images. To generate metadata for cloud images, use the metadata plugin with the generate-image subcommand. This is useful for creating metadata for custom images. The metadata is stored in SimpleStreams, a data format designed to provide a standardized way to represent and discover metadata about cloud resources.

juju metadata generate-image

The cloud specification comes from the current Juju model, but it is possible to override certain cloud attributes, including the region, endpoint, and charm base using the command arguments. While “amd64” serves as the default setting for the architecture, this option can also be adjusted to accommodate different architectural requirements.

See more: juju metadata > generate-image

The generated metadata image can then be used to speed up bootstrap and deployment.

See more: juju bootstrap, Bootstrapping, VMware vSphere and Juju

For agent binaries. To create metadata for Juju agent binaries, use the metadata plugin with the generate-agent-binaries subcommand. This generates simplestreams metadata for agent binaries, facilitating their discovery and use.

juju metadata generate-agent-binaries -d <workingdir>

The simplestream stream for which metadata is generated is specified using the --stream parameter (default is “released”). Metadata can be generated for any supported stream - released, proposed, testing, devel.

juju metadata generate-agent-binaries -d <workingdir> --stream proposed

Newly generated metadata will be merged with any existing metadata that is already there. To first remove metadata for the specified stream before generating new metadata, use the --clean option.

juju metadata generate-agent-binaries -d <workingdir> --stream proposed --clean

See more: juju metadata > generate-agent-binaries

Validate metadata

For images. To validate image metadata and ensure the specified image or images exist for a model, use the metadata plugin with the validate-images subcommand.

juju metadata validate-images

The key model attributes may be overridden using command arguments, so that the validation may be performed on arbitrary metadata.

See more: juju metadata > validate-images

For agent binaries. To ensure that the compressed tar archives (.tgz) for the Juju agent binaries are available and correct, use the metadata plugin with the validate-agent-binaries subcommand. For example:

juju metadata validate-agent-binaries

It is also possible to indicate the os type for which to validate, the cloud provider, region as well as the endpoint. It is possible to specify a local directory containing agent metadata, in which case cloud attributes like provider type, region etc are optional.

See more: juju metadata > validate-agent-binaries

Add metadata

For images. To add custom image metadata to your model, use the metadata plugin with the add-image subcommand. This is useful when you have specific cloud images that you want Juju to use for creating instances. For example:

juju metadata add-image <image-id>

It is also possible to pass various options to add an image for a specific base, denote the image architecture, choose a model to operate in, specify the operating system series (e.g., focal, bionic) that the image supports, and the cloud region where this image exists, etc.

See more: juju metadata > add-image

If you need to sign your simplestreams metadata for security purposes, use the metadata plugin with the sign subcommand.

juju metadata sign -d <directory> -k <key>

The specified keyring file is expected to contain an amored private key. If the key is encrypted, then a passphrase should be specified using the command option --passphrase to decrypt the key.

See more: juju metadata > sign metadata

View all the known metadata

For images. To view a list of cloud image metadata currently used by Juju, use the metadata plugin with the images (or its alias list-images ) subcommand. This shows the images Juju considers when choosing an image to start.

juju metadata images
juju metadata list-images --format yaml

The result list can be filtered in order to show specific images for a region, architecture or a set of bases using the OS name and the version. For example:

juju metadata images --bases ubuntu@22.04 --region eu-west-1 --model mymodel

See more: juju metadata > images

Delete metadata

For images. To remove previously added image metadata from a Juju environment, use the metadata plugin with the delete-image subcommand followed by the id of the image.

juju metadata delete-image <image-id>

The command also allows you to specify whether this operation should show a verbose output or no informational output at all. The --model option can be set in order to specify the model to operate in.

See more: juju metadata > delete-image

Contributors: @manadart, @simonrichardson, @tmihoc, @toaksoy

Last updated 4 months ago. Help improve this document in the forum.