[Terraform] How we use export file from Terraform in order to import it to Genesys Cloud?

Genesys Cloud Integrations
1

Refer to this link: Terraform Registry

For example, Once we have exported with "genesyscloud_user" resource table. I got a output file is "genesyscloud.tf.json" and "terraform.tfstate"

How I use this export files? I want to import it back. It is difference format file between export file (output file from terraform and resource block on terraform)

Is it possible to use it?

Thanks in advance,
Pitak

2

Hi Pitak,

The primary use case for the export feature is to jumpstart you on taking an existing organization and putting it under "terraform" control.

This means that when you do an export and you don't exclude anything, you will get a complete dump of all resources that our provider currently manages. You also will get a state file created too. At this point, you can make modifications to your genesyscloud.tf.json and then run a terraform apply (though I would highly recommend against using the local state file and instead import the state file into a remote backing state) and apply your changes to an environment.

Some individuals are using terraform export to:

  1. Back up date from their existing organization in the event that somebody on their team inadvertently destroys their data. While you can CX as Code to export the data to back up. The ability to recover is going to be driven by your own individual needs. Genesys Cloud does not have a big red "recover" button that can take a CX as Code export and recover from it. You have to develop your own playbooks on how you will take the records exported and add them back into Genesys Cloud. This means testing and playbooks.

  2. Export data and apply it as a snapshot change to another environment. Not everyone wants to maintain their CX as Code definitions by hand. I have seen some customers play around with exporting their data from their dev environment, not using the state file from dev, and then incorporating their changes into their test terraform files and promoting them to a new environment. This can be done and is very specific to the individual customers.

CX as Code and Terraform is primarily a CI/CD tool where cloud infra definitions are maintained in text files and kept under source control. You can build other solutions on top of them, but at this point building anything else is the responsibility of the individual customer and you need to do your own testing to make sure it works for you.

I hope that helps.

Thanks,
John Carnell
Manager, Developer Engagement

3

Hello John Carnell,
Thanks for your information. I got your point of concept.
However, Could we have narrow down into the details, How to?
Refer to your second item: 2) Export data and apply it as a snapshot change to another environment.
= By concept, I can export all configurations not exclusion anything. So, I will got the output file "genesyscloud.tf.json". which are whole configuration on my Genesys Cloud

Let clarify this point first, genesyscloud.tf.json is an output of terraform format, but unfortunately this file is seems not ready to use for importing via terraform, right? (Please help to confirm this point). If you open the output file. it is json format and i don't sure how to use it?
So as i knew, we have to modify format of genesyscloud.tf.json file to terraform resource block on terraform plan file** configuration, correct?

Thanks in advance
Best Regards,
Pitak

5

Hi Pitak,

Terraform supports both JSON and HCL as formats for defining objects. By default when we export the terraform configuration we by default export it into a JSON format. This terraform article explains how to use JSON with terraform.

A couple of things to be aware of:

  1. Our CX as Code provider does support the ability to export the Terraform as HCL. There is a flag called export_as_hcl if you want to export the code in an HCL format.

  2. When we export code we "mangle" the names of each object by putting a unique number at the end of each exported object to ensure the name of the object is unique. As I stated above, we do not officially support "snapshotting" of code from one environment to the next. I am not saying it can't be done, but usually, we have developers export the terraform data from the dev environment (without a state file) and then apply it against a test environment with a terraform state file in place. This usually involves exporting the terraform data, checking it into source control, and then running a CI/CD job that would then run the terraform apply against a different environment (e.g. test). One thing to be aware of is that there are certain Genesys Cloud objects where you can have two types of the same object with the same name. Since the original use case was for jump-starting an existing organization with CX as Code we chose to add unique numbers to each name. This can be problematic because when you are trying to build an export process from one organization to the next the names you are exporting are not stable. As a result, when developers build an export they usually had to do a 'like' or 'contains' type search on the JSON as they or they manipulate and remove the unique extensions from the name. We are working on a feature to disable name mangling.

  3. The last thing to be aware of is that there are a few objects we do not export (e.g. credentials and certain types of edge configuration). When we encounter these types of objects we create tf.vars file with an empty "" placeholder that you can populate. Obviously, we don't want to expose secrets so most customers use a secret vault to manage things like this.

