diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 0f3cab942..bbf3a1cb0 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -110,7 +110,7 @@ jobs: - name: Unit tests run: bundle exec rake tests:unit - run-dita: + generate-docs: runs-on: ubuntu-24.04 steps: - name: Initialize @@ -122,10 +122,8 @@ jobs: bundler-cache: true - name: Generate docs run: bundle exec rake docs:all - - name: Docs test - uses: dita-ot/dita-ot-action@4.3.5 - with: - build: dita -i documentation/bolt.ditamap -o out -f html5 --processing-mode=strict + - name: Generate and verify Jekyll docs + run: bundle exec rake docs:jekyll docs:jekyll_verify local_transports: name: "local transport ${{ matrix.ruby }} ${{ matrix.os }}" @@ -466,7 +464,7 @@ jobs: - cache_modules_linux - cache_modules_windows - unit - - run-dita + - generate-docs - local_transports - winrm_transport - apply diff --git a/.gitignore b/.gitignore index ea3fbfc23..92dcdba61 100644 --- a/.gitignore +++ b/.gitignore @@ -78,3 +78,4 @@ pwsh_module/PuppetBolt.psd1 pwsh_module/autogenerated.tests.ps1 pwsh_module/en-US pwsh_module/PuppetBolt +/documentation/jekyll_build/ diff --git a/documentation/README.md b/documentation/README.md index 3844bb66a..825fb291c 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -1,163 +1,41 @@ # Bolt documentation -This directory contains the markdown files used to generate the official -[Bolt Documentation](https://puppet.com/docs/bolt/latest/bolt.html). To make -changes to most of Bolt's documentation, you can edit the corresponding -markdown file directly. However, some of Bolt's documentation is generated -as part of the release process and requires edits to either Bolt's source -code or to the template used to generate the documentation. +This directory contains the ERB templates used to generate reference documentation +for OpenBolt. Static documentation pages live in the +[openvox-docs](https://github.com/OpenVoxProject/openvox-docs) repository. -## Generated documentation +## Generated reference documentation -Several pages of Bolt's documentation are generated as part of Bolt's release -process and do not have markdown files in this directory. Each of the generated -pages has an associated Embedded Ruby template located in the -[templates](./templates) directory as well as a [rake task](../rakelib/docs.rake) -that is used to generate the documentation. Each rake task retrieves data from -Bolt's source code and sends it to a rendering engine that generates a markdown -file from the template. The generated markdown file is saved to the -`documentation` directory. +Several reference pages are generated from Bolt's source code. Each has an ERB +template in the [templates](./templates) directory and a corresponding rake task in +[rakelib/docs.rake](../rakelib/docs.rake). -You can generate all documentation using the following rake task: +Generate all reference pages: ```shell -$ bundle exec rake docs:all +bundle exec rake docs:all ``` -Here are each of the documenation pages that are generated, the files -that you might need to modify to make changes to the generated documentation, -and the rake task used to generate the documentation. - -### *nix shell commands - -**Documentation page** -- https://puppet.com/docs/bolt/latest/bolt_command_reference.html - -**Template file** -- [`bolt_command_reference.md.erb`](./templates/bolt_command_reference.md.erb) - -**Relevant source code** -- [`bolt_option_parser.rb`](../lib/bolt/bolt_option_parser.rb) - -To generate this documentation, run: - -```shell -$ bundle exec rake docs:command_reference -``` - -### PowerShell cmdlets - -**Documentation page** -- https://puppet.com/docs/bolt/latest/bolt_cmdlet_reference.html - -**Template file** -- [`bolt_cmdlet_reference.md.erb`](./templates/bolt_cmdlet_reference.md.erb) - -**Relevant source code** -- [`bolt_option_parser.rb`](../lib/bolt/bolt_option_parser.rb) -- [`pwsh.rb`](../rakelib/lib/pwsh.rb) - -To generate this documentation, run: - -```shell -$ bundle exec rake docs:cmdlet_reference -``` - -### Bolt functions - -**Documentation page** -- https://puppet.com/docs/bolt/latest/plan_functions.html - -**Template file** -- [`reference.md.erb`](./templates/reference.md.erb) - -**Relevant source code** - -The rake task for this page uses `puppet-strings` to generate documentation -from comments in a function's source code. Bolt ships with several core modules -that are located in the `bolt-modules` directory. To modify the documentation -for a plan function, locate its file and modify the comments. - -- [`boltlib`](../bolt-modules/boltlib/lib/puppet/functions) -- [`ctrl`](../bolt-modules/boltlib/lib/puppet/functions) -- [`file`](../bolt-modules/boltlib/lib/puppet/functions) -- [`out`](../bolt-modules/boltlib/lib/puppet/functions) -- [`prompt`](../bolt-modules/boltlib/lib/puppet/functions) -- [`system`](../bolt-modules/boltlib/lib/puppet/functions) - -To generate this documentation, run: - -```shell -$ bundle exec rake docs:function_reference -``` - -### `bolt-defaults.yaml` options - -**Documentation page** -- https://puppet.com/docs/bolt/latest/bolt_defaults_reference.html - -**Template file** -- [`bolt_defaults_reference.md.erb`](./templates/bolt_defaults_reference.md.erb) - -**Relevant source code** -- [`config/options.rb`](../lib/bolt/config/options.rb) - -To generate this documentation, run: - -```shell -$ bundle exec rake docs:defaults_reference -``` - -### `bolt-project.yaml` options - -**Documentation page** -- https://puppet.com/docs/bolt/latest/bolt_project_reference.html - -**Template file** -- [`bolt_project_reference.md.erb`](./templates/bolt_project_reference.md.erb) - -**Relevant source code** -- [`config/options.rb`](../lib/bolt/config/options.rb) - -To generate this documentation, run: +Generate Jekyll-ready output (rendered templates + `.md` links rewritten to `.html`): ```shell -$ bundle exec rake docs:project_reference +bundle exec rake docs:jekyll ``` -### Transport configuration options +Output is written to `documentation/jekyll_build/` (gitignored). The openvox-docs +copy pipeline runs `rake docs:jekyll` and copies this directory to pick up the +reference pages. -**Documentation page** -- https://puppet.com/docs/bolt/latest/bolt_transports_reference.html +## Reference pages and their templates -**Template file** -- [`bolt_transports_reference.md.erb`](./templates/bolt_transports_reference.md.erb) - -**Relevant source code** -- [`config/transport/`](../lib/bolt/config/transport) (Each transport defines - its available options.) -- [`config/transport/options.rb`](../lib/bolt/config/transport/options.rb) - -To generate this documentation, run: - -```shell -$ bundle exec rake docs:transports_reference -``` - -### Escalating privilege with Bolt - -**Documentation page** -- https://puppet.com/docs/bolt/latest/privilege_escalation.html - -**Template file** -- [`privilege_escalation.md.erb`](./templates/privilege_escalation.md.erb) - -**Relevant source code** -- [`bolt_option_parser.rb`](../lib/bolt/bolt_option_parser.rb) -- [`config/transport/options.rb`](../lib/bolt/config/transport/options.rb) - -To generate this documentation, run: - -```shell -$ bundle exec rake docs:privilege_escalation -``` +| Page | Template | Rake task | +| ---- | -------- | --------- | +| Shell command reference | `templates/bolt_command_reference.md.erb` | `docs:command_reference` | +| PowerShell cmdlet reference | `templates/bolt_cmdlet_reference.md.erb` | `docs:cmdlet_reference` | +| Plan functions | `templates/plan_functions.md.erb` | `docs:function_reference` | +| `bolt-defaults.yaml` options | `templates/bolt_defaults_reference.md.erb` | `docs:defaults_reference` | +| `bolt-project.yaml` options | `templates/bolt_project_reference.md.erb` | `docs:project_reference` | +| Transport configuration | `templates/bolt_transports_reference.md.erb` | `docs:transports_reference` | +| Privilege escalation | `templates/privilege_escalation.md.erb` | `docs:privilege_escalation` | +| Bolt data types | `templates/bolt_types_reference.md.erb` | `docs:type_reference` | +| Packaged modules | `templates/packaged_modules.md.erb` | `docs:packaged_modules` | diff --git a/documentation/analytics.md b/documentation/analytics.md deleted file mode 100644 index f45ff1d99..000000000 --- a/documentation/analytics.md +++ /dev/null @@ -1,70 +0,0 @@ -# Analytics - -Bolt collects data about how you use it to help the Bolt team make decisions -about how to improve it. You can opt out of providing this data. Analytics is -disabled by default. - -## Opt out of data collection - -You can opt out of data collection by setting an option in Bolt's configuration -or by setting an environment variable. - -### Bolt configuration - -To disable data collection, set `analytics: false` in your [configuration -file](configuring_bolt.md). This option is supported in the system-wide, -user-level, and project configuration files. `false` is the default value. - -```yaml -# bolt-defaults.yaml -analytics: false -``` - -Setting the `analytics: false` option in a configuration file disables data -collection universally. You cannot override the option by setting it to `true` -in another configuration file. For example, setting `analytics: true` in a -project configuration file does not enable data collection if you've set -`analytics: false` in the system-wide or user-level configuration file. - -### Environment variable - -To disable data collection, set the `BOLT_DISABLE_ANALYTICS` environment -variable to any value. - -``` -export BOLT_DISABLE_ANALYTICS=true -``` - -## Data collected - -Each time you run Bolt, it collects the following information and associates it -with a randomly generated, non-identifiable user UUID: - -- Bolt version -- User locale -- Operating system and version -- The name of the executed command, such as `command run` or `task show` -- The names of built-in functions called from a plan -- Transports used and the number of targets using each transport -- The number of targets and groups defined in the inventory -- The number of targets targeted with a command -- The output format selected, such as `human` or `json` -- Whether the Bolt project directory was determined from the location of a - `bolt-project.yaml` file or with the `--project` command-line option -- The number of times built-in tasks and plans are run -- The number of statements in a manifest block and how many resources that - produces for each target -- The number of steps in a YAML plan -- The return type of a YAML plan, such as an expression or a value -- Which built-in plugins Bolt is using -- Topics viewed with `bolt guide ` -- IDs of any deprecation warnings -- Whether the source file for `upload_file`, `run_script`, or `file::read` plan - functions uses an absolute path or a module path. -- Whether a task is run in no-operation mode. -- Whether `future.script_interpreter` is enabled. - -## Viewing collected data - -To see the data Bolt collects, add the `--log-level trace` option to your Bolt -command or use `-LogLevel trace` if you're using PowerShell. diff --git a/documentation/applying_manifest_blocks.md b/documentation/applying_manifest_blocks.md deleted file mode 100644 index acfc86664..000000000 --- a/documentation/applying_manifest_blocks.md +++ /dev/null @@ -1,547 +0,0 @@ -# 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.md#dependency-management). - -📖 **Related information** - -- [Configure Bolt to download and install modules](bolt_installing_modules.md#) -- [Modules overview](modules.md) -- [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.md) 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.md#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.md) 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.md#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.md#). - -[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.md#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.md) - -## 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.md#puppetdb_query) -- [`puppetdb_facts`](plan_functions.md#puppetdb_facts) -- [`facts`](plan_functions.md#facts) -- [`vars`](plan_functions.md#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.md#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.md#adding-options-to-bolt-commands) -- [Bolt Projects](projects.md) - - -### 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.md#adding-options-to-bolt-commands) -- [Bolt projects](projects.md) -- [Puppet language Bolt plans](writing_plans.md) -- For information on how Bolt loads the modulepath, see [Modules overview](modules.md#modulepath). -- To learn more about using Puppet device modules, see [Running Bolt on network - devices](running_bolt_network.md#-using-puppet-device-modules-from-an-apply-block) diff --git a/documentation/automating_windows_targets.md b/documentation/automating_windows_targets.md deleted file mode 100644 index 696334755..000000000 --- a/documentation/automating_windows_targets.md +++ /dev/null @@ -1,285 +0,0 @@ -# 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.md#) 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.md). 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.md#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.md). For more - information about Bolt projects see [Bolt projects](projects.md). - - -### 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.md#) 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.md#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.md) -- 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.md) -- [Inventory files](inventory_files.md) -- [Applying Puppet code](applying_manifest_blocks.md) - -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/documentation/bolt.ditamap b/documentation/bolt.ditamap deleted file mode 100644 index d401ffdf4..000000000 --- a/documentation/bolt.ditamap +++ /dev/null @@ -1,142 +0,0 @@ - - - - - - bolt - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - How to construct and run Bolt commands. - - - - - Tips for running Bolt when targeting network devices. - - - - - - - How to run scripts using Bolt. - - - - - How to create a plan that runs a script. - - - - - - - Before you run a plan in your environment, inspect the plan to determine what effect it will have on your targets. - - - - - Bolt can run plans, allowing multiple scripts, tasks and Bolt commands to be tied together. - - - - - YAML plans run a list of steps in order, which allows you to define simple workflows. Steps can contain embedded Puppet code expressions to add logic where necessary. - - - - - Plans allow you to run more than one task with a single command, compute values for the input to a task, process the results of tasks, or make decisions based on the result of running a task. - - - - - - - - - Before you run a task in your environment, inspect the task to determine what effect it will have on your targets. - - - - - Bolt can run Puppet tasks on remote targets without requiring any Puppet infrastructure. - - - - - Bolt tasks are similar to scripts, but they are kept in modules and can have metadata. This allows you to reuse and share them. - - - - - - - - - - - - - - - - - - - - - - - - Examples of how to run Powershell scripts, use Bolt inventory, convert a script to a task, and write a Bolt plan, all on Windows. - - - - - An example of deploying a Telegraf, InfluxDB, and Grafana stack with Bolt, this demonstrates using existing Puppet content to quickly provide value. - - - - - - - - - - - - - - - - - - - diff --git a/documentation/bolt.md b/documentation/bolt.md deleted file mode 100644 index dda3d1a24..000000000 --- a/documentation/bolt.md +++ /dev/null @@ -1,91 +0,0 @@ -# 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/documentation/bolt_connect_puppetdb.md b/documentation/bolt_connect_puppetdb.md deleted file mode 100644 index b7dfacb4d..000000000 --- a/documentation/bolt_connect_puppetdb.md +++ /dev/null @@ -1,291 +0,0 @@ -# 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