diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 8925df1bf..0c6c34562 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -79,6 +79,7 @@ jobs: run: | bundle exec rake references:openfact INSTALLPATH=docs bundle exec rake references:openvox INSTALLPATH=docs + bundle exec rake references:openbolt INSTALLPATH=docs bundle exec jekyll build - name: Archive website run: | diff --git a/.gitignore b/.gitignore index 1ce2c5b48..aa0aca053 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ vendor vendor/puppet +vendor/openbolt vendor/hiera vendor/facter vendor/bundle diff --git a/Rakefile b/Rakefile index d54bb4bdb..ab8143458 100644 --- a/Rakefile +++ b/Rakefile @@ -30,6 +30,7 @@ task :references do puts 'The following references are available:' puts 'bundle exec rake references:openvox [VERSION= INSTALLPATH=]' puts 'bundle exec rake references:openfact [VERSION= INSTALLPATH=]' + puts 'bundle exec rake references:openbolt [VERSION= INSTALLPATH=]' puts 'bundle exec rake references:version_tables' puts ' VERSION can be omitted, uses latest tag' puts ' INSTALLPATH can be omitted, defaults to references_output/' @@ -46,6 +47,11 @@ namespace :references do PuppetReferences.build_facter_references(ENV.fetch('VERSION', nil)) end + task openbolt: 'references:check' do + require 'puppet_references' + PuppetReferences.build_openbolt_references(ENV.fetch('VERSION', nil)) + end + task :version_tables do require 'puppet_references' PuppetReferences.build_version_tables diff --git a/_config.yml b/_config.yml index ff87e839d..c5d1ba6ff 100644 --- a/_config.yml +++ b/_config.yml @@ -61,6 +61,13 @@ collections: output: true permalink: '/openvoxdb/8.x/:path:output_ext' + openbolt_latest: + output: true + permalink: '/openbolt/latest/:path:output_ext' + openbolt_5x: + output: true + permalink: '/openbolt/5.x/:path:output_ext' + openvox-containers_latest: output: true permalink: '/openvox-containers/latest/:path:output_ext' @@ -110,6 +117,19 @@ defaults: values: nav: openvoxdb_8x + - scope: + path: '' + type: openbolt_latest + values: + layout: default + nav: openbolt_5x + - scope: + path: '' + type: openbolt_5x + values: + layout: default + nav: openbolt_5x + - scope: path: '' type: openvox-containers_latest diff --git a/_data/nav/openbolt_5x.yml b/_data/nav/openbolt_5x.yml new file mode 100644 index 000000000..2be5fae59 --- /dev/null +++ b/_data/nav/openbolt_5x.yml @@ -0,0 +1,135 @@ +--- +- text: Welcome to Puppet Bolt® + link: bolt.html + items: + - text: Developer updates + link: developer_updates.html + - text: Release notes + link: release_notes.html + - text: Bolt versioning + link: bolt_versioning.html + - text: Upgrading to Bolt 3.0 + link: upgrading_to_bolt_3.html + - text: Known issues + link: bolt_known_issues.html +- text: Installing Bolt + items: + - text: Installing Bolt + link: bolt_installing.html + - text: Run Bolt from a Docker image + link: running_bolt_in_docker.html +- text: Getting started with Bolt + link: getting_started_with_bolt.html +- text: Configuring Bolt + items: + - text: Bolt projects + link: projects.html + - text: Inventory files + link: inventory_files.html + - text: Configuring Bolt + link: configuring_bolt.html + - text: Logs + link: logs.html + - text: Escalating privilege with Bolt + link: privilege_escalation.html + - text: Setting up VS Code for Bolt + link: vscode_and_bolt.html +- text: Running Bolt + items: + - text: Run Bolt + link: running_bolt_commands.html + - text: Run Bolt on network devices + link: running_bolt_network.html +- text: Scripts + items: + - text: Running scripts + link: bolt_running_scripts.html + - text: Wrapping a script in a plan + link: creating_a_script_plan.html +- text: Plans + link: plans.html + items: + - text: Inspecting plans + link: inspecting_plans.html + - text: Running plans + link: bolt_running_plans.html + - text: Writing plans in YAML + link: writing_yaml_plans.html + - text: Writing plans in the Puppet language + link: writing_plans.html + - text: Debugging plans + link: debugging_plans.html + - text: Testing plans + link: testing_plans.html +- text: Tasks + link: tasks.html + items: + - text: Inspecting tasks + link: inspecting_tasks.html + - text: Running tasks + link: bolt_running_tasks.html + - text: Writing tasks + link: writing_tasks.html + - text: Task helpers + link: task_helpers.html +- text: Modules + items: + - text: Modules overview + link: modules.html + - text: Installing modules + link: bolt_installing_modules.html + - text: Module structure + link: module_structure.html + - text: Packaged modules + link: packaged_modules.html +- text: Plugins + items: + - text: Using plugins + link: using_plugins.html + - text: Supported plugins + link: supported_plugins.html + - text: Writing plugins + link: writing_plugins.html +- text: Using Bolt with Puppet + items: + - text: Applying Puppet code + link: applying_manifest_blocks.html + - text: Using Bolt with Hiera + link: hiera.html + - text: Connecting Bolt to PuppetDB + link: bolt_connect_puppetdb.html +- text: Bolt Examples + link: bolt_examples.html + items: + - text: Automating Windows targets + link: automating_windows_targets.html + - text: Deploy a TIG stack with Bolt + link: tig_stack.html +- text: "\U0001F9EA Experimental features" + link: experimental_features.html +- text: Reference + items: + - text: "*nix shell commands" + link: bolt_command_reference.html + - text: PowerShell cmdlets + link: bolt_cmdlet_reference.html + - text: JSON output + link: json_output_reference.html + - text: Plan functions + link: plan_functions.html + - text: Data types + link: bolt_types_reference.html + - text: Transport configuration options + link: bolt_transports_reference.html + - text: bolt-defaults.yaml options + link: bolt_defaults_reference.html + - text: bolt-project.yaml options + link: bolt_project_reference.html + - text: inventory.yaml fields + link: bolt_inventory_reference.html + - text: BoltSpec reference + link: boltspec_reference.html +- text: Troubleshooting + link: troubleshooting.html +- text: Glossary + link: glossary.html diff --git a/_data/nav_map.yml b/_data/nav_map.yml index eb191ab0c..53412a26b 100644 --- a/_data/nav_map.yml +++ b/_data/nav_map.yml @@ -14,6 +14,10 @@ collections: openvoxdb_latest|openvoxdb_8x base: /openvoxdb/latest/ +- nav_key: openbolt_5x + collections: openbolt_latest|openbolt_5x + base: /openbolt/latest/ + - nav_key: openvox-containers_latest collections: openvox-containers_latest base: /openvox-containers/latest/ diff --git a/_data/navigation.yml b/_data/navigation.yml index 13a1da9e2..37b57f493 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -10,6 +10,9 @@ - title: OpenVoxDB url: /openvoxdb/latest/ collections: [openvoxdb_latest, openvoxdb_8x] +- title: OpenBolt + url: /openbolt/latest/ + collections: [openbolt_latest, openbolt_5x] - title: OpenVox Containers url: /openvox-containers/latest/ collections: [openvox-containers_latest] diff --git a/docs/_openbolt_5x/.gitignore b/docs/_openbolt_5x/.gitignore new file mode 100644 index 000000000..962a31104 --- /dev/null +++ b/docs/_openbolt_5x/.gitignore @@ -0,0 +1,14 @@ +# ERB-generated reference pages — copied here by CI (bundle exec rake references:openbolt) +bolt_cmdlet_reference.md +bolt_command_reference.md +bolt_defaults_reference.md +bolt_project_reference.md +bolt_transports_reference.md +bolt_types_reference.md +packaged_modules.md +plan_functions.md +privilege_escalation.md +*.png +*.jpg +*.gif +*.svg diff --git a/docs/_openbolt_5x/.gitkeep b/docs/_openbolt_5x/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/_openbolt_5x/.markdownlint.yaml b/docs/_openbolt_5x/.markdownlint.yaml new file mode 100644 index 000000000..73334c62d --- /dev/null +++ b/docs/_openbolt_5x/.markdownlint.yaml @@ -0,0 +1,86 @@ +--- +# Ported from upstream Puppet Bolt docs. These rules fire extensively across +# the imported content but do not reflect errors in meaning or structure. +# TODO: fix violations and remove this file — https://github.com/OpenVoxProject/openvox-docs/issues/199 + +# MD060: 260 violations — table columns not padded to aligned_delimiter width +table-column-style: false + +# MD009: 136 violations — trailing spaces throughout source +no-trailing-spaces: false + +# MD031: 132 violations — fenced code blocks missing surrounding blank lines +blanks-around-fences: false + +# MD030: 132 violations — extra spaces after list markers (e.g. "- item") +list-marker-space: false + +# MD040: 123 violations — fenced code blocks without a language specifier +fenced-code-language: false + +# MD036: 120 violations — bold/italic used as informal headings +no-emphasis-as-heading: false + +# MD033: 86 violations — inline HTML beyond what the root config permits +no-inline-html: false + +# MD032: 64 violations — lists not surrounded by blank lines +blanks-around-lists: false + +# MD049: 26 violations — inconsistent emphasis delimiter (* vs _) +emphasis-style: false + +# MD004: 22 violations — inconsistent unordered list markers +ul-style: false + +# MD007: 18 violations — unordered list indentation +ul-indent: false + +# MD027: 13 violations — multiple spaces after blockquote marker +no-multiple-space-blockquote: false + +# MD014: 11 violations — shell commands with $ prefix followed by output +commands-show-output: false + +# MD013: 9 violations — lines exceeding the 210-char root limit +line-length: false + +# MD051: 6 violations — link fragments referencing headings that don't exist +link-fragments: false + +# MD055: 4 violations — inconsistent table pipe style +table-pipe-style: false + +# MD047: 4 violations — files missing a trailing newline +single-trailing-newline: false + +# MD045: 4 violations — images without alt text +no-alt-text: false + +# MD034: 4 violations — bare URLs +no-bare-urls: false + +# MD029: 4 violations — ordered list prefix style +ol-prefix: false + +# MD022: 4 violations — headings not surrounded by blank lines +blanks-around-headings: false + +# MD056: 1 violation — inconsistent column count across table rows +table-column-count: false + +# MD028: 1 violation — blank line inside block quote +no-blanks-blockquote: false + +# MD010: 1 violation — hard tabs +no-hard-tabs: false + +# MD012: violations — multiple consecutive blank lines (root config alias not recognized) +no-multiple-blanks: + maximum: 2 + +# MD024: duplicate headings that are siblings (e.g. repeated language-specific task sections) +no-duplicate-heading: false + +# MD025: multiple H1 headings in a document +single-title: false diff --git a/docs/_openbolt_5x/applying_manifest_blocks.md b/docs/_openbolt_5x/applying_manifest_blocks.md new file mode 100644 index 000000000..7b4022eae --- /dev/null +++ b/docs/_openbolt_5x/applying_manifest_blocks.md @@ -0,0 +1,552 @@ +--- +layout: default +title: Applying Puppet code +--- + +# Applying Puppet code + +You can use Bolt to apply blocks of Puppet code, called manifest blocks, to +remote targets. + +You can create manifest blocks that use existing content from the Forge, or use +a plan to mix procedural orchestration and action with declarative resource +configuration from a block. Most features of the Puppet language are available +in a manifest block: classes, custom resource types, and functions. For +information about what language features aren't supported, see [Manifest block +limitations](#manifest-block-limitations). + +> 🔩 **Tip:** If you installed Bolt as a Ruby Gem, make sure you have installed + the core modules required to use the `puppet apply` command. These modules are + listed in the [Bolt GitHub + repository](https://github.com/puppetlabs/bolt/blob/main/Puppetfile) and you + can install them using the [module management workflow](modules.html#dependency-management). + +📖 **Related information** + +- [Configure Bolt to download and install modules](bolt_installing_modules.html#) +- [Modules overview](modules.html) +- [Puppet Forge](https://forge.puppet.com/) + +## Applying manifest blocks from the command line + +Similar to the [`puppet apply` +command](https://puppet.com/docs/puppet/latest/man/apply.html), which applies a +standalone Puppet manifest to a local system, you can use Bolt to apply +Puppet manifests to remote targets. + +Manifest blocks require facts to compile. When Bolt applies Puppet manifests, it +automatically installs the packages necessary to run the apply command and +gathers facts using [facter](https://puppet.com/docs/facter/latest/), making the +facts available to the manifest block. Bolt also identifies targets that do not +have Puppet agents and runs the [`openvox_bootstrap::install` +task](https://forge.puppet.com/puppet/openvox_bootstrap) to install the agent. + +> **Note:** Bolt installs the OpenVox agent package to enable the use of Puppet + code. It does not require setting up a server-agent architecture between the + remote systems and the local system running Bolt. + +### Applying manifest files + +Bolt can apply a manifest from a file by passing an absolute path to the +manifest: + +- _\*nix shell command_ + + ```shell + bolt apply manifests/server.pp --targets servers + ``` + +- _PowerShell cmdlet_ + + ```powershell + Invoke-BoltApply -Manifest manifests/server.pp -Targets servers + ``` + +### Applying manifest code + +Bolt can apply manifest code directly by passing the code to the `execute` +command-line option: + +- _\*nix shell command_ + + ```shell + bolt apply --execute "file { '/etc/puppetlabs': ensure => present }" --targets servers + ``` + +- _PowerShell cmdlet_ + + ```powershell + Invoke-BoltApply -Execute "file { '/etc/puppetlabs': ensure => present }" -Targets servers + ``` + +### Definitions and declarations + +When applying manifest blocks, it's important to understand the distinction +between _definitions_ and _declarations_. + +Definitions, which include class definitions and defined resource types, are +blocks of Puppet code that can be used when called by name. Defining a class or +defined type makes the code available to a catalog, but does not add it to the +catalog. A class or defined type that is not called by name, or _declared_, is +not added to the catalog, and thus none of the code in those definitions will be +applied to the targets. + +When you apply a manifest containing only definitions, Bolt will issue a helpful +warning to let you know that the apply will do nothing: + +```shell +$ bolt apply --execute "define bolt { file { 'etc/puppetlabs': ensure => present } }" --targets servers + +Manifest only contains definitions and will result in no changes on the targets. +. . . +``` + +📖 **Related information** + +- [Defining and declaring + classes](https://puppet.com/docs/puppet/latest/lang_classes.html) +- [Defining and declaring defined + types](https://puppet.com/docs/puppet/latest/lang_defined_types.html) + +### How manifest blocks are applied + +Bolt compiles the code in your manifest block into a catalog. Bolt compiles code +in the following order: + +- Facts gathered from the targets or set in your inventory. +- [`vars`](inventory_files.html) set in your inventory. + +Like the code compiled with the `puppet apply` command, all of the variables are +generated. As a result, you can reuse code between Bolt and Puppet. Bolt then +copies custom module content from the modulepath to the targets and applies the +catalog using Puppet. + +After the catalog compiles and is executed successfully on all targets, `bolt +apply` displays the reports generated by applying the catalog on each target. + +### Return value + +When you run the command, Bolt will first install required packages and gather +facts, apply the catalog compiled from the manifest blocks, and then report a +summary of any changes made on the remote systems: + +```shell +Starting: install puppet and gather facts on target1, target2 +Finished: install puppet and gather facts with 0 failures in 3.81 sec +Starting: apply catalog on target1, target2 +Started on target1... +Started on target2... +Finished on target1: + changed: 1, failed: 0, unchanged: 0, skipped: 0, noop: 0 +Finished on target2: + changed: 1, failed: 0, unchanged: 0, skipped: 0, noop: 0 +Finished: apply catalog with 0 failures in 4.52 sec +Successful on 2 targets: target1,target2 +Ran on 2 targets in 8.42 sec +``` + +## Applying Puppet code from Puppet Forge modules in a YAML plan + +You can apply Puppet code from a module downloaded from the Puppet Forge in a +YAML plan. To apply Puppet code in a YAML plan, use the YAML plan `resources` +step. + +To learn more about applying Puppet code in YAML plans, see [Writing YAML +plans](writing_yaml_plans.html#applying-puppet-code-from-puppet-forge-modules). + +## Applying manifest blocks from a Puppet plan + +You can apply manifest blocks to remote systems during execution of a Puppet +plan using the `apply` function. + +Manifest blocks require facts to compile. If your plan includes a manifest +block, use the `apply_prep` function in your plan _before_ your manifest block. +The `apply_prep` function installs the packages necessary to run the apply +command and gathers facts by running +[facter](https://puppet.com/docs/facter/latest/), making the facts available to +the manifest block. The `apply_prep` function also identifies the targets that +do not have Puppet agents and runs the [`puppet_agent::install` +task](https://forge.puppet.com/puppetlabs/puppet_agent) to install the agent. + +> **Note:** Bolt installs the Puppet agent package to enable the use of Puppet + code. It does not require setting up a server-agent architecture between the + remote systems and the local system running Bolt. + +### Options + +The `apply` function supports the following options: + +- `_catch_errors => true` returns a `ResultSet` including failed results, rather + than failing the plan. + +- `_description => ` adds a description to the apply block, + allowing you to distinguish apply blocks. + +- `_noop => true` applies the manifest block in Puppet no-operation mode, + returning a report of the changes it would make, but takes no action. + +- `_run_as => ` applies the manifest block as the specified user. (This + option is for transports that allow a user to run commands under a different + username.) + +```puppet +# Preview installing docker as root on $targets. +apply($targets, _catch_errors => true, _noop => true, _run_as => root) { + include 'docker' +} +``` + +### How manifest blocks are applied + +Bolt compiles the code in your manifest block into a catalog. Bolt compiles code +in the following order: + +- Facts gathered from the targets or set in your inventory. +- Local variables from the plan. +- [`vars`](inventory_files.html) set in your inventory. + +Like the code compiled with the `puppet apply` command, all the variables are +generated. As a result, you can reuse code between Bolt and Puppet. Bolt then +copies custom module content from the Bolt modulepath to the targets and +applies the catalog using Puppet. + +After the catalog compiles and is executed successfully on all targets, `apply` +returns the reports generated by applying the catalog on each target. + +### Return value + +The `apply` function returns a [`ResultSet` +object](https://puppet.com/docs/bolt/latest/bolt_types_reference.html#resultset) +that contains an [`ApplyResult` +object](https://puppet.com/docs/bolt/latest/bolt_types_reference.html#applyresult) +for each target. + +```puppet +$results = apply($targets) { ... } +$results.each |$result| { + notice($result.report) +} +``` + +### Report keys + +The [`ApplyResult` object](bolt_types_reference.html#applyresult) includes a +`report` method that returns a hash representation of the +[`Puppet::Transaction::Report`](https://puppet.com/docs/puppet/latest/format_report.html) +object. Each property on the object corresponds to a key with the same name in +the report hash. However, not every property is presented in the hash for every +result. Only properties that have a value from the apply are present in the +hash. + +For example, to access and print the logs from a report in your plan, you can +access the `logs` key in the report hash: + +```puppet +plan example ( + TargetSpec $targets +) { + # Install the openvox-agent package and gather facts + $targets.apply_prep + + # Apply Puppet code + $apply_results = apply($targets) { + file { '/etc/puppetlabs': + ensure => present + } + } + + # Print log messages from the report + $apply_results.each |$result| { + $result.report['logs'].each |$log| { + out::message("${log['level'].upcase}: ${log['message']}") + } + } +} +``` + +Running the above plan prints output similar to this: + +```shell +$ bolt plan run example --targets server +Starting: plan example +Starting: install puppet and gather facts on server +Finished: install puppet and gather facts with 0 failures in 4.01 sec +Starting: apply catalog on server +Finished: apply catalog with 0 failures in 4.59 sec +INFO: Applying configuration version '1612480754' +INFO: Creating state file /tmp/d20210204-3818-1az3s99/var/state/state.yaml +NOTICE: Applied catalog in 0.01 seconds +Finished: plan example in 8.64 sec +``` + +## Configuring concurrency + +Each target requires a separate catalog be compiled with its unique `facts` and +`vars`. The apply action compiles and applies catalogs in parallel on the Bolt +host. Concurrency of catalog compilation is controlled by the +`compile-concurrency` config option. This option is limited to twice the number +of threads your CPU can run concurrently. Catalog application, on the other +hand, uses the Bolt default thread pool controlled by the `concurrency` option. + +## Using Hiera data in a manifest block + +Use [Hiera](https://puppet.com/docs/puppet/latest/hiera_intro.html) to separate +configuration from context-specific data, where context might be fact-based or the +name of a target. + +> **Note:** Only Hiera version 5 is supported in Bolt. + +Hiera is a key-value configuration data look up system, used for separating data +from Puppet code. You use Hiera data to implicitly override default class +parameters. You can also explicitly look up data from Hiera via the [`lookup` +function](https://puppet.com/docs/puppet/latest/function.html#lookup): + +```puppet +plan do_thing() { + apply('localhost') { + notice("Some data in Hiera: ${lookup('mydata')}") + } +} +``` + +Manifest block compilation can access Hiera data that you add to your Bolt +configuration. The default location for Hiera config is `/hiera.yaml`. +You can change this with the `hiera-config` key in a Bolt config file or the +`--hiera-config` CLI option. + +Following the Hiera 5 convention, the default data directory is relative to +`hiera.yaml` at `/data`. For configuration file examples, see [Configuring +Hiera](https://puppet.com/docs/puppet/latest/hiera_config_yaml_5.html). Bolt +will not automatically load any Hiera data from this directory. If you want to load data from a +data file you must set the relevant paths in your Hiera config. + +> **Note**: The target name is made available to Hiera as `trusted.certname`. You can learn more about + [interpolating variables into Hiera config + here](https://puppet.com/docs/puppet/latest/hiera_merging.html#interpolate_puppet_variable). + +If a custom data provider is used, such as `hiera-eyaml`, which allows you to +encrypt your data, the gem dependencies must be available to Bolt. See [Install +gems with Bolt packages](bolt_installing.html#). + +[Hiera interpolations](https://puppet.com/docs/puppet/latest/hiera_merging.html#hiera_interpolation) +are not supported in Bolt outside of apply blocks, because Hiera data is looked up per-target and +plans do not run in a per-target context. If you want to use Hiera to look up data outside of an apply +block, you can use a [plan hierarchy](writing_plans.html#using-hiera-data-in-plans). + +## Puppet log functions in Bolt + +You can use Puppet log functions in Bolt plans, but Bolt log levels do not map +directly to Puppet log levels. For example, a `notice` function in a plan logs +at the `info` level in Bolt. Log levels map as follows: + +| Puppet log level | Bolt log level | +| --- | --- | +| `debug` | `trace` | +| `info` | `debug` | +| `notice` | `info` | +| `warning` | `warn` | +| `err` | `error` | +| `alert` | `error` | +| `emerg` | `fatal` | +| `crit` | `fatal` | + +📖 **Related information** + +- [Configuring Bolt](configuring_bolt.html) + +## Available plan functions + +In addition to the standard Puppet functions available to a catalog, such as +`lookup()`, you can use the following Bolt functions in a manifest block: + +- [`puppetdb_query`](plan_functions.html#puppetdb_query) +- [`puppetdb_facts`](plan_functions.html#puppetdb_facts) +- [`facts`](plan_functions.html#facts) +- [`vars`](plan_functions.html#vars) + +## Manifest block limitations + +Exported resources are not supported in manifest blocks. You must pass exported +resources directly instead of exporting and collecting them from PuppetDB. If +you need to interact with resources managed during a normal run, use the +[`puppetdb_query` function](plan_functions.html#puppetdb_query). + +In addition, the following top-level variables, which exist in normal catalog +compilation, are not included during manifest block compilation: + +- `$server_facts` +- Master variables like `$servername` +- `$environment` + +You can optionally set these from a target's `vars`, but they don't have +defaults in Bolt. + +## Examples + +### Create a sample manifest for nginx on Linux + +Create a manifest that sets up a web server with nginx, and run it as a plan. + +1. Go to the `site-modules` directory in the default Bolt project directory: + `~/.puppetlabs/bolt/site-modules` + +1. Create a module named profiles. + - If you use the Puppet Development Kit: `pdk new module profiles` + - Otherwise create `~/.puppetlabs/bolt/site-modules/profiles` + +1. Add a `plans` directory to the profiles module. + +1. In the plans directory, create a manifest file called `nginx_install.pp` and + add the following code: + + ```puppet + plan profiles::nginx_install( + TargetSpec $targets, + String $site_content = 'hello!', + ) { + + # Install the openvox-agent package if Puppet is not detected. + # Copy over custom facts from the Bolt modulepath. + # Run the `facter` command line tool to gather target information. + $targets.apply_prep + + # Compile the manifest block into a catalog + apply($targets) { + if($facts['os']['family'] == 'redhat') { + package { 'epel-release': + ensure => present, + before => Package['nginx'], + } + $html_dir = '/usr/share/nginx/html' + } else { + $html_dir = '/var/www/html' + } + + package {'nginx': + ensure => present, + } + + file {"${html_dir}/index.html": + content => $site_content, + ensure => file, + } + + service {'nginx': + ensure => 'running', + enable => 'true', + require => Package['nginx'] + } + } + } + ``` + +1. Run the plan on a target: + + ```shell + bolt plan run profiles::nginx_install --targets mytarget.mydomain + ``` + +1. In a web browser, open `mytarget.mydomain`. The page displays the text + `hello!` + +> 🔩 **Tip:** For complex web server deployments, consider adding the + [puppet-nginx](https://forge.puppet.com/puppet/nginx) module. + +📖 **Related information** + +- [NGINX](https://www.nginx.com/resources/glossary/nginx/) +- [Specify targets](running_bolt_commands.html#adding-options-to-bolt-commands) +- [Bolt Projects](projects.html) + + +### Create a Bolt plan for IIS on Windows + +Create a manifest that sets up a web server with IIS and run it as a plan. + +1. Create a directory to use as your Bolt project or use an existing directory. +1. Convert the directory into a Bolt project named 'profiles' by running `bolt project init + profiles`, or `New-BoltProject -Name profiles` if you're using PowerShell. +1. Add the `puppetlabs-iis` module to your `bolt-project.yaml` under the `modules` key: + ``` + modules: + - name: puppetlabs-iis + version_requirement: 4.3.2 + ``` +1. Run `bolt module install` or `Install-BoltModule` if you're using PowerShell. +1. Create a new Puppet language Bolt plan inside your project by running + `bolt plan new profiles` or `New-BoltPlan -Name profiles -Pp` on PowerShell. This creates a `plans/` + directory in your Bolt project, and a file named `init.pp` inside that directory with some basic + commands. +1. Replace the contents of `/plans/init.pp` with this Bolt plan: + ```puppet + plan profiles( + TargetSpec $targets, + String $site_content = 'hello!', + ) { + + # Install the openvox-agent package if Puppet is not detected. + # Copy over custom facts from the Bolt modulepath. + # Run the `facter` command line tool to gather target information. + $targets.apply_prep + + # Compile the manifest block into a catalog + return apply($targets, '_catch_errors' => true) { + $iis_features = ['Web-WebServer','Web-Scripting-Tools'] + + iis_feature { $iis_features: + ensure => 'present', + } + + # Delete the default website to prevent a port binding conflict. + iis_site {'Default Web Site': + ensure => absent, + require => Iis_feature['Web-WebServer'], + } + + iis_site { 'minimal': + ensure => 'started', + physicalpath => 'c:\\inetpub\\minimal', + applicationpool => 'DefaultAppPool', + require => [ + File['minimal'], + Iis_site['Default Web Site'] + ], + } + + file { 'minimal': + ensure => 'directory', + path => 'c:\\inetpub\\minimal', + } + + file { 'content': + ensure => 'file', + path => 'c:\\inetpub\\minimal\\index.html', + content => $site_content, + } + } + } + ``` + This plan uses the `apply` function to apply a manifest to targets. The manifest uses the + [puppetlabs-iis module](https://forge.puppet.com/modules/puppetlabs/iis) to set up an IIS + server on the targets. +1. Run the plan on a target: + _\*nix shell command_ + ```shell + bolt plan run profiles --targets winrm://mytarget.mydomain + ``` + _PowerShell cmdlet_ + ```shell + Invoke-BoltPlan -Name profiles -Targets winrm://mytarget.mydomain + ``` + +1. In a web browser, open `mytarget.mydomain`. The page displays the text + `hello!` + +📖 **Related information** +- [IIS](https://www.iis.net) +- [Specify targets](running_bolt_commands.html#adding-options-to-bolt-commands) +- [Bolt projects](projects.html) +- [Puppet language Bolt plans](writing_plans.html) +- For information on how Bolt loads the modulepath, see [Modules overview](modules.html#modulepath). +- To learn more about using Puppet device modules, see [Running Bolt on network + devices](running_bolt_network.html#-using-puppet-device-modules-from-an-apply-block) diff --git a/docs/_openbolt_5x/automating_windows_targets.md b/docs/_openbolt_5x/automating_windows_targets.md new file mode 100644 index 000000000..1cec07380 --- /dev/null +++ b/docs/_openbolt_5x/automating_windows_targets.md @@ -0,0 +1,290 @@ +--- +layout: default +title: Automating Windows targets +--- + +# Automating Windows targets + +Here are some common use cases that you can accomplish with Bolt on Windows targets. + +## Run a PowerShell script that restarts a service + +To show you how you can use Bolt to reuse your existing PowerShell scripts, this +guide walks you through running a script with Bolt, and then converting the +script to a Bolt task and running that. + +> **Before you begin** +> +> - Ensure you’ve already [installed Bolt](bolt_installing.html#) on your +> Windows machine. +> - Identify a remote Windows target to work with. +> - Ensure you have Windows credentials for the target. +> - Ensure you have [configured Windows Remote +> Management](https://docs.microsoft.com/en-us/windows/desktop/winrm/installation-and-configuration-for-windows-remote-management) +> on the target. + +The example script, +called [restart_service.ps1](https://gist.github.com/RandomNoun7/03dfb910e5d93fefaae6e6c2da625c44#file-restart_service-ps1), +performs common task of restarting a service on demand. The process involves +these steps: + +1. Run your PowerShell script on a Windows target. +1. Create an inventory file to store information about the target. +1. Convert your script to a task. +1. Execute your new task. + + +### 1. Run your PowerShell script on a Windows target + +First, we’ll use Bolt to run the script as-is on a single target. + +1. Create a Bolt project directory to work in, called `bolt-guide`. +1. Copy the + [`restart_service.ps1`](https://gist.github.com/RandomNoun7/03dfb910e5d93fefaae6e6c2da625c44#file-restart_service-ps1) + script into `bolt-guide`. +1. In the `bolt-guide` directory, run the `restart_service.ps1` script: + ``` + bolt script run .\restart_service.ps1 W32Time --targets winrm:// -u Administrator -p + ``` + + ![](restart_service.png) + + **Note:** The `-p` option prompts you to enter a password. + + By running this command, you’ve brought your script under Bolt control and + have run it on a remote target. When you ran your script with Bolt, the + script was transferred into a temporary directory on the remote target, it + ran on that target, and then it was deleted from the target. + + +### 2. Create an inventory file to store information about your targets + +To run Bolt commands against multiple targets at once, you need to provide +information about the environment by creating an [inventory +file](inventory_files.html). The inventory file is a YAML file that contains a +list of targets and target specific data. + +1. Inside the `bolt-guide` directory, use a text editor to create an + `inventory.yaml` file and a `bolt-project.yaml` file. The `inventory.yaml` file is where + connection information is stored, while `bolt-project.yaml` tells Bolt that the directory is a project + and that it should load the inventory file from the directory. +1. Inside the new `inventory.yaml` file, add the following content, listing the + fully qualified domain names of the targets you want to run the script on, + and replacing the credentials in the `winrm` section with those appropriate + for your target: + ```yaml + groups: + - name: windows + targets: + - + - + config: + transport: winrm + winrm: + user: Administrator + password: + ``` + + **Note:** To have Bolt securely prompt for a password, use the + `--password-prompt` command-line option without supplying any value. This + prevents the password from appearing in a process listing or on the console. + Alternatively you can use the [`prompt` plugin](supported_plugins.html#prompt) to + set configuration values via a prompt. + + You now have an inventory file where you can store information about your + targets. + + You can also configure a variety of options for Bolt in `bolt-project.yaml`. For more + information about configuration see [Configuring Bolt](configuring_bolt.html). For more + information about Bolt projects see [Bolt projects](projects.html). + + +### 3. Convert your script to a Bolt task + +To convert the `restart_service.ps1` script to a task, giving you the ability to +reuse and share it, create a [task metadata](writing_tasks.html#) file. Task +metadata files describe task parameters, validate input, and control how the +task runner executes the task. + +**Note:** This guide shows you how to convert the script to a task by manually +creating the `.ps1` file in a directory called `tasks`. Alternatively, you can +use Puppet Development Kit (PDK), to create a task by using the [`pdk new +task` +command](https://puppet.com/docs/pdk/1.x/pdk_reference.html#pdk-new-task-command). +If you’re going to be creating a lot of tasks, using PDK is worth getting to +know. For more information, see the [PDK +documentation.](https://puppet.com/docs/pdk/1.x/pdk_overview.html) + +1. In the `bolt-guide` directory, create the following subdirectories: + ``` + bolt-guide/ + └── modules + └── gsg + └── tasks + ``` +1. Move the `restart_service.ps1` script into the `tasks` directory. +1. In the `tasks` directory, use your text editor to create a task metadata + file — named after the script, but with a `.json` extension, in this + example, `restart_service.json`. +1. Add the following content to the new task metadata file: + + ```json + { + "puppet_task_version": 1, + "supports_noop": false, + "description": "Stop or restart a service or list of services on a target.", + "parameters": { + "service": { + "description": "The name of the service, or a list of service names to stop.", + "type": "Variant[Array[String],String]" + }, + "norestart": { + "description": "Immediately restart the services after start.", + "type": "Optional[Boolean]" + } + } + } + ``` + +1. Save the task metadata file and navigate back to the `bolt-guide` directory. + + You now have two files in the `gsg` module’s `tasks` directory: + `restart_service.ps1` and `restart_service.json` -- the script is officially + converted to a Bolt task. Now that it’s converted, you no longer need to + specify the file extension when you call it from a Bolt command. +1. Validate that Bolt recognizes the script as a task: + + ``` + bolt task show gsg::restart_service + ``` + + ![](bolt_PS_2.png) + + Congratulations! You’ve successfully converted the `restart_service.ps1` + script to a Bolt task. + +1. Execute your new task: + ``` + bolt task run gsg::restart_service service=W32Time --targets windows + ``` + + ![](bolt_PS_3.png) + + **Note:** `--targets windows` refers to the name of the group of targets + that you specified in your inventory file. For more information, see + [Specify targets](running_bolt_commands.html#adding-options-to-bolt-commands). + +## Deploy a package with Bolt and Chocolatey + +You can use Bolt with Chocolatey to deploy a package on a Windows target. First, +use the `apply` command to install Chocolatey on the target. Next, use Puppet's +Chocolatey package provider to install the package. + +This example installs the Frogsay package on a Windows target. + +**Before you begin:** +- [Install Bolt](bolt_installing_modules.html) +- Configure Windows Remote Management (WinRM) on your Windows target. + +To install the Frogsay package with Chocolatey: +1. Install the Chocolatey module to your Bolt project. This allows you to + install Chocolatey to your target in the next step. + - If you're using an existing Bolt project: + + _\*nix shell command_ + + ```shell + bolt module add puppetlabs-chocolatey + ``` + + _PowerShell cmdlet_ + + ```powershell + Add-BoltModule -Module puppetlabs-chocolatey + ``` + + - If you want to create a project (named `choco_project`) that includes the Chocolatey module. Create a directory named `choco_project` and run the following command inside the directory: + + _\*nix shell command_ + + ```shell + bolt project init chocho_project --modules puppetlabs-chocolatey + ``` + + _PowerShell cmdlet_ + + ```powershell + New-BoltProject -Name choco_project -Modules puppetlabs-chocolatey + ``` + +1. Install Chocolatey on your Windows target using the `apply` command: + + _\*nix shell command_ + + ```shell + bolt apply -e 'include chocolatey' -t -u -p --transport winrm + ``` + + _PowerShell cmdlet_ + + ```powershell + Invoke-BoltApply -Execute "include chocolatey" -Targets -User -Password -Transport winrm + ``` + +1. Use the built-in Package task to install Frogsay on your target: + + _\*nix shell command_ + + ```shell + bolt task run package -t -u -p --transport winrm action=install name=frogsay + ``` + + _PowerShell cmdlet_ + + ```powershell + Invoke-BoltTask -Name package -Targets -User -Password -Transport winrm action=install name=frogsay + ``` + +1. Run `frogsay` on your target to test: + + _\*nix shell command_ + + ```shell + bolt command run 'frogsay ribbit' -t -u -p --transport winrm + ``` + + _PowerShell cmdlet_ + + ```powershell + Invoke-BoltCommand 'frogsay ribbit' -Targets -User -Password -Transport winrm + ``` + + Your output should look something like this: + ```shell + Started on example.windowstarget.net... + Finished on example.windowstarget.net: + STDOUT: + + WORRIED ABOUT LONG LINES? FROG CAN HOLD YOUR PLACE FOR UP TO 65534 + SECONDS BEFORE IT FORGETS WHAT IT'S DOING AND HOPS AWAY. + / + @..@ + (----) + ( >__< ) + ^^ ~~ ^^ + Successful on 1 target: example.windowstarget.net + Ran on 1 target in 2.19 sec + ``` + +If you need to install packages on multiple targets, create a Bolt project with +an inventory for your targets. Using an inventory allows you to group your +targets together and dramatically simplifies Bolt commands. + +📖 **Related information** + +- [Bolt projects](projects.html) +- [Inventory files](inventory_files.html) +- [Applying Puppet code](applying_manifest_blocks.html) + +Do you have a real-world use case for Bolt that you'd like to share? Reach out to us in the #bolt +channel on [Slack](https://slack.puppet.com). \ No newline at end of file diff --git a/docs/_openbolt_5x/bolt.md b/docs/_openbolt_5x/bolt.md new file mode 100644 index 000000000..4b83997b1 --- /dev/null +++ b/docs/_openbolt_5x/bolt.md @@ -0,0 +1,96 @@ +--- +layout: default +title: Welcome to Puppet Bolt® +--- + +# Welcome to Puppet Bolt® + +Bolt is an open source orchestration tool that automates the manual work it +takes to maintain your infrastructure. Use Bolt to automate tasks that you +perform on an as-needed basis or as part of a greater orchestration workflow. +For example, you can use Bolt to patch and update systems, troubleshoot servers, +deploy applications, or stop and restart services. Bolt can be installed on your +local workstation and connects directly to remote targets with SSH or WinRM, so +you are not required to install any agent software. + +
+ + + + + + + + + + + + + + +
Helpful Bolt docs linksOther useful places
+

