Charm Metadata v2

Charm Metadata Reference

Type: Meta

Serialized location: /metadata.yaml

Field Since Default Description
name
string
- required Name of the charm.
summary
string
- required A short one line summary of the charm.
description
string
- required A full description of the charm, can be multiple lines.
maintainers
[]string
- nil List of maintainers in the formation “First Last ”.
terms
[]string
- nil List of terms a charm user must agree with.
min-juju-version
string
- nil Version (e.g. “2.6.10”) that represents the earliest version of juju this charm can be deployed to.
series
[]string
proposed:
deprecation
nil List of supported charm base platforms/versions. In the form of “focal”, “bionic”, “centos7” etc.
Deprecation: to be supplemented by platforms/architectures/systems.
tags
[]string
- nil List of short tags used by the charm store.
categories
[]string
- nil List of categories used by the charm store.
subordinate
bool
proposed:
deprecation
false True if the charm is meant to be deployed as a subordinate to a principal charm.
Deprecation: to be supplemented by platforms
provides
map[string]Relation
- nil Relations provided by this charm.
Key represents the Relation name.
requires
map[string]Relation
- nil Relations required by this charm.
Key represents the Relation name.
peers
map[string]Relation
- nil Mutual relations between units/peers of this charm.
Key represents the peer Relation name.
extra-bindings
map[string]nil
- nil Extra bindings for the charm, for example binding extra network interfaces. Key only map.Value must be none.
Key represents the binding name.
storage
map[string]Storage
- nil Storage requests for the charm.
Key represents the Storage name.
devices
map[string]Device
- nil Device requests for the charm, e.g. GPU.
Key represents the Device name.
platforms
[]Platform
proposed required List of platforms this charm supports.
architectures
[]Architecture
proposed all List of CPU architectures this charm and all it’s containers support.
systems
[]System
proposed required List of systems (base image, base OS, version, channel) this charm supports. Has no impact on the charm’s containers, only the charm itself.
containers
map[string]Container
proposed nil Map of containers to be created adjacent to the charm. On kubernetes these are sidecars. Other platforms the behaviour is to be determined and will likely be fulfilled by a container runtime like LXD, containerd, Docker. Adjacency control is likely to arrive in a future revision (such as charm running on machine-0 and container-1 running on machine-1 etc.)
The key represents the container name.
deployment
Deployment
proposed:
deprecation
nil Deployment information for legacy Kubernetes charms.
resources
map[string]Resource
- nil Resources to accompany the charm.
The key represents the resource name.

Type: Relation

Field Since Default Description
interface
string
- required The interface schema this relation conforms to.
limit
int
- nil Maximum number of connections to this relation endpoint.
optional
bool
- false True if this relation is optional.
scope
RelationScope
- “global” Scope of the relation.

Type: Storage

Field Since Default Description
type
StorageType
- required Type of storage requested.
description
string
- nil Description of the storage requested.
shared
bool
- false True indicates all units of the application share the storage.
read-only
bool
- false True indicates the storage should be made read-only where possible.
multiple
StorageCount
- nil Determines the number of storage instances to be requested.
minimum-size
string
- nil Size in the forms 1.0G, 1GiB, 1.0GB. Size multipliers are M, G, T, P, E, Z or Y. If no multiplier is supplied, M is implied.
location
string
- nil Location is the mount location for filesystem stores. For multi-stores, the location acts as the parent directory for each mounted store.
properties
[]string
- nil List of properties. Currently only supported value is “transient”.

Type: StorageCount

Field Since Default Description
range
int/string
- nil int: exact number of storage instances
string: in the form of m-n or m+ or m- where m and n are integers

Type: Device

Field Since Default Description
type
string
- required Type of device requested. Currently supported values:
- gpu
- nvidia.com/gpu
- amd.com/gpu
description
string
- nil Description of the device requested.
countmin
int
- nil Minimum number of devices required.
countmax
int
- nil Maximum number of devices required.

Type: System

Field Since Default Description
os
string
proposed Name of the os e.g. ubuntu, centos, windows, osx, opensuse or genericlinux
Cannot be used with resource.
channel
string
proposed Channel of the os e.g. 18.04/stable or 20.04/stable.
Cannot be used with resource.
resource
string
proposed Name of the resource to use as the system. This can reference an OCI image resource.
Cannot be used with image/version.

Type: Container

Field Since Default Description
systems
[]System
proposed required List of systems (base image, base OS, version, channel) this container supports.
mounts
[]Mount
proposed nil List of mounted storage for this container.

Type: Mount

