update_trusted_facts

Module containing a plan to update trusted facts on nodes via the Puppet Enterprise console.

Table of Contents

1. Description
2. Setup - The basics of getting started with update_trusted_facts
   • What update_trusted_facts affects
   • Beginning with update_trusted_facts
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

The built in method to update trusted facts in Puppet enterprise requires root shell access to the Puppet primary server. This level of access is generally not available to most users in an organisation and provides significant more access than required for this task.

By using this module, fine grained access can be granted to specific users to update trusted facts via the update_trusted_facts plan from the console.

Furthermore this plan preserves all existing facts on an agent certificate and does not rely on the csr_attributes.yaml file being present on a host.

Setup

What update_trusted_facts affects

This module affects the following

• Updates the csr_attributes.yaml file on systems. Taking the existing trusted facts from agent certificate and merging the proposed changes set in the plan. Existing values in csr_attributes.yaml will be replaced during this process This also occurs when the plan is run in noop
• Regenerates the agent certificate using the puppet infrastructure run regenerate_agent_certificate Does not perform this step in noop

Beginning with update_trusted_facts

Include the module within your Puppetfile.

Usage

Run the plan update_trusted_facts::update_trusted_facts from the Puppet Enterprise console.

Note: If you restrict access to plans via RBAC and only grant users permission to run this plan; you will also need to grant users access to enterprise_tasks::agent_cert_regen plan.

Required parameters

• targets (TargetSpec - see here)

Targets can be specified as a comma separated list to run the plan on multiple host at a time.

Optional parameters

• pe_primary_server (FQDN) - Update_trusted_facts will automatically attempt to resolve the primary using the pe_status_check_role fact. Setting this parameter will override that behaviour.
• preserve_existing_facts (Boolean - whether to keep existing facts. If set to false all existing facts will be wiped and replace with those set in the plan)
• ignore_infra_status_error (Boolean - Ignore errors from puppet infrastructure status command. May allow the plan to operate if some Puppet infrastructure components are failing)
• noop (Boolean - Run the plan in noop. csr_attributes.yaml will still generated however certificates will not be resigned.)

Trusted facts supported The following trusted facts are supported by the plan. All are optional parameters, set as required. All accept String as input.

• pp_role
• pp_uuid
• pp_environment
• pp_apptier
• pp_department
• pp_datacenter
• pp_instance_id
• pp_image_name
• pp_preshared_key
• pp_cost_center
• pp_product
• pp_project
• pp_application
• pp_service
• pp_employee
• pp_created_by
• pp_software_version
• pp_cluster
• pp_provisioner
• pp_region
• pp_zone
• pp_network
• pp_securitypolicy
• pp_cloudplatform
• pp_hostname

Limitations

Tested with the following combinations. Expected to work for all Windows, Enterprise Linux, Debian, Ubuntu versions.

Puppet Enterprise

• 2021.7.2

Puppet Nodes

• Windows 2019
• RHEL 8

To support legacy version of Puppet Enterprise (Before changing naming standard to Primary server from master.) You must set the support_legacy_pe parameter to true.

Development

If you find any issues with this module, please log them in the issues register of the GitHub project. Issues

Reference

Table of Contents

Functions

• update_trusted_facts::trusted_fact_names: Returns an array of trusted facts lint:ignore:140chars

Tasks

• confirm_primary_server: A short description of this task
• set_csr_attributes: Merges existing trusted fact

Plans

• update_trusted_facts::update_trusted_facts: PE plan to update trusted facts on a certificate via Puppet enterprise console, while preserving existing trusted facts.

Functions

update_trusted_facts::trusted_fact_names

Type: Puppet Language

Returns an array of trusted facts lint:ignore:140chars

update_trusted_facts::trusted_fact_names()

Returns an array of trusted facts lint:ignore:140chars

Returns: Array of trusted facts

Tasks

confirm_primary_server

A short description of this task

Supports noop? false

Parameters

pe_primary_server

Data type: String

Puppet Primary server hostname

ignore_infra_status_error

Data type: Boolean

Ignore puppet infra status stderr

set_csr_attributes

Merges existing trusted fact

Supports noop? false

Parameters

trusted_facts

Data type: Hash

Trusted facts to add

preserve_existing_facts

Data type: Boolean

Preserve existing trusted facts

Plans

update_trusted_facts::update_trusted_facts

lint:ignore:140chars lint:ignore:strict_indent

This plans allows for the easy modification of trusted facts on already deployed nodes via the Puppet Enterprise console. It will preserve the existing trusted facts by reading the existing certificate and merging any proposed changes over existing. This behaviour can be changed by setting the preserve_existing_facts parameter to false We require the Puppet Primary to be specified when runing the plan due to limitations of running plans in orchestor.

To learn more about Puppet plans, see documentation:

• http://pup.pt/bolt-puppet-plans
• https://www.puppet.com/docs/pe/2021.7/plans_limitations.html

Parameters

The following parameters are available in the update_trusted_facts::update_trusted_facts plan:

