Service Catalog Configuration

When using ServiceNow with the HCP Terraform integration, you will configure at least one service catalog item. You will also configure one or more version control system (VCS) repositories or no-code modules containing the Terraform configurations which will be used to provision that infrastructure. End users will request infrastructure from the service catalog, and HCP Terraform will fulfill the request by creating a new workspace, applying the configuration, and then reporting the results back to ServiceNow.

Prerequisites

Before configuring a service catalog, you must install and configure the HCP Terraform integration software on your ServiceNow instance. These steps are covered in the installation documentation.

Additionally, you must have have the following information:

1. The no-code module name or the OAuth token ID and repository identifier for each VCS repository that HCP Terraform will use to provision infrastructure. Your Terraform Admin will provide these to you. Learn more in Configure VCS Repositories or No-Code Modules.
2. Any Terraform or environment variables required by the configurations in the given VCS repositories or no-code modules.

Once these steps are complete, in order for end users to provision infrastructure with ServiceNow and HCP Terraform, the ServiceNow Admin will perform the following steps to make Service Items available to your end users.

1. Add at least one service catalog for use with Terraform.
2. If you are using the VCS flow, configure at least one one VCS repository in ServiceNow.
3. Create variable sets to define Terraform and environment variables to be used by HCP Terraform to provision infrastructure.

Add the Terraform Service Catalog

First, add a Service Catalog for use with the Terraform integration. Depending on your organization's needs, you might use a single service catalog, or several. If you already have a Service Catalog to use with Terraform, skip to the next step.

1. In ServiceNow, open the Service Catalog > Catalogs view by searching for "Service Catalog" in the left-hand navigation.
   1. Click the plus sign in the top right.
   2. Select "Catalogs > Terraform Catalog > Title and Image" and choose a location to add the Service Catalog.
   3. Close the "Sections" dialog box by clicking the "x" in the upper right-hand corner.

Configure VCS Repositories or No-Code Modules

Terraform workspaces created through the ServiceNow Service Catalog for Terraform can be associated with a VCS provider repository or be backed by a no-code module in your organization's private registry. Administrators determine which workspace type end users can request from the Terraform Catalog. Below are the key differences between the version control and no-code approaches.

VCS configuration

To make infrastructure available to your users through version control workspaces, you must add one or more VCS repositories containing Terraform configurations to the Service Catalog for Terraform.

1. In ServiceNow, open the "Terraform > VCS Repositories" table by searching for "Terraform" in the left-hand navigation.
2. Click "New" to add a VCS repository, and fill in the following fields:
   • Name: The name for this repository. This name will be visible to end users, and does not have to be the same as the repository name as defined by your VCS provider. Ideally it will succinctly describe the infrastructure that will be provisioned by Terraform from the repository.
   • OAuth Token ID: The OAuth token ID that from your HCP Terraform organization's VCS providers settings. This ID specifies which VCS provider configured in HCP Terraform 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 <ORGANIZATION>/<REPO_NAME> or <PROJECT KEY>/<REPO_NAME>. Azure DevOps repositories use the format <ORGANIZATION>/<PROJECT>/_git/<REPO_NAME>.
   • The remaining fields are optional.
     • Branch: The branch within the repository, if different from the default branch.
     • Working Directory: The directory within the repository containing Terraform configuration.
     • Terraform Version: The version of Terraform to use. This will default to the latest version of Terraform supported by your HCP Terraform instance.
3. Click "Submit".

After configuring your repositories in ServiceNow, the names of those repositories will be available in the "VCS Repository" dropdown menu a user orders new workspaces through the following items in the Terraform Catalog:

• Create Workspace
• Create Workspace with Variables
• Provision Resources
• Provision Resources with Variables

No-Code Module Configuration

In version 2.5.0 and newer, ServiceNow administrators can configure Catalog Items using no-code modules. This release introduces two new additions to the Terraform Catalog - no-code workspace create and update Items. Both utilize no-code modules from the private registry in HCP Terraform to enable end users to request infrastructure without writing code.

The following Catalog Items allow you to build and manage workspaces with no-code modules:

• Provision No-Code Workspace and Deploy Resources: creates a new Terraform workspace based on a no-code module of your choice, supplies required variable values, runs and applies Terraform.
• Update No-Code Workspace and Deploy Resources: Updates an existing no-code workspace to the most recent no-code module version, updates that workspace's attached variable values, and then starts and applies a new Terraform run.

