Managing the Jamf Platform with Terraform: the Jamf Platform provider

In unseren bisherigen Artikeln haben wir die Grundlagen der Infrastructure as Code behandelt und gezeigt, wie Sie Jamf Pro und Jamf Protect Konfigurationen mit Terraform verwalten. Falls Sie diese noch nicht gelesen haben, lohnt es sich, damit zu beginnen, da sie Installation, Projektstruktur und State Management abdecken.

Dieses Mal konzentrieren wir uns auf die Jamf Platform APIs, die kürzlich in die öffentliche Beta eingetreten sind. Diese APIs treiben eine neue Generation von Jamf Microservices an, die neben Jamf Pro und Jamf Protect laufen, einschließlich Blueprints, Compliance Benchmarks und Device Groups. Wir haben einen dedizierten Terraform Provider entwickelt, mit dem Sie diese Ressourcen als Code verwalten können.

Warum ein dedizierter Provider für Jamf Platform Microservices?

Die Jamf Platform APIs sind eine separate API-Oberfläche von den Jamf Pro Classic und Pro APIs. Sie unterstützen Funktionen, die sich von den Ressourcen unterscheiden, die Sie mit dem Jamf Pro Provider verwalten, und authentifizieren sich durch einen anderen Satz von Credentials gegen ein regionales API Gateway (us.apigw.jamf.com, eu.apigw.jamf.com oder apac.apigw.jamf.com).

Blueprints ermöglichen es Ihnen, den gewünschten Konfigurationszustand für eine Gerätegruppe zu definieren und ihn in einer einzelnen Operation bereitzustellen. Compliance Benchmarks ermöglichen es Ihnen, Sicherheits-Baselines nach Branchenstandards aus dem macOS Security Compliance Project (mSCP) anzuwenden und zu überwachen, wie sich Ihre Flotte entwickelt. Device Groups bieten Ihnen eine Möglichkeit, Geräte auf Plattformebene zu organisieren und anzusteuern. Dies sind alles erstklassige Funktionen, die ihren eigenen Provider mit maßgeschneiderten Schemas für die verwalteten Ressourcen verdienen.

Falls Sie Blueprints und Benchmarks bisher über die Jamf Pro Konsole verwaltet haben, wissen Sie bereits, dass die Neuinitialisierung einer Konfiguration über Mandanten oder die Verfolgung von Änderungen im Laufe der Zeit viel Klickarbeit bedeutet. Mit diesem Provider lebt Ihre gesamte Konfiguration in Git, durchläuft Code Reviews und wird überall dort konsistent angewendet, wo Sie sie benötigen.

Was wird abgedeckt?

Der Provider wird mit 3 Ressourcen, 12 Data Sources, 3 List-Ressourcen und 4 Device Actions ausgeliefert. Hier sind die wichtigsten Bereiche:

Compliance Benchmark Engine - Erstellen und verwalten Sie Compliance Benchmarks gegen mSCP-Baselines einschließlich CIS Level 1 und 2, NIST 800-53 (Low, Moderate, High) und DISA STIG. Sie können einzelne Regeln aktivieren oder deaktivieren, Organisation-Defined Values (ODV) anpassen und Benchmarks auf bestimmte Device Groups anwenden. Data Sources ermöglichen es Ihnen, verfügbare Baselines, Regeln und vorhandene Benchmarks abzufragen.

Blueprints - Definieren Sie Device-Konfigurierungs-Blueprints, die Software-Update-Erzwingung, Software-Update-Einstellungen, Passcode-Richtlinien, Safari-Einstellungen, Lesezeichen und Erweiterungen, Disk Management, Audio-Zubehör-Einstellungen, Mathematik-Einstellungen, Service-Hintergrundaufgaben, Service-Konfigurationsdateien, Legacy-Payloads und benutzerdefinierte DDM-Deklarationen abdecken. Jeder Blueprint ist auf eine oder mehrere Device Groups ausgerichtet und kann als Code bereitgestellt oder zurückgezogen werden. Data Sources ermöglichen es Ihnen, vorhandene Blueprints und verfügbare Blueprint-Komponenten abzufragen.

Device Groups - Erstellen Sie intelligente und statische Device Groups für Computer und mobile Geräte mit kriteriengestützten Mitgliedschaftsregeln für intelligente Gruppen und expliziten Mitgliederlisten für statische Gruppen. Diese Gruppen werden von Benchmarks und Blueprints für die Ausrichtung referenziert.

Unified Inventory - Schreibgeschützte Data Sources zum Abfragen einzelner Geräte und Gerätelisten auf Plattformebene.

Device Actions - Terraform 1.14+ Actions für Lösch-, Neustart-, Herunterfahrts- und Aufhebungs-Vorgänge auf verwalteten Geräten.