• targets
• pe_primary_server
• preserve_existing_facts
• ignore_infra_status_error
• noop
• support_legacy_pe
• pp_role
• pp_uuid
• pp_environment
• pp_apptier
• pp_department
• pp_datacenter
• pp_instance_id
• pp_image_name
• pp_preshared_key
• pp_cost_center
• pp_product
• pp_project
• pp_application
• pp_service
• pp_employee
• pp_created_by
• pp_software_version
• pp_cluster
• pp_provisioner
• pp_region
• pp_zone
• pp_network
• pp_securitypolicy
• pp_cloudplatform
• pp_hostname

targets

Data type: TargetSpec

The targets to run on (note this must match the certnames used by Puppet / shown in PE console).

pe_primary_server

Data type: Optional[Stdlib::Fqdn]

The Puppet Enterprise primary server in your PE installation you are running the plan from. Update_trusted_facts will automatically attempt to resolve the primary using the pe_status_check_role fact. Setting this parameter will override that behaviour.

Default value: undef

preserve_existing_facts

Data type: Boolean

Whether to preserve existing facts from the nodes. If set to false all existing facts will be wiped and replaced with those set in the plan. Default: true

Default value: true

ignore_infra_status_error

Data type: Boolean

Ignore errors from 'puppet infrastructure status' command. This is used to verify the primary server. Can be used to allow the plan the run when some PE components are unavaliable. Default: false

Default value: false

noop

Data type: Boolean

Run the plan in noop. csr_attributes.yaml will still generated, however certificates will not be resigned. Default: false

Default value: false

support_legacy_pe

Data type: Boolean

Attempt to support legacy PE. Default: false

Default value: false

pp_role

Data type: Optional[String]

Set the pp_role trusted fact. Default: undef

Default value: undef

pp_uuid

Data type: Optional[String]

Set the pp_uuid trusted fact. Default: undef

Default value: undef

pp_environment

Data type: Optional[String]

Set the pp_environment trusted fact. Default: undef

Default value: undef

pp_apptier

Data type: Optional[String]

Set the pp_apptier trusted fact. Default: undef

Default value: undef

pp_department

Data type: Optional[String]

Set the pp_department trusted fact. Default: undef

Default value: undef

pp_datacenter

Data type: Optional[String]

Set the pp_datacenter trusted fact. Default: undef

Default value: undef

pp_instance_id

Data type: Optional[String]

Set the pp_instance_id trusted fact. Default: undef

Default value: undef

pp_image_name

Data type: Optional[String]

Set the pp_image_name trusted fact. Default: undef

Default value: undef

pp_preshared_key

Data type: Optional[String]

Set the pp_preshared_key trusted fact. Default: undef

Default value: undef

pp_cost_center

Data type: Optional[String]

Set the pp_cost_center trusted fact. Default: undef

Default value: undef

pp_product

Data type: Optional[String]

Set the pp_product trusted fact. Default: undef

Default value: undef

pp_project

Data type: Optional[String]

Set the pp_project trusted fact. Default: undef

Default value: undef

pp_application

Data type: Optional[String]

Set the pp_application trusted fact. Default: undef

Default value: undef

pp_service

Data type: Optional[String]

Set the pp_service trusted fact. Default: undef

Default value: undef

pp_employee

Data type: Optional[String]

Set the pp_employee trusted fact. Default: undef

Default value: undef

pp_created_by

Data type: Optional[String]

Set the pp_created_by trusted fact. Default: undef

Default value: undef

pp_software_version

Data type: Optional[String]

Set the pp_software_version trusted fact. Default: undef

Default value: undef

pp_cluster

Data type: Optional[String]

Set the pp_cluster trusted fact. Default: undef

Default value: undef

pp_provisioner

Data type: Optional[String]

Set the pp_provisioner trusted fact. Default: undef

Default value: undef

pp_region

Data type: Optional[String]

Set the pp_region trusted fact. Default: undef

Default value: undef

pp_zone

Data type: Optional[String]

Set the pp_zone trusted fact. Default: undef

Default value: undef

pp_network

Data type: Optional[String]

Set the pp_network trusted fact. Default: undef

Default value: undef

pp_securitypolicy

Data type: Optional[String]

Set the pp_securitypolicy trusted fact. Default: undef

Default value: undef

pp_cloudplatform

Data type: Optional[String]

Set the pp_cloudplatform trusted fact. Default: undef

Default value: undef

pp_hostname

Data type: Optional[String]

Set the pp_hostname trusted fact. Default: undef

Default value: undef

Changelog

All notable changes to this project will be documented in this file.

Release 2.0.0

Features

• Improve plan run time by using enterprise_task::test_connect to verify connectivity. Thanks chambersmp
• Bumped PDK to version 3.2.0
• Plan can now automatically detect the primary server thanks to the pe_status_check_role fact.
• Minor lint fixes.
• Added github actions lint and unit tests.

Release 1.0.0

Features

• Added support for older Puppet enterprise versions which still use 'master' instead of 'primary server'. (must set the support_legacy_pe parameter to true to enable this support)

Bugfixes

• Added exception handling for reading existing csr_attributes.yaml. Corrupted yaml caused the plan to fail for that node. Csr_attributes data is now ignored if its invalid.

Release 0.2.0

Features

• Minor documentation updates

Bugfixes

• No longer require a valid API token under the root user on the Puppet primary server. https://github.com/benjamin-robertson/update_trusted_facts/issues/1

Known Issues

Release 0.1.0

Features

• First release to forge.

Bugfixes

Known Issues