Active Directory Integration Example¶

This example demonstrates how to join a Qumulo cluster to an Active Directory domain using the qumulo_ad resource. AD integration enables Windows authentication for SMB shares and centralized user management.

Features¶

The qumulo_ad resource supports:

Domain join with optional Organizational Unit (OU) placement
Protocol security with configurable SMB signing, sealing, and AES encryption
POSIX attribute mapping for RFC 2307 UID/GID attributes from AD
Trusted domain searches for multi-domain environments
Force leave for cleanup when AD credentials are unavailable

Architecture¶

┌─────────────────────────────────────────────────────────────────────────┐
│                        ACTIVE DIRECTORY DOMAIN                          │
│                         (corp.example.com)                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐         │
│  │ Domain Controller│  │ Domain Controller│  │ Global Catalog  │         │
│  │   dc1.corp.com   │  │   dc2.corp.com   │  │   gc.corp.com   │         │
│  └────────┬─────────┘  └────────┬─────────┘  └────────┬────────┘         │
│           │                     │                     │                  │
│           └─────────────────────┼─────────────────────┘                  │
│                                 │                                        │
│                          ┌──────┴──────┐                                 │
│                          │ LDAP/Kerberos│                                │
│                          │  Port 389    │                                │
│                          │  Port 88     │                                │
│                          └──────┬───────┘                                │
└─────────────────────────────────┼────────────────────────────────────────┘
                                  │
                                  ▼
                    ┌─────────────────────────┐
                    │     QUMULO CLUSTER      │
                    │                         │
                    │  Computer Account:      │
                    │  OU=Servers,DC=corp,... │
                    │                         │
                    │  SMB Signing: Required  │
                    │  SMB Sealing: Preferred │
                    │  Kerberos: AES          │
                    └─────────────────────────┘
                                  │
                    ┌─────────────┼─────────────┐
                    │             │             │
                    ▼             ▼             ▼
              ┌───────────┐ ┌───────────┐ ┌───────────┐
              │  Windows  │ │  Windows  │ │   Linux   │
              │  Client   │ │  Client   │ │  Client   │
              │           │ │           │ │  (POSIX)  │
              └───────────┘ └───────────┘ └───────────┘

Prerequisites¶

Qumulo cluster with REST API access (port 8000)
Active Directory domain with reachable domain controllers
AD account with permission to join computers to the domain
DNS resolution from the cluster to AD domain controllers
Network connectivity on ports 88 (Kerberos), 389 (LDAP), 445 (SMB)

Network Requirements¶

Port	Protocol	Direction	Purpose
88	TCP/UDP	Cluster -> DC	Kerberos authentication
389	TCP/UDP	Cluster -> DC	LDAP queries
636	TCP	Cluster -> DC	LDAPS (if using secure LDAP)
445	TCP	Clients -> Cluster	SMB file sharing
3268	TCP	Cluster -> GC	Global Catalog queries

Usage¶

Create a terraform.tfvars file:

cluster_endpoint = "https://cluster.example.com:8000"
cluster_username = "admin"
cluster_password = "cluster-admin-password"

# Active Directory settings
ad_domain   = "corp.example.com"
ad_username = "svc_qumulo_join"
ad_password = "join-account-password"
ad_ou       = "OU=Servers,OU=Qumulo,DC=corp,DC=example,DC=com"

# Security settings
require_signing = true   # Enforce SMB signing
require_sealing = false  # Prefer but don't require encryption
require_aes     = true   # Enforce AES for Kerberos

# POSIX mapping (for Linux clients)
use_posix_attributes   = true
search_trusted_domains = false

Initialize and apply:

terraform init -upgrade
terraform plan
terraform apply

Variables¶

