https://github.com/puppetlabs/puppetlabs-bootstrap
The bootstrap task module
https://github.com/puppetlabs/puppetlabs-bootstrap
module unsupported
Last synced: 3 months ago
JSON representation
The bootstrap task module
- Host: GitHub
- URL: https://github.com/puppetlabs/puppetlabs-bootstrap
- Owner: puppetlabs
- License: apache-2.0
- Created: 2017-09-15T04:20:55.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2025-02-04T18:15:43.000Z (5 months ago)
- Last Synced: 2025-03-29T10:08:08.230Z (3 months ago)
- Topics: module, unsupported
- Language: PowerShell
- Homepage:
- Size: 246 KB
- Stars: 4
- Watchers: 97
- Forks: 34
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# bootstrap
#### Table of Contents
1. [Description](#description)
1. [Requirements](#requirements)
1. [Usage - Configuration options and additional functionality](#usage)
1. [Reference - An under-the-hood peek at what the task is doing and how](#reference)
1. [Limitations - OS compatibility, etc.](#limitations)
1. [Development - Guide for contributing to the module](#development)
1. [Getting help - Some Helpful commands](#getting-help)
## Description
This module provides the bootstrap task. This allows you to install Puppet agents on un-puppeted hosts via the ssh or winrm transports.
> This module is not supported or maintained by Puppet and does not qualify for Puppet Support plans. It's provided without guarantee or warranty and you can use it at your own risk. All bugfixes, updates, and new feature development will come from community contributions.
>
> [tier:community]
## Requirements
This module requires both the `bolt` gem on the machine from which you are running bolt commands (the controller node), and a Puppet Enterprise 2017.3 or later master hosting agent repositories.
Linux machines receiving task requests must have bash for now. Windows machines must have PowerShell. (See [Limitations](#limitations) for more info.)
## Usage
To run the bootstrap task, use the bolt command, specifying the PE master from which the Puppet agent package should be installed and to which the agent should submit its certificate for signing.
#### Example: Basic usage
On the command line:
* For Linux, run `bolt task run bootstrap::linux master= --nodes x,y,z --modulepath /path/to/modules`
* For Windows, run `bolt task run bootstrap::windows master= --nodes x,y,z --modulepath /path/to/modules`
For all advanced examples below, simply replace `bootstrap::linux` by `bootstrap::windows` to perform the action on Windows
#### Example: Verify the master's CA on initial connection
Optionally to validate the connection during the bootstrap process, specify the puppet master's CA cert by adding the cacert_content option:
`bolt task run bootstrap::linux master= cacert_content="$(cat /etc/puppetlabs/puppet/ssl/certs/ca.pem)" --nodes x,y,z --modulepath /path/to/modules`
#### Example: Specify a custom certname
Optionally to install the Puppet agent with a certname other than the fqdn of the target node, specify the custom certname:
`bolt task run bootstrap::linux master= certname= --nodes x,y,z --modulepath /path/to/modules`
#### Example: Specify the environment
Optionally to install the puppet-agent with a specific environment other than the default environment `production`, specify the custom environment:
`bolt task run bootstrap::linux master= environment= --nodes x,y,z --modulepath /path/to/modules`
#### Example: Specify noop
Optionally to install the puppet-agent with noop:
`bolt task run bootstrap::linux master= set_noop=true--nodes x,y,z --modulepath /path/to/modules`
#### Example: Specify custom dns alt names
Optionally to install the Puppet agent with custom dns alt names, specify the custom dns alt names:
`bolt task run bootstrap::linux master= dns_alt_names= --nodes x,y,z --modulepath /path/to/modules`
(see [Compile master installation](https://docs.puppet.com/pe/latest/install_multimaster.html) documentation for more info).
You can also run tasks in the PE console. See PE task documentation for complete information.
#### Example: Specify a custom_attribute
Optionally to install the Puppet agent and adding a setting to puppet.conf and including it in the custom_attributes section of csr_attributes.yaml: `bolt task run bootstrap master= custom_attribute='["="]' --nodes x,y,z --modulepath /path/to/modules`
#### Example: Specify a extension_request
Optionally to install the Puppet agent and adding a setting to puppet.conf and including it in the extension_requests section of csr_attributes.yaml: `bolt task run bootstrap master= extension_request=key='["="]' --nodes x,y,z --modulepath /path/to/modules`
## Reference
For detailed reference information, see the [REFERENCE.md](https://github.com/puppetlabs/puppetlabs-bootstrap/blob/master/REFERENCE.md)
## Limitations
The bootstrap task currently installs the agent via the Puppet Enterprise package management tools, and FOSS repository support will be added later. See the [Puppet Enterprise](https://puppet.com/docs/pe/latest/installing_agents.html) documentation for more information.
For an extensive list of supported operating systems, see [metadata.json](https://github.com/puppetlabs/puppetlabs-bootstrap/blob/master/metadata.json)
The bootstrap task is tested to work with Windows Management Framework >= v3.0+ and .NET >= v4.6 on the supported Windows operating systems.
## Development
Acceptance tests for this module leverage [puppet_litmus](https://github.com/puppetlabs/puppet_litmus).
To run the acceptance tests follow the instructions [here](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module).
You can also find a tutorial and walkthrough of using Litmus and the PDK on [YouTube](https://www.youtube.com/watch?v=FYfR7ZEGHoE).
If you submit a change to this module, be sure to regenerate the reference documentation as follows:
```bash
puppet strings generate --format markdown --out REFERENCE.md
```
## Getting Help
To display help for the bootstrap task, run `puppet task show bootstrap::linux` or `puppet task show bootstrap::windows`
To show help for the task CLI, run `puppet task run --help` or `bolt task run --help`