File 'actions.yaml'
List of files in the charm project >
actions.yaml
The actions.yaml
file in a charm project is an optional file that may be used to define the actions supported by the charm.
The file contains a YAML map for each defined action. Each map starts with the key <action name>
. The rest of this document gives details about this key.
Expand to view the full spec at once
<action 1>:
description: <string>
parallel: <boolean>
execution-group: <string>
params:
<param 1>: <JSON Schema>
<param 2>: <JSON Schema>
…
<other keys>
<action name 2>:
…
Expand to view a simple example
The following shows a simple example of an actions.yaml
file, defining three actions named pause
, resume
, and snapshot
. The snapshot
action takes a single string parameter named outfile
:
pause:
description: Pause the database.
additionalProperties: false
resume:
description: Resume a paused database.
additionalProperties: false
snapshot:
description: |
Take a snapshot of the database.
Descriptions can be extended to multiple lines.
params:
outfile:
type: string
description: The filename to write to.
additionalProperties: false
Expand to view a complex example
The following example showcases a more complex configuration file that uses features of JSON schema to define detailed options. It also makes the filename
field mandatory:
snapshot:
description: Take a snapshot of the database.
params:
filename:
type: string
description: The name of the snapshot file.
compression:
type: object
description: The type of compression to use.
properties:
kind:
type: string
enum: [gzip, bzip2, xz]
quality:
description: Compression quality
type: integer
minimum: 0
maximum: 9
required: [filename]
additionalProperties: false
The above action could be run with juju run <unit> snapshot filename=out.tar.gz compression.kind=gzip
. This demonstrates how to pass objects with the CLI.
Contents:
Key <action>
Status
Required, one for each action.
Purpose
To define an action supported by the charm.
The information stated here will feed into juju actions <charm>
and juju run <charm unit> <action>
, helping a Juju end user know what actions and action parameters are defined for the charm.
See more: Juju |
juju actions
, Juju |juju run
Structure
Name: The name of the key (<action name>
) is defined by the charm author. It must be
a valid Python identifier that does not collide with Python keywords except that it may contain hyphens (which will be mapped to underscores in the Python event handler).
Type: Map.
Value: A series of keys-value pairs corresponding to action metadata and to parameter validation, defined as follows:
<action>:
# Action metadata keys
description: <string>
parallel: <boolean>
execution-group: <string>
# Parameter validation keys, cf. JSON Schema object
params:
<param 1>: <...>
<param 2>: <...>
…
<other key-value pairs>
As you can see, the action definition schema defines a typical JSON Schema object, except:
- It includes some new keys specific to actions:
description
,parallel
, andexecution-group
. - It does not currently support the JSON Schema concepts
$schema
and$ref
. - The
additionalProperties
andrequired
keys from JSON Schema can be used at the top-level of an action (adjacent todescription
andparams
), but also used anywhere within a nested schema.
See more: JSON schema
where
<action>.description
-
Status: Optional but recommended.
-
Purpose: To describe the action.
-
Structure: Type: String.
<action>.parallel
-
Status: Optional, defaults to false.
-
Purpose: To set whether to allow tasks created by this action to execute in parallel.
-
Structure: Type: Boolean.
See more: Juju |
juju run
, Juju | Task
<action>.execution-group
-
Status: Optional, defaults to “”.
-
Purpose: Sets in which execution group to place tasks created by this action.
-
Structure: Type: String.
See more: Juju |
juju run
, Juju | Task
<action>.params
-
Status: Optional.
-
Purpose: To define the fixed parameters for the action. Fixed parameters are those with a name given by a fixed string.
-
Structure: Type: Map. Value: One or more key-value pairs where each key is a parameter name and each value is the YAML equivalent of a valid JSON Schema. The entire map of
<action>.params
is inserted into the action schema object as a “properties” validation keyword. The Juju CLI may read the “description” annotation keyword of each parameter to present to the user when describing the action.
<action>.*
-
Status: Optional.
-
Purpose: To define additional validation or annotation keywords of the action schema object.
-
Structure: Name: A valid keyword of a JSON Schema object instance that will be merged into the action schema object. For example,
additionalProperties
orrequired
. Type: Various.
Contributors: @dannycocks , @mmkay
Last updated a day ago.