使用 Terraform 管理 Jamf Platform：Jamf Platform provider

在我們之前的文章中，我們涵蓋了基礎設施即程式碼的基礎知識，以及如何使用 Terraform 管理 Jamf Pro 和 Jamf Protect 設定。如果您還沒有閱讀這些文章，值得先從這些開始，因為它們涵蓋了安裝、專案結構和狀態管理。

這次我們將重點放在 Jamf Platform APIs 上，這些 API 最近進入公開測試版。這些 API 為新一代 Jamf 微服務提供支持，這些微服務與 Jamf Pro 和 Jamf Protect 並行，包括 blueprints、合規基準和設備群組。我們建立了一個專用的 Terraform provider，讓您可以將這些資源作為程式碼來管理。

為什麼需要為 Jamf Platform 微服務提供專用 provider？

Jamf Platform APIs 是與 Jamf Pro Classic 和 Pro APIs 分離的 API 表面。它們提供的功能與使用 Jamf Pro provider 管理的資源不同，並透過針對區域 API 閘道的不同認證集進行驗證（us.apigw.jamf.com、eu.apigw.jamf.com 或 apac.apigw.jamf.com）。

Blueprints 讓您定義一群設備所需的設定狀態，並在單一操作中進行部署。合規基準讓您應用來自 macOS Security Compliance Project (mSCP) 的業界標準安全基準，並監控您的設備群落的表現。設備群組提供了在平台級別組織和鎖定設備的方式。這些都是值得擁有自己 provider 的第一類功能，具有為其管理的資源量身打造的架構。

如果您一直透過 Jamf Pro 主控台管理 blueprints 和基準，您已經知道跨租戶重新建立設定或追蹤變更意味著大量點擊。使用此 provider，您的整個設定存在於 Git 中，透過程式碼審查，並在您需要的任何地方一致地應用。

涵蓋範圍？

該 provider 附帶 3 個資源、12 個資料來源、3 個列表資源和 4 個設備動作。主要領域包括：

合規基準引擎 - 根據 mSCP 基準（包括 CIS Level 1 和 2、NIST 800-53（低、中、高）和 DISA STIG）建立和管理合規基準。您可以啟用或停用個別規則、自訂組織定義值 (ODV) 並將基準鎖定到特定設備群組。資料來源讓您查詢可用的基準、規則和現有基準。

Blueprints - 定義設備設定 blueprints，涵蓋軟體更新強制執行、軟體更新設定、密碼原則、Safari 設定、書籤和擴充功能、磁碟管理、音訊配件設定、數學設定、服務背景工作、服務設定檔、舊版酬載和自訂 DDM 宣告。每個 blueprint 鎖定一個或多個設備群組，可以作為程式碼進行部署或取消部署。資料來源讓您查詢現有 blueprints 和可用的 blueprint 元件。

設備群組 - 為電腦和行動設備建立智慧和靜態設備群組，具有智慧群組的條件型成員資格規則和靜態群組的明確成員清單。基準和 blueprints 參考這些群組以進行鎖定。

統一庫存 - 用於在平台級別查詢個別設備和設備清單的唯讀資料來源。

設備動作 - Terraform 1.14+ 動作，針對受管設備執行擦除、重新啟動、關機和取消管理操作。

所有資源都支持完整的 CRUD 操作和 terraform import。

入門

如果您遵循了介紹文章，您應該已經安裝了 Terraform 並對專案結構方式有基本的了解。此處的步驟類似。

1. 為 Jamf Platform API 建立 API 認證

前往 Jamf Account 並建立具有您需要之權限的 API 用戶端，以管理您想要管理的資源。Jamf Developer 入口網站上的 Getting Started 指南會逐步說明此程序。

2. 設定 provider

將 provider 新增至您的 Terraform 設定：

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
}

您也可以使用環境變數來保持 provider 塊清潔：

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"

如往常一樣，請確保這些認證不會在您的 Git 儲存庫中結束。使用 terraform.tfvars 檔案並將其新增至您的 .gitignore。

3. 定義您的資源

讓我們逐步介紹一些高影響力的範例。

設備群組

在建立基準或 blueprints 之前，您需要一個設備群組來鎖定它們。以下是智慧電腦群組，以執行 macOS 26 或更新版本的設備為目標：

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

此群組可以透過 ID 在您的基準和 blueprint 資源中參考，以便 Terraform 理解依存性圖並以正確的順序建立所有內容。

合規基準

合規基準使用內建於合規基準引擎中的 mSCP 基準。首先，使用資料來源取得您想要的基準的規則。然後建立參考這些規則並鎖定您的設備群組的基準：

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

