{"payload":{"allShortcutsEnabled":false,"fileTree":{"docs":{"items":[{"name":"connect_bolt_pe.md","path":"docs/connect_bolt_pe.md","contentType":"file"},{"name":"sensitive_task_output.md","path":"docs/sensitive_task_output.md","contentType":"file"}],"totalCount":2},"":{"items":[{"name":"docs","path":"docs","contentType":"directory"},{"name":"spec","path":"spec","contentType":"directory"},{"name":"tasks","path":"tasks","contentType":"directory"},{"name":".fixtures.yml","path":".fixtures.yml","contentType":"file"},{"name":".gitattributes","path":".gitattributes","contentType":"file"},{"name":".gitignore","path":".gitignore","contentType":"file"},{"name":".gitlab-ci.yml","path":".gitlab-ci.yml","contentType":"file"},{"name":".pdkignore","path":".pdkignore","contentType":"file"},{"name":".project","path":".project","contentType":"file"},{"name":".rspec","path":".rspec","contentType":"file"},{"name":".rubocop.yml","path":".rubocop.yml","contentType":"file"},{"name":".travis.yml","path":".travis.yml","contentType":"file"},{"name":".yardopts","path":".yardopts","contentType":"file"},{"name":"CHANGELOG.md","path":"CHANGELOG.md","contentType":"file"},{"name":"CODEOWNERS","path":"CODEOWNERS","contentType":"file"},{"name":"Gemfile","path":"Gemfile","contentType":"file"},{"name":"LICENSE","path":"LICENSE","contentType":"file"},{"name":"README.md","path":"README.md","contentType":"file"},{"name":"Rakefile","path":"Rakefile","contentType":"file"},{"name":"appveyor.yml","path":"appveyor.yml","contentType":"file"},{"name":"metadata.json","path":"metadata.json","contentType":"file"}],"totalCount":21}},"fileTreeProcessingTime":9.364048,"foldersToFetch":[],"repo":{"id":128118822,"defaultBranch":"main","name":"puppetlabs-bolt_shim","ownerLogin":"puppetlabs","currentUserCanPush":false,"isFork":false,"isEmpty":false,"createdAt":"2018-04-04T20:35:58.000Z","ownerAvatar":"https://avatars.githubusercontent.com/u/234268?v=4","public":true,"private":false,"isOrgOwned":true},"symbolsExpanded":false,"treeExpanded":true,"refInfo":{"name":"main","listCacheKey":"v0:1639688196.5155861","canEdit":false,"refType":"branch","currentOid":"d1b21a6dd51b42be94b010d17693339904f4d4d2"},"path":"docs/connect_bolt_pe.md","currentUser":null,"blob":{"rawLines":null,"stylingDirectives":null,"colorizedLines":null,"csv":null,"csvError":null,"dependabotInfo":{"showConfigurationBanner":false,"configFilePath":null,"networkDependabotPath":"/puppetlabs/puppetlabs-bolt_shim/network/updates","dismissConfigurationNoticePath":"/settings/dismiss-notice/dependabot_configuration_notice","configurationNoticeDismissed":null},"displayName":"connect_bolt_pe.md","displayUrl":"https://github.com/puppetlabs/puppetlabs-bolt_shim/blob/main/docs/connect_bolt_pe.md?raw=true","headerInfo":{"blobSize":"6.93 KB","deleteTooltip":"You must be signed in to make or propose changes","editTooltip":"You must be signed in to make or propose changes","ghDesktopPath":"https://desktop.github.com","isGitLfs":false,"onBranch":true,"shortPath":"2ded46c","siteNavLoginPath":"/login?return_to=https%3A%2F%2Fgithub.com%2Fpuppetlabs%2Fpuppetlabs-bolt_shim%2Fblob%2Fmain%2Fdocs%2Fconnect_bolt_pe.md","isCSV":false,"isRichtext":true,"toc":[{"level":1,"text":"Connecting Bolt to PE","anchor":"connecting-bolt-to-pe","htmlText":"Connecting Bolt to PE"},{"level":2,"text":"How it works","anchor":"how-it-works","htmlText":"How it works"},{"level":2,"text":"Connecting Bolt to PE","anchor":"connecting-bolt-to-pe-1","htmlText":"Connecting Bolt to PE"},{"level":3,"text":"Install the bolt_shim module in a PE environment","anchor":"install-the-bolt_shim-module-in-a-pe-environment","htmlText":"Install the bolt_shim module in a PE environment"},{"level":3,"text":"Assign task permissions to a user role","anchor":"assign-task-permissions-to-a-user-role","htmlText":"Assign task permissions to a user role"},{"level":3,"text":"Specify and configure the PCP transport","anchor":"specify-and-configure-the-pcp-transport","htmlText":"Specify and configure the PCP transport"},{"level":3,"text":"Configure Bolt to connect to PuppetDB","anchor":"configure-bolt-to-connect-to-puppetdb","htmlText":"Configure Bolt to connect to PuppetDB"},{"level":2,"text":"Running tasks","anchor":"running-tasks","htmlText":"Running tasks"},{"level":2,"text":"Limitations","anchor":"limitations","htmlText":"Limitations"}],"lineInfo":{"truncatedLoc":"161","truncatedSloc":"128"},"mode":"file"},"image":false,"isCodeownersFile":null,"isPlain":false,"isValidLegacyIssueTemplate":false,"issueTemplate":null,"discussionTemplate":null,"language":"Markdown","languageID":222,"large":false,"planSupportInfo":{"repoIsFork":null,"repoOwnedByCurrentUser":null,"requestFullPath":"/puppetlabs/puppetlabs-bolt_shim/blob/main/docs/connect_bolt_pe.md","showFreeOrgGatedFeatureMessage":null,"showPlanSupportBanner":null,"upgradeDataAttributes":null,"upgradePath":null},"publishBannersInfo":{"dismissActionNoticePath":"/settings/dismiss-notice/publish_action_from_dockerfile","releasePath":"/puppetlabs/puppetlabs-bolt_shim/releases/new?marketplace=true","showPublishActionBanner":false},"rawBlobUrl":"https://github.com/puppetlabs/puppetlabs-bolt_shim/raw/main/docs/connect_bolt_pe.md","renderImageOrRaw":false,"richText":"

Connecting Bolt to PE

\n

Although it's possible to connect Bolt to Puppet Enterprise (PE) using the\nPuppet Communications Protocol (PCP) transport, in most cases this is not\nnecessary, because tasks and plans are already supported from the console or the\ncommand line using\nPE orchestrator.\nWherever possible, we recommend using PE tasks and plans instead of connecting\nBolt to PE over PCP. For more information, see Tasks and\nplans.

\n

For some Bolt features, connecting Bolt to PE over PCP requires the bolt_shim\nmodule. Before you attempt to use the bolt_shim module, note that:

\n\n

You might want to use the PCP transport for the following reasons:

\n\n

How it works

\n

Using the bolt_shim module, you can configure Bolt to use the orchestrator API\nand perform actions on PE nodes. When you run Bolt plans, the plan logic is\nprocessed locally on the node running Bolt, while corresponding commands,\nscripts, tasks, and file uploads run remotely using the orchestrator API.

\n

Connecting Bolt to PE

\n

Before you can connect Bolt to PE, you must install\nBolt.

\n

To set up Bolt to use the orchestrator API, you must:

\n\n

Install the bolt_shim module in a PE environment

\n

Bolt uses a task to execute commands, upload files, and run scripts over\norchestrator. To install this task, install the puppetlabs-bolt_shim\nmodule from the Forge. Install\nthe code in the same environment as the other tasks you want to run.

\n

In addition to the bolt_shim module, any task or module content you want to\nexecute over Puppet Communications Protocol (PCP) must be present in the PE\nenvironment. For details about downloading and installing modules for Bolt, see\nSet up Bolt to download and install\nmodules.\nBy allowing only content that is present in the PE environment to be executed\nover PCP, you maintain role-based access control over the nodes you manage in\nPE.

\n

To enable the Boltapply action, you must install the\npuppetlabs-apply_helpers\nmodule.

\n

Note: Bolt over orchestrator can require a large amount of memory to convey\nlarge messages, such as the plugins and catalogs sent by apply. You might need\nto increase the Java heap\nsize\nfor orchestration services.

\n

Assign task permissions to a user role

\n
\n

CAUTION: Tasks executed with the bolt_shim module allow users\nto run any command as root on the nodes. Use the module at\nyour own risk.

\n
\n
    \n
  1. \n

    In the console, click Access control > User roles.

    \n
  2. \n
  3. \n

    From the list of user roles, click the role you want to have task\npermissions.

    \n
  4. \n
  5. \n

    On the Permissions tab, in the Type box, select Tasks.

    \n
  6. \n
  7. \n

    For Permission, select Run tasks, and select All from the\nInstance drop-down list.

    \n
  8. \n
  9. \n

    Click Add permission, and commit the change.

    \n
  10. \n
\n

Specify and configure the PCP transport

\n

Bolt runs tasks through the orchestrator when a target uses the pcp transport.\nYou can configure Bolt to connect to orchestrator in the config section of\nyour inventory file, or in the inventory-config section of your\nbolt-defaults.yaml file. This configuration is not shared with puppet task. By default, Bolt uses the\nproduction environment in PE when running tasks.

\n

For example, your inventory file might look something\nlike this:

\n
groups: \n  - name: linux    \n    targets:\n      - nix0.example.com\n  - name: windows  \n    targets:\n      - win0.example.com\nconfig: \n  transport: pcp\n  pcp:\n    cacert: \"certs/cert.pem\"\n    service-url: \"https://primary.example.com:8143\"\n    token-file: \"tokens/token\"
\n

If you want to connect to multiple PE instances, create groups for each instance\nand configure the pcp transport for each group.

\n

For more information on configuration options for the pcp transport, see\nTransport configuration\noptions.

\n

Configure Bolt to connect to PuppetDB

\n

Bolt can authenticate with PuppetDB through an SSL client certificate or a PE\nRBAC token. For more information see the Bolt docs for Connecting Bolt to\nPuppetDB.

\n
puppetdb:\n  server_urls: [\"https://expensive-tower.delivery.puppetlabs.net:8081\", \"https://amber-publisher.delivery.puppetlabs.net:8081\"]\n  cacert: /tmp/ca.pem\n  token: ~/.puppetlabs/token
\n

Running tasks

\n

In order to run tasks on nodes connected to your PE instance, each task must be\ninstalled on the PE primary. To view tasks or plans installed on the PE primary's\nproduction environment, run puppet task show or puppet plan show\nrespectively. To specify an environment other than production, use the\n--environment flag. For example, puppet task show --environment test.

\n

Limitations

\n

Some PCP functionality, such as running scripts, does not work if your\n/tmp directory is mounted with noexec.

\n
","renderedFileInfo":null,"shortPath":null,"symbolsEnabled":true,"tabSize":8,"topBannersInfo":{"overridingGlobalFundingFile":false,"globalPreferredFundingPath":null,"showInvalidCitationWarning":false,"citationHelpUrl":"https://docs.github.com/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files","actionsOnboardingTip":null},"truncated":false,"viewable":true,"workflowRedirectUrl":null,"symbols":{"timed_out":false,"not_analyzed":false,"symbols":[{"name":"Connecting Bolt to PE","kind":"section_1","ident_start":2,"ident_end":23,"extent_start":0,"extent_end":7101,"fully_qualified_name":"Connecting Bolt to PE","ident_utf16":{"start":{"line_number":0,"utf16_col":2},"end":{"line_number":0,"utf16_col":23}},"extent_utf16":{"start":{"line_number":0,"utf16_col":0},"end":{"line_number":161,"utf16_col":0}}},{"name":"How it works","kind":"section_2","ident_start":2293,"ident_end":2305,"extent_start":2290,"extent_end":2613,"fully_qualified_name":"How it works","ident_utf16":{"start":{"line_number":39,"utf16_col":3},"end":{"line_number":39,"utf16_col":15}},"extent_utf16":{"start":{"line_number":39,"utf16_col":0},"end":{"line_number":46,"utf16_col":0}}},{"name":"Connecting Bolt to PE","kind":"section_2","ident_start":2616,"ident_end":2637,"extent_start":2613,"extent_end":6576,"fully_qualified_name":"Connecting Bolt to PE","ident_utf16":{"start":{"line_number":46,"utf16_col":3},"end":{"line_number":46,"utf16_col":24}},"extent_utf16":{"start":{"line_number":46,"utf16_col":0},"end":{"line_number":149,"utf16_col":0}}},{"name":"Install the `bolt_shim` module in a PE environment","kind":"section_3","ident_start":3045,"ident_end":3095,"extent_start":3041,"extent_end":4390,"fully_qualified_name":"Install the `bolt_shim` module in a PE environment","ident_utf16":{"start":{"line_number":57,"utf16_col":4},"end":{"line_number":57,"utf16_col":54}},"extent_utf16":{"start":{"line_number":57,"utf16_col":0},"end":{"line_number":83,"utf16_col":0}}},{"name":"Assign task permissions to a user role","kind":"section_3","ident_start":4394,"ident_end":4432,"extent_start":4390,"extent_end":4970,"fully_qualified_name":"Assign task permissions to a user role","ident_utf16":{"start":{"line_number":83,"utf16_col":4},"end":{"line_number":83,"utf16_col":42}},"extent_utf16":{"start":{"line_number":83,"utf16_col":0},"end":{"line_number":102,"utf16_col":0}}},{"name":"Specify and configure the PCP transport","kind":"section_3","ident_start":4974,"ident_end":5013,"extent_start":4970,"extent_end":6102,"fully_qualified_name":"Specify and configure the PCP transport","ident_utf16":{"start":{"line_number":102,"utf16_col":4},"end":{"line_number":102,"utf16_col":43}},"extent_utf16":{"start":{"line_number":102,"utf16_col":0},"end":{"line_number":136,"utf16_col":0}}},{"name":"Configure Bolt to connect to PuppetDB","kind":"section_3","ident_start":6106,"ident_end":6143,"extent_start":6102,"extent_end":6576,"fully_qualified_name":"Configure Bolt to connect to PuppetDB","ident_utf16":{"start":{"line_number":136,"utf16_col":4},"end":{"line_number":136,"utf16_col":41}},"extent_utf16":{"start":{"line_number":136,"utf16_col":0},"end":{"line_number":149,"utf16_col":0}}},{"name":"Running tasks","kind":"section_2","ident_start":6579,"ident_end":6592,"extent_start":6576,"extent_end":6971,"fully_qualified_name":"Running tasks","ident_utf16":{"start":{"line_number":149,"utf16_col":3},"end":{"line_number":149,"utf16_col":16}},"extent_utf16":{"start":{"line_number":149,"utf16_col":0},"end":{"line_number":157,"utf16_col":0}}},{"name":"Limitations","kind":"section_2","ident_start":6974,"ident_end":6985,"extent_start":6971,"extent_end":7101,"fully_qualified_name":"Limitations","ident_utf16":{"start":{"line_number":157,"utf16_col":3},"end":{"line_number":157,"utf16_col":14}},"extent_utf16":{"start":{"line_number":157,"utf16_col":0},"end":{"line_number":161,"utf16_col":0}}}]}},"copilotInfo":null,"copilotAccessAllowed":false,"csrf_tokens":{"/puppetlabs/puppetlabs-bolt_shim/branches":{"post":"kG3fUAczD94lXASXnDPnYfoHRcqT3joxU-NFfn5bAyi21AFfPcJiCL972BlIdWFWG-uMxYS-Y8RF0vdVxki09w"},"/repos/preferences":{"post":"nbbKCnGU4xIhT34Uayw-6fawmsIqclu7zt130a5Eq5Rko0Vjopo3LDNhQjeXEeYYHseKT30xbxkfY13C2KLUHw"}}},"title":"puppetlabs-bolt_shim/docs/connect_bolt_pe.md at main · puppetlabs/puppetlabs-bolt_shim"}