CX as Code
A tool to declaratively manage Genesys Cloud resources and configuration across organizations using Terraform By HashiCorp.
Introduction
Terraform
Terraform is a tool for building and managing infrastructures. It takes in configuration files, which specify how the resources should be set up and configured, and Terraform will generate an execution plan describing what needs to be done to reach the desired state. Then applies the plan and builds the specified infrastructure. When new changes are made to the configuration files, Terraform is able to detect differences and generate incremental execution plans for changes. Check out the official Terraform website for more information.
Genesys Cloud Provider
Genesys Cloud Provider is a plugin for Terraform that allows managing Genesys Cloud infrastructure. The provider implements resources to interact with Genesys Cloud Public API to apply desired changes. By invoking specific APIs to perform all of the CRUD operations, resources are able to manage and update Genesys Cloud data objects. To be able to invoke APIs, the provider requires an OAuth Client configured with a Client Credentials grant. For instructions to set up an OAuth Client in your org, see this article.
Setting up CX as Code
Requirements
CX as Code needs a version of Terraform greater than 0.13.x installed. See Download Terraform for installation instructions.
Using Published Genesys Cloud Provider
After Terraform CLI is installed, create the Terraform configuration file and run terraform init
in the same directory to setup the provider. The configuration file should contain settings for both Terraform and Genesys Cloud Provider. See Terraform Settings for detailed documentation. You can check out the Genesys Cloud registry to find out the list of supported resource types and their documentation, including related APIs, example usage and schemas. Here is an example of the configuration file.
terraform {
required_version = "~> 0.14.0"
required_providers {
genesyscloud = {
source = "mypurecloud/genesyscloud"
version = "~> 1.0.0"
}
}
}
provider "genesyscloud" {
oauthclient_id = "<client-id>"
oauthclient_secret = "<client-secret>"
aws_region = "<aws-region>"
}
Note: The recommended approach is to set the following environment variables in order to avoid explicitly hardcoding OAuth client information.
GENESYSCLOUD_OAUTHCLIENT_ID
GENESYSCLOUD_OAUTHCLIENT_SECRET
GENESYSCLOUD_REGION
Using Genesys Cloud Provider Locally
Build Local Provider
- Clone the source code repo
- Enter
terraform-provider-genesyscloud
directory - Run
make build
to build the provider
Use Local Provider
In order to use a locally compiled version of the provider, the correct binary for your system must be copied to the local ~/.terraform.d/plugins
folder. In terraform-provider-genesyscloud
directory, run make sideload
to build the provider and copy it to the correct folder. In your Terraform configuration file, specify version 0.1.0 and set the provider source to genesys.com/mypurecloud/genesyscloud
. Run terraform init
and verify that it finds the local version.
Resources
Resources are the most important elements in Terraform. Each individual resource type represents an infrastructure object, and within resource block it defines how each data object is configured. Check out the resource page for detailed information. For each resource type, you can go to Genesys Cloud Provider Registry and find out schemas for resource attributes. The list of supported resources is located on the left side of the registry page named Resources. Here is the User Resource as an example.
Resource Example
Group Resource
resource "genesyscloud_group" "test_group" {
name = "Testing Group"
description = "Group for Testers"
type = "official"
visibility = "public"
rules_visible = true
owner_ids = [genesyscloud_user.test-user.id]
member_ids = [genesyscloud_user.test-user.id]
addresses {
number = "3174181234"
type = "GROUPRING"
}
}
Auth Division Resource
resource "genesyscloud_auth_division" "marketing" {
name = "Marketing"
description = "Custom Division for Marketing"
}
Data Source
There may be cases where you want to reference existing resources in a Terraform configuration file but do not want those resources to be managed by Terraform. Data sources allow data to be fetched or computed for use elsewhere in Terraform configuration. The use of data sources allows a Terraform configuration to make use of information defined outside of Terraform, or defined by another separate Terraform configuration. Genesys Cloud Provider supports several data source types that can act as a read-only resource for existing objects in your org. To include one in your configuration, add a data
block to your configuration file with one of the supported data source types.
Data Source Example
data "genesyscloud_auth_division" "marketing" {
name = "marketing"
}
data "genesyscloud_routing_language" "english" {
name = "english"
}
Export Resources
There is a special type of resource, genesyscloud_tf_export
, which can be used to export multiple existing resources into a local Terraform JSON configuration file. To export specific resources, after the Terraform CLI is installed and the terraform configuration file requiring the Genesys Cloud provider is created, add a section of genesyscloud_tf_export
resource to the same configuration file. Within this section, you can specify the directory for the configuration file, resources to be exported, and whether to include the Terraform state file or not. A detailed tutorial and explanation can be found in the registry documentation. Below is an example of the export resource usage.
terraform {
required_providers {
genesyscloud = {
source = "mypurecloud/genesyscloud"
version = "~> 1.0.0"
}
}
}
resource "genesyscloud_tf_export" "export" {
directory = "./genesyscloud"
resource_types = ["genesyscloud_user"] <-- export user resource
include_state_file = true
}
Manage and Apply Changes of Infrastructure
To apply any changes to the organization, Terraform needs an execution plan to perform actions. terraform plan
is the Terraform command to create the execution plan. After modifying resources, use this command to create and review the execution plan. This command will first read the existing remote infrastructure, and generate the plan based on the differences between current configuration and previous state. It should display all potential changes and prompt users for confirmation. If you wish to save the execution plan to a file on disk, you can use the optional -out=FILE
flag to do so. Note: terraform plan
does NOT actually apply any changes described in the plan, therefore you can use the command to check and verify your changes before executing the plan. Check out terraform plan for detailed usage.
terraform apply
is the command to execute the plan and apply changes to the remote infrastructure. The default and the most straightforward use is without any flag, in which case the command will automatically generate the execution plan (same result as terraform plan
) and prompt users for approval before performing any actions. If you run terraform plan
first and saves the execution plan to a specific file path, you can pass in the filename of the plan to the command. In this case it will NOT prompt for confirmation and will directly apply changes. See official documentation of terraform apply for details.
For more usage information, check out the official Terraform CLI page.
Live Demo from DevDrops
<iframe width="560" height="315" src="https://www.youtube.com/embed/ol_8HYSGmGg" title="YouTube video player" frameborder="0" allowfullscreen></iframe>