The convergence of Infrastructure as Code (IaC) and enterprise IT Service Management (ITSM) represents a critical evolution in modern DevOps practices. For organizations utilizing Terraform for cloud resource provisioning, the need to bridge the gap between automated code execution and traditional change management processes is paramount. The integration between Terraform and ServiceNow facilitates this bridge, enabling organizations to maintain the velocity of automated deployments while strictly adhering to compliance, audit, and approval workflows. This integration is not merely a convenience feature; it is a structural necessity for enterprises operating at scale, where infrastructure changes must be tracked, approved, and documented within a centralized Configuration Management Database (CMDB). The primary mechanisms for this integration include the official HashiCorp HCP Terraform Service Catalog integration, community-driven providers like the tylerhatton/servicenow provider, and custom API-driven workflows that leverage the ServiceNow REST API for change request generation and policy enforcement.
Architecture and Integration Topology
The integration landscape between Terraform and ServiceNow is categorized into three primary architectural models. The first and most robust model is the native HCP Terraform integration, which is currently at version v2.9.0. This integration is available in both the Standard and Premium editions of HCP Terraform. It operates by establishing a direct bidirectional connection between the ServiceNow instance and the HCP Terraform cloud platform. This model is designed for self-service provisioning, allowing end-users to order Service Items within the ServiceNow portal, which in turn triggers the creation of Terraform workspaces and the execution of Terraform runs using configurations hosted in Version Control Systems (VCS) or no-code modules.
The second model involves the use of Terraform providers that manage ServiceNow configuration directly via code. The tylerhatton/servicenow provider is a prominent example in this category. It utilizes the ServiceNow Table API to manage a broad spectrum of ServiceNow entities. This approach is suitable for organizations that wish to manage their ITSM configuration (such as users, roles, and catalog items) as code alongside their infrastructure.
The third model is a custom workflow approach, often implemented via CI/CD pipelines or Terraform provisioners. In this model, the integration happens at specific lifecycle points: before the apply phase to create change requests for approval, and after the apply phase to update the CMDB with new or modified Configuration Items (CIs). This method relies on the ServiceNow REST API and is highly flexible, allowing for the creation of incidents automatically if failures occur during the Terraform execution.
| Integration Model | Primary Mechanism | Use Case | Key Component |
|---|---|---|---|
| HCP Terraform Catalog | Native UI Integration | Self-service provisioning, Policy enforcement | HCP Terraform API, ServiceNow Flow Designer |
| Provider-based | Terraform HCL Code | Managing ITSM config as code | tylerhatton/servicenow Provider |
| Custom Workflow | CI/CD Steps / Provisioners | Change Management, CMDB Sync | ServiceNow REST API, Terraform local-exec |
Role-Based Configuration and Administration
A critical aspect of the HCP Terraform Service Catalog integration is the separation of administrative duties. Because the ServiceNow instance and the HCP Terraform organization are often managed by different teams, the documentation explicitly defines two roles: the ServiceNow Admin and the Terraform Admin. The Terraform Admin is responsible for configuring the HCP Terraform organization, specifically creating a dedicated team for the integration and generating a team API token. This token is essential for the integration to operate under the permissions of that specific team, ensuring that the workspaces and runs created by the integration have the correct scope of access.
The Terraform Admin must provide the following artifacts to the ServiceNow Admin to facilitate the connection:
- An Organization name
- A team API token
- The hostname of the HCP Terraform instance
- Available no-code modules or version control repositories containing Terraform configurations
- Details about required variables for the integration
Once the ServiceNow Admin receives these artifacts, they proceed to install the Terraform ServiceNow Catalog integration software into their ServiceNow instance. This installation process requires specific ServiceNow roles, specifically admin or x_terraform.config_user. The integration is typically found by searching for the "Terraform" integration published by "HashiCorp Inc".
Configuring the HCP Terraform Connection
The connection between ServiceNow and HCP Terraform is established through the ServiceNow Service Management screen. The ServiceNow Admin navigates to the configuration table for the integration, specifically the Terraform > Configs path. To create a new connection, the admin selects "New" and inputs the necessary parameters. The Org Name field is set to the HCP Terraform organization name. The Hostname field requires the URL of the Terraform instance. For SaaS users of HCP Terraform, the hostname is strictly https://app.terraform.io. It is imperative to include the https:// protocol prefix in this field. For on-premise or Hybrid instances, the specific hostname of the Terraform Enterprise instance must be used.
The API Team Token field is populated with the token generated by the Terraform Admin. Additionally, the ServiceNow Admin has the option to utilize a MID Server. If the ServiceNow instance requires outbound traffic to be routed through a MID Server to reach the Terraform instance, the admin can select the corresponding checkbox and enter the MID Server Name. Once these details are submitted, the connection is established, allowing the integration to communicate with the HCP Terraform API.
Variable Mapping and Configuration Management
One of the most technically dense aspects of the HCP Terraform integration is the handling of variables. ServiceNow utilizes the concept of a Variable Set, which is a collection of ServiceNow Variables referenced in a Flow from a Service Catalog item. The Terraform Integration codebase leverages the tf_variable.createVariablesFromSet() function to dynamically create Terraform Variables and Terraform Environment Variables within the HCP Terraform workspace via the API. This function operates by iterating through the provided ServiceNow Variable Set and applying specific naming conventions to map ServiceNow variables to their Terraform counterparts.
The mapping conventions are strictly defined to ensure data integrity and security. The system looks for variables following the prefixes tf_var_hcl_, tf_env_, sensitive_tf_var_hcl_, and sensitive_tf_env_.
| ServiceNow Variable Name Convention | HCP Terraform Variable Type | Description |
|---|---|---|
tf_var_hcl_VARIABLE_NAME |
Terraform Variable | A standard Terraform input variable. |
tf_env_ENV_NAME |
Environment Variable | A standard Terraform environment variable. |
sensitive_tf_var_hcl_VARIABLE_NAME |
Sensitive Terraform Variable (Write Only) | A sensitive variable that is write-only in the HCP Terraform UI. |
sensitive_tf_env_ENV_NAME |
Sensitive Environment Variable (Write Only) | A sensitive environment variable that is write-only in the HCP Terraform UI. |
This mapping mechanism allows ServiceNow users to input complex configuration data, such as AWS credentials or instance types, through the ServiceNow form. These values are then securely passed to the HCP Terraform workspace, where they are available to the Terraform configuration. The integration codebase includes ServiceNow Script Includes Classes that interface with HCP Terraform, utilizing these mapping conventions to ensure that the data types and sensitivity levels match the requirements of the Terraform run.
Workflow Execution and Policy Enforcement
The workflow within the integration is designed to handle the lifecycle of a Terraform run, from initiation to completion. The integration builds upon generic ServiceNow API constructs, specifically Catalogs, Variables, and Workflows. Catalogs serve as the top-level collection, providing an entry point for users. Variables and Variable Sets are embedded within Forms, allowing users to enter data. Workflows allow users to embed ECMA5 scripts that can access variables from the invoking object.
In a typical execution scenario, a user initiates a service request. This triggers the creation of a Workspace in HCP Terraform. The integration then adds any necessary credentials and variables to the workspace. A Terraform Run is manually or automatically triggered. If the Terraform plan results in a cost or risk that exceeds predefined thresholds, a policy override may be required. For example, a Sentinel policy might detect a monthly cost exceeding $20/month. In such cases, the integration creates a manual approval request in ServiceNow. This request is assigned to a designated approver. Once the approver approves the request in ServiceNow, the integration makes a REST request to the Terraform Policy Override API, allowing the run to proceed. This mechanism ensures that while automation drives the execution, human oversight is retained for high-risk or high-cost changes.
The tylerhatton/servicenow Provider Approach
For organizations that prefer to manage ServiceNow configuration directly through Terraform HCL, the tylerhatton/servicenow provider offers a comprehensive solution. This provider supports Terraform version 1.0 and above and requires a ServiceNow instance with an account that has permission to read and write the tables intended for management. For local development, Go 1.25 or higher is required. The provider covers 63 resources and 49 data sources, spanning a wide range of ServiceNow entities including users, groups, ACLs, roles, UI scripts, business rules, and service catalog items.
The provider uses HTTP Basic authentication against the ServiceNow Table API. To utilize the provider, the Terraform configuration must specify the provider source and version.
```hcl
terraform {
required_providers {
servicenow = {
source = "tylerhatton/servicenow"
version = "~> 0.10"
}
}
}
provider "servicenow" {
instanceurl = "https://dev00000.service-now.com/"
username = var.servicenowusername
password = var.servicenow_password
}
```
With the provider configured, administrators can define resources such as users. For instance, creating a user named Jane Doe is accomplished with the following resource block:
hcl
resource "servicenow_user" "jane" {
user_name = "jane.doe"
first_name = "Jane"
last_name = "Doe"
email = "[email protected]"
active = true
}
This approach allows for the versioning and peer review of ITSM changes alongside infrastructure changes, ensuring that the ServiceNow environment remains synchronized with the infrastructure it governs.
Implementing Change Management via REST API
In environments where the native HCP integration is not suitable, or for on-premise Terraform Enterprise setups, organizations often implement custom integration points using the ServiceNow REST API. This approach typically involves three key steps: creating change requests before the apply, updating the CMDB after the apply, and generating incidents on failure.
Before the apply phase, a CI/CD step, a local-exec provisioner, or a custom provider is used to create a ServiceNow change request. This request captures the details of the planned changes, including the target resources and the expected impact. The change request is then routed through the organization's approval workflow. Only upon approval does the Terraform apply proceed. This ensures that all infrastructure changes are documented and authorized.
After the apply phase is successful, the integration updates the CMDB with new or modified Configuration Items. This synchronization ensures that the CMDB accurately reflects the current state of the infrastructure, which is critical for impact analysis and incident management. If the Terraform run fails, the integration can create an incident in ServiceNow automatically. This incident contains the error details from the Terraform log, allowing IT operations teams to diagnose and resolve the issue efficiently.
Developer Reference and Customization
The Terraform ServiceNow integration is designed to be extensible. ServiceNow developers can customize the integration by modifying the Script Includes and leveraging the API endpoints provided by the HCP Terraform integration. The developer reference documents the tf_variable.createVariablesFromSet() function in detail, explaining how it loops through the variable set collection to create necessary variables. This function takes the ServiceNow Variable Set and the HCP Terraform workspace ID as inputs.
Customization is particularly useful when organizations have specific naming conventions or data requirements that do not align with the default mapping. For example, if an organization uses a different prefix for sensitive variables, the Script Include can be modified to accommodate this. Additionally, developers can create custom Flows in ServiceNow that interact with the HCP Terraform API to perform specific actions, such as polling the status of a Terraform run or retrieving the state of a workspace.
Security and Access Control
Security is a paramount concern in the Terraform-ServiceNow integration. The use of team API tokens ensures that the integration operates with the least privilege necessary. The Terraform Admin creates a dedicated team and generates a token for that team, rather than using an organization-wide token. This limits the scope of the integration's actions to the resources managed by that team.
On the ServiceNow side, the integration requires specific roles such as admin or x_terraform.config_user. These roles grant the necessary permissions to install and configure the integration. Additionally, the use of sensitive variables, as indicated by the sensitive_ prefix, ensures that credentials and other sensitive data are not exposed in the HCP Terraform UI. These variables are write-only, meaning that once set, their values cannot be viewed in the UI, but they can still be used in Terraform runs.
Conclusion
The integration of Terraform and ServiceNow is a multifaceted undertaking that addresses the complex needs of modern enterprise IT. By leveraging the HCP Terraform Service Catalog integration, organizations can enable self-service provisioning while maintaining strict control over approvals and compliance. The use of specific naming conventions for variables ensures that data is passed securely and accurately between the two systems. The tylerhatton/servicenow provider offers an alternative approach for those who wish to manage ITSM configuration as code, while custom REST API workflows provide the flexibility to integrate change management and CMDB synchronization into existing CI/CD pipelines.
The success of this integration depends on clear role definitions, secure credential management, and a thorough understanding of the API mechanisms involved. The HCP Terraform integration, with its current version at v2.9.0, provides a robust foundation for this integration, supported by comprehensive documentation and a well-defined set of conventions for variable mapping. As organizations continue to adopt Infrastructure as Code, the ability to seamlessly integrate with ITSM platforms like ServiceNow will become increasingly critical for maintaining operational efficiency and regulatory compliance. The technical details outlined in this guide, from the configuration of the MID Server to the implementation of policy overrides, provide the necessary depth for engineers and administrators to successfully deploy and manage this critical integration.