Administrators can skip configuring VCS repositories in ServiceNow when using no-code modules. The only input required in the no-code workspace request form is the name of the no-code module.

Before utilizing a no-code module, you must publish it to the your organization's private module registry. With this one-time configuration complete, ServiceNow Administrators can then call the modules through Catalog requests without repository management, simplifying the use of infrastructure-as-code.

Hands On: Try the Self-service enablement with HCP Terraform and ServiceNow tutorial.

Configure a Variable Set

Most Terraform configurations can be customized with Terraform variables or environment variables. You can create a Variable Set within ServiceNow to contain the variables needed for a given configuration. Your Terraform Admin should provide these to you.

1. In ServiceNow, open the "Service Catalog > Variable Sets" table by searching for "variable sets" in the left-hand navigation.
2. Click "New" to add a Variable Set.
3. Select "Single-Row Variable Set".
   • Title: User-visible title for the variable set.
   • Internal name: The internal name for the variable set.
   • Order: The order in which the variable set will be displayed.
   • Type: Should be set to "Single Row"
   • Application: Should be set to "Terraform"
   • Display title: Whether the title is displayed to the end user.
   • Layout: How the variables in the set will be displayed on the screen.
   • Description: A long description of the variable set.
4. Click "Submit" to create the variable set.
5. Find and click on the title of the new variable set in the Variable Sets table.
6. At the bottom of the variable set details page, click "New" to add a new variable.

• Type: Should be "Single Line Text" for most variables, or "Masked" for variables containing sensitive values.
• Question: The user-visible question or label for the variable.
• Name: The internal name of the variable. This must be derived from the name of the Terraform or environment variable. Consult the table below to determine the proper prefix for each variable name.
• Tooltip: A tooltip to display for the variable.
• Example Text: Example text to show in the variable's input box.

1. Under the "Default Value" tab, you can set a default value for the variable.
2. Continue to add new variables corresponding to the Terraform and environment variables the configuration requires.

When the Terraform integration applies configuration, it will map ServiceNow variables to Terraform and environment variables using the following convention. ServiceNow variables that begin with "sensitive_" will be saved as sensitive variables within HCP Terraform.

Provision Infrastructure

Once you configure the Service Catalog for Terraform, ServiceNow users can request infrastructure to be provisioned by HCP Terraform.

These requests will be fulfilled by HCP Terraform, which will:

1. Create a new workspace from the no-code module or the VCS repository provided by ServiceNow.
2. Configure variables for that workspace, also provided by ServiceNow.
3. Plan and apply the change.
4. Report the results, including any outputs from Terraform, to ServiceNow.

Once this is complete, ServiceNow will reflect that the Request Item has been provisioned.

Execution Mode

If using v2.2.0 or above, the Service Catalog app allows you to set an execution mode for your Terraform workspaces. There are two modes to choose from:

• The default value is "Remote", which instructs HCP Terraform to perform runs on its disposable virtual machines.
• Selecting "Agent" mode allows you to run Terraform operations on isolated, private, or on-premises infrastructure. This option requires you to create an Agent Pool in your organization beforehand, then provide that Agent Pool's id when you order a new workspace through the Service Catalog.

Workspace Name

Version 2.4.0 of the Service Catalog for Terraform introduces the ability to set custom names for your Terraform workspaces. You can choose a prefix for your workspace name that the Service Catalog app will append the ServiceNow RITM number to. If you do not define a workspace prefix, ServiceNow will use RITM number as the workspace name.

Workspace names can include letters, numbers, dashes (-), and underscores (_), and should not exceed 90 characters. Refer to the workspace naming recommendations for best practices.

Workspace Tags

Version 2.4.0 also allows you to add custom tags to your Terraform workspaces. Use the "Workspace Tags" field to provide a comma-separated list of tags that will be parsed and attached to the workspace in HCP Terraform.

Tags give you an easier way to categorize, filter, and manage workspaces provisioned through the Service Catalog for Terraform. We recommend that you set naming conventions for tags with your end users to avoid variations such as ec2, aws-ec2, aws_ec2.

Workspace tags have a 255 character limit and can contain letters, numbers, colons, hyphens, and underscores. Refer to the workspace tagging rules for more details.