From 5fe1a026f3ab06afe3b4f008dac9112aaf1b2362 Mon Sep 17 00:00:00 2001 From: Arthur Lawson Date: Tue, 17 Aug 2021 11:55:02 -0700 Subject: [PATCH] (GH-1465) Add glossary of bolt terms !no-release-note --- documentation/bolt.ditamap | 1 + documentation/glossary.md | 147 +++++++++++++++++++++++++++++++++---- 2 files changed, 133 insertions(+), 15 deletions(-) diff --git a/documentation/bolt.ditamap b/documentation/bolt.ditamap index 12d90259a1..95ba154411 100644 --- a/documentation/bolt.ditamap +++ b/documentation/bolt.ditamap @@ -126,4 +126,5 @@ + diff --git a/documentation/glossary.md b/documentation/glossary.md index a9cb414021..bcdea1dd75 100644 --- a/documentation/glossary.md +++ b/documentation/glossary.md @@ -8,13 +8,34 @@ The Puppet agent software package, also known as `puppet-agent`. ## apply +Use the `apply` [Bolt plan function](writing_plans.md) to apply a block of Puppet code (also known as a manifest +block) to a target. + +Before you can apply a manifest to a target, prepare the target using +the `apply_prep` plan function. See [`apply_prep`](#apply-prep). + +📖 **Related information** + +- [Applying Puppet code](https://puppet.com/docs/bolt/latest/applying_manifest_blocks.html) + +## apply_prep + +A [Bolt plan function](writing_plans.md) that installs the `puppet-agent` package on targets +if needed and collects facts, including any custom facts found in Bolt's module +path. The `puppet-agent` package and facts are required for an `apply`. + +📖 **Related information** + +- [Applying Puppet code](https://puppet.com/docs/bolt/latest/applying_manifest_blocks.html) +- [`apply_prep` example](plan_functions.md#apply-prep) + ## catalog A catalog is a file that describes the desired state of each managed resource on a target. It is a compilation of all the resources that the Puppet agent applies to a given target, as well as the relationships between those resources. -Catalogs are compiled by Bolt from manifests and agent-provided data during an +Bolt compiles catalogs from manifests and agent-provided data during an apply. Bolt then serves the compiled catalog to the agent on a target. Unlike the manifests from which they are compiled, catalogs don't contain any @@ -25,10 +46,15 @@ specific target, and generated by a target. - [Catalog compilation](https://puppet.com/docs/puppet/latest/subsystem_catalog_compilation.html#subsystem_catalog_compilation) +## controller + +A controller is any device that you use to run Bolt. See [Installing Bolt](bolt_installing.md) +for a list of supported platforms. + ## fact A fact is a piece of information about a target, such as its hostname, IP -address, or operating system. +address, or operating system. Facts are typically gathered by Puppet's [Facter](#Facter) tool. ## Facter @@ -36,12 +62,22 @@ Facter is a system inventory tool. Facter reads facts about a target, such as its hostname, IP address, and operating system, and makes them available to Bolt. -Facter includes many built-in facts, and you can view their names and values for -a particular node by running `facter` on the target's command line. +Facter includes many built-in facts, and you can view the names and values for +a particular node by running `bolt task run facts -t mytarget`. + +## future + +A Future is a custom Puppet data type in Bolt. -## feature +A Future object is returned by the `background()` plan function +and can be passed to the `wait()` plan function +to block on the result of the backgrounded code block. -## function +📖 **Related information** + +- [Background function](plan_functions.md#background) +- [Wait function](plan_functions.md#wait) +- [Future custom type](bolt_types_reference.md#future) ## group @@ -51,10 +87,18 @@ that share a common trait by a simple, human-readable name. 📖 **Related information** -- [Inventory files](inventory_file_v2.md) +- [Inventory files](inventory_files.md) ## Hiera +Hiera is a built-in key-value configuration data lookup system, which lets you +separate data from your code. + +📖 **Related information** + +- [How to use Hiera](https://puppet.com/docs/puppet/7/hiera_intro.html) +- [Using bolt with Hiera](hiera.md) + ## inventory The inventory describes the targets that you run Bolt commands on, along with @@ -70,13 +114,24 @@ configuration file named `bolt-project.yaml` alongside the inventory file. 📖 **Related information** -- [Inventory files](inventory_file_v2.md) +- [Inventory files](inventory_files.md) - [inventory.yaml fields](bolt_inventory_reference.md) ## log +Bolt supports multiple log levels. You can configure the log level from the +CLI, or in a project configuration file. Supported logging levels, in order +from most to least information logged, are `trace`, `debug`, `info`, `warn`, +`error`, and `fatal`. + +📖 **Related information** + +- [Bolt logs](logs.md) + ## manifest +A directory for storing your Puppet code files, known as manifests. + ## module Modules are shareable, reusable packages of Puppet content. They can include @@ -91,7 +146,7 @@ and view the modules that are available to the project. 📖 **Related information** -- [Managing modules in Bolt projects](managing_modules.md) +- [Modules](modules.md) - [Installing modules](bolt_installing_modules.md) - [Module structure](module_structure.md) @@ -109,8 +164,8 @@ modulepath, and bundled content, which is added to the end of the modulepath. Modules loaded from a directory listed earlier in the modulepath take precedence over modules with the same name loaded from a directory later in the modulepath. -Bolt will not warn or error when two modules share a name and instead will -ignore modules with a lower precedence. +If Bolt finds two modules with the same name in your modulepath, it ignores the +module with the lower precedence and does not print a warning or error message. ## plan @@ -120,8 +175,8 @@ Plans allow you to do complex operations, such as running multiple actions with one command, computing values for the input for an action, or running certain actions based on the results of another action. -Plans can be written in YAML or in the Puppet language, and can be packaged as -part of a module or project. +You can write a plan in YAML or in the Puppet language, and they can be packaged +as part of a module or project. 📖 **Related information** @@ -130,8 +185,37 @@ part of a module or project. - [Writing plans in YAML](writing_yaml_plans.md) - [Writing plans in the Puppet language](writing_plans.md) +## Plan function + +Plans written in the Puppet language can use Puppet functions that are built +into Bolt and Puppet, or custom functions + +📖 **Related information** + +- [Bolt built-in functions](plan_functions) +- [Puppet built-in functions](https://puppet.com/docs/puppet/7/function.html) +- [More information on custom functions](https://puppet.com/docs/puppet/7/writing_custom_functions.html) + ## plugin +Bolt supports the use of plugins to dynamically load information during a Bolt +run and change how Bolt executes certain actions. Bolt ships with some plugins, +but you can also create your own plugins or install plugins created by other users. + +There are three types of plugins that you can use with Bolt: + +- Reference plugins: Use to fetch data from an external source and store it in a static data object. + +- Secret plugins: Use to create keys for encryption and decryption, to encrypt plaintext, or to decrypt ciphertext. + +- Puppet library plugins: Use to install Puppet libraries on a target when a plan calls the apply_prep function. + +📖 **Related information** + +- [Supported plug-ins](supported_plugins.md) +- [Using plug-ins](using_plugins.md) +- [Writing plug-ins](writing_plugins.md) + ## project A Bolt project is a directory that serves as the launching point for Bolt and @@ -156,6 +240,13 @@ project. ## puppetfile +A puppetfile specifies the modules installed in your project. Bolt manages this +file. Avoid editing it. + +📖 **Related information** + +- [Common project files & directories](projects.md#common-files-and-directories-in-a-project) + ## target A target is a device that Bolt connects to and runs actions on. Targets can be @@ -163,7 +254,7 @@ physical, such as servers, or virtual, such as containers or virtual machines. 📖 **Related information** -- [Inventory files](inventory_file_v2.md) +- [Inventory files](inventory_files.md) ## task @@ -184,6 +275,32 @@ the task runner executes the task. ## transport +A transport defines the connection method that Bolt uses to connect to a target. +SSH, WinRM, and local are some of the most commonly used transports. + +There is a Docker transport that simplifies connecting to Docker containers, +but the SSH transport is useful for gaining a broader understanding of how Bolt +inventory files work. + +📖 **Related information** + +- [Specify a transport](running_bolt_commands.md#specify-a-transport) +- [Transport config options](bolt_transports_reference.md) + ## type -## var +The different custom types that can be used in a Bolt plan. + +📖 **Related information** +- [Bolt Types](bolt_types_reference.md) + +## type alias + +Type aliases 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. + +📖 **Related information** + +- [Type aliases](bolt_types_reference.md#type-aliases) +