W naszych poprzednich artykułach omówiliśmy podstawy Infrastructure as Code i jak zarządzać konfiguracją Jamf Pro i Jamf Protect za pomocą Terraform. Jeśli jeszcze ich nie przeczytałeś, warto zacząć od nich, ponieważ obejmują instalację, strukturę projektów i zarządzanie stanem.
Tym razem skupiamy się na API Jamf Platform, które niedawno weszły w publiczną betę. Te interfejsy API napędzają nową generację mikrousług Jamf, które znajdują się obok Jamf Pro i Jamf Protect, w tym blueprints, Compliance Benchmarks i grupy urządzeń. Opracowaliśmy dedykowanego dostawcę Terraform, który pozwala na zarządzanie tymi zasobami jako kod.
Dlaczego dedykowany dostawca dla mikrousług Jamf Platform?
API Jamf Platform to oddzielna powierzchnia API od Classic i Pro APIs Jamf Pro. Napędzają one możliwości, które są różne od zasobów, którymi zarządzasz za pomocą dostawcy Jamf Pro, i uwierzytelniają się za pośrednictwem innego zestawu poświadczeń w regionalnej bramie API (us.apigw.jamf.com, eu.apigw.jamf.com lub apac.apigw.jamf.com).
Blueprints pozwalają na zdefiniowanie pożądanego stanu konfiguracji dla grupy urządzeń i wdrożenie go w jednej operacji. Compliance Benchmarks pozwalają na zastosowanie przemysłowych standardów bezpieczeństwa z macOS Security Compliance Project (mSCP) i monitorowanie, jak radzi sobie Twoja flota. Grupy urządzeń dają sposób na organizowanie i kierowanie urządzeń na poziomie platformy. Są to wszystkie pierwszoklasowe możliwości, które zasługują na własnego dostawcę, ze schematami specjalnie skonstruowanymi dla zasobów, którymi zarządzają.
Jeśli zarządzałeś blueprintami i benchmarkami za pośrednictwem konsoli Jamf Pro, już wiesz, że odtworzenie konfiguracji w wielu dzierżawach lub śledzenie zmian w czasie wymaga wiele klikania. Dzięki temu dostawcy, cała Twoja konfiguracja znajduje się w Git, przechodzi przez przegląd kodu i jest stosowana konsekwentnie wszędzie tam, gdzie jej potrzebujesz.
Co obejmuje?
Dostawca jest dostarczany z 3 zasobami, 12 źródłami danych, 3 zasobami list i 4 działaniami na urządzeniach. Oto kluczowe obszary:
Silnik Benchmark Zgodności - Twórz i zarządzaj benchmarkami zgodności względem linii bazowych mSCP, w tym CIS Level 1 i 2, NIST 800-53 (Low, Moderate, High) i DISA STIG. Możesz włączać lub wyłączać poszczególne reguły, dostosowywać Wartości Zdefiniowane przez Organizację (ODV) i kierować benchmarki do określonych grup urządzeń. Źródła danych pozwalają na zapytanie dostępnych linii bazowych, reguł i istniejących benchmarków.
Blueprints - Definiuj blueprinty konfiguracji urządzeń obejmujące wymuszanie aktualizacji oprogramowania, ustawienia aktualizacji oprogramowania, zasady hasła, ustawienia Safari, zakładki i rozszerzenia, zarządzanie dyskami, ustawienia akcesoriów audio, ustawienia matematyki, zadania w tle usługi, pliki konfiguracyjne usługi, starsze ładunki i niestandardowe deklaracje DDM. Każdy blueprint jest kierowany do jednej lub więcej grup urządzeń i może być wdrożony lub cofnięty jako kod. Źródła danych pozwalają na zapytanie istniejących blueprintów i dostępnych komponentów blueprintu.
Grupy Urządzeń - Twórz inteligentne i statyczne grupy urządzeń dla komputerów i urządzeń mobilnych, z regułami członkostwa opartymi na kryteriach dla grup inteligentnych i wyraźnymi listami członków dla grup statycznych. Te grupy są odwoływane przez benchmarki i blueprinty do kierowania.
Unified Inventory - Tylko do odczytu źródła danych do zapytania poszczególnych urządzeń i list urządzeń na poziomie platformy.
Działania na Urządzeniach - Terraform 1.14+ actions dla operacji wymazywania, ponownego uruchomienia, wyłączania i anulowania zarządzania na zarządzanych urządzeniach.
Wszystkie zasoby obsługują pełne operacje CRUD i terraform import.
Rozpoczęcie pracy
Jeśli postępowałeś zgodnie z artykułem wprowadzającym, powinieneś już mieć zainstalowany Terraform i podstawowe zrozumienie struktury projektów. Kroki tutaj są podobne.
1. Utwórz poświadczenia API dla API Jamf Platform
Przejdź do Jamf Account i utwórz klienta API z uprawnieniami potrzebnymi do zarządzania zasobami. Przewodnik Getting Started na portalu Jamf Developer przechodzi przez ten proces.
2. Skonfiguruj dostawcę
Dodaj dostawcę do konfiguracji 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
}
Alternatywnie możesz użyć zmiennych środowiskowych, aby utrzymać blok dostawcy czysty:
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"
Jak zawsze, upewnij się, że te poświadczenia nie trafią do repozytorium Git. Użyj pliku terraform.tfvars i dodaj go do .gitignore.
3. Zdefiniuj swoje zasoby
Przejdźmy przez kilka przykładów o dużym wpływie.
Grupy urządzeń
Zanim utworzysz benchmarki lub blueprinty, będziesz chciał grupę urządzeń do których je kierować. Oto inteligentna grupa komputerów, która kieruje urządzenia działające na macOS 26 lub nowszym:
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"
}
]
}
Ta grupa może być następnie odwoływana za pomocą ID w zasobach benchmark i blueprint, dzięki czemu Terraform rozumie graf zależności i tworzy wszystko w odpowiedniej kolejności.
Benchmarki zgodności
Benchmarki zgodności używają linii bazowych mSCP, które są wbudowane w silnik Compliance Benchmark Engine. Najpierw użyj źródła danych, aby pobrać reguły dla linii bazowej, którą chcesz. Następnie utwórz benchmark, który odwołuje się do tych reguł i kieruje do grupy urządzeń:
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"
}
To tworzy benchmark CIS Level 1 w trybie monitorowania, ograniczony do grupy inteligentnej, którą zdefiniowaliśmy wcześniej. Każda reguła z linii bazowej jest dołączana, a ty możesz selektywnie wyłączać poszczególne reguły lub ustawiać niestandardowe wartości ODV, aby dopasować się do wymagań organizacji. Na przykład, aby dostosować określoną regułę:
rules = [
{
id = "system_settings_time_server_configure"
enabled = true
odv_value = "ntp.example.com"
},
{
id = "system_settings_critical_update_install_enforce"
enabled = true
}
]
Ustawienie enforcement_mode na "MONITOR_AND_ENFORCE" będzie automatycznie naprawiać niezgodne ustawienia.
Warto zauważyć, że API Compliance Benchmark Engine nie oferuje obecnie metody PUT lub PATCH dla benchmarków. Oznacza to, że każda zmiana zasobu benchmark w konfiguracji Terraform spowoduje zniszczenie i ponowne utworzenie (wymuszenie zamiany) zamiast aktualizacji w miejscu. Pamiętaj o tym przy wprowadzaniu zmian do benchmarków, które są już wdrożone i aktywnie raportują na urządzeniach.
Prawdziwa moc polega na tym, że możesz kontrolować wersje dokładnego zestawu reguł i dostosowań, które zastosowałeś, przejrzać zmiany za pośrednictwem pull requestów i replikować ten sam benchmark w wielu dzierżawach bez żadnego ręcznego wysiłku.
Blueprints
Blueprinty łączą wiele komponentów konfiguracji w jedną jednostkę, która jest wdrażana do jednej lub więcej grup urządzeń. Każdy typ komponentu mapuje się na domenę konfiguracji Declarative Device Management (DDM). Oto blueprint, który konfiguruje ustawienia aktualizacji oprogramowania z odroczeniami i automatyczną instalacją:
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"
}
}
I oto blueprint, który wymusza zasadę hasła:
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
}
}
Każdy blueprint mapuje się na jeden zestaw grup urządzeń za pośrednictwem atrybutu device_groups, który przyjmuje zestaw UUID Platformy. Ustawienie deployed na true mówi dostawcy, aby wdrożył blueprint (i ponownie go wdrożył, jeśli będzie nieaktualny). Ustawienie go na false go cofa.
Możesz również używać komponentu software_update do wymuszenia konkretnej wersji systemu operacyjnego do konkretnej daty, atrybutu legacy_payloads dla tradycyjnych ładunków profilu konfiguracyjnego lub custom_declarations dla dowolnych deklaracji DDM, których dostawca jeszcze nie ma dedykowanego komponentu.
4. Zastosuj swoją konfigurację
Te same polecenia, które znasz z innych dostawców, tutaj się stosują:
terraform init # Inicjuj i pobierz dostawcę
terraform plan # Przejrzyj, co zostanie utworzone, zmienione lub usunięte
terraform apply # Zastosuj zmiany (zostaniesz poproszony o potwierdzenie)
Wprowadzanie istniejącej dzierżawy pod zarządzanie
Jeśli już masz blueprinty, benchmarki i grupy urządzeń skonfigurowane w dzierżawie, nie musisz zaczynać od zera. Każdy zasób w dostawcy obsługuje terraform import, dzięki czemu możesz wprowadzić istniejące zasoby pod zarządzanie Terraform bez ich ponownego tworzenia.
Odkrywanie istniejących zasobów za pomocą zapytania Terraform
Jeśli używasz Terraform 1.14+, dostawca obsługuje zasoby list, funkcję, która pozwala na bezpośrednie zapytanie istniejącej infrastruktury z Terraform. Jest to przydatne do odkrywania, co już znajduje się w dzierżawie przed importem.
Utwórz plik zapytania (np. 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"
}
}
}
Następnie uruchom:
terraform query -generate-config-out=generated.tf
Terraform będzie odpytywać dzierżawę, zwrócić pasujące zasoby wraz z ich ID i wygenerować zarówno bloki zasobów, jak i bloki importu w generated.tf. Zasoby list blueprint i benchmark obsługują filtr search do dopasowania podciągu bez rozróżniania wielkości liter do nazw i opisów. Zasób list grupy urządzeń obsługuje bloki filter z selektorami RSQL dla name, description, deviceType i groupType, co daje precyzyjną kontrolę nad zwracanymi grupami.
Importowanie zasobów
Po otrzymaniu potrzebnych ID możesz używać bloków importu, aby wprowadzić je pod zarządzanie. Z 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"
}
Uruchom terraform plan, aby wygenerować konfigurację dla importowanych zasobów, usprawnij ją w razie potrzeby, a następnie zarządzaj nimi jako kodem. Aby uzyskać więcej informacji na temat zbiorcze importu zasobów, zobacz dokumentację zbiorcze importu HashiCorp.
Używanie obok innych dostawców Jamf
Ten dostawca jest zaprojektowany do pracy obok innych dostawców Terraform w ekosystemie Jamf. Możesz go używać razem z:
- Jamf Protect Provider - do zarządzania zasobami w Jamf Protect (plany bezpieczeństwa punktów końcowych, zapobieganie zagrożeniom, telemetria i inne) za pośrednictwem API Jamf Protect GraphQL.
- Deployment Theory Jamf Pro Provider - do zarządzania zasobami w produkcie Jamf Pro (zasady, skrypty, profile konfiguracyjne, grupy i inne) za pośrednictwem Classic i Pro APIs.
Dzięki tym dostawcom możesz zarządzać całym środowiskiem Jamf jako kodem z jednego projektu Terraform. Wspólny wzorzec to używanie dostawcy Jamf Pro do tworzenia zasobów, takich jak grupy inteligentne i zasady, a następnie odwoływanie się do wynikowych ID Platformy w dostawcy Jamf Platform dla benchmarków i blueprintów.
Angażowanie się
Dostawca jest open-source na licencji MPL i opublikowany zarówno w rejestrach HashiCorp i OpenTofu. Jest zbudowany na Framework Terraform Plugin HashiCorp (Protocol v6) i zawiera testy integracyjne. Dostawca używa naszego open source jamfplatform-go-sdk, który możesz zaimportować do swoich własnych projektów Go do skryptów i automatyzacji względem API Jamf Platform.
Zapraszamy do współpracy. Raporty błędów, prośby o funkcje i pull requesty są wszyscy doceniani. Dostawca będzie rosnąć w lockstep z API Jamf Platform, gdy dodane będą więcej możliwości.