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.

:warning: Starting with Charmcraft 2.5, the actions.yaml file is created automatically from information you provide in the charmcraft.yaml file file. For backwards compatibility, Charmcraft will continue to allow the use of the actions.yaml file, but you may not duplicate keys across the two files.

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:

  1. It includes some new keys specific to actions: description, parallel, and execution-group.
  2. It does not currently support the JSON Schema concepts $schema and $ref.
  3. The additionalProperties and required keys from JSON Schema can be used at the top-level of an action (adjacent to description and params), 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 or required. Type: Various.

Contributors: @charlie4284 , @dannycocks , @mmkay, @tmihoc

Last updated 2 months ago. Help improve this document in the forum or File an issue .