Alle Ressourcen unterstützen vollständige CRUD-Operationen und terraform import.

Erste Schritte

Falls Sie dem Einführungsartikel gefolgt sind, sollten Sie bereits Terraform installiert haben und ein grundlegendes Verständnis für die Projektstruktur haben. Die Schritte hier sind ähnlich.

1. Erstellen Sie API-Credentials für die Jamf Platform API

Navigieren Sie zu Jamf Account und erstellen Sie einen API-Client mit den Berechtigungen, die Sie für die Ressourcen benötigen, die Sie verwalten möchten. Die Getting Started Anleitung im Jamf Developer Portal führt Sie durch diesen Prozess.

2. Konfigurieren Sie den Provider

Fügen Sie den Provider zu Ihrer Terraform-Konfiguration hinzu:

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
}

Sie können auch Umgebungsvariablen verwenden, um den Provider Block sauberer zu halten:

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"

Stellen Sie wie immer sicher, dass diese Credentials nicht in Ihrem Git-Repository landen. Verwenden Sie eine terraform.tfvars Datei und fügen Sie sie zu Ihrer .gitignore hinzu.

3. Definieren Sie Ihre Ressourcen

Lassen Sie uns einige hochgradig wirkungsvolle Beispiele durchgehen.

Device Groups

Bevor Sie Benchmarks oder Blueprints erstellen, möchten Sie eine Device Group, auf die Sie sie abzielen können. Hier ist eine intelligente Computer-Gruppe, die auf Geräte mit macOS 26 oder später abzielt:

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"
    }
  ]
}

Diese Gruppe kann dann anhand ihrer ID in Ihren Benchmark- und Blueprint-Ressourcen referenziert werden, sodass Terraform den Abhängigkeitsgraph versteht und alles in der richtigen Reihenfolge erstellt.

Compliance Benchmarks

Compliance Benchmarks verwenden die mSCP-Baselines, die in die Compliance Benchmark Engine eingebaut sind. Verwenden Sie zunächst eine Data Source, um die Regeln für die gewünschte Baseline abzurufen. Erstellen Sie dann einen Benchmark, der diese Regeln referenziert und auf Ihre Device Group abzielt:

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"
}

Dies erstellt einen CIS Level 1 Benchmark im Monitor-Modus, der auf die intelligente Gruppe beschränkt ist, die wir zuvor definiert haben. Jede Regel aus der Baseline ist enthalten, und Sie können einzelne Regeln selektiv deaktivieren oder benutzerdefinierte ODV-Werte setzen, um Ihre Organisationsanforderungen zu erfüllen. Beispiel zum Anpassen einer bestimmten Regel:

rules = [
  {
    id        = "system_settings_time_server_configure"
    enabled   = true
    odv_value = "ntp.example.com"
  },
  {
    id      = "system_settings_critical_update_install_enforce"
    enabled = true
  }
]

Das Setzen von enforcement_mode auf "MONITOR_AND_ENFORCE" führt eine automatische Behebung nicht konformer Einstellungen durch.

Es ist erwähnenswert, dass die Compliance Benchmark Engine API derzeit keine PUT- oder PATCH-Methode für Benchmarks bietet. Dies bedeutet, dass jede Änderung an einer Benchmark-Ressource in Ihrer Terraform-Konfiguration zu einer Zerstörungs- und Wiederherstellung (Force Replacement) führt, anstatt ein lokales Update durchzuführen. Berücksichtigen Sie dies, wenn Sie Änderungen an Benchmarks vornehmen, die bereits bereitgestellt sind und aktiv auf Geräten berichten.

Die eigentliche Stärke liegt darin, dass Sie den genauen Satz von Regeln und Anpassungen, die Sie angewendet haben, in der Versionskontrolle pflegen, Änderungen über Pull Requests überprüfen und denselben Benchmark über mehrere Mandanten hinweg ohne manuelle Aufwände replizieren können.

Blueprints

Blueprints kombinieren mehrere Konfigurationskomponenten zu einer einzelnen Einheit, die auf eine oder mehrere Device Groups bereitgestellt wird. Jeder Komponententyp entspricht einer Declarative Device Management (DDM) Deklarations-Konfigurationsdomäne. Hier ist ein Blueprint, der Software-Update-Einstellungen mit Aufschüben und automatischer Installation konfiguriert:

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"
  }
}

Und hier ist ein Blueprint, der eine Passcode-Richtlinie erzwingt:

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
  }
}

Jeder Blueprint wird einer einzelnen Gerätegruppe über das Attribut device_groups zugeordnet, das eine Reihe von Platform UUIDs benötigt. Wenn Sie deployed auf true setzen, werden Sie dem Provider mitteilen, den Blueprint bereitzustellen (und erneut bereitzustellen, falls er nicht aktuell ist). Wenn Sie es auf false setzen, wird es nicht bereitgestellt.

