Configure ServiceNow Service Graph Connector for Terraform Cloud
Note
The ServiceNow Service Graph Connector for Terraform is currently in private beta. Please contact your HashiCorp account team for more information on how to join.
The ServiceNow Service Graph Connector for Terraform lets you import cloud infrastructure resources managed by Terraform Cloud or Terraform Enterprise into your ServiceNow Configuration Management Database (CMDB), so you can maintain a clean, complete system of record of your resources and services. Terraform is an infrastructure-as-code tool that lets teams safely and reliably provision and maintain cloud infrastructure. By connecting Terraform to ServiceNow, you can manage and search for your Terraform-allocated resources alongside the rest of your company's infrastructure.
In this tutorial you will provision a cloud resource with Terraform Cloud, configure the Service Graph Connector for Terraform, and import the resource into the ServiceNow CMDB.
Prerequisites
This tutorial assumes that you are familiar with the Terraform and Terraform Cloud workflows. If you are new to Terraform, complete the Get Started collection first. If you are new to Terraform Cloud, complete the Terraform Cloud Get Started tutorials first.
For this tutorial, you will need:
- Terraform v1.3+ installed locally.
- An AWS account.
- A Terraform Cloud or Terraform Enterprise account and organization.
- A Terraform Cloud variable set configured with your AWS credentials.
- A ServiceNow instance of version "San Diego" or newer and an account with
admin
orx_hashi_service_gr.terraform_user
access.
If you do not already have a ServiceNow instance, or do not have administrator access, create a developer instance for free using ServiceNow Developer.
Create and scope Terraform API token
In order for ServiceNow to interact with Terraform Cloud, you must give it a Terraform Cloud API token. The permissions of this token determine what resources the service graph connector will import into the CMDB. While you could use a user API token, it could import resources from multiple organizations. By providing a team API token, you can scope permissions to only import resources from specified workspaces within a single organization.
Visit your organization’s Settings > Teams page. Scroll down to the Team API Token section and click Create a team token. Save this token in a safe place; Terraform Cloud only displays it once. You will use it to configure ServiceNow later in this tutorial.
Configure Service Graph Connector for Terraform API token
In the top navigation of your ServiceNow instance's control panel, click on All, search for Service Graph Connector for Terraform, and click Setup. Next, click Get Started.
Next, in the Configure the Terraform connection section, click Get Started.
In the Configure Terraform authentication credentials section, click Configure. Set the API Key to the Terraform Cloud team API token that you created earlier in this tutorial and click Update.
In the Configure Terraform authentication credentials section, click Mark as Complete.
Configure Terraform connection
By default, the Service Graph Connector is configured to connect to Terraform Cloud. If you are using Terraform Enterprise, complete the following steps to connect to your Terraform Enterprise server. If you are using Terraform Cloud, skip this section and proceed to the next section.
In the Configure Terraform connection section, click Configure.
Set the Connection URL to the URL of your Terraform Enterprise instance and click Update.
In the Configure Terraform connection section, click Mark as Complete.
Enable ServiceNow webhook
In the top navigation, click on All, search for Scheduled Imports, and click on Scheduled Imports.
Select the SG-Terraform Scheduled Process State record, then click To edit this record click To edit the record click here.
Click the Active checkbox to enable it, then click Update.
Tip
The Service Graph Connector for Terraform can also be schedule to periodically poll Terraform Cloud. To do so, navigate to Service Graph Connector for Terraform > Import Schedule. Both options may be enabled, or you may choose to enable only the webhook or scheduled import.
Create workspace and webhook
Clone the example configuration for this tutorial.
Change into the repository directory.
Open the main.tf
file in your code editor to review it. It contains the following resources:
- The AWS Terraform provider
- An EC2 instance of size
t2.micro
- The AMI that the EC2 instance will use
- An output that will provide the instance ID
Tip: If multiple users in your Terraform Cloud organization will run this tutorial, add a unique suffix to the workspace name in main.tf
.
Set your Terraform Cloud organization name as an environment variable.
Initialize your configuration. As part of initialization, Terraform creates a workspace titled learn-terraform-snow-sgc
.
Next, create the webhook in Terraform Cloud. Navigate to the learn-terraform-snow-sgc
workspace and click Settings > Notifications. Click Create a Notification.
Keep the Destination as the default option of Webhook. Choose a descriptive name Name.
For the Webhook URL enter https://<SERVICENOW_HOSTNAME>/api/x_hashi_service_gr/sg_terraform_webhook
and replace <SERVICENOW_HOSTNAME>
with the hostname of your ServiceNow instance.
Under Triggers choose Only certain events and enable notifications only on Completed runs. Click Create Notification.
Apply configuration
Now in your terminal apply your Terraform configuration. When prompted, type yes
to confirm the operation.
Note
This tutorial assumes that you are using a tutorial-specific Terraform organization with a global variable set of your AWS credentials. Review the Create a Credential Variable Set for detailed guidance. If you are using a scoped variable set, assign it to your new workspace now.
The instance_id
output lets you identify your instance in ServiceNow.
View resources in ServiceNow
In the top navigation of ServiceNow, click on All and search for CMDB Workspace, and click on CMDB Workspace.
Perform a Configuration Item (CI) search by selecting Virtual Machine Instance under Class and clicking Search
A few minutes after applying your Terraform configuration, you should see an entry for an instance with an ID that matches the Terraform output from the beginning of this tutorial.
Note
The Service Graph Connector automatically imports all instances that the provided API key has access to. If your Terraform Cloud organization manages other instances, they will also appear in this list.
Clean up infrastructure
Destroy the resources that you created in this tutorial. When prompted, type yes
to confirm the operation.
Optionally, delete your learn-terraform-snow-sgc
workspace in your Terraform organization.
The Service Graph Connector automatically marks the deleted EC2 instance as Non-Operational in the ServiceNow CMDB.
Next steps
In this tutorial, you installed and configured the ServiceNow Service Graph Connector for Terraform and imported Terraform-managed resources into the ServiceNow CMDB. To learn more about how you can use Terraform Cloud or Terraform Enterprise to build and manage your infrastructure, check out the following resources:
- Learn more about Terraform Enterprise.
- Learn how to deploy resources with Terraform in ServiceNow with the Terraform ServiceNow Service Catalog Integration.
- Read about ServiceNow Service Graph Connectors.
- Read about the ServiceNow Configuration Management Database.