DOCSEARCHbyAlgolia
Submit Docs

Puppet

repository·main·Indexed 27 days ago

https://github.com/puppetlabs/puppet

An automated administrative engine used to manage Linux, Unix, and Windows systems through centralized specifications. It enables tasks such as user management, package installation, and configuration updates. The project includes an HTTP API for programmatic interaction and a comprehensive acceptance testing framework using Beaker and Rake for validating changes across various hypervisors like Docker and VMPooler.

Tokens
88.9K
Snippets
165
Records
642
Agent score
91%

What's inside puppetlabs-puppet

  1. Overview of Puppet CLI subcommands

    main
    Puppet's command line interface is provided via a single puppet binary that utilizes various subcommands to perform different tasks. The subcommands are categorized by their frequency of use and intended audience: Core Tools, Secondary subcommands, and Niche subcommands.

  2. Overview of Puppet

    main
    Puppet is an automated administrative engine for Linux, Unix, and Windows systems. It performs administrative tasks—such as adding users, installing packages, and updating server configurations—based on a centralized specification.

  3. Understand Puppet resource types and providers

    main

    Puppet manages system state using resource types. Each type defines a desired state through attributes (parameters and properties).

    • Attributes/Parameters: Determine the desired state of a resource (e.g., owner, mode).
    • Providers: The implementation layer that executes the changes on the target system. Puppet selects a default provider automatically, but you can override it using the provider attribute.
    • Features: Specific capabilities supported by certain providers (e.g., a package provider might support a purgeable feature allowing ensure => purged).

    To interactively browse and manage resources via the CLI, use the puppet resource subcommand.

  4. Manage files with the `file` resource type

    main

    The file resource type manages files, directories, and symlinks, including their content, ownership, and permissions.

    Key behaviors:

    • Autorequires: Automatically requires the user or group that owns the file, and any parent directories of the file.
    • Windows Support: File contents are managed in binary mode; Puppet does not automatically translate line endings. Symlinks require the Puppet agent to have the "Create Symbolic Links" privilege.
    • Safety: Puppet avoids destroying directories unless the force attribute is set to true.

  5. Manage running services with the `service` resource type

    main

    The service resource type is used to manage running services on a target system. Because service support varies by platform, providing more information in the resource attributes helps ensure correct behavior.

    Handling Services without Status Commands

    If a service's init script lacks a working status command, you must:

    1. Set hasstatus => false.
    2. Either specify a custom command using the status attribute or rely on Puppet to search the process table using the pattern attribute.

    Refreshing Services

    service resources can respond to refresh events (via notify, subscribe, or the ~> arrow). When a service receives a refresh event, Puppet will restart it. The restart method follows this priority:

    1. If hasrestart => true, Puppet uses the init script's restart command.
    2. If the restart attribute is explicitly provided, Puppet uses that command.
    3. Otherwise, Puppet uses the service's stop and start commands.

  6. Define and use the `schedule` resource type

    main

    The schedule resource type allows you to define time-based windows for resource application. You can restrict specific resources from running by using the schedule metaparameter.

    Important Limitations:

    • Schedules can only stop a resource from being applied; they cannot force a resource to run at a specific time.
    • There is no guarantee a resource will run at a specific time; it will only run if a Puppet agent run occurs within the defined schedule.
    • It is recommended to use wide scheduling windows (e.g., several hours) combined with period and repeat to ensure execution occurs.
    • The statettl setting on the agent can affect schedule accuracy; if statettl is lower than the schedule span, resources might be applied multiple times because the last-checked information expired.
    schedule { 'everyday':
  period => daily,
  range  => '2 - 4',
}

exec { '/usr/bin/apt-get update':
  schedule => 'everyday',
}

  7. Use the exec resource to execute external commands

    main

    The exec resource allows you to run external commands on the target system. To ensure idempotency (preventing harm from multiple runs), you should use one of the following methods:

    1. Idempotent commands: Use commands that are safe to run multiple times (e.g., apt-get update).
    2. Conditional execution: Use onlyif, unless, or creates to prevent the command from running if certain conditions are met.
    3. Refresh-only: Use refreshonly => true to ensure the command only runs when triggered by a change in a dependent resource.

    Caution: If your exec logic becomes complex, consider developing a custom resource type instead for better predictability and maintainability.

  8. Manage packages with the `package` resource type

    main

    The package resource type allows you to manage software packages on a target system. Puppet can automatically detect the appropriate packaging format based on the platform, but you can manually specify a provider if needed.

    Key Behaviors:

    • Autorequires: If Puppet is managing the files specified in adminfile, responsefile, or source, the package resource will automatically require those files.
    • Referencing: You must use the resource title to make a reference to a package resource (e.g., Package['my_package_title']). The name attribute is not a synonym for the title in references.
    • Multiple Resources: You can declare multiple package resources with the same name as long as they have unique titles and different providers.

  9. Understand Puppet testing types

    main

    Puppet uses three primary types of automated testing:

    • Unit tests: Test individual components in isolation. They use canned information to hide system implementations and should never affect the system state. Located in the spec/ directory.
    • Integration tests: Test different units of code together to ensure subsystems interact correctly. Located in the spec/ directory.
    • Acceptance tests: Test high-level behaviors by changing system state and checking the result. These are destructive and should be run on throwaway systems. Located in the acceptance/tests/ directory.

  10. Manage files with the `file` type

    main

    The file type manages files, directories, and symlinks, including their content, ownership, and permissions.

    Key Behaviors:

    • Autorequires: Automatically requires the user or group managing the file, as well as any parent directories.
    • Content Management: Use content for direct strings or source to download from remote locations (e.g., puppet:///, http://, or local paths).
    • Windows Note: File contents are managed in binary mode; Puppet does not automatically translate line endings.
    • Directory Safety: Puppet avoids destroying directories unless force => true is set.

  11. Understand Puppet Run Modes

    main

    Puppet operates in different 'run modes', which change how settings are resolved. The default run mode is :user, but it can be switched to :agent or :server.

    For example, if puppet.conf contains:

    [server]
node_terminus=exec

    Calling Puppet[:node_terminus] will return exec if the run mode is :server, but will return nil (or the default) if the run mode is :user or :agent.

  12. Understand the Puppet HTTP API structure

    main

    Since Puppet 4, the HTTP API is split into two distinct, versioned APIs:

    1. Configuration API: Prefixed with /puppet. Used for configuration-related services like facts, catalogs, and reports.
    2. Certificate Authority (CA) API: Prefixed with /puppet-ca. Used for PKI and certificate management.

    All endpoints are explicitly versioned (e.g., /puppet/v3 or /puppet-ca/v1). While primarily designed for the Puppet agent, external tools can interact with these services.