Sie können auch die Komponente software_update verwenden, um eine bestimmte Betriebssystemversion bis zu einem bestimmten Datum zu erzwingen, das Attribut legacy_payloads für traditionelle Konfigurationsprofile-Payloads oder custom_declarations für beliebige DDM-Deklarationen, für die der Provider noch keine dedizierte Komponente hat.

4. Wenden Sie Ihre Konfiguration an

Die gleichen Befehle, die Sie von den anderen Providern kennen, gelten auch hier:

terraform init       # Initialize and download the provider
terraform plan       # Review what will be created, changed or destroyed
terraform apply      # Apply the changes (you'll be asked to confirm)

Bringen Sie einen vorhandenen Mandanten unter Verwaltung

Falls Sie bereits Blueprints, Benchmarks und Device Groups in Ihrem Mandanten konfiguriert haben, müssen Sie nicht von vorne beginnen. Jede Ressource im Provider unterstützt terraform import, sodass Sie vorhandene Ressourcen unter Terraform-Verwaltung bringen können, ohne sie neu zu erstellen.

Entdecken Sie vorhandene Ressourcen mit Terraform query

Falls Sie Terraform 1.14+ verwenden, unterstützt der Provider List Resources, eine Funktion, mit der Sie Ihre vorhandene Infrastruktur direkt von Terraform aus abfragen können. Dies ist nützlich, um zu entdecken, was bereits in Ihrem Mandanten vorhanden ist, bevor Sie es importieren.

Erstellen Sie eine Query-Datei (z. B. 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"
    }
  }
}

Führen Sie dann aus:

terraform query -generate-config-out=generated.tf

Terraform fragt Ihren Mandanten ab, gibt die entsprechenden Ressourcen zusammen mit ihren IDs zurück und generiert sowohl die Ressourcenblöcke als auch die Import-Blöcke in generated.tf. Die Blueprint- und Benchmark-List-Ressourcen unterstützen einen search Filter für Substring-Matching (Groß-/Kleinschreibung egal) gegen Namen und Beschreibungen. Die Device Group List-Ressource unterstützt filter Blöcke mit RSQL-Selektoren für name, description, deviceType und groupType, was Ihnen präzise Kontrolle über die zurückgegebenen Gruppen gibt.

Import von Ressourcen

Sobald Sie die IDs haben, die Sie benötigen, können Sie Import Blöcke verwenden, um sie unter Verwaltung zu bringen. Mit 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"
}

Führen Sie terraform plan aus, um die Konfiguration für die importierten Ressourcen zu generieren, verfeinern Sie sie nach Bedarf, und ab diesem Punkt werden sie als Code verwaltet. Weitere Informationen zum Massen-Import von Ressourcen finden Sie in der Bulk-Import-Dokumentation von HashiCorp.

Verwendung neben anderen Jamf Providern

Dieser Provider ist für die Zusammenarbeit mit anderen Terraform Providern im Jamf Ökosystem konzipiert. Sie können ihn zusammen mit diesen verwenden:

Jamf Protect Provider - zur Verwaltung von Ressourcen in Jamf Protect (Endpoint Security Pläne, Threat Prevention, Telemetry und vieles mehr) über die Jamf Protect GraphQL API.
Deployment Theory Jamf Pro Provider - zur Verwaltung von Ressourcen in Jamf Pro (Richtlinien, Skripte, Konfigurationsprofile, Gruppen und vieles mehr) über seine Classic und Pro APIs.

Mit diesen Providern können Sie Ihre gesamte Jamf-Umgebung als Code aus einem einzelnen Terraform-Projekt verwalten. Ein übliches Muster ist die Verwendung des Jamf Pro Providers zum Erstellen von Ressourcen wie intelligenten Gruppen und Richtlinien, die anschließend die resultierenden Platform IDs im Jamf Platform Provider für Benchmarks und Blueprints referenzieren.

Beteiligung

Der Provider ist Open-Source unter der MPL-Lizenz und wird sowohl in der HashiCorp als auch in der OpenTofu Registry veröffentlicht. Er wird auf HashiCorps Terraform Plugin Framework (Protokoll v6) aufgebaut und umfasst umfassende Integrationstests. Der Provider verwendet unseres Open-Source jamfplatform-go-SDK, das Sie in Ihre eigenen Go-Projekte zum Scripting und zur Automatisierung gegen die Jamf Platform API importieren können.

Wir begrüßen Beiträge. Bug Reports, Feature Requests und Pull Requests sind alle willkommen. Der Provider wird sich weiterhin parallel mit den Jamf Platform APIs entwickeln, wenn weitere Funktionen hinzugefügt werden.

Anleitungen