diff --git a/_data/nav/openbolt_5x.yml b/_data/nav/openbolt_5x.yml index b279617c6..dcffdbd11 100644 --- a/_data/nav/openbolt_5x.yml +++ b/_data/nav/openbolt_5x.yml @@ -4,8 +4,6 @@ items: - text: Overview link: index.html - - text: Developer updates - link: developer_updates.html - text: Release notes link: release_notes.html - text: Known issues diff --git a/docs/_openbolt_5x/bolt_installing_modules.md b/docs/_openbolt_5x/bolt_installing_modules.md index 2402945f4..fbdc91cf6 100644 --- a/docs/_openbolt_5x/bolt_installing_modules.md +++ b/docs/_openbolt_5x/bolt_installing_modules.md @@ -178,7 +178,7 @@ OpenBolt updates your modules to the latest available versions and attempts to resolve all of the modules in the project configuration file to ensure that there are no version conflicts between modules and their dependencies. -## Manually specify modules in an OpenBolt project +## Manually specify modules in an OpenBolt project {#manually-specify-modules-in-a-bolt-project} In most cases, you can use the OpenBolt command line to install a new module. However, there are times when you might want to manually specify a module diff --git a/docs/_openbolt_5x/developer_updates.md b/docs/_openbolt_5x/developer_updates.md index 3e16d8f52..5b6f9b178 100644 --- a/docs/_openbolt_5x/developer_updates.md +++ b/docs/_openbolt_5x/developer_updates.md @@ -1,484 +1,40 @@ --- layout: default -title: Developer updates +title: Dotted fact names --- -# Developer updates +# Dotted fact names {#deprecating-dotted-fact-names} -Find out what the Bolt team is working on and why we're making the decisions -we're making. +OpenBolt prints a deprecation warning when a target has a fact whose name +contains a dot, such as `role.name`. The fact can come from the inventory file +or be set during a plan run: -## April 2021 - -### How Bolt loads scripts - -#### Where we are - -Currently, you can point to the location of a script or file as an absolute path -or use a [Module-style load -path](/openvox/latest/file_serving.html). Puppet -module-style paths use the syntax `/`, where the `` is the -name of the module on the modulepath to load from, and `` is the path to the file -within the `/files/` subdirectory. For example, if you provided Bolt with -`ruby_task_helper/task_helper.rb`, Bolt would find the `ruby_task_helper` module on the modulepath, -and look in `ruby_task_helper/files/` for the file `task_helper.rb`. Similarly, when provided -`powershell_task_helper/BoltPwshHelper/BoltPwshHelper.psm1`, Bolt looks in -`powershell_task_helper/files/BoltPwshHelper/` for `BoltPwshHelper.psm1`. - -You can also load tasks and plans as first-class citizens of a module, but with a slightly -different syntax that uses double colons instead of slashes. For example, provided -the task `terraform::apply`, Bolt finds the `terraform` module on the modulepath and looks in -`terraform/tasks` for a task called `apply` (with any file extension). If you used the name -`terraform::subdir::apply`, Bolt would look in `terraform/tasks/subdir/` for `apply`. - -All of these loading methods leave out one of the most common Bolt artifacts: scripts. You can load -a script using module-style file loading, but the script needs to be in the `files/` subdirectory of -a module, not the `scripts/` subdirectory. It's about time scripts got their due as the Bolt -workhorses they are. That's why we're introducing a more elegant and comprehensible workflow for -sharing and loading scripts from a module. With these changes, there's no magic to understanding -where Bolt is loading a script from, and scripts are more visible as the core Bolt entities that -they are. - -#### Where we're going - -Eventually, you'll be able to load scripts and files using their fully qualified names. In other -words, you'll provide Bolt with a more specific path to the script or file within a module. Files -will remain in a module's `files/` subdirectory, but scripts will live in a new `scripts/` -subdirectory. For example, to load a file you'll provide Bolt with `/files/myfile`. To -load a script, you'll use the syntax `/scripts/myscript.sh`. - -This more detailed syntax will make scripts first-class citizens in Bolt, and disambiguate loading -files vs loading scripts from a module. Plus, it is easier to understand where files are coming from -if the fully qualified name is provided, as opposed to magically looking in the `files/` directory -for a file. Once this feature is fully rolled out, the old syntax `/myfile` will -no longer load from the `files/` subdirectory of a module. - -#### How we get there 🚲 - -This is a big change in how Bolt loads file and scripts, so it's going to take a few different -phases to transition from where we are to where we're going. Inevitably, in order for a module to -function with older versions of Bolt, module authors will need to have scripts in two places at some -point: one under the `files/` directory and one in the new location that Bolt will load from. We -know this is a burden on content authors, but we think it's worth the improved experience for users -new to the Puppet ecosystem and Bolt. - -**Phase 1**: In this phase, fully qualified name will be opt-in using the new `file_paths` -project-level configuration option, which is nested under the `future` key. When provided with the -following paths, Bolt will search these subdirectories in order: - -- Provided: `module/myscript.sh` - - Load from `files/myscript.sh` (old behavior) -- Provided: `module/scripts/myscript.sh` - - Load from `files/scripts/myscript.sh` (old behavior) - - Fall back to `scripts/myscript.sh` (new behavior) -- Provided: `module/files/myscript.sh` - - Load from `files/files/myscript.sh` (old behavior) - - Fall back to `files/myscript.sh` (new behavior) - -**Phase 2**: In this phase, we'll switch the precedence of paths that Bolt -searches: so Bolt will first look in the new location for a given path, and then -the old location. Because this is a breaking change, it will either be gated by -the same future flag as above, or will happen with a major version release. - -- Provided: `module/myscript.sh` - - Load from `files/myscript.sh` (old behavior) -- Provided: `module/scripts/myscript.sh` - - Load from `scripts/myscript.sh` (new behavior) - - Fall back to `files/scripts/myscript.sh` (old behavior) -- Provided: `module/files/myscript.sh` - - Load from `files/myscript.sh` (new behavior) - - Fall back to `files/files/myscript.sh` (old behavior) - -**Phase 3**: In this phase, we will issue a deprecation warning when Bolt finds -a script in a `files` directory, or if you provide Bolt with the old -module-style name. - -- Provided: `module/myscript.sh` - - Raise deprecation warning -- Provided: `module/scripts/myscript.sh` - - Raise a deprecation warning if file is found at `files/scripts/myscript.sh` -- Provided: `module/files/myscript.sh` - - Raise a deprecation warning if file is found at `files/files/myscript.sh` - -**Phase 4**: In the final phase, Bolt will only load scripts from specific paths -and will error if provided a non-specific module syntax. - -- Provided: `module/myscript.sh` - - Error -- Provided: `module/scripts/myscript.sh` - - Load from `scripts/myscript.sh` -- Provided: `module/files/myscript.sh` - - Load from `files/myscript.sh` - -We don't have a timeline yet for when each phase will happen, beyond that Phase 1 is already in -progress and should be rolled out in late-April or early-May. We will communicate when we're moving -into a new phase as best we can once we are ready to move into that phase. - -## March 2021 - -### Deprecating dotted fact names - -With the release of Facter 4, dotted fact names are automatically converted to -structured facts. For example, the custom fact `role.name = server` becomes the -following structured fact: - -```puppet -{ - "role" => { - "name" => "server" - } -} +```text +Target 'localhost' includes dotted fact names: 'role.name'. Dotted fact names are deprecated and Bolt does not automatically convert facts with dotted names to structured facts. For more information, see https://pup.pt/bolt-dotted-facts [ID: dotted_fact_name] ``` -This is a significant change from earlier versions of Facter, which permitted -dotted fact names. - -Because Bolt allows you to set facts in the inventory file or during a plan run, -and uses Facter directly (such as when running the `apply_prep` function) and -indirectly (such as when making a PuppetDB query), we've updated Bolt to warn -you when it detects a dotted fact name. - -If Bolt detects that a target has a dotted fact name set in either the inventory -or during a plan run, it displays a deprecation warning. Bolt does not -automatically convert these facts to structured facts, which is inconsistent -behavior with Facter 4. - -To suppress these deprecation warnings, you can either update your facts or add -the `dotted_fact_name` ID to the `disable-warnings` option in your project -configuration. - -## November 2020 - -### Changes coming in Bolt 3.0 - -With the new year fast approaching, the team is preparing to release the next -major version of Bolt: **Bolt 3.0**! Over the next few releases you'll start -to see deprecation warnings for specific features and configuration options that -are slated for removal in Bolt 3.0. To help you prepare for the release, we've -compiled a list of expected changes and removals. - -#### Changes - -- **Ship with Puppet 7** - - Bolt packages will ship with Puppet 7. This change should not impact most - users, but changes to the Puppet language might require updating your Bolt - plans. - - To read more about the changes in Puppet 7, see the [Puppet 7 release - notes](/openvox/latest/release_notes.html). - -- **Ship with Ruby 2.7** - - Bolt packages will ship with Ruby 2.7 instead of Ruby 2.5.1. This change will - not affect most users who install the Bolt package, as Bolt packages ship with - their own Ruby. However, gem installs will require Ruby 2.7 or higher, and - users who install gems with Bolt's Ruby might also need to update their gems. - -- **New default modulepath** - - Since the introduction of the module feature in Bolt 2.30.0, Bolt has used a - shorter, simpler default modulepath when a project enables the feature. - Starting in Bolt 3.0, the module management feature will be enabled for all - projects, meaning the default modulepath will also be updated. - - To read more about the new module management workflow and the updated - modulepath, see the [modules overview](modules.html). - -- **Move PowerShell module to PowerShell Gallery** - - The PuppetBolt PowerShell module will be distributed through [PowerShell - Gallery](https://www.powershellgallery.com/). - -- **Ship with `bolt.bat` file on Windows** - - Bolt packages on Windows will ship with a `bolt.bat` batch file. This will - disable the `bolt` and `Invoke-BoltCommandLine` commands in Powershell. Users - should instead use the built-in [PowerShell - cmdlets](bolt_cmdlet_reference.html). - -- **New default configuration for the local transport** - - In Bolt 2.x, Bolt applied the following settings to targets named `localhost` by default: - - ```yaml - targets: - - name: localhost - config: - transport: local - local: - interpreters: - .rb: RbConfig.ruby # This uses the Ruby we ship with Bolt - features: - - puppet-agent - ``` - - These settings will now be applied to all targets using the local transport. Settings can be - overridden at the target level in inventory. They can also be enabled or disabled starting in Bolt - 2.37 using the `bundled-ruby` local transport config option. - -- **`apply_settings` configuration option renamed to `apply-settings`** - - Most other configuration options in Bolt use hyphens instead of underscores. - - For a full list of project configuration options, see the [bolt-project.yaml - options](bolt_project_reference.html) reference page. - -- **`plugin_hooks` configuration option renamed to `plugin-hooks`** - - Most other configuration options in Bolt use hyphens instead of underscores. - - For a full list of project configuration options, see the [bolt-project.yaml - options](bolt_project_reference.html) reference page. - -- **`puppetfile` configuration option renamed to `module-install`** - - This configuration option has a confusing name that implies the path to a - Puppetfile. The new name more clearly indicates that it configures how modules - are installed. - - For a full list of project configuration options, see the [bolt-project.yaml - options](bolt_project_reference.html) reference page. - - - **`target` key for YAML plan steps renamed to `targets`** - - This key has been deprecated in favor of the `targets` key. - - For more information about writing YAML plans, see [writing YAML - plans](writing_yaml_plans.html). - -- **`source` key for YAML plan `upload` step renamed to `upload`** - - This key has been deprecated in favor of the `upload` key. - - For more information about upload YAML plan step, see [writing YAML - plans](writing_yaml_plans.html#file-upload-step). - -- **`private-key` and `public-key` parameters for pkcs7 plugin renamed to - `private_key` and `public_key`** - - These keys have been deprecated in favor of the `private_key` and `public_key` - parameters. - - For more information about the `pkcs7` plugin, see the [Forge - documentation](https://forge.puppet.com/puppetlabs/pkcs7). +OpenBolt keeps such a fact under its dotted name. It doesn't turn `role.name` +into a `role` fact that contains `name`. OpenFact does the same by default, but +when its [`force-dot-resolution`](/openfact/latest/configuring_openfact.html) +setting is `true`, it treats the dot as structure. On targets with that setting, +the same name means a structured fact to OpenFact and a flat one to OpenBolt. -#### Removals - -- **Packages for Debian 8 will be removed** - - Debian 8 reached end-of-life on June 30, 2020. - - For a full list of supported platforms, see [installing - Bolt](bolt_installing.html). - -- **Support for `bolt.yaml` configuration file will be removed** - - Bolt will no longer support the `bolt.yaml` configuration file. Instead, you - should use `bolt-project.yaml` in your project and `bolt-defaults.yaml` at the - user and system level. - - For more information about configuring your project, see [configuring - Bolt](configuring_bolt.html). - -- **`bolt puppetfile *` commands and `*-BoltPuppetfile` PowerShell cmdlets will - be removed** - - These commands are being removed in favor of the new `bolt module *` commands - and `*-BoltModule` PowerShell cmdlets. - - To read more about the new module management workflow and the updated - modulepath, see the [modules overview](modules.html). - -- **Support for PowerShell 2.0 will be dropped** - - PowerShell 2.0 has been deprecated since 2017 and adds unecessary complexity - for Bolt. Bolt will no longer support running on controllers when using - PowerShell 2.0 or when connecting to remote targets running PowerShell 2.0. - -- **`--boltdir` command-line option will be removed** - - This command-line option has been deprecated in favor of `--project`. - -- **`--configfile` command-line option will be removed** - - This command-line option provides little value and adds unecessary complexity - to Bolt. Instead, use the `--project` command-line option to run Bolt from a - specific project. - -- **`--debug` command-line option will be removed** - - This command-line option has been deprecated in favor of `--log-level debug`. - Additionally, Bolt now writes a debug log to `bolt-debug.log` by default, - removing the need to explicitly run in debug mode for most users. - -- **`--description` command-line option will be removed** - - This command-line option provides little value. - -- **`inventoryfile` configuration option will be removed** - - Bolt already offers the `--inventoryfile` command-line option to use a - non-default inventory file for a single run. However, there is little value in - configuring a permanent non-default inventoryfile for a project. - -- **`notice` log level will be removed** - - The `notice` log level has already been soft-deprecated. Bolt does not log - any messages at this level. Messages logged in apply blocks using the `notice()` - function are logged by Bolt at the `info` level. - -#### Updating your project - -While some of these changes will require you to manually update files, others -can be made automatically with Bolt. We'll be updating the project migrate -command to automatically update your Bolt project to use the latest features and -best practices. You can run this command now to pick up any changes that have -already been made, or wait until Bolt 3.0 is released to pick up all changes at -once. - -To migrate your project, run the following command in your project directory: - -_\*nix shell command:_ - -```console -bolt project migrate -``` - -_PowerShell cmdlet:_ - -```powershell -Update-BoltProject -``` - -Keep in mind that this command only makes changes to a project. Changes to plans -and configuration files at the user and system level will need to be made -manually. For more information on how the `migrate` command changes your project -files, see [Migrate a Bolt project](projects.html#migrate-an-openbolt-project). - -### Puppet 7 Release Prep - -[Puppet 7](https://puppet.com/docs/puppet/7.0/puppet_index.html) is set to be -released November 19th, 2020. While the Bolt package won't be pulling in Puppet -7 until early next year, the `puppet_agent::install` task bundled with Bolt will -pick up Puppet 7 agents by default when the packages are available. This means -that using the `apply_prep()` Bolt plan function or the install task directly -will be pulling in a major version bump for the agent. While we don't anticipate -any of the changes in the agent to affect Bolt users, if you find you need to -use the Puppet 6 agent, you can configure `apply_prep()` and the -`puppet_agent::install` task to do so. - -The `puppet_agent::install` task accepts a `collections` parameter that tells -the task which collection to download the package from. This defaults to -`puppet` which maps to the latest collection, but you can set this value to -`puppet6` to pull in the latest Puppet 6 agent. You can pass this parameter on -the command line: - -_\*nix shell command:_ - -```console -bolt task run puppet_agent::install -t mytargets collection='puppet6' -``` - -_PowerShell cmdlet:_ - -```powershell -Invoke-BoltTask -Name puppet_agent::install -Targets mytargets collection='puppet6' -``` - -Or to the `run_task()` plan function: - -```puppet -run_task('puppet_agent::install', $targets, { collection => 'puppet6' }) -``` - -If you need the `apply_prep()` plan function to install the Puppet 6 agents -instead of Puppet 7, you can configure this by [configuring the puppet_library -plugin hook](using_plugins.html#puppet-library-plugins) in either -`bolt-project.yaml` or `bolt-defaults.yaml`: +To avoid the ambiguity, use structured facts instead of dotted names. For +example, in an inventory file: ```yaml -plugin_hooks: - puppet_library: - task: puppet_agent - collection: puppet6 +targets: + - uri: web01.example.com + facts: + role: + name: server ``` -## September 2020 - -### Module management in Bolt projects - -We've recently finished work on a major improvement to Bolt projects: module -management! With this improvement, you no longer need to manually manage your -modules and their dependencies in a Puppetfile and can instead automate that -process with Bolt. +To suppress the warning instead, add the `dotted_fact_name` ID to the +`disable-warnings` option in your project configuration: -If you want to try it out, [create a -project](bolt_installing_modules.html#create-an-openbolt-project-with-pre-installed-modules) -or migrate an existing project with the following command: - -_\*nix shell command:_ - -```console -bolt project migrate -``` - -_PowerShell cmdlet:_ - -```powershell -Update-BoltProject +```yaml +# bolt-project.yaml +disable-warnings: + - dotted_fact_name ``` - -#### Why are we making these changes? - -So why did we make this change to how Bolt manages modules? Because managing a -project's modules could be a frustrating process that includes multiple steps: - -- Find the module you want to add to your project -- Find all of the dependencies for that module -- Determine which version of each module is compatible with every other module - you have installed -- Manually update your Puppetfile to include each module -- Install the Puppetfile - -By offloading most of this work to Bolt, you now only need to list the modules -you care about in your project configuration. Bolt takes care of resolving a -module's dependencies and installing compatible versions. This greatly -simplifies the process of managing your project's modules: - -- Find the module you want to add to your project -- Tell Bolt to install the module with all of its dependencies - -With these changes, we've also updated where Bolt installs modules. You no -longer need to worry about accidentally overwriting local modules when you -install a Puppetfile, because Bolt installs modules to a special directory that -is not part of the configured modulepath. - -The new module management feature is available starting with **Bolt 2.30.0**. To -try it out, [create a -project](bolt_installing_modules.html#create-an-openbolt-project-with-pre-installed-modules) -or [migrate an existing project](./projects.html#migrate-an-openbolt-project). - -Here's a summary of what's changed: - -- **Managed module installation directory:** Bolt now installs modules it - manages into the `.modules/` directory instead of `modules/`. Avoid committing - `.modules/` to source control. Your users can download your Bolt project and - use the `bolt module install` *nix shell command, or `Install-BoltModule` - cmdlet to download the required modules. -- **Non-managed module directory:** Bolt no longer uses the `site-modules/` - directory. Store any modules that you don't want Bolt to manage in the - `modules/` directory. -- **Module configuration:** Your `bolt-project.yaml` file contains a `modules` - key that lists the direct module dependencies of your Bolt project. Unless you - need to pin a module to a specific version, avoid editing the `modules` list - directly. Instead, use the `bolt module add` command. -- **Puppetfile:** The Puppet file is now a lock file. Bolt generates a - Puppetfile each time you modify your modules with a Bolt command. Do not edit - the Puppetfile directly. Instead, use Bolt commands to manage your modules, - and rely on Bolt to manage the Puppetfile. You can compare a Puppetfile to a - [Gemfile.lock](https://bundler.io/rationale.html#checking-your-code-into-version-control) - file in Ruby, or a - [yarn.lock](https://classic.yarnpkg.com/en/docs/yarn-lock/) file in Yarn. -- **modulepath:** The new modulepath is `['modules']` and Bolt always appends - `.modules` to the modulepath. diff --git a/docs/_openbolt_5x/experimental_features.md b/docs/_openbolt_5x/experimental_features.md index 74d95f740..c224f9012 100644 --- a/docs/_openbolt_5x/experimental_features.md +++ b/docs/_openbolt_5x/experimental_features.md @@ -5,33 +5,25 @@ title: 🧪 Experimental features # 🧪 Experimental features -Most larger Bolt features are released initially in an experimental or unstable -state. This allows the Bolt team to gather feedback from real users quickly -while iterating on new functionality. Almost all experimental features are -eventually stabilized in future releases. While a feature is experimental, its -API might change, requiring the user to update their code or configuration. The -Bolt team attempts to make these changes painless by providing useful warnings -around breaking behavior where possible. +The features on this page are experimental. While a feature is experimental, its +configuration, behavior, or API might change between minor releases, so you +might need to update your code or configuration when you upgrade OpenBolt. ## Configuration policies and the `policy` command -This feature was introduced in [Bolt 3.21.0](https://github.com/puppetlabs/bolt/blob/main/CHANGELOG.md#bolt-3210-2021-12-16). - -### What are policies? - Configuration policies are public Puppet classes stored in the `manifests/` directory of modules on the modulepath. Just like other Puppet code, you can apply policies directly to one or more targets. -### Policies in a Bolt project's configuration file +### Policies in an OpenBolt project's configuration file The project configuration file, `bolt-project.yaml`, supports a `policies` key which lists the policies available to a project. A Puppet class becomes a policy when you list it under the `policies` key. If you do not configure the -`policies` key, no policies will be available for Bolt to apply. +`policies` key, no policies will be available for OpenBolt to apply. You can manually add policies to the `policies` key in `bolt-project.yaml`, or -manage policies using the Bolt command line. The `policies` key supports glob +manage policies using the OpenBolt command line. The `policies` key supports glob patterns for easily listing multiple policies. For example, `myproject::*` includes both the `myproject::admin` and `myproject::sshkeys` policies. @@ -49,7 +41,7 @@ policies: ### Creating new policies -You can use Bolt to create a new policy in your project and add it to the +You can use OpenBolt to create a new policy in your project and add it to the `policies` key in your project configuration. For example, to create a new project-level policy named `myproject::user`, run: @@ -65,7 +57,7 @@ project-level policy named `myproject::user`, run: New-BoltPolicy -Name myproject::user ``` -Bolt creates an empty class in the project's `manifests/` directory that you can +OpenBolt creates an empty class in the project's `manifests/` directory that you can populate with code. Policy names must follow [class naming conventions](/openvox/latest/lang_reserved.html#classes-and-defined-resource-types). @@ -113,7 +105,7 @@ Modulepath Applying policies is similar to [applying Puppet code](applying_manifest_blocks.html), with -the addition that you can apply one or more policies at a time. The Bolt +the addition that you can apply one or more policies at a time. The OpenBolt commands for applying policies accept a single policy name or a comma-separated list of policy names to apply to a list of one or more targets. @@ -146,25 +138,23 @@ Successful on 1 target: mytarget Ran on 1 target in 15.2 sec ``` -Before applying policies, Bolt uses the `apply_prep` function to collect facts and +Before applying policies, OpenBolt uses the `apply_prep` function to collect facts and ensure that the puppet-agent package is available on each target. For more -information on how Bolt uses `apply_prep`, see [Applying manifest +information on how OpenBolt uses `apply_prep`, see [Applying manifest blocks](applying_manifest_blocks.html#applying-manifest-blocks-from-a-puppet-plan). -Bolt creates a single line of Puppet code to compile and apply to the provided -targets. This line of code includes the syntax `include ` and Bolt +OpenBolt creates a single line of Puppet code to compile and apply to the provided +targets. This line of code includes the syntax `include ` and OpenBolt logs the line at the debug level. ## `run_container` plan step -This feature was introduced in [Bolt 3.5.0](https://github.com/puppetlabs/bolt/blob/main/CHANGELOG.md#bolt-350-2021-3-29). - Currently available as a Puppet plan function, `run_container()` runs a provided image and returns the `stdout`, `stderr`, and `exit_code` for that image. The function supports several options, including `cmd` to specify a command to run in the container, `volumes` to mount volumes to the container, and `ports` to publish ports from the container on the host. You can see all the supported options in the [plan function documentation](plan_functions.html#run_container). -The function runs the container on the Bolt controller, not on remote targets. This function is +The function runs the container on the OpenBolt controller, not on remote targets. This function is supported on both \*nix and Windows systems. This plan clones the [Relay repository](https://github.com/puppetlabs/relay), builds the Go binary in a @@ -186,7 +176,7 @@ plan bolt ( ## Podman support -Bolt now has experimental support for [Podman](https://podman.io/), a daemonless container engine. +OpenBolt has experimental support for [Podman](https://podman.io/), a daemonless container engine. The Podman transport supports connecting to containers managed by Podman on the local system. The Podman transport accepts many of the same configuration options as the Docker transport. You can see the full list of supported configuration options [on the transport reference @@ -208,7 +198,7 @@ targets: ## FreeBSD jails support -Bolt now has experimental support for [FreeBSD +OpenBolt has experimental support for [FreeBSD jails](https://docs.freebsd.org/en/books/handbook/jails/), a lightweight virtualization solution that allow for the creation of isolated environments within a single FreeBSD system. The jail transport supports connecting to jails running on the local system. @@ -232,10 +222,8 @@ targets: ## Streaming output -This feature was introduced in [Bolt 3.2.0](https://github.com/puppetlabs/bolt/blob/main/CHANGELOG.md#bolt-320-2021-3-08). - -You can set the new `stream` output option in `bolt-project.yaml` or `bolt-defaults.yaml`, or -specify the option on the command line as `--stream`. Bolt streams results back to the console as +You can set the `stream` output option in `bolt-project.yaml` or `bolt-defaults.yaml`, or +specify the option on the command line as `--stream`. OpenBolt streams results back to the console as they are received, with the target's safe name (the URI without the password included) and the stream (either 'out' or 'err') appended to the message, like so: @@ -250,15 +238,13 @@ Finished on docker://puppet_6_node: Hello! ``` -As you can see, when you configure output to stream, Bolt may print to the console twice: -once as the actions are running, and again after Bolt prints the results. You can prevent -Bolt from printing the results once the action has completed by specifying the `--no-verbose` +As you can see, when you configure output to stream, OpenBolt may print to the console twice: +once as the actions are running, and again after OpenBolt prints the results. You can prevent +OpenBolt from printing the results once the action has completed by specifying the `--no-verbose` command-line option. ## LXD Transport -This feature was introduced in [Bolt 3.2.0](https://github.com/puppetlabs/bolt/blob/main/CHANGELOG.md#bolt-320-2021-3-08). - The LXD transport supports connecting to Linux containers on the local system. Similar to the Docker transport, the LXD transport accepts the name of the container as the URI, and connects to the container by shelling out to the `lxc` command. The example inventory file below demonstrates @@ -274,24 +260,21 @@ targets: ## Plugin caching -This feature was introduced in [Bolt -2.37.0](https://github.com/puppetlabs/bolt/blob/main/CHANGELOG.md#bolt-2370-2020-12-07). - -Bolt supports the use of plugins to dynamically load information during a Bolt run and change how -Bolt executes certain actions. Bolt also loads all configuration plugins for most Bolt commands, and +OpenBolt supports the use of plugins to dynamically load information during an OpenBolt run and change how +OpenBolt executes certain actions. OpenBolt also loads all configuration plugins for most OpenBolt commands, and all inventory plugins for any action that requires the inventory, even if the action only uses a subset of targets from the inventory. Plugins can sometimes take a long time to execute, and several -plugin invocations can add quite a bit of start up time to any Bolt command regardless of whether it +plugin invocations can add quite a bit of start up time to any OpenBolt command regardless of whether it uses the plugin results. -To mitigate the time it takes for Bolt to load plugins, we've introduced plugin caching. Plugin +To reduce the time OpenBolt spends loading plugins, you can turn on plugin caching. Plugin caching is enabled by configuring a Time to Live (TTL) for the cache, either by setting a default TTL for all plugins with the `plugin-cache` project configuration option or by setting `ttl` under -the `_cache` option for an individual plugin invocation. The TTL is always in seconds. Bolt caches -plugin results inside the Bolt project, and removes all expired cache entries whenever it -uses a cache result. This prevents cache entries from getting orphaned and never removed. Bolt +the `_cache` option for an individual plugin invocation. The TTL is always in seconds. OpenBolt caches +plugin results inside the OpenBolt project, and removes all expired cache entries whenever it +uses a cache result. This prevents cache entries from getting orphaned and never removed. OpenBolt identifies a cache result based on a hash (delightfully named 'bubblebabble') of the entire plugin -invocation, minus the `_cache` key. If any element of the plugin invocation changes, Bolt reloads +invocation, minus the `_cache` key. If any element of the plugin invocation changes, OpenBolt reloads the plugin and updates the cache. You can set `ttl` to 0 to disable caching for a particular plugin. Caching is disabled by default, @@ -303,7 +286,7 @@ invocations. future release. Users can clear all cache entries using the `--clear-cache` or `-ClearCache` command-line option -with any Bolt command. +with any OpenBolt command. This inventory sets a TTL of 1 hour, or 3600 seconds, for the PuppetDB plugin: @@ -327,13 +310,9 @@ plugin-cache: > **NOTE**: The same cache and cache configuration is used for the `resolve_reference()` plan function. -## Parallelism in Bolt plans - -The `parallelize()` plan function was introduced in [Bolt -2.35.0](https://github.com/puppetlabs/bolt/tree/main/CHANGELOG.md#bolt-2350-2020-11-16). -The `background()` and `wait()` plan functions were introduced in [Bolt 3.9.0](https://github.com/puppetlabs/bolt/tree/main/CHANGELOG.md#bolt-390-2021-05-25). +## Parallelism in OpenBolt plans -For context, Bolt plan functions have always run concurrently across targets - that is, if a +For context, OpenBolt plan functions have always run concurrently across targets - that is, if a function takes a list of targets and operates on them, the function runs that step on each target in parallel. For example, the following plan runs `hostname` on all targets at the same time, waits for all targets to finish, and then runs `whoami` on all targets at the same time. @@ -349,7 +328,7 @@ plan myplan(TargetSpec $targets) { In the example above, `target3` has to wait for `hostname` to finish on `target1` and `target2` before it can run `whoami`. -While useful, this form of parallelism is limited. Bolt plans have a few methods that allow a block +While useful, this form of parallelism is limited. OpenBolt plans have a few methods that allow a block of plan steps to execute in the background while other parts of the plan execute in parallel: * The `background` plan function begins executing a block of code in parellel with the main plan @@ -389,7 +368,7 @@ The code block has access to all existing variables when it's created, and has i new variables are not accessible outside the code block. Plans will return normally even when they have Futures running in the background, and those -Futures will continue to execute in parallel. However, Bolt itself will not exit until all Futures +Futures will continue to execute in parallel. However, OpenBolt itself will not exit until all Futures have completed in order to ensure that all work is finished. Any errors raised after the calling plan has finished will be logged at warn level for visibility. @@ -409,7 +388,7 @@ background. Then the backgrounded commands and tasks are waited on before contin # $targets = target1,target2,target3 plan myplan(TargetSpec $targets) { $binary_future = background("Run mycoolbinary") || { - # These commands execute sequentially per target. Bolt connects to the targets in + # These commands execute sequentially per target. OpenBolt connects to the targets in # parallel, but waits for the cp command to finish before running chmod run_command("cp /home/user/Downloads/mycoolbinary /home/user/bin", $targets) run_command("chmod +x /home/user/bin/mycoolbinary", $targets) @@ -434,7 +413,7 @@ The function blocks until the Futures finish, with an optional timeout. If provi unfinished Futures raise a timeout error if they have not completed within the timeout. You can return errors instead of raising them by passing `_catch_errors => true` to `wait()`. The `wait()` function returns the results from the Future blocks once they've all finished. If a Future errors, -Bolt only raises the error after all other Futures finish executing and return to `wait()`. +OpenBolt only raises the error after all other Futures finish executing and return to `wait()`. ### `parallelize()` plan function @@ -477,7 +456,7 @@ Within a backgrounded code block, only the following functions can run in parall * `download_file`. You can run other functions from a parallelize or background block, but those functions will block -execution on other targets until they complete. For example, in the following plan, Bolt can start +execution on other targets until they complete. For example, in the following plan, OpenBolt can start running `task2` and `task3` while `task1` is still executing. However, it cannot start `task4` while `out::message` is executing on any of the targets. @@ -539,16 +518,16 @@ $result = wait($futures) out::message($result) ``` -If any step of the block errors, Bolt stops executing the block for that target, but continues +If any step of the block errors, OpenBolt stops executing the block for that target, but continues executing for all other targets from the input array. When the block finishes, if there is an error in the result array, the plan throws a `PlanFailure` and includes the entire result array in the -`details` key of the failure. If the block is wrapped in a `catch_errors()` block, Bolt catches the +`details` key of the failure. If the block is wrapped in a `catch_errors()` block, OpenBolt catches the `PlanFailure` and continues to execute the plan. If you've provided `_catch_errors => true` -to `wait()`, Bolt returns any errors raised and the plan continues to execute. +to `wait()`, OpenBolt returns any errors raised and the plan continues to execute. #### Viewing failing results in parallel blocks -When an action fails in a parallel block, such as a task returning an error, Bolt +When an action fails in a parallel block, such as a task returning an error, OpenBolt does not print the error result to the console. For example, the following plan runs a non-existent command on targets in parallel: @@ -566,7 +545,7 @@ plan example ( } ``` -Bolt does not print the error result from the targets the command is run on, +OpenBolt does not print the error result from the targets the command is run on, making it difficult to know why the command failed: ```console @@ -624,18 +603,14 @@ parallel block failed on 2 targets ## `ResourceInstance` data type -This feature was introduced in [Bolt -2.10.0](https://github.com/puppetlabs/bolt/blob/main/CHANGELOG.md#bolt-2100-2020-05-18). +Outside this data type, OpenBolt's ability to interact with Puppet's Resource +Abstraction Layer is limited: the `apply` function generates catalogs and +returns events, and the `get_resources` plan function queries resources on a +target. The `ResourceInstance` data type lets plan authors build resource-based +logic into their plans, for a discover-inspect-execute workflow with resources +on remote systems. -Bolt has had a limited ability to interact with Puppet's Resource Abstraction -Layer. You could use the `apply` function to generate catalogs and return -events, and the `get_resources` plan function can be used to query resources on -a target. The `ResourceInstance` data type is the first step in enabling plan -authors to build resource-based logic into their plans to enable a -discover-inspect-execute workflow for interacting with resources on remote -systems. - -Use the `ResourceInstance` data type is used to store information about a single +The `ResourceInstance` data type stores information about a single resource on a target, including its observed state, desired state, and any related events. @@ -649,7 +624,7 @@ related events. The recommended way to create `ResourceInstance` objects is by setting them directly on a `Target` object using the `Target.set_resources` function. Use the function to set one or more resources on a target at a time. You can read more -about this function in [Bolt plan functions](plan_functions.html#set_resources). +about this function in [OpenBolt plan functions](plan_functions.html#set_resources). The `Target.set_resources` function can set existing `ResourceInstance` objects on a target, or take hashes of parameters to create new `ResourceInstance` @@ -679,7 +654,7 @@ $target.set_resources( on. > > **Note:** If the `target` parameter is any target other than the one you are - setting the resource on, Bolt will raise an error. + setting the resource on, OpenBolt will raise an error. When setting resources using existing `ResourceInstance` objects, you can pass either a single `ResourceInstance` or an array of `ResourceInstance` objects. @@ -693,10 +668,10 @@ $target.set_resources( ``` > **Note:** If the target for a `ResourceInstance` does not match the target it - is being set on, Bolt will raise an error. + is being set on, OpenBolt will raise an error. A target can only have a single instance of a given resource. If you set a -duplicate resource on a target, Bolt shallow merges the `state` and +duplicate resource on a target, OpenBolt shallow merges the `state` and `desired_state` of the duplicate resource with the `state` and `desired_state` of the existing resource and adds any `events` for the duplicate resource to the existing resource. @@ -777,7 +752,7 @@ using [the data type's functions](bolt_types_reference.html#resourceinstance). The `ResourceInstance` data type has several built-in functions. These range from accessing the object's attributes to modifying and overwriting state. For a -full list of the available functions, see [Bolt data +full list of the available functions, see [OpenBolt data types](bolt_types_reference.html#resourceinstance). ### Example usage @@ -851,15 +826,12 @@ $apply_results.each |$result| { ## Native SSH transport -This feature was introduced in [Bolt -2.10.0](https://github.com/puppetlabs/bolt/blob/main/CHANGELOG.md#bolt-2100-2020-05-18). - -Bolt's SSH transport uses the ruby library `net-ssh`, which is a pure ruby +OpenBolt's SSH transport uses the ruby library `net-ssh`, which is a pure ruby implementation of the SSH2 client protocol. While robust, the library lacks support for some features and algorithms that are available in native SSH. When -you use the native SSH transport, Bolt uses the SSH executable you've +you use the native SSH transport, OpenBolt uses the SSH executable you've specified instead of using `net-ssh`. Essentially, using the native SSH -transport is the same as running SSH on your command line, but with Bolt +transport is the same as running SSH on your command line, but with OpenBolt managing the connections. To use the native SSH transport, under the `config` option in your inventory @@ -875,14 +847,14 @@ ssh: ``` The value of `ssh-command` can be either a string or an array, and you can -provide any command-line options to the command. Bolt appends -Bolt-configuration settings to the command, as well as the specified target, -when connecting. Not all Bolt configuration options are supported using the +provide any command-line options to the command. OpenBolt appends +its configuration settings to the command, as well as the specified target, +when connecting. Not all OpenBolt configuration options are supported using the native SSH transport, but you can configure most options in your OpenSSH Config. See [Transport configuration options](bolt_transports_reference.html#ssh) for a list -of supported Bolt SSH options. +of supported OpenBolt SSH options. -Bolt transports have two main functions: executing remotely, and copying files +OpenBolt transports have two main functions: executing remotely, and copying files to the remote targets. `ssh-command` is what configures the remote execution, and `copy-command` configures the copy command. The default is `scp -r`, and `rsync` is not supported at this time. @@ -927,7 +899,7 @@ To encrypt SSH connections using the unsupported algorithm Ciphers+=chacha20-poly1305@openssh.com ``` -2. In your inventory file, configure Bolt to use the SSH shell command: +2. In your inventory file, configure OpenBolt to use the SSH shell command: ```yaml # inventory.yaml diff --git a/docs/_openbolt_5x/inventory_files.md b/docs/_openbolt_5x/inventory_files.md index c132bbad1..5811fd148 100644 --- a/docs/_openbolt_5x/inventory_files.md +++ b/docs/_openbolt_5x/inventory_files.md @@ -445,9 +445,9 @@ for a given target, running on the `fruits` group also resolves the plugin. ## Inventory file versioning -This page documents version 2 inventory files. Version 1 inventory files are -deprecated and lack features like plugins. If you're using Bolt 2.0 or later, -use version 2 inventory files. If you need to migrate your inventory files from +This page documents version 2 inventory files, the only version OpenBolt reads. +OpenBolt stops with an error when it finds a version 1 inventory file, which +lists targets under a `nodes` key. If you need to migrate your inventory files from version 1, you can use the `migrate` command documented at [Migrate an OpenBolt project](projects.html#migrate-an-openbolt-project). diff --git a/docs/_openbolt_5x/modules.md b/docs/_openbolt_5x/modules.md index 2ace73151..eab1384d8 100644 --- a/docs/_openbolt_5x/modules.md +++ b/docs/_openbolt_5x/modules.md @@ -121,23 +121,21 @@ _PowerShell cmdlet:_ Get-BoltModule ``` -## Compatibility with Bolt versions +## Compatibility with older projects and OpenVox Server -Bolt 2.30.0 introduced module dependency management. The changes introduced by -this feature affect: +Module dependency management affects: -- Existing OpenBolt projects that were created before the dependency changes came - into effect. For information on how to migrate your OpenBolt project to use - dependency management, see [Migrate an OpenBolt - project](projects.html#migrate-an-openbolt-project). +- Older projects that don't use dependency management yet. For information on + how to migrate your OpenBolt project to use dependency management, see + [Migrate an OpenBolt project](projects.html#migrate-an-openbolt-project). - Your OpenVox Server environments (if you're using the dependency management feature). ### OpenVox Server compatibility -OpenBolt sets the moduledir in the Puppetfile to `.modules/` which is not on the -modulepath in versions of Bolt before 2.30.0. If you're using OpenBolt's dependency -management feature in an OpenVox Server environment, you must specify +OpenBolt sets the moduledir in the Puppetfile to `.modules/`, which is not on an +OpenVox Server environment's default modulepath. If you're using OpenBolt's +dependency management feature in an OpenVox Server environment, you must specify `.modules` on the modulepath in your [environment.conf](/openvox/latest/config_file_environment.html#example). @@ -148,6 +146,3 @@ For example: modulepath = site:dist:modules:$basemodulepath:.modules ``` - -You can learn more about the module changes introduced in Bolt 2.23.0 in the -[September 2020 developer update](./developer_updates.html#september-2020). diff --git a/docs/_openbolt_5x/projects.md b/docs/_openbolt_5x/projects.md index 5c3209a66..2b688a3e6 100644 --- a/docs/_openbolt_5x/projects.md +++ b/docs/_openbolt_5x/projects.md @@ -293,8 +293,7 @@ Currently, the `migrate` command: - Updates inventory files from version 1. - Updates projects to use `bolt-project.yaml` and `inventory.yaml` instead of `bolt.yaml`. -- Updates projects to implement module dependency management. Dependency - management was introduced in Bolt 2.30.0. +- Updates projects to use module dependency management. To migrate a project: