Discharge7443/fleet
1
0
Fork 0
Code Issues Pull Requests Actions 31 Packages Projects Releases Wiki Activity

Add docs for Fleet's Puppet module (#13837)

Browse Source 
- Add doc page to explain setup and usage of Fleet's Puppet module
This commit is contained in:
Noah Talerman
2023-09-13 16:39:41 -04:00
committed by GitHub
parent 1ce9eb5976
commit c481d67abb
2 changed files with 158 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/Using Fleet/Puppet-module.md
+157
View File
@@ -0,0 +1,157 @@
# Puppet module
_Available in Fleet Premium_
Use [Fleet's Puppet module](https://forge.puppet.com/modules/fleetdm/fleetdm/readme) to automatically install custom configuration profiles on your macOS hosts based on host attributes you define in Puppet.
The module also includes functions for releasing a macOS host from [Await Configuration](https://developer.apple.com/documentation/devicemanagement/release_device_from_await_configuration) and sending any custom MDM commands.
## Setup
To set up the Puppet module, we will do the following steps:
1. Install the Puppet module
2. Configure Puppet to talk to Fleet using Hiera
3. Set Fleet as a reporter
### Step 1: install the Puppet module
Install [Fleet's Puppet module](https://forge.puppet.com/modules/fleetdm/fleetdm/readme). For more instructions on how to install Puppet modules, check out the Puppet docs [here](https://www.puppet.com/docs/puppet/8/modules_installing.html).
### Step 2: configure Puppet to talk to Fleet using Heira
1. Create an API-only user with the GitOps role in Fleet. Instructions for creating an API-only user in Fleet are [here](./fleetctl-CLI.md#create-an-api-only-user).
2. Get the API token for your new API-only user. Learn how [here](./fleetctl-CLI.md#get-the-api-token-of-an-api-only-user).
3. Set `fleetdm::host` and `fleetdm::token` values to your Fleet server's URL and the API token respectively. Here's an example of the Hiera YAML:
```yaml
fleetdm::host: https://fleet.example.com
fleetdm::token: your-api-token
```
Puppet docs on configuring Hiera are [here](https://www.puppet.com/docs/puppet/6/hiera_config_yaml_5.html).
If you have staging and production Puppet environments, you can optionally set different values for each environment. This allows you to have your staging and production environments that talk to separate staging and production Fleet servers.
### Step 3: set Fleet as a reporter
In your Puppet configuration, set `http:fleetdm` as the value for `reports`. Here's an example of the Puppet configuration:
```
reports = http,fleetdm
```
Puppet configuration reference docs are [here](https://www.puppet.com/docs/puppet/7/configuration#reports).
## Install configuration profiles
Using the Puppet module you can define the set of configuration profiles for each host (Puppet node) and Fleet will create a team with these profiles and assign the host to that team.
When a host is assigned to a team in Fleet, all configuration profiles for that team are installed on the host.
As an example, let's install one configuration profile on all hosts. Here's what your Puppet code will look like:
```pp
node default {
fleetdm::profile { 'com.apple.payload.identifier':
template => template('example-profile.mobileconfig'),
group => 'MacOS workstations',
}
}
```
This will create a team called "MacOS workstations" with the `example-profile.mobileconfig` configuration profile and assign all hosts to this team.
Use the `group` parameter to define the team name in Fleet.
As another example, let's assign one configuration profile to all hosts and another configuration profile to only my M1 hosts. Here's what your Puppet code will look like:
```pp
node default {
fleetdm::profile { 'com.apple.payload.identifier-1':
template => template('example-profile.mobileconfig'),
group => 'MacOS workstations',
}
if $facts['architecture'] == 'intel' {
fleetdm::profile { 'com.apple.payload.identifier-2':
ensure => absent,
template => template('m1-only.mobileconfig'),
group => 'Intel',
}
} else {
fleetdm::profile { 'com.apple.example-2':
template => template('com.apple.payload.identifier-2'),
group => 'MacOS workstations',
}
}
}
```
This will create two teams in Fleet:
1. "MacOS workstations" with two configuration profiles: `example-profile.mobileconfig` and `m1-only.mobileconfig`.
2. "MacOS workstations - Intel" with one configuration profile: `example-profile.mobileconfig`.
Set the `ensure` parameter to `absent` to create teams that exclude specific profiles.
For more examples check out the `examples/` folder in Fleet's GitHub repository [here](https://github.com/fleetdm/fleet/tree/main/ee/tools/puppet/fleetdm/examples).
> Note that all teams created by Puppet inherit the bootstrap package, macOS Setup Assistant settings, and end user authentication settings from "No team." Learn more about these [here](./MDM-macOS-setup.md). In addition all teams automatically enable disk encryption. Learn more about disk encryption [here](./MDM-disk-encryption.md).
## Release host
If you set `await_device_configured` to `true` in your [macOS Setup Assistant settings](./MDM-macOS-setup.md#macos-setup-assistant), you can use the `fleetdm::release_device` function to release the host from the Setup Assistant.
Here's what your Puppet code, with error handling, will look like:
```pp
$host_uuid = $facts['system_profiler']['hardware_uuid']
$response = fleetdm::release_device($host_uuid)
$err = $response['error']
if $err != '' {
notify { "error releasing device: ${err}": }
}
```
## Custom commands
You can use the `fleetdm::command_xml` function to send any custom MDM command to a host.
Here's what your Puppet code, with error handling, will look like:
```pp
$host_uuid = $facts['system_profiler']['hardware_uuid']
$command_uuid = generate('/usr/bin/uuidgen').strip
$xml_data = "<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE plist PUBLIC '-//Apple//DTD PLIST 1.0//EN' 'http://www.apple.com/DTDs/PropertyList-1.0.dtd'>
<plist version='1.0'>
<dict>
<key>Command</key>
<dict>
<key>RequestType</key>
<string>EnableRemoteDesktop</string>
</dict>
<key>CommandUUID</key>
<string>${command_uuid}</string>
</dict>
</plist>"
$response = fleetdm::command_xml($host_uuid, $xml_data)
$err = $response['error']
if $err != '' {
notify { "Error sending MDM command: ${err}": }
}
```
The above example includes the XML payload for the `EnableRemoteDesktop` MDM command. Learn more about creating the payload for other custom commands [here](./MDM-commands.md).
<meta name="pageOrderInSection" value="1508">
<meta name="title" value="Puppet module">
<meta name="description" value="Learn how to use Fleet's Puppet module to automatically assign custom configuration profiles on your macOS hosts.">
<meta name="navSection" value="Device management">
ee/tools/puppet/fleetdm/README.md
+1 -150
View File
@@ -1,150 +1 @@
# fleetdm
## Table of Contents
1. [Description](#description)
1. [Setup - The basics of getting started with fleetdm](#setup)
* [Setup requirements](#setup-requirements)
* [Beginning with fleetdm](#beginning-with-fleetdm)
1. [Usage - Configuration options and additional functionality](#usage)
* [Defining profiles for a device](#defining-profiles-for-a-device)
* [Releasing a device from await configuration](#releasing-a-device-from-await-configuration)
3. [Limitations - OS compatibility, etc.](#limitations)
4. [Development - Guide for contributing to the module](#development)
## Description
Manage MDM settings for macOS devices using [Fleet](https://fleetdm.com)
## Setup
### Setup Requirements
This module requires to add `fleetdm` as a reporter in your `report` settings,
this helps Fleet understand when your Puppet run is finished and assign the
device to a team with the necessary profiles.
For example, in your server configuration:
```
reports = http,fleetdm
```
To communicate with the Fleet server, you also need to provide your server URL
and a token as Hiera values:
```yaml
---
fleetdm::host: https://example.com
fleetdm::token: my_token
```
Note: for the token, we recommend using an [API-only user][1], with a GitOps role.
### Beginning with fleetdm
## Usage
### Defining profiles for a device
The `examples/` folder in this repo contain some examples. Generally, you can
define profiles using the custom resource type `fleetdm::profile`:
```pp
node default {
fleetdm::profile { 'com.apple.universalaccess':
template => template('fleetdm/profile-template.mobileconfig.erb'),
group => 'workstations',
}
}
```
The `group` parameter is used to create/match profiles with teams in
Fleet. In the example above, all devices will be assigned to a team named
`workstations`.
You can use this feature along with the `ensure` param to create teams that
**don't** contain specific profiles, for example given the following manifest:
```pp
node default {
fleetdm::profile { 'com.apple.universalaccess':
template => template('fleetdm/profile-template.mobileconfig.erb'),
group => 'workstations',
}
if $facts['architecture'] == 'x86_64' {
fleetdm::profile { 'my.arm.only.profile':
ensure => absent,
template => template('fleetdm/my-arm-only-profile.mobileconfig.erb'),
group => 'amd64',
}
} else {
fleetdm::profile { 'my.arm.only.profile':
template => template('fleetdm/my-arm-only-profile.mobileconfig.erb'),
group => 'workstations',
}
}
}
```
Assuming you have devices with both architectures checking in, you'll end up
with the following two teams in Fleet:
- `workstations`: with two profiles, `com.apple.universalaccess` and `my.arm.only.profile`
- `workstations - amd64`: with only one profile, `com.apple.universalaccess`
### Sending a custom MDM Command
You can use the `fleetdm::command_xml` function to send any custom MDM command to the device:
```pp
$host_uuid = $facts['system_profiler']['hardware_uuid']
$command_uuid = generate('/usr/bin/uuidgen').strip
$xml_data = "<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE plist PUBLIC '-//Apple//DTD PLIST 1.0//EN' 'http://www.apple.com/DTDs/PropertyList-1.0.dtd'>
<plist version='1.0'>
<dict>
<key>Command</key>
<dict>
<key>RequestType</key>
<string>EnableRemoteDesktop</string>
</dict>
<key>CommandUUID</key>
<string>${command_uuid}</string>
</dict>
</plist>"
$response = fleetdm::command_xml($host_uuid, $xml_data)
$err = $response['error']
if $err != '' {
notify { "Error sending MDM command: ${err}": }
}
```
### Releasing a device from await configuration
If your DEP profile had `await_device_configured` set to `true`, you can use the `fleetdm::release_device` function to release the device:
```
$host_uuid = $facts['system_profiler']['hardware_uuid']
$response = fleetdm::release_device($host_uuid)
$err = $response['error']
if $err != '' {
notify { "error releasing device: ${err}": }
}
```
## Limitations
At the moment, this module only works for macOS devices.
## Development
Information about how to contribute can be found in the [`CONTRIBUTING.md` file](https://github.com/fleetdm/fleet/blob/main/ee/tools/puppet/fleetdm/CONTRIBUTING.md).
[1]: https://fleetdm.com/docs/using-fleet/fleetctl-cli#using-fleetctl-with-an-api-only-user
Learn how to setup and use Fleet's Puppet module here on [fleetdm.com/docs](https://fleetdm.com/docs/using-fleet/puppet-module).