這會在監視模式中建立 CIS Level 1 基準，其範圍為我們之前定義的智慧群組。基準中的每個規則都包括在內，您可以選擇性地停用個別規則或設定自訂 ODV 值以符合您的組織要求。例如，自訂特定規則：

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

將 enforcement_mode 設定為 "MONITOR_AND_ENFORCE" 將自動修復不符合規範的設定。

值得注意的是，合規基準引擎 API 目前不提供基準的 PUT 或 PATCH 方法。這意味著對 Terraform 設定中基準資源的任何變更都將導致銷毀並重新建立（強制替換），而不是就地更新。對已部署且在設備上主動報告的基準進行變更時，請牢記這一點。

真正的力量在於您可以版本控制已應用的確切規則集和自訂項目、透過提取請求審查變更，以及以零手動工作量在多個租戶之間複製相同的基準。

Blueprints

Blueprints 將多個設定元件組合成部署到一個或多個設備群組的單一單位。每個元件類型對應到聲明式設備管理 (DDM) 宣告設定域。以下是設定軟體更新設定與延期和自動安裝的 blueprint：

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

以下是強制執行密碼原則的 blueprint：

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

每個 blueprint 透過 device_groups 屬性對應到單一設備群組集合，該屬性採用一組 Platform UUID。將 deployed 設定為 true 告訴 provider 部署 blueprint（如果其過期，則重新部署）。將其設定為 false 會將其取消部署。

您也可以使用 software_update 元件在特定日期強制執行特定 OS 版本、使用 legacy_payloads 屬性進行傳統設定檔酬載，或使用 custom_declarations 進行 provider 尚未提供專用元件的任意 DDM 宣告。

4. 應用您的設定

您從其他 provider 了解的相同命令也適用於此處：

terraform init       # 初始化並下載 provider
terraform plan       # 檢視將建立、變更或銷毀的內容
terraform apply      # 套用變更（系統會要求您確認）

將現有租戶納入管理

如果您已在租戶中設定了 blueprints、基準和設備群組，則不需要從頭開始。provider 中的每個資源都支持 terraform import，因此您可以將現有資源納入 Terraform 管理，而無需重新建立它們。

使用 Terraform query 探索現有資源

如果您執行 Terraform 1.14+，provider 支援列表資源，這是一項允許您直接從 Terraform 查詢現有基礎設施的功能。這對於在匯入之前探索租戶中已有的內容很有用。

建立查詢檔案（例如 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"
    }
  }
}

然後執行：

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

Terraform 將查詢您的租戶，傳回相符的資源及其 ID，並將資源塊和匯入塊都產生至 generated.tf。blueprint 和基準列表資源支援 search 篩選器，用於對名稱和描述進行不區分大小寫的子字串匹配。設備群組列表資源支援包含用於 name、description、deviceType 和 groupType 之 RSQL 選擇器的 filter 塊，為您提供對傳回的群組的精確控制。

匯入資源

一旦您擁有所需的 ID，您可以使用匯入塊將其納入管理。使用 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"
}

執行 terraform plan 以為匯入的資源產生設定、根據需要進行調整，從那一刻起它們將作為程式碼進行管理。如需更多有關大量匯入資源的資訊，請參見 HashiCorp 的大量匯入文件。

與其他 Jamf provider 搭配使用

此 provider 設計為與 Jamf 生態系統中的其他 Terraform provider 並行使用。您可以將其與以下項目搭配使用：

Jamf Protect Provider - 用於透過 Jamf Protect GraphQL API 管理 Jamf Protect 中的資源（端點安全計劃、威脅防止、遙測等）。
Deployment Theory Jamf Pro Provider - 用於透過其 Classic 和 Pro API 管理 Jamf Pro 中的資源（原則、指令碼、設定檔、群組等）。

在這些 provider 之間，您可以從單一 Terraform 專案將整個 Jamf 環境作為程式碼進行管理。常見的模式是使用 Jamf Pro provider 建立資源，如智慧群組和原則，然後在 Jamf Platform provider 中參考基準和 blueprints 的結果 Platform ID。

參與

該 provider 是開源的，採用 MPL 許可，並發佈在 HashiCorp 和 OpenTofu 登錄表上。它建立在 HashiCorp 的 Terraform Plugin Framework（Protocol v6）之上，並包括整個集成測試。該 provider 使用我們開源的 jamfplatform-go-sdk，您可以將其匯入到您自己的 Go 專案中，以針對 Jamf Platform API 進行指令碼編寫和自動化。

我們歡迎貢獻。錯誤報告、功能請求和提取請求都受到讚賞。隨著更多功能的新增，該 provider 將與 Jamf Platform API 同步繼續增長。

指南