Install Bolt +

    +
  • Installing Bolt - Follow the installation instructions for your operating system: *nix, macOS, or Windows.
    • +
+

+

Upgrade to Bolt 3.0

+

Make one-time changes to your remote targets +

+

+

Automate your workflow with existing tasks and plans +

+

+

Create your own tasks and plans +

+

+ 		+

Learn the basics +

+

+

Watch Bolt development +

+

+

Docs for related Puppet products +

+

+

Why and how people are using Bolt +

+

+

Share and contribute +

+

+
diff --git a/docs/_openbolt_5x/bolt_connect_puppetdb.md b/docs/_openbolt_5x/bolt_connect_puppetdb.md new file mode 100644 index 000000000..625cc557c --- /dev/null +++ b/docs/_openbolt_5x/bolt_connect_puppetdb.md @@ -0,0 +1,296 @@ +--- +layout: default +title: Connecting Bolt to PuppetDB +--- + +# Connecting Bolt to PuppetDB + +Configure Bolt to connect to PuppetDB. + +## PuppetDB authorization + +Bolt can authenticate with PuppetDB through an SSL client certificate or a PE +RBAC token. + +## Client certificate + +Add the certname for the certificate you want to authenticate with +to `/etc/puppetlabs/puppetdb/certificate-allowlist`. This certificate has full +access to all PuppetDB API endpoints and can read all data, push new data, or +run commands on PuppetDB. To test the certificate you run the following curl +command. + +``` +curl -X GET $SERVER_URL/pdb/query/v4 --data-urlencode 'query=nodes[certname] {}' --cert $CERT_PATH --key $KEY_PATH --cacert $CACERT_PATH +``` + +## Token-based authentication with PE RBAC token + +If you use Puppet Enterprise you can grant more restricted access to PuppetDB +with a PE role-based access control (RBAC) token. + +1. In PE, verify you are assigned to a role that has the appropriate RBAC + permission. It needs the permission type **Nodes** and the action **View + node data from PuppetDB**. + +2. From the command line, run `puppet-access login --lifetime