As you can tell there are a lot of things that go into building an export process. That is one of the reasons why it is not an officially supported use case. There are a lot of customer-specific variables that go into play when you are talking about a migration process that uses snapshots vs. managing all of your configuration in CX as Code and then running it through a CI/CD pipeline.

Hope that helps.

Thanks,
John Carnell
Manager, Developer Engagement

6

Hi John Carnell,
Refer to 1 item on HCL format, I try to export with HCL format and apply terraform plan (terraform apply).
put this argument
.
..
<export_as_hcl = true>
..
.

System will show "terraform Error: Unsupported argument"

However, I try to search the same error. It seems no longer support HCL export with terraform on new 1.2.5 latest version or not support latest version yet

Ref: CX as Code Exporting existing Genesys Cloud configuration

Resolution: I should have using a version older than 1.1.0. Not sure this suitable way to do with HCL format. For another solution. for example, delete .terraform.lock.hcl file and then do a terraform init. it doesn't work for me

So, The above reason. Let we have to continue using JSON format

Right now, I m able to export with JSON File Structure (Nested block).
But my point is still the same one.
It is difficult to mapping/convert form JSON (Nested block) within resource blocks to native syntax (Resource block) .
I mean "Nested Block Mapping" (JSON Configuration Syntax - Configuration Language | Terraform by HashiCorp)
Do you have the solution/workaround to convert it to resource block? If we are not convert it first, we cannot use the export json format in order to import to any system anymore.

Thanks,
Pitak

7

Hi Pitak,

Not quite sure how you are executing the export. But our export is not based in Terraform's native functionality. Instead, we wrote an "export" resource in our Terraform provider. This means you have to configure it as a resource within a main.tf. For example, I was actually working with export right now. So I set up file called main.tf and put the following in the file:

terraform {
  required_providers {
    genesyscloud = {
      source  = "mypurecloud/genesyscloud"
    }
  }
}

resource "genesyscloud_tf_export" "export" {
  directory =  "./export"
  resource_types     = ["genesyscloud_routing_queue"]
  include_state_file = false
  log_permission_errors = true
  export_as_hcl = true
}

I always set up my export "job" independent of my main job.
I then run a terraform init and a terraform apply.

It exported everything as HCL without a problem.

For the second item around native syntax can you post an example object that you are trying to import (please scrub it if it has any sensitive data)? That might allow us to better understand what is going on.

Thanks,
John

8

Hi John,
Here is my terraform plan:

terraform {
required_providers {
genesyscloud = {
source = "mypurecloud/genesyscloud"
version = "~> 1.0.0"
}
}
}
resource "genesyscloud_tf_export" "export" {
directory = "./genesyscloud/datatable/"
resource_types = ["genesyscloud_architect_datatable"]
include_state_file = true
log_permission_errors = true
export_as_hcl = true
}

The result after terraform apply:
System will show "terraform Error: Unsupported argument"

image
image867×777 21.7 KB

Since the export file is not based on Terraform's native functionality. So, I understand that we cannot use this file in order to import it back to another system directly, right? Do we have to srcub/convert it to native terraform first? it is my point

Note: My terraform is 1.2.5 version (latest version as of 22July2022)

Thanks,
Pitak

9

Hi John,
I try to do it with Terraform v1.0.11. but the result is as same as terraform the latest version 1.2.5
"Error: Unsupported argument"
An argument named "export_as_hcl" is not expected here.

Please help to suggest

Thanks,
Pitak

10

Hi Pitak,

Found the issue after I downloaded your file. You have your version constraint on the resource provider set to low. The issue is not with the version of terraform you are using, but the version of our CX as code provider.

By using ~> you are saying give me anything that is version 1.0.x which is a really old version of CX as Code provider.

Delete your .terraform and terraform.lock.hcl file and try this:

terraform {
  required_providers {
    genesyscloud = {
      source  = "mypurecloud/genesyscloud"
      version = ">= 1.4"
    }
  }
}
resource "genesyscloud_tf_export" "export" {
  directory             = "./genesyscloud/datatable/"
  resource_types        = ["genesyscloud_architect_datatable"]
  include_state_file    = true
  log_permission_errors = true
  export_as_hcl         = true
}

1.4.0 is the latest version of our terraform provider. I tested your code with the change on the version constraint and it worked. Sorry I didn't catch this sooner.

Thanks,
John Carnell
Manager, Developer Engagement

11

Hi John,
It works for now. the HCL output file can be generated properly.

Thanks for the useful information,
Pitak

13