Data types

Sections

This page lists custom data types used in Bolt plans and their functions.

Custom data types

Bolt ships with several custom data types that can be used within a plan.

ApplyResult

An apply action returns an ApplyResult. An ApplyResult is part of a ResultSet object and contains information about the apply action.

You can access ApplyResult functions with dot notation, using the syntax: ApplyResult.function.

The following functions are available to ApplyResult objects.

FunctionReturn typeDescription
actionStringThe action performed. ApplyResult.action always returns the string apply.
errorOptional[Error]Returns an Error object constructed from the _error field of the result's value.
messageOptional[String]The _output field of the result's value.
okBooleanWhether the result was successful.
reportHash[String, Data]The Puppet report from the apply action. Equivalent to calling ApplyResult.value['report']. The report is a hash representation of the Puppet::Transaction::Report object, where each property corresponds to a key in the report hash. For more information, see Result keys.
targetTargetThe target the result is from.
to_dataHashA serialized representation of ApplyResult.
valueHashA hash including the Puppet report from the apply action under a report key.

ContainerResult

The run_container plan function returns a ContainerResult object. A ContainerResult is a standalone object (not part of a ResultSet) that includes either the stdout and stderr values from running the container, or an _error object if the container exited with a nonzero exit code.

You can access ContainerResult functions with dot notation, using the syntax: ContainerResult.function.

The following functions are available to ContainerResult objects.

FunctionReturn typeDescription
[]DataAccesses the value hash directly and returns the value for the key. This function does not use dot notation. Call the function directly on the ContainerResult. For example, $result[key].
errorOptional[Error]An object constructed from the _error field of the result's value.
okBooleanWhether the result was successful.
statusStringEither success if the result was successful or failure.
stderrStringThe value of 'stderr' output by the container.
stdoutStringThe value of 'stdout' output by the container.
to_dataHashA serialized representation of ContainerResult.
valueHash[String, Data]A hash including the stdout, stderr, and exit_code received from the container.

ResourceInstance

ResourceInstance objects are used to store the observed and desired state of a target's resource and to track events for the resource. These objects do not modify or interact with a target's resources.

The ResourceInstance data type is experimental and might change in a future release. You can learn more about this data type and how to use it in the experimental features documentation.

You can access ResourceInstance functions with dot notation, using the syntax: ResourceInstance.function.

The following functions are available to ResourceInstance objects.

FunctionReturn typeDescription
[]DataAccesses the state hash directly and returns the value for the specified attribute. This function does not use dot noation. Call the function directly on the ResourceInstance. For example, $resource['ensure'].
add_eventArray[Hash[String, Data]]Add an event for the resource.
desired_stateOptional[Hash[String, Data]]Attributes describing the desired state of the resource.
eventsOptional[Array[Hash[String, Data]]]Events for the resource.
overwrite_desired_stateHash[String, Data]Overwrites the desired state of the resource.
overwrite_stateHash[String, Data]Overwrites the observed state of the resource.
referenceStringThe resources reference string. For example, File[/etc/puppetlabs].
set_desired_stateHash[String, Data]Sets attributes describing the desired state of the resource. Performs a shallow merge with existing desired state.
set_stateHash[String, Data]Sets attributes describing the observed state of the resource. Performs a shallow merge with existing state.
stateOptional[Hash[String, Data]]Attributes describing the observed state of the resource.
targetTargetThe resource's target.
titleStringThe resource title.
typeVariant[String, Type[Resource]]The resource type.

Result

For each target that you execute an action on, Bolt returns a Result object and adds the Result to a ResultSet object. A Result object contains information about the action you executed on the target.

You can access Result functions with dot notation, using the syntax: Result.function.

The following functions are available to Result objects.

FunctionReturn typeDescription
[]Variant[Data, Sensitive[Data]]Accesses the value hash directly and returns the value for the key. This function does not use dot nation. Call the function directly on the Result. For example, $result['key'].
actionStringThe type of result. For example, task or command.
errorOptional[Error]An object constructed from the _error field of the result's value.
messageOptional[String]The _output field of the result's value.
okBooleanWhether the result was successful.
sensitiveOptional[Sensitive[Data]]The _sensitive field of the result's value, wrapped in a Sensitive object. Call unwrap() to extract the value.
statusStringEither success if the result was successful or failure.
targetTargetThe target the result is from.
to_dataHashA serialized representation of Result.
valueHash[String, Data]The output or return of executing on the target.

Command and script result value keys

The Result object returned by the run_command and run_script plan function includes the following keys on the value hash:

KeyTypeDescription
exit_codeNumberThe command's or script's exit code.
merged_outputStringOutput written to both standard error (stderr) and standard out (stdout) in the order that Bolt received the output.
stderrStringOutput written to standard error (stderr).
stdoutStringOutput written to standard out (stdout).

