Need help understanding Juju's YAML syntax for overlay bundles

juju
,
1

hello, I’m new to juju, yaml and maas.
I found the following syntax in a YAML file and wanted help understanding it.
I found this in openstack-base-61.zip openstack-base-spaces-overlay.yaml

variables:
  public-space:        &public-space         public-space
applications:
  neutron-gateway:
    bindings:
      "": *public-space
  # text continues

I need help understanding the syntax here.
In the file “openstack-base-spaces-overlay.yaml” I see a line “variables”, that I get, what I need help with is the following line: public-space: &public-space public-space
what is the syntax, what is: “public-space:”? what is “&public-space”? It looks like the 3 is the value to supplement “public-space”

Is the first item what to look for in terms of YAML tags, the 2nd item the variable to replace with item 3?

Thanks.

2

Hi @nathan-flowers, welcome to the community!

This is actually YAML syntax for creating named entities. It’s a relatively uncommon feature within YAML and stems from YAML’s XML heritage. To make things slightly more complex, we namespace named entities as well with a key. So there’s some duplication.

The triple public-space line (public-space: &public-space public-space) creates a named entity &public-space with the value public space. That named entity is assigned a key for Juju’s purposes as a “bundle variable”, which explains the public-space: term at the start of the line.

In more abstract terms, this is what each “public-space” is doing:

variables:
  <variable-1>:        <named-entity-1>         <value-1>
  [<variable-2>:        <named-entity-2>         <value-2> ...]

Looking it in full context again, hopefully it’s slightly more obvious what each role is performing:

variables:
  public-space:        &public-space         public-space

The variables block is Juju-specific. It is a location for describing variables that are used elsewhere in the bundle file.

Sidebar: I’m not entirely sure why this isn’t a list of named entities. Another approach—that may not be valid YAML—would be to use a list of variables:

variables:
  - &public-space         public-space

So anyway, we now have a variable &public-space. How do we refer to it? With the asterisk prefix.

# ...
applications:
  neutron-gateway:
    bindings:
      "": *public-space

This is saying, “Dear Juju, please use the public-space variable’s value as the default binding for the neutron-gateway application”.

If the &../*.. syntax is cryptic, we apologise! We were just following the spec. And the YAML authors are probably not at fault for that. Their heritage is the C deference operator. Like many things in computing, there’s always someone else to blame.

Anyway, I hope that clarifies the situation

3 
Thank you very much for the explanation. Can you offer some links to primers for further reading?

I'm taking from your example:
Variables:

<Variable-1>:    <named-entity-1>    <value-1>


what is the proper syntax here for: 
<variable> <named-entity> <value>

VariableName:    &named-entity     value

What is required what is not?
in your example:

<yourExample>
variables:
  - &public-space         public-space
<yourExample/>

it appears only 
  &named-entity       value 
is required yet you reference "variable" or is that the "-" in your example I quoted?

also which of the <variable> <named-entity> <value> needs to match the bundle syntax ymal.

is this possible?
<example>
variables:
  ceph-cluster-network:     &cluster-cider        10.30.0.0/20

  mysql:
...
    options:
      access-network: *internal-cider
      cluster-network: *cluster-cider

<example/>

or does only this work

<example>
variables:
  cluster-network:     &cluster-cider        10.30.0.0/20

  mysql:
...
    options:
      access-network: *internal-cider
      cluster-network: *cluster-cider
<example/>


Thank you.
4

I think that you’re looking for the bundles reference doc. Here’s the relevant snippet:

#
# variables:
#
# Includes the optional definition of variables using anchors. Corresponding
# values are later manifested with the use of aliases. An anchor is a string
# prefixed with an ampersand (&) whereas an alias is the same string prefixed
# by an asterisk (*). The alias will typically be used to specify a value for an
# application option (see element 'options'). 
#

variables:
 data-port:           &data-port            br-ex:eno2
 worker-multiplier:   &worker-multiplier    0.25
5

Thank you again very much.
one last question.

in the 3 columns of the format that is under variables.
col1: &col2 col3

does column 1 have to match a namespace or whatever it is called in juju referenced elsewhere in the yaml?

For example does the bold parts need to match or can I use the alias however I wish?
First example the bold part doesn’t match

variables:
ceph-cluster-network: &cluster-cider 10.30.0.0/20

mysql:
…
options:
access-network: *internal-cider
cluster-network: *cluster-cider

or does only this work
Second example the bold part matches

variables:
cluster-network: &cluster-cider 10.30.0.0/20

mysql:
…
options:
access-network: *internal-cider
cluster-network: *cluster-cider