» Terraform ServiceNow Service Catalog Integration Setup Instructions
Integration version: v1.0.0
Note: The ServiceNow Catalog integration is designed for use by Terraform Enterprise customers. We do not currently recommend using it with the SaaS version of Terraform Cloud.
The Terraform ServiceNow Service Catalog integration enables your end-users to provision self-serve infrastructure via ServiceNow. By connecting ServiceNow with Terraform Enterprise, this integration lets ServiceNow users create workspaces and perform Terraform runs, using prepared Terraform configurations hosted in VCS repositories.
Integrating ServiceNow with Terraform Enterprise involves several configuration steps. You will perform some of these steps in ServiceNow, and some of them in Terraform Enterprise.
|Prepare an organization for use with the ServiceNow Catalog.|
|Create a team that can manage workspaces in that organization.|
|Create a team API token so the integration can use that team's permissions.|
|Retrieve the unique ID that Terraform Enterprise uses to identify your VCS provider.|
|Import the integration from source control.|
|Connect the integration with Terraform Enterprise, using the team API token you prepared.|
|Add the Terraform Service Catalog to enable it for your users.|
|Add VCS repositories with Terraform configurations as catalog items.|
Once these steps are completed, self-serve infrastructure will be available through the ServiceNow Catalog. Terraform Enterprise will provision and manage any requested infrastructure.
To start using Terraform with ServiceNow Catalog Integration, you must already have:
- An account on a Terraform Enterprise instance.
- A ServiceNow instance or developer instance. You can request a ServiceNow developer instance at developer.servicenow.com.
- A supported version control system (VCS) with read access to repositories with Terraform configuration.
- A private Git repository to host the ServiceNow integration.
It does not require additional ServiceNow modules and has been tested on the following ServiceNow server versions:
» Obtaining the ServiceNow Integration
Before beginning setup, you must obtain a copy of the Terraform ServiceNow Catalog integration software. Contact your HashiCorp sales representative to get access to the software.
Once you have obtained the files from your sales representative, check them into a private Git repository before beginning these setup instructions.
» Terraform Enterprise Setup
Before installing the ServiceNow integration, you need to perform some setup and gather some information in Terraform Enterprise.
- Create an organization (or choose an existing organization) where ServiceNow will create new workspaces.
- Create a team for that organization called "ServiceNow", and ensure that it has the organization-level "Manage Workspaces" permission. You do not need to add any users to this team.
- On the "ServiceNow" team's settings page, generate a team API token. Save this API token for later.
- If you haven't yet done so, connect a VCS provider for this Terraform organization.
- On the organization's VCS provider settings page, find the "OAuth Token ID" for your VCS provider. This is an opaque ID that Terraform Enterprise uses to identify this VCS provider. Save the OAuth Token ID for later.
» Installing the ServiceNow Integration
» ServiceNow Server Studio
Import the integration using the ServiceNow Studio.
- Launch the ServiceNow Studio by typing "studio" in the search on the left-hand side.
- Click "Import from Source Control."
- If this is not your first time opening the Studio, you can also access this from File > Import from Source Control.
- Fill in the information required to import the integration:
<your VCS username>
<a VCS Personal Access Token or your password>
- Select the Terraform application.
- Application > Terraform
- You can now close the ServiceNow Studio or continue customizing the application.
» Enable Polling Workers (Recommended)
The integration includes 2 ServiceNow Workflow Schedules to poll the Terraform Enterprise API using ServiceNow Outbound HTTP REST requests. By default, all workflow schedules are set to On-Demand. These can be customized inside the ServiceNow Server Studio:
- Select the Worker Poll Run State (Workflow > Workflow Schedule).
- Change the value for the Run field from "On-Demand" to "Periodically".
- Set Repeat Intervals to 1-5 minutes.
- Click "Update".
» Worker Poll Apply Run
This worker approves runs for any workspaces that have finished a Terraform plan and are ready to apply their changes. It also adds a comment on the request item for those workspaces notifying that a run has been triggered.
» Worker Poll Run State
The worker synchronizes ServiceNow with the current run state of Terraform workspaces by polling the Terraform Enterprise API. On state changes, the worker adds a comment to the ServiceNow request item with the updated run state and other metadata.
» Connecting to Terraform Enterprise
- Exit Service Now Studio and return to the ServiceNow Service Management Screen.
- Using the left-hand navigation, open the configuration table for the integration to manage the Terraform Enterprise connection.
- Terraform > Configs
- Click on "New" to create a new Terraform Enterprise connection:
- Set API Team Token to the Terraform Enterprise Team Token you created earlier.
- Set Hostname to the hostname of your Terraform Enterprise instance. (If you're using the SaaS version of Terraform Cloud, this is app.terraform.io.)
- Set Org Name to the name of the Terraform Enterprise organization you wish to use for new workspaces created by ServiceNow.
» Adding the Terraform Service Catalog
- In ServiceNow, open the Service Catalog > Catalogs view by searching for "catalogs" in the left-hand navigation.
- Click the plus sign in the top right.
- Select Terraform and choose a place to add it.
At this point, your users can request Terraform infrastructure via ServiceNow, but there are not yet any infrastructure items available to request.
» Configuring VCS Repositories
To make infrastructure available to your users, you must add one or more workspace templates to the Terraform service catalog. A workspace template is a VCS repository that contains a Terraform configuration; any repository that could be connected to a manually-created Terraform Enterprise workspace can also be used as a workspace template in the ServiceNow integration.
- In ServiceNow, open the Terraform > VCS Repositories table by searching for "terraform" in the left-hand navigation.
- Click "New" to add a VCS repository for fulfillment through the Terraform Service Catalog.
- Name: The name for this workspace template that you want users to see.
- OAuth Token ID: The OAuth Token ID that you copied from your Terraform Enterprise organization's VCS providers settings. This ID specifies which VCS provider hosts the desired repository.
- Identifier: The VCS repository that contains the Terraform configuration for this workspace template. Repository identifiers are determined by your VCS provider; they typically use a format like
<PROJECT KEY>/<REPO NAME>.
- The remaining fields are optional.
Note: Currently, the integration defaults to creating workspaces with auto-apply enabled. Since VCS-backed workspaces start Terraform runs when changes are merged, changes to a workspace template repository may cause new runs in any Terraform workspaces created from it.
» Terraform Variables and ServiceNow Variable Sets
ServiceNow has the concept of a Variable Set which is a collection of ServiceNow Variables that can be referenced in a workflow from a Service Catalog item. The Terraform Integration codebase can create Terraform Variables and Terraform Environment Variables via the API using the
This function looks for variables following these conventions:
|ServiceNow Variable Name||Terraform Enterprise Variable|
This function takes the ServiceNow Variable Set and Terraform Workspace ID. It will loop through the given variable set collection and create any Terraform variables or Terraform environment variables.
» Customizing with ServiceNow "Script Includes" Libraries
The Terraform/ServiceNow Integration codebase includes ServiceNow Script Includes Classes that are used to interface with Terraform Enterprise. The codebase also includes example catalog items and workflows that implement the interface to Terraform API.
These classes and examples can be used to help create ServiceNow Catalog Items customized to your specific ServiceNow instance and requirements.
» Script Include Classes
The ServiceNow Script Include Classes can be found in the ServiceNow Studio > Server Development > Script Include.
||Helper to pull values from the SN Terraform Configs Table|
||SN HTTP REST Wrapper for requests to Terraform API|
||Resources for Terraform Run API Requests|
||Manage ServiceNow Terraform Table Records|
||Miscellaneous helper functions|
||Resources for Terraform Variable API Requests|
||Manage ServiceNow Terraform VCS Repositories Table Records|
||Resources for Terraform Workspace API Requests|
» Example Service Catalog Workflows
The ServiceNow Example Workflows can be found in the ServiceNow Studio > Workflow > Workflow. By default, the workflows execute upon submitting an order request for the various catalog items. Admins can modify the workflows to wait on an approval action, include approval rules, and specify approver groups.
|Create Workspace||Creates a new Terraform Enterprise workspace from VCS repository.|
|Create Workspace with Variables||Creates a new Terraform Enterprise workspace from VCS repository and creates any variables provided.|
|Create Run||Creates/Queues a new run on the Terraform Enterprise workspace.|
|Apply Run||Applies a run on the Terraform Enterprise workspace.|
|Provision Resources||Creates a Terraform Enterprise workspace (with auto-apply), creates/queues a run, applies the run when ready.|
|Provision Resources with Variables||Creates a Terraform Enterprise workspace (with auto-apply), creates any variables, creates/queues a run, applies the run when ready.|
|Poll Run State||Polls the Terraform Enterprise API for the current run state of a workspace.|
|Poll Apply Run||Polls the Terraform Enterprise API and applies any pending Terraform runs.|
» ServiceNow ACLs
Access control lists (ACLs) restrict user access to objects and operations based on permissions granted. This integration includes the following roles that can be used to manage various components.
|Access Control Roles||Description|
||Can manage the connection from the ServiceNow application to your Terraform Enterprise organization.|
||Can manage all of the Terraform resources created in ServiceNow.|
||Can manage the VCS repositories available for catalog items to be ordered by end-users.|
For users who only need to order from the Terraform Catalog, we recommend creating another role with read-only permissions for
x_terraform_vcs_repositories to view the available repositories for ordering infrastructure.