Download result value keys

The Result object returned by the download_file plan function includes the following key on the value hash:

KeyTypeDescription
pathStringThe path to the downloaded file on the local host.

ResultSet

For each target that you execute an action on, Bolt returns a Result object and adds the Result to a ResultSet object. In the case of apply actions, Bolt returns a ResultSet with one or more ApplyResult objects.

You can access ResultSet functions with dot notation, using the syntax: ResultSet.function.

The following functions are available to ResultSet objects.

FunctionReturn typeDescription
[]Variant[Result, ApplyResult, Array[Variant[Result, ApplyResult]]]The accessed results. This function does not use dot notation. Call the function directly on the ResultSet. For example, $results[0].
countIntegerThe number of results in the set.
emptyBooleanWhether the set is empty.
error_setResultSetThe set of failing results.
filter_setResultSetFilters a set of results by the contents of the block.
findOptional[Variant[Result, ApplyResult]]Retrieves a result for a specified target.
firstOptional[Variant[Result, ApplyResult]]The first result in the set. Useful for unwrapping single results.
namesArray[String]The names of all targets that have a Result in the set.
okBooleanWhether all results were successful. Equivalent to $results.error_set.empty.
ok_setResultSetThe set of successful results.
resultsArray[Variant[Result, ApplyResult]]All results in the set.
targetsArray[Target]The list of targets that have results in the set.
to_dataArray[Hash]An array of serialized representations of each result in the set.

Target

The Target object represents a target and its specific connection options.

You can access Target functions with dot notation, using the syntax: Target.function.

The following functions are available to Target objects.

FunctionReturn typeDescription
configOptional[Hash[String, Data]]The inventory configuration for the target. This function returns the configuration set directly on the target in inventory.yaml or set in a plan using Target.new or set_config(). It does not return default configuration values or configuration set in Bolt configuration files.
factsOptional[Hash[String, Data]]The target's facts. This function does not look up facts for a target and only returns the facts specified in an inventory.yaml file or set on a target during a plan run. To retrieve facts for a target and set them in inventory, run the facts plan or puppetdb_fact plan.
featuresOptional[Array[String]]The target's features.
hostOptional[String]The target's hostname.
nameOptional[String]The target's human-readable name, or its URI if a name was not given.
passwordOptional[String]The password to use when connecting to the target.
plugin_hooksOptional[Hash[String, Data]]The target's plugin_hooks configuration options.
portOptional[Integer]The target's connection port.
protocolOptional[String]The protocol used to connect to the target. This is equivalent to the target's transport, expect for targets using the remote transport. For example, a target with the URI http://example.com using the remote transport would return http for the protocol.
resourcesOptional[Hash[String, ResourceInstance]]The target's resources. This function does not look up resources for a target and only returns resources set on a target during a plan run.
safe_nameOptional[String]The target's safe name. Equivalent to name if a name was given, or the target's uri with any password omitted.
target_aliasOptional[Variant[String, Array[String]]]The target's aliases.
transportStringThe transport used to connect to the target.
transport_configHash[String, Data]The merged configuration for the target's transport. This function returns configuration that includes defaults set by Bolt, configuration set in inventory.yaml, configuration set in bolt-defaults.yaml, and configuration set in a plan using set_config().
uriOptional[String]The target's URI.
userOptional[String]The user to connect to the target.
varsOptional[Hash[String, Data]]The target's variables.

Type Aliases

Bolt also ships with type aliases, which provide an alternate name for existing types or lists of types. These types can be used within a plan, and have all of the attributes and functions of whichever Puppet type they are set to in the plan.

TargetSpec

A TargetSpec is an alias for any of the following types:

  • String

  • Target (defined above)

  • Array[TargetSpec] (yep, it's recursive!)

You can pass TargetSpec objects to get_targets() to return an Array[Target]. Generally, you shouldn't need to worry about the distinction between TargetSpec and Target/Array[Target], because most Bolt plan functions handle them automatically. But if your use case requires it, you can use get_targets() to return an exact list of targets.

📖 Related information

  • For more information on how to use TargetSpec in a plan, see Writing plans.

PlanResult

A PlanResult describes the supported return values of a plan. This is the type returned from the run_plan() plan function. Similarly, a parallelize() plan function returns an Array[PlanResult]. Plans can return just about any Puppet type, so the PlanResult can be any of the following types:

  • Boolean

  • Numeric

  • String

  • Undef

  • Error

  • Result

  • ApplyResult

  • ResultSet

  • Target

  • ResourceInstance

  • Array[PlanResults]

  • Hash{String => PlanResult}. In other words, a Hash where each key is a String and each corresponding value is a PlanResult, which could be any of the above types, including another Hash.

📖 Related information

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.