» Terraform ServiceNow Service Catalog Integration Setup Instructions

The Terraform ServiceNow Service Catalog integration enables your end-users to provision self-serve infrastructure via ServiceNow. By connecting ServiceNow to Terraform Cloud, this integration lets ServiceNow users order Service Items, create workspaces, and perform Terraform runs using prepared Terraform configurations hosted in VCS repositories.

» Summary of the Setup Process

The integration relies on Terraform ServiceNow Catalog integration software installed within your ServiceNow instance. Installing and configuring this integration requires administration in both ServiceNow and Terraform Cloud. Since administrators of these services within your organization are not necessarily the same person, this documentation refers to a ServiceNow Admin and a Terraform Admin.

First, the Terraform Admin will configure your Terraform Cloud organization with a dedicated team for the ServiceNow integration, and obtain a team API token for that team. The Terraform Admin will provide your organization name, the team API token, the hostname of your Terraform Cloud instance, and details about version control repositories containing Terraform configurations and required variables to the ServiceNow Admin.

Next, the ServiceNow Admin will install the Terraform ServiceNow Catalog integration to your ServiceNow instance, and configure it using the team API token and hostname.

Finally, the ServiceNow Admin will create a Service Catalog within ServiceNow for the Terraform integration, and configure it using the version control repositories and variable definitions provided by the Terraform Admin.

Once these steps are complete, self-serve infrastructure will be available through the ServiceNow Catalog. Terraform Cloud will provision and manage requested infrastructure and report the status back to ServiceNow.

» Prerequisites

To start using Terraform with the ServiceNow Catalog Integration, you must have:

• An administrator account on a Terraform Enterprise instance or within a Terraform Cloud organization.
• An administrator account on your ServiceNow instance.
• One or more supported version control systems (VCSs) with read access to repositories with Terraform configurations.

This integration has been tested on the following ServiceNow server versions:

• New York
• Orlando
• Paris

It requires the following ServiceNow Plugins as dependencies:

• Flow Designer support for the Service Catalog
• ServiceNow IntegrationHub Action Step
• ServiceNow IntegrationHub Starter Pack

» Configure Terraform Cloud

Before installing the ServiceNow integration, the Terraform Admin will need to perform the following steps to configure and gather information from Terraform Cloud.

1. Either create an organization or choose an existing organization where ServiceNow will create new workspaces. Save the organization name for later.

2. Create a team for that organization called "ServiceNow", and ensure that it has permission to manage workspaces. You do not need to add any users to this team.

3. On the "ServiceNow" team's settings page, generate a team API token. Save the team API token for later.

4. If you haven't yet done so, connect a VCS provider to this Terraform organization. This provider will include one or more repositories with Terraform configurations. Any repository that could be connected to a manually-created Terraform Cloud workspace can also be used as a workspace template in the ServiceNow integration.

5. On your organization's VCS provider settings page (Settings > VCS Providers), find the "OAuth Token ID" for the VCS provider or providers you will be using with the ServiceNow integration. Terraform Cloud uses the OAuth token ID to identify and authorize the VCS provider. Save the OAuth token ID for later.

6. Identify one or more VCS repositories in the VCS provider containing Terraform configurations that will be provisioned by the ServiceNow Terraform integration. Take note of any Terraform or environment variables used by the repositories you select. Save the Terraform and environment variables for later.

7. Provide the following information to the ServiceNow Admin.

   1. The organization name
   2. The team API token
   3. The hostname of your Terraform Enterprise instance, or of Terraform Cloud. The hostname of Terraform Cloud is app.terraform.io.
   4. The OAuth token ID(s) of your VCS provider(s), and the repository identifier for each VCS repository containing Terraform configurations that will be used by the integration.
      
   5. Any Terraform or environment variables required by the configurations in the given VCS repositories.

For instance, if you are configuring this integration for your company, Example Corp, using two GitHub repositories, you would share values like the following with the ServiceNow Admin.

Terraform Enterprise Organization Name: `ServiceNowExampleOrg`

Team API Token: `q2uPExampleELkQ.atlasv1.A7jGHmvufExampleTeamAPITokenimVYxwunJk0xD8ObVol054`

Terraform Enterprise Hostname: `terraform.corp.example`

OAuth Token ID (GitHub org: example-corp): `ot-DhjEXAMPLELVtFA`
  - Repository ID (Developer Environment): `example-corp/developer-repo`
    - Environment variables:
      - `AWS_ACCESS_KEY_ID=AKIAEXAMPLEKEY`
      - `AWS_SECRET_ACCESS_KEY=ZB0ExampleSecretAccessKeyGjUiJh`
      - `AWS_DEFAULT_REGION=us-west-2`
    - Terraform variables:
      - `instance_type=t2.medium`
  - Repository ID (Testing Environment): `example-corp/testing-repo`
    - Environment variables:
      - `AWS_ACCESS_KEY_ID=AKIAEXAMPLEKEY`
      - `AWS_SECRET_ACCESS_KEY=ZB0ExampleSecretAccessKeyGjUiJh`
      - `AWS_DEFAULT_REGION=us-west-2`
    - Terraform variables:
      - `instance_type=t2.large`

» Install the ServiceNow Integration

Before beginning setup, the ServiceNow Admin must install the Terraform ServiceNow Catalog integration software.

This can be added to your ServiceNow instance from the ServiceNow Store. Search for the "Terraform" integration, published by "HashiCorp Inc".

» Connect ServiceNow to Terraform Cloud

Once the integration is installed, the ServiceNow Admin can connect your ServiceNow instance to Terraform Cloud. Before you begin, you will need the information described in the "Configure Terraform Cloud" section from your Terraform Admin.

Once you have this information, connect ServiceNow to Terraform Cloud with the following steps.

1. Navigate to your ServiceNow Service Management Screen.
2. Using the left-hand navigation, open the configuration table for the integration to manage the Terraform Cloud connection.
   • Terraform > Configs
3. Click on "New" to create a new Terraform Cloud connection.
   • Set Org Name to the Terraform Cloud organization name.
   • Click on the "Lock" icon to set Hostname to the hostname of your Terraform Enterprise instance. If you are using the SaaS version of Terraform Cloud, the hostname is https://app.terraform.io. Be sure to include "https://" before the hostname.
   • Set API Team Token to the Terraform Cloud team API token.
4. Click "Submit".

» Create and Populate a Service Catalog

Now that you have connected ServiceNow to Terraform Cloud, you are ready to create a Service Catalog using the VCS repositories provided by the Terraform Admin.

Navigate to the Service Catalog documentation to begin. You can also refer to this documentation whenever you need to add or update request items.

» ServiceNow Developer Reference

ServiceNow developers who wish to customize the Terraform integration can refer to the developer documentation.

» ServiceNow Administrator's Guide.

Refer to the ServiceNow Administrator documentation for information about configuring the integration.

» Example Customizations

Once the ServiceNow integration is installed, you can consult the example customizations documentation.