Skip to content

Latest commit

 

History

History
141 lines (108 loc) · 6.5 KB

README.md

File metadata and controls

141 lines (108 loc) · 6.5 KB

Terraform Provider for SimpleMDM

This repository contains the Terraform provider that manages resources in SimpleMDM. The provider is implemented with the Terraform Plugin Framework and uses the official simplemdm-go-client to talk to SimpleMDM's REST API.

Installation

Add the provider to your Terraform configuration. Published releases are available on the Terraform Registry:

terraform {
  required_providers {
    simplemdm = {
      source  = "DavidKrau/simplemdm"
      version = "~> 0.1"
    }
  }
}

provider "simplemdm" {
  # Optional. Defaults to https://a.simplemdm.com
  host   = "a.simplemdm.com"

  # Required unless provided via the SIMPLEMDM_APIKEY environment variable.
  apikey = var.simplemdm_api_key
}

The provider accepts two configuration attributes:

Attribute Environment variable Notes
apikey SIMPLEMDM_APIKEY Required. API key for your tenant.
host SIMPLEMDM_HOST Optional. Override the API hostname (defaults to a.simplemdm.com).

Documentation and examples

  • Generated documentation for every resource and data source lives in docs/.
  • Copyable end-to-end examples for the provider, resources, and data sources are in examples/.

Regenerate the documentation whenever schemas change:

go generate ./...

Project layout

Path Description
provider/ Provider, resource, data source, and acceptance test implementations.
internal/ Helper packages that support the provider.
docs/ Terraform Plugin Docs output used by the Terraform Registry.
examples/ Working configuration snippets for the provider.
scripts/ Utility scripts, including fixture discovery helpers for tests.

Development workflow

This project uses Go 1.24 (see go.mod). Typical development steps:

# Install dependencies and verify the provider builds
go mod download
go build ./...

# Run linting (same tool as CI)
golangci-lint run

# Run unit tests
go test ./...

Pre-commit hooks

Formatting expectations are codified via pre-commit. The configured hooks run gofmt and a few general hygiene checks before each commit. Install and enable the hooks locally with:

pip install pre-commit  # once per development environment
pre-commit install

Run the hooks manually across the entire repository with pre-commit run --all-files.

Acceptance tests

Acceptance tests are located under provider/ and can be run with:

TF_ACC=1 SIMPLEMDM_APIKEY="your-api-key" go test -v -cover ./provider/

The suite skips tests automatically when required fixtures are missing, allowing day-to-day development to rely on dynamic coverage while CI can opt into additional cases by setting the appropriate environment variables. GitHub Actions runs the same command in .github/workflows/test.yml.

Fixture environment variables

The following optional variables unlock additional tests. Values should reference existing objects in a SimpleMDM test tenant:

Variable Used by Purpose
SIMPLEMDM_APP_ID App data source, assignment group resource ID of an app available to your tenant.
SIMPLEMDM_ASSIGNMENT_GROUP_ID Assignment group data source and resource Fixture assignment group (device groups are deprecated).
SIMPLEMDM_ATTRIBUTE_NAME Attribute data source Name of an existing custom attribute.
SIMPLEMDM_CUSTOM_DECLARATION_DEVICE_ID Custom declaration device assignment resource Device capable of receiving DDM declarations.
SIMPLEMDM_DEVICE_GROUP_ID Device group data source, enrollment and script job resources Existing device group when cloning or referencing real groups.
SIMPLEMDM_DEVICE_GROUP_CLONE_SOURCE_ID Device group resource Source device group for clone operations.
SIMPLEMDM_DEVICE_GROUP_NAME Device group resource Name reused across updates during acceptance tests.
SIMPLEMDM_DEVICE_GROUP_ATTRIBUTE_KEY Device group resource Attribute key validated during updates.
SIMPLEMDM_DEVICE_GROUP_ATTRIBUTE_VALUE Device group resource Initial attribute value.
SIMPLEMDM_DEVICE_GROUP_ATTRIBUTE_UPDATED_VALUE Device group resource Updated attribute value.
SIMPLEMDM_DEVICE_GROUP_PROFILE_ID Device and device group resources Profile assigned during tests.
SIMPLEMDM_DEVICE_GROUP_PROFILE_UPDATED_ID Device and device group resources Updated profile reference.
SIMPLEMDM_DEVICE_GROUP_CUSTOM_PROFILE_ID Device and device group resources Custom profile assigned during tests.
SIMPLEMDM_DEVICE_GROUP_CUSTOM_PROFILE_UPDATED_ID Device and device group resources Updated custom profile reference.
SIMPLEMDM_DEVICE_ID Device data source, device command resource, script job data source ID of an enrolled device. Required for device-centric commands.
SIMPLEMDM_ENROLLMENT_CONTACT Enrollment resource Contact email or phone used to create an enrollment invitation.
SIMPLEMDM_ENROLLMENT_CONTACT_UPDATE Enrollment resource Optional updated contact value to exercise update paths.
SIMPLEMDM_ENROLLMENT_ID Enrollment data source ID of an existing enrollment.
SIMPLEMDM_PROFILE_ID Profile data source, assignment group resource ID of a profile created via the SimpleMDM UI.
SIMPLEMDM_SCRIPT_ID Script data source ID of an existing script.
SIMPLEMDM_SCRIPT_JOB_ID Script job data source ID of an existing script job.

Use scripts/discover-test-fixtures.sh to collect common fixture IDs automatically from your tenant and output gh secret set commands that match the CI workflow.

Known issues

  • Device groups are deprecated in SimpleMDM. The legacy simplemdm_devicegroup resource and data source remain for backward compatibility, but new deployments should favor simplemdm_assignmentgroup.
  • Device name updates require a manual PATCH request outside of Terraform.
  • Profiles and custom profiles applied to assignment groups or devices cannot be updated via API; Terraform compares the desired configuration against the previous state only.