Name	Description	Type	Default
`cluster_endpoint`	Qumulo cluster REST API endpoint	`string`	-
`cluster_username`	Qumulo cluster admin username	`string`	`"admin"`
`cluster_password`	Qumulo cluster admin password	`string`	-
`ad_domain`	Active Directory domain name (e.g., corp.example.com)	`string`	-
`ad_username`	AD username with permission to join computers	`string`	-
`ad_password`	AD password for the join account	`string`	-
`ad_ou`	Organizational Unit path for the computer account	`string`	`""`
`require_signing`	Require SMB signing (true) or prefer it (false)	`bool`	`false`
`require_sealing`	Require SMB encryption (true) or prefer it (false)	`bool`	`false`
`require_aes`	Require AES for Kerberos (true) or prefer it (false)	`bool`	`false`
`use_posix_attributes`	Use POSIX attributes from AD for UID/GID mapping	`bool`	`false`
`search_trusted_domains`	Search trusted domains for user/group lookups	`bool`	`false`

Outputs¶

Name	Description
`ad_status`	Current AD domain membership status
`ad_domain`	Joined AD domain name
`ad_domain_netbios`	NetBIOS name of the joined domain
`ad_ou`	OU where the computer account was created
`ad_domain_controllers`	Discovered domain controllers
`ad_signing`	SMB signing configuration
`ad_sealing`	SMB sealing (encryption) configuration
`ad_crypto`	Kerberos encryption configuration

Protocol Security Settings¶

SMB Signing¶

Setting	Value	Description
`NO_SIGNING`	Disabled	No signing (not recommended)
`WANT_SIGNING`	Preferred	Sign if client supports it (default)
`REQUIRE_SIGNING`	Required	Reject unsigned connections

SMB Sealing (Encryption)¶

Setting	Value	Description
`NO_SEALING`	Disabled	No encryption
`WANT_SEALING`	Preferred	Encrypt if client supports it (default)
`REQUIRE_SEALING`	Required	Reject unencrypted connections

Kerberos Encryption¶

Setting	Value	Description
`NO_AES`	Disabled	Allow legacy encryption (RC4)
`WANT_AES`	Preferred	Use AES if available (default)
`REQUIRE_AES`	Required	Only accept AES encryption

Security Considerations¶

Service Account: Use a dedicated service account for domain join, not a personal admin account. Grant only "Join computers to the domain" permission.
Credential Storage: Store AD credentials securely:
```
export TF_VAR_ad_password="your-password"
```
Or use a secrets manager integration.
OU Placement: Place the computer account in a dedicated OU with appropriate Group Policy settings.
Protocol Security: For security-sensitive environments:
Enable require_signing = true to prevent MITM attacks
Enable require_sealing = true for encrypted SMB traffic
Enable require_aes = true to disable weak Kerberos encryption
Force Leave: The force_leave option orphans the computer account in AD. Use only when AD credentials are unavailable at destroy time.

Full Configuration¶

# Example: Managing Active Directory on a Qumulo Cluster
#
# This example demonstrates how to join a Qumulo cluster to an
# Active Directory domain using the qumulo_ad resource.
#
# The resource supports:
# - Domain join with optional OU placement
# - SMB signing/sealing configuration
# - Kerberos encryption settings
# - POSIX attribute mapping from AD
# - Trusted domain searches
# - Force leave for cleanup scenarios

terraform {
  required_providers {
    qumulo = {
      source  = "qumulo-terraform-registry.s3.us-east-1.amazonaws.com/qumulo/qumulo"
      version = "~> 1.0"
    }
  }
}

variable "cluster_endpoint" {
  description = "Qumulo cluster REST API endpoint (e.g., https://cluster:8000)"
  type        = string
}

variable "cluster_username" {
  description = "Qumulo cluster admin username"
  type        = string
  default     = "admin"
}

variable "cluster_password" {
  description = "Qumulo cluster admin password"
  type        = string
  sensitive   = true
}

# Variables for Active Directory
variable "ad_domain" {
  description = "Active Directory domain name (e.g., corp.example.com)"
  type        = string
}