Field Since Default Description
storage
string
proposed required Name of storage to mount from the charm storage.
location
string
proposed nil Location is the mount location for filesystem stores. For multi-stores, the location acts as the parent directory for each mounted store.

Type: Deployment

Field Since Default Description
type
DeploymentType
proposed:
deprecation
“stateful” Type of deployment in kubernetes.
mode
DeploymentMode
proposed:
deprecation
“workload” Type of charm runtime location.
service
ServiceType
proposed:
deprecation
nil Type of kubernetes service to create.
min-version
string
proposed:
deprecation
nil Minimum version of kubernetes this charm supports.

Type: Resource

Field Since Default Description
type
ResourceType
- “file” Type of the resource.
filename
string
- nil Name of the file resource.
description
string
- nil Description of the resource.

Enumeration: RelationScope

Value Since Description
“global” -
“container” -

Enumeration: Platform

Value Since Description
“machine” proposed Charm can be deployed to a machine or virtual machine.
“kubernetes” proposed Charm can be deployed to kubernetes.
“machine-subordinate” proposed Charm can be deployed as a subordinate to a machine principal.

Enumeration: Architecture

Value Since Description
“amd64” proposed AMD64 architecture
“arm64” proposed ARM64 architecture
“ppc64el” proposed PPC64EL architecture
“s390x” proposed S390X architecture

Enumeration: StorageType

Value Since Description
“block” - Block device storage.
“filesystem” - Filesystem storage.

Enumeration: DeploymentType

Value Since Description
“stateful” proposed:
deprecation
Stateful deployment in kubernetes.
“stateless” proposed:
deprecation
Stateless deployment in kubernetes.
“daemon” proposed:
deprecation
Node daemon deployment in kubernetes.

Enumeration: DeploymentMode

Value Since Description
“operator” proposed:
deprecation
Charm has no more than one unit which is collocated on the operator.
“workload” proposed:
deprecation
Charm has one or more units located in separate kubernetes pods.

Enumeration: ServiceType

Value Since Description
“cluster” proposed:
deprecation
Kubernetes service with a cluster IP address.
“loadbalancer” proposed:
deprecation
Kubernetes service with a possible external or internal load balancer.
“external” proposed:
deprecation
Kubernetes service that points to an external name (DNS/IP).
“omit” proposed:
deprecation
Don’t create a service.

Enumeration: ResourceType

Value Since Description
“file” - File resource.
“oci-image” - OCI image resource.
3 Likes

Nice to see this articulated here, and cleanly, thank you

1 Like

Would it be simpler to have ‘subordinate’ rather than ‘machine-subordinate’?

Yeah good point, since we haven’t fully implemented machine/subordinate we can easily make this improvement.

While we are here, oci-image translates to open-container-image-image :slight_smile:

So perhaps just oci would be nicer.

For System:resource could we instead do System:oci just to be explicit that it’s an OCI resource that’s necessary?

At the moment System:resource references a declared Resource which must have a ResourceType of “oci-image” (agree “oci” would be better).

If in the future a different image format or ResourceType can be used in a System, it can be swapped in by updating the type of the single resources: entry for the System:resource reference.

By changing System:resource to System:oci wouldn’t you lose that flexibility, and have to introduce a different System:new-format for each new resource type that can be used by System?

Ah, yes, I see that now, thank you.

OCI Image is actually Open Container Initiative Image, and they do call it the OCI image spec
https://opencontainers.org/release-notices/v1-0-1-image-spec/

I don’t mind just calling it “oci” as it is shorter and currently not ambiguious, but the ‘i’ doesn’t stand for image.

Hmm, yeah, I’d say “oci-image” is probably best then to be super clear what it means.

Kind of related, in the Resource type definition…

… I was wondering whether it should accommodate a “tag” field or similar (I’m not sure what the proper name should be here) that specifies the image rather than relying on the resource’s reference?

Basically, if the “file” ResourceType needs a filename, should the “oci-image” ResourceType also use some specific tag/url/whatnot that can be changed in the resources section without updating all the places it is referenced?

I’m not super familiar with k8s, so if that resource reference used in the containers section is really just the name given to the “Application” (in Juju speak) and the actual image version etc is managed elsewhere, just ignore me!

The current oci-image resource type takes the ‘docker url’ to the image. Which can include tags, etc. So it is still allowing a tag, but also allows you to point to a different docker hub registry.

1 Like

I’m assuming that you could use focal/stable or just focal to reference a series or are we telling people to use the version number exclusively?

Also I’m assuming that the order still has the same order as the now deprecated series in metadata.yaml - it will pick the first one and correctly use that? I would expect that we should explain that ordering of given arrays/slices matter.