In onze vorige artikelen behandelden we de fundamenten van Infrastructure as Code en hoe u Jamf Pro en Jamf Protect-configuratie met Terraform kunt beheren. Als u die nog niet heeft gelezen, zijn ze de moeite waard om mee te beginnen aangezien ze installatie, projectstructuur en state management behandelen.
Deze keer richten we onze aandacht op de Jamf Platform API's, die recent in publieke beta zijn gegaan. Deze API's ondersteunen een nieuwe generatie Jamf-microservices die naast Jamf Pro en Jamf Protect zitten, inclusief blueprints, Compliance Benchmarks en apparaatgroepen. We hebben een specifieke Terraform-provider gebouwd waarmee u deze resources als code kunt beheren.
Waarom een specifieke provider voor Jamf Platform-microservices?
De Jamf Platform API's zijn een apart API-oppervlak van de Jamf Pro Classic en Pro API's. Ze ondersteunen mogelijkheden die verschillen van de resources die u beheert met de Jamf Pro-provider, en ze authenticeren via een andere set credentials tegen een regionale API-gateway (us.apigw.jamf.com, eu.apigw.jamf.com of apac.apigw.jamf.com).
Blueprints laten u de gewenste configuratiestatus voor een groep apparaten definiëren en deze in één operatie uitrollen. Compliance Benchmarks laten u industrie-standaard beveiligingsbaselines van het macOS Security Compliance Project (mSCP) toepassen en monitoren hoe uw vloot eraan voldoet. Apparaatgroepen geven u een manier om apparaten op platformniveau te organiseren en te targeten. Dit zijn allemaal first-class mogelijkheden die hun eigen provider verdienen, met schema's die speciaal zijn gebouwd voor de resources die ze beheren.
Als u blueprints en benchmarks via de Jamf Pro-console heeft beheerd, weet u al dat het recreëren van een setup over tenants of het bijhouden van wijzigingen in de tijd veel klikken betekent. Met deze provider leeft uw volledige configuratie in Git, gaat door code review en wordt consistent toegepast waar u het nodig heeft.
Wat dekt het?
De provider wordt geleverd met 3 resources, 12 data sources, 3 list resources en 4 device actions. Hier zijn de belangrijkste gebieden:
Compliance Benchmark Engine - Maak en beheer compliance benchmarks tegen mSCP-baselines inclusief CIS Level 1 en 2, NIST 800-53 (Low, Moderate, High) en DISA STIG. U kunt individuele regels in- of uitschakelen, Organization-Defined Values (ODV) aanpassen en benchmarks targeten naar specifieke apparaatgroepen. Data sources laten u beschikbare baselines, regels en bestaande benchmarks opvragen.
Blueprints - Definieer apparaatconfiguratie-blueprints die software update-handhaving, software update-instellingen, wachtwoordbeleid, Safari-instellingen, bladwijzers en extensies, schijfbeheer, audio-accessoire-instellingen, wiskundige instellingen, service-achtergrondtaken, service-configuratiebestanden, legacy payloads en aangepaste DDM-declaraties omvatten. Elke blueprint target een of meer apparaatgroepen en kan als code worden uitgerold of teruggetrokken. Data sources laten u bestaande blueprints en beschikbare blueprint-componenten opvragen.
Apparaatgroepen - Maak smart en static apparaatgroepen voor computers en mobiele apparaten, met criteria-gebaseerde lidmaatschapsregels voor smart groups en expliciete ledenlijsten voor static groups. Deze groepen worden gerefereerd door benchmarks en blueprints voor targeting.
Unified Inventory - Alleen-lezen data sources voor het opvragen van individuele apparaten en apparaatlijsten op platformniveau.
Device Actions - Terraform 1.14+ actions voor wissen, herstarten, afsluiten en unmanage-operaties tegen beheerde apparaten.
Alle resources ondersteunen volledige CRUD-operaties en terraform import.
Aan de slag
Als u het introductie-artikel heeft gevolgd, zou u al Terraform geïnstalleerd moeten hebben en een basiskennis van hoe projecten zijn gestructureerd. De stappen hier zijn vergelijkbaar.
1. Maak API-credentials voor de Jamf Platform API
Ga naar Jamf Account en maak een API-client met de permissies die u nodig heeft voor de resources die u wilt beheren. De Getting Started-gids op het Jamf Developer-portaal leidt u door dit proces.
2. Configureer de provider
Voeg de provider toe aan uw Terraform-configuratie:
terraform {
required_providers {
jamfplatform = {
source = "Jamf-Concepts/jamfplatform"
version = "~> 0.15.0"
}
}
}
provider "jamfplatform" {
base_url = var.jamfplatform_base_url
client_id = var.jamfplatform_client_id
client_secret = var.jamfplatform_client_secret
tenant_id = var.jamfplatform_tenant_id
}
U kunt ook omgevingsvariabelen gebruiken om het provider-blok schoon te houden:
export JAMFPLATFORM_BASE_URL="https://us.apigw.jamf.com"
export JAMFPLATFORM_CLIENT_ID="your-client-id"
export JAMFPLATFORM_CLIENT_SECRET="your-client-secret"
export JAMFPLATFORM_TENANT_ID="your-tenant-id"
Zoals altijd, zorg ervoor dat deze credentials niet in uw Git-repository belanden. Gebruik een terraform.tfvars-bestand en voeg het toe aan uw .gitignore.
3. Definieer uw resources
Laten we enkele impactvolle voorbeelden doorlopen.
Apparaatgroepen
Voordat u benchmarks of blueprints maakt, wilt u een apparaatgroep om ze op te targeten. Hier is een smart computergroep die apparaten target die macOS 26 of later draaien:
resource "jamfplatform_device_group" "macos_26_plus" {
name = "macOS 26+"
group_type = "smart"
device_type = "computer"
criteria = [
{
criteria = "Operating System Version"
operator = "greater than or equal"
value = "26.0"
}
]
}
Deze groep kan vervolgens op ID worden gerefereerd in uw benchmark- en blueprint-resources, zodat Terraform de afhankelijkheidsgrafiek begrijpt en alles in de juiste volgorde aanmaakt.
Compliance benchmarks
Compliance benchmarks gebruiken de mSCP-baselines die zijn ingebouwd in de Compliance Benchmark Engine. Gebruik eerst een data source om de regels voor de gewenste baseline op te halen. Maak dan een benchmark die naar die regels verwijst en uw apparaatgroep target:
data "jamfplatform_cbengine_rules" "cis_lvl1" {
baseline_id = "cis_lvl1"
}
resource "jamfplatform_cbengine_benchmark" "cis_level_1" {
title = "CIS macOS Level 1"
description = "CIS Level 1 benchmark - Managed by Terraform"
source_baseline_id = "cis_lvl1"
sources = [
for s in data.jamfplatform_cbengine_rules.cis_lvl1.sources : {
branch = s.branch
revision = s.revision
}
]
rules = [
for r in data.jamfplatform_cbengine_rules.cis_lvl1.rules : {
id = r.id
enabled = r.enabled
}
]
target_device_group = jamfplatform_device_group.macos_26_plus.id
enforcement_mode = "MONITOR"
}
Dit maakt een CIS Level 1-benchmark in monitormodus, gescoped naar de smart group die we eerder definieerden. Elke regel van de baseline is opgenomen, en u kunt selectief individuele regels uitschakelen of aangepaste ODV-waarden instellen om overeen te komen met de vereisten van uw organisatie. Bijvoorbeeld, om een specifieke regel aan te passen:
rules = [
{
id = "system_settings_time_server_configure"
enabled = true
odv_value = "ntp.example.com"
},
{
id = "system_settings_critical_update_install_enforce"
enabled = true
}
]
Het instellen van enforcement_mode op "MONITOR_AND_ENFORCE" zal niet-conforme instellingen automatisch herstellen.
Het is vermeldenswaard dat de Compliance Benchmark Engine API momenteel geen PUT- of PATCH-methode biedt voor benchmarks. Dit betekent dat elke wijziging aan een benchmark-resource in uw Terraform-configuratie resulteert in een destroy-and-recreate (force replacement) in plaats van een in-place update. Houd dit in gedachten bij het maken van wijzigingen aan benchmarks die al zijn uitgerold en actief rapporteren op apparaten.
De echte kracht hier is dat u de exacte set regels en aanpassingen die u heeft toegepast kunt versiebeheren, wijzigingen kunt reviewen via pull requests en dezelfde benchmark kunt repliceren over meerdere tenants met nul handmatige inspanning.
Blueprints
Blueprints componeren meerdere configuratiecomponenten in één eenheid die wordt uitgerold naar een of meer apparaatgroepen. Elk componenttype mapt naar een Declarative Device Management (DDM) declaratie-configuratiedomein. Hier is een blueprint die software update-instellingen configureert met uitstellingen en automatische installatie:
resource "jamfplatform_blueprints_blueprint" "software_update_settings" {
name = "Software Update Settings"
description = "Managed by Terraform"
deployed = true
device_groups = [jamfplatform_device_group.macos_26_plus.id]
software_update_settings = {
allow_standard_user_os_updates = true
automatic_download = "AlwaysOn"
automatic_install_os_updates = "AlwaysOn"
automatic_install_security_updates = "AlwaysOn"
deferral_major_period_days = 30
deferral_minor_period_days = 14
deferral_system_period_days = 3
notifications_enabled = true
rapid_security_response_enabled = true
rapid_security_response_rollback_enabled = false
recommended_cadence = "Newest"
}
}
En hier is een blueprint die een wachtwoordbeleid afdwingt:
resource "jamfplatform_blueprints_blueprint" "passcode_policy" {
name = "Passcode Policy"
description = "Managed by Terraform"
deployed = true
device_groups = [jamfplatform_device_group.macos_26_plus.id]
passcode_policy = {
require_passcode = true
require_alphanumeric_passcode = true
minimum_length = 12
minimum_complex_characters = 1
maximum_failed_attempts = 10
maximum_inactivity_in_minutes = 5
maximum_passcode_age_in_days = 90
passcode_reuse_limit = 5
}
}
Elke blueprint mapt naar één set apparaatgroepen via het device_groups-attribuut, dat een set Platform UUID's accepteert. Het instellen van deployed op true vertelt de provider de blueprint uit te rollen (en opnieuw uit te rollen als deze achterloopt). Het instellen op false trekt deze terug.
U kunt ook de software_update-component gebruiken om een specifieke OS-versie tegen een specifieke datum af te dwingen, het legacy_payloads-attribuut voor traditionele configuratieprofiel-payloads, of custom_declarations voor willekeurige DDM-declaraties waarvoor de provider nog geen specifieke component heeft.
4. Pas uw configuratie toe
Dezelfde commando's die u kent van de andere providers zijn hier van toepassing:
terraform init # Initialiseer en download de provider
terraform plan # Bekijk wat wordt aangemaakt, gewijzigd of vernietigd
terraform apply # Pas de wijzigingen toe (u wordt gevraagd te bevestigen)
Een bestaande tenant onder beheer brengen
Als u al blueprints, benchmarks en apparaatgroepen geconfigureerd heeft in uw tenant, hoeft u niet vanaf nul te beginnen. Elke resource in de provider ondersteunt terraform import, zodat u bestaande resources onder Terraform-beheer kunt brengen zonder ze opnieuw aan te maken.
Bestaande resources ontdekken met Terraform query
Als u Terraform 1.14+ draait, ondersteunt de provider list resources, een functie waarmee u uw bestaande infrastructuur rechtstreeks vanuit Terraform kunt bevragen. Dit is nuttig om te ontdekken wat er al in uw tenant zit voordat u het importeert.
Maak een query-bestand (bijv. discover.tfquery.hcl):
list "jamfplatform_blueprints_blueprint" "software_update" {
provider = jamfplatform
include_resource = true
config {
search = "software update"
}
}
list "jamfplatform_cbengine_benchmark" "cis_benchmarks" {
provider = jamfplatform
include_resource = true
config {
search = "CIS"
}
}
list "jamfplatform_device_group" "smart_computer_groups" {
provider = jamfplatform
include_resource = true
config {
filter {
selector = "deviceType"
argument = "COMPUTER"
}
filter {
join_with = "and"
selector = "groupType"
argument = "SMART"
}
}
}
Voer dan uit:
terraform query -generate-config-out=generated.tf
Terraform bevraagt uw tenant, retourneert de overeenkomende resources samen met hun ID's, en genereert zowel de resource-blokken als import-blokken in generated.tf. De blueprint- en benchmark-list resources ondersteunen een search-filter voor case-insensitive substring-matching tegen namen en beschrijvingen. De apparaatgroep-list resource ondersteunt filter-blokken met RSQL-selectors voor name, description, deviceType en groupType, wat u precieze controle geeft over welke groepen worden geretourneerd.
Resources importeren
Zodra u de ID's heeft die u nodig heeft, kunt u import-blokken gebruiken om ze onder beheer te brengen. Met Terraform 1.5+:
import {
to = jamfplatform_blueprints_blueprint.software_update_settings
id = "your-blueprint-uuid"
}
import {
to = jamfplatform_cbengine_benchmark.cis_level_1
id = "your-benchmark-uuid"
}
Voer terraform plan uit om de configuratie voor de geïmporteerde resources te genereren, verfijn deze indien nodig, en vanaf dat moment worden ze beheerd als code. Voor meer over bulk-importeren van resources, zie HashiCorp's bulk import documentation.
Gebruiken naast andere Jamf-providers
Deze provider is ontworpen om samen te werken met de andere Terraform-providers in het Jamf-ecosysteem. U kunt het samen gebruiken met:
- Jamf Protect Provider - voor het beheren van resources in Jamf Protect (endpoint security plans, threat prevention, telemetrie en meer) via de Jamf Protect GraphQL API.
- Deployment Theory Jamf Pro Provider - voor het beheren van resources in Jamf Pro (policies, scripts, configuratieprofielen, groepen en meer) via zijn Classic en Pro API's.
Tussen deze providers kunt u uw volledige Jamf-omgeving als code beheren vanuit één Terraform-project. Een gangbaar patroon is de Jamf Pro-provider te gebruiken om resources zoals smart groups en policies aan te maken, en vervolgens de resulterende Platform ID's te refereren in de Jamf Platform-provider voor benchmarks en blueprints.
Meedoen
De provider is open-source onder de MPL-licentie en gepubliceerd op zowel de HashiCorp als OpenTofu registries. Het is gebouwd op HashiCorp's Terraform Plugin Framework (Protocol v6) en bevat integratietests door het hele project. De provider gebruikt onze open source jamfplatform-go-sdk die u kunt importeren in uw eigen Go-projecten voor scripting en automatisering tegen de Jamf Platform API.
We verwelkomen bijdragen. Bugrapporten, feature requests en pull requests worden allemaal gewaardeerd. De provider zal blijven groeien in lijn met de Jamf Platform API's naarmate meer mogelijkheden worden toegevoegd.