variable "ad_username" {
  description = "AD username with permission to join computers to the domain"
  type        = string
}

variable "ad_password" {
  description = "AD password for the join account"
  type        = string
  sensitive   = true
}

variable "ad_ou" {
  description = "Organizational Unit path for the computer account (optional)"
  type        = string
  default     = ""
}

# Protocol security settings
variable "require_signing" {
  description = "Require SMB signing (REQUIRE_SIGNING) or prefer it (WANT_SIGNING)"
  type        = bool
  default     = false
}

variable "require_sealing" {
  description = "Require SMB encryption/sealing (REQUIRE_SEALING) or prefer it (WANT_SEALING)"
  type        = bool
  default     = false
}

variable "require_aes" {
  description = "Require AES for Kerberos (REQUIRE_AES) or prefer it (WANT_AES)"
  type        = bool
  default     = false
}

# Advanced options
variable "use_posix_attributes" {
  description = "Use POSIX attributes from AD for UID/GID mapping"
  type        = bool
  default     = false
}

variable "search_trusted_domains" {
  description = "Search trusted domains for user/group lookups"
  type        = bool
  default     = false
}

# Define connection profile for the cluster
provider "qumulo" {
  connection_profiles = [
    {
      name                 = "cluster1"
      endpoint             = var.cluster_endpoint
      username             = var.cluster_username
      password             = var.cluster_password
      insecure_skip_verify = true # Required for clusters with self-signed certificates
    }
  ]
}

# Join the cluster to Active Directory
resource "qumulo_ad" "main" {
  connection_profile = "cluster1"

  # Required: Domain and credentials
  domain      = var.ad_domain
  ad_username = var.ad_username
  ad_password = var.ad_password

  # Optional: Specify an OU for the computer account
  # If not specified, the default Computers container is used
  ou = var.ad_ou

  # Optional: Enable POSIX attribute mapping from AD
  # Useful when AD stores UID/GID values in RFC 2307 attributes
  use_ad_posix_attributes = var.use_posix_attributes

  # Optional: Search trusted domains for user/group lookups
  search_trusted_domains = var.search_trusted_domains

  # Protocol security settings
  # Options: NO_SIGNING, WANT_SIGNING (default), REQUIRE_SIGNING
  signing = var.require_signing ? "REQUIRE_SIGNING" : "WANT_SIGNING"

  # Options: NO_SEALING, WANT_SEALING (default), REQUIRE_SEALING
  sealing = var.require_sealing ? "REQUIRE_SEALING" : "WANT_SEALING"

  # Options: NO_AES, WANT_AES (default), REQUIRE_AES
  crypto = var.require_aes ? "REQUIRE_AES" : "WANT_AES"

  # Optional: Force leave without AD credentials on destroy
  # Set to true if AD credentials may be unavailable at destroy time
  # WARNING: This orphans the computer account in AD
  force_leave = false

  timeouts {
    create = "10m"
    update = "10m"
    delete = "10m"
  }
}

# Outputs
output "ad_status" {
  description = "Current AD domain membership status"
  value       = qumulo_ad.main.status
}

output "ad_domain" {
  description = "Joined AD domain name"
  value       = qumulo_ad.main.domain
}

output "ad_domain_netbios" {
  description = "NetBIOS name of the joined domain"
  value       = qumulo_ad.main.domain_netbios
}

output "ad_ou" {
  description = "OU where the computer account was created"
  value       = qumulo_ad.main.ou
}

output "ad_domain_controllers" {
  description = "Discovered domain controllers"
  value       = qumulo_ad.main.dcs
}

output "ad_signing" {
  description = "SMB signing configuration"
  value       = qumulo_ad.main.signing
}

output "ad_sealing" {
  description = "SMB sealing (encryption) configuration"
  value       = qumulo_ad.main.sealing
}

output "ad_crypto" {
  description = "Kerberos encryption configuration"
  value       = qumulo_ad.main.crypto
}