# Getting started with a Terraform product


AWS Service Catalog enables quick, self-service provisioning with governance for your [ HashiCorp Terraform](https://developer.hashicorp.com/terraform/intro/terraform-editions) configurations within AWS. You can use AWS Service Catalog as a single tool to organize, govern, and distribute your Terraform configurations at scale within AWS. AWS Service Catalog supports Terraform across several key features, including cataloging of standardized and pre-approved Terraform templates, access control, versioning, tagging, and sharing to other AWS accounts. In AWS Service Catalog, your end users see a simple list of products and versions they have access to, and can then deploy those products in a single action. 

**Note**  
To continue support of HashiCorp technologies, as a result of the recent licensing changes to Terraform, AWS Service Catalog changed any previous references of *Terraform Open Source* to *External*. The External product type includes support for the Terraform Community Edition, previously known as Terraform Open Source. For more information and instructions about migrating your existing Terraform Open Source products and provisioned products to the External product type, review [Updating existing Terraform Open Source products and provisioned products to the External product type](update_terraform_open_source_to_external.md). 

The steps in the following tutorial will help you get started with a Terraform product in AWS Service Catalog. 

As the catalog administrator, you work in a central administrator account (hub account). Both Terrafrm Community Edition and Terraform Cloud products require a Terraform provisioning engine, which you can learn more about in [Provisioning engine for Terraform Community Edition (External product type)](getstarted-terraform-engine.md#getstarted-terraform-engine-os) and [Provisioning engine for Terraform Cloud](getstarted-terraform-engine.md#getstarted-terraform-engine-cloud). 

During the tutorial, you perform the following tasks in the administrator account:
+ Create a Terraform product using either the *Terraform Cloud* or *External* product type. Service Catalog uses the External product type to support Terraform Community Edition products. 
+ Associate the product with a portfolio
+ Create a launch constraint to allow your end users to provision the product
+ Tag the product
+ Share the portfolio and the Terraform product with the end user account (spoke account) 

In the tutorial, you share a portfolio using the organization sharing option from the admin hub account, which is also the management account of the Organization. For more information on organization sharing, see [Sharing a Portfolio](catalogs_portfolios_sharing_how-to-share.md). 

The AWS resource contained in the Terraform product you create in the tutorial is a simple Amazon S3 bucket. 

**Note**  
 Before you begin, make sure that you complete the action items in [Setting Up AWS Service Catalog](setup.md). 

**Topics**
+ [

# Updating existing Terraform Open Source products and provisioned products to the External product type
](update_terraform_open_source_to_external.md)
+ [

# Prerequisite: Configure your Terraform provisioning engine
](getstarted-terraform-engine.md)
+ [

# Step 1: Terraform configuration file download
](getstarted-template-Terraform.md)
+ [

# Step 2: Create a Terraform product
](getstarted-product-Terraform.md)
+ [

# Step 3: Create a AWS Service Catalog portfolio
](getstarted-portfolio-Terraform.md)
+ [

# Step 4: Add product to portfolio
](getstarted-portfolio-add-product-Terraform.md)
+ [

# Step 5: Create launch roles
](getstarted-launchrole-Terraform.md)
+ [

# Step 6: Add a Launch constraint to your Terraform product
](getstarted-launchconstraint-Terraform.md)
+ [

# Step 7: Grant end user access
](getstarted-deploy-Terraform.md)
+ [

# Step 8: Share portfolio with end user
](getstarted-share-portfolio-end-user-Terraform.md)
+ [

# Step 9: Test the end user experience
](getstarted-verify-Terraform.md)
+ [

# Step 10: Monitoring Terraform provisioning operations
](getstarted-monitoring-Terraform.md)

# Updating existing Terraform Open Source products and provisioned products to the External product type
Updating to External product type

To continue support of HashiCorp technologies, as a result of the recent licensing changes to Terraform, AWS Service Catalog changed any previous references of *Terraform Open Source* to *External*. The External product type includes support for Terraform Community Edition, previously known as Terraform Open Source. AWS Service Catalog no longer supports Terraform Open Source as a valid product type for any *new* products or provisioned products. You can only update or terminate existing Terraform Open Source resources, including product versions and provisioned products.

If you have not already done so, you must transition all existing Terraform Open Source products and provisioned products to External products, by following the instructions in this section. 

1. Update your existing Terraform Reference Engine for AWS Service Catalog to include support for both **External** and **Terraform Open Source** product types. For instructions about updating your Terraform Reference Engine, review our [GitHub Repository](https://github.com/aws-samples/service-catalog-engine-for-terraform-os). 

1. Recreate any existing Terraform Open Source products using the new External product type. 

1. Delete any existing products that use the Terraform Open Source product type.

1. Reprovision remaining resources to use the new External product type.

1. Terminate any existing provisioned products that use the Terraform Open Source product type. 

After transitioning your existing products, use the External product type for any new products that use a tar.gz configuration file. 

AWS Service Catalog will support customers through this change as needed. If these changes require extensive effort for your account, or impact critical product workloads, contact your account representitive to request assistance. 

# Prerequisite: Configure your Terraform provisioning engine


As a prerequisite to creating Terraform products in AWS Service Catalog, you must install and configure a provisioning engine in your Service Catalog administrator account (hub account). The provisioning engine is required for both Terraform Community Edition products (using the External product type) and Terraform Cloud products (using the Terraform Cloud product type). 

**Note**  
Engine configuration is a one-time setup that takes approximately 30 minutes. 

## Provisioning engine for Terraform Community Edition (External product type)


AWS Service Catalog uses the *External* product type to support Terraform Community Edition products. The *External* product type also supports other provisioning tools, including Pulumi, Ansible, Chef, and more based on the configuration of the provisioning engine. 

For AWS Service Catalog products that use the External product type with HashiCorp's Terraform Community Edition, you must install and configure a Terraform provisioning engine in your AWS Service Catalog administrator account (hub account). AWS manages this engine and its resources. 

AWS Service Catalog provides a GitHub repository with instructions on [ installing and configuring the AWS-provided Terraform provisioning engine](https://github.com/aws-samples/service-catalog-engine-for-terraform-os/). The repo includes the following information: 
+ Required installation tools
+ Building the code
+ Deploying to an AWS account
+ Additional information about provisioning workflows, quality assurance, and limitations

## Provisioning engine for Terraform Cloud


For AWS Service Catalog products that use the Terraform Cloud product type with HashiCorp's Terraform Cloud, you must install and configure a Terraform provisioning engine in your AWS Service Catalog administrator account (hub account). HashiCorp manages this engine in a remote environment. 

HashiCorp provides a GitHub repository with instructions on configuring the [ Terraform Cloud engine for AWS Service Catalog](https://github.com/hashicorp/aws-service-catalog-engine-for-tfc). The repo includes the following information: 
+ Required installation tools
+ Building the code
+ Deploying to an AWS account
+ Additional information about provisioning workflows, quality assurance, and limitations

# Step 1: Terraform configuration file download
Step 1: Terraform configuration file download

 You can use a Terraform configuration file to create and provision HashiCorp Terraform products. These configurations are plain text files and describe the resources that you want to provision. You can use the text editor of your choice to create, update, and save configurations. For product creation, you must upload Terraform configurations as a **tar.gz file**. In this tutorial, AWS Service Catalog provides a simple configuration file so you can get started. The configuration creates an Amazon S3 bucket. 

## Configuration file download


AWS Service Catalog provides a sample [https://github.com/aws-samples/service-catalog-engine-for-terraform-os/blob/main/sample-provisioning-artifacts/s3bucket.tar.gz?raw=true](https://github.com/aws-samples/service-catalog-engine-for-terraform-os/blob/main/sample-provisioning-artifacts/s3bucket.tar.gz?raw=true) configuration file for you to use in this tutorial. 

## Configuration file overview


The text of the sample configuration file follows:

```
variable "bucket_name" {
  type = string
}
provider "aws" {
}
resource "aws_s3_bucket" "bucket" {
  bucket = var.bucket_name
}
output regional_domain_name {
  value = aws_s3_bucket.bucket.bucket_regional_domain_name
}
```

**Configuration Resources**

The configuration file declares the resources to be created when AWS Service Catalog provisions the product. It consists of the following sections:
+ **Variable** (optional) – The value definitions that an administrator user (hub account administrator) can assign to customize the configuration. Variables provide a consistent interface to change how a given configuration behaves. The label after the variable keyword is a name for the variable, which must be unique among all variables in the same module. This name is used to assign an outside value to the variable, and to reference the variable's value from within the module. 
+ **Provider** (optional) – The cloud service provider for resource provisioning, which is `AWS`. AWS Service Catalog only supports `AWS` as the provider. As a result, the Terraform provisioning engine overrides any other listed provider to `AWS`. 
+ **Resource** (required) – The AWS infrastructure resource for provisioning. For this tutorial, the Terraform configuration file specifies Amazon S3. 
+ **Output** (optional) – The returned information or value, similar to returned values in a programming language. You can use outputs data to configure infrastructure workflow with automation tools. 

# Step 2: Create a Terraform product
Step 2: Create a Terraform product

After installing the Terraform provisioning engine, you are ready to create a HashiCorp Terraform product in AWS Service Catalog. In this tutorial, you create a Terraform product containing a simple Amazon S3 bucket. 

**To create a Terraform product**

1. Open the AWS Service Catalog console at [https://console.aws.amazon.com/servicecatalog/](https://console.aws.amazon.com/servicecatalog/) and sign in as an admin user. 

1. Navigate to the **Administration** section, and then choose **Product list**. 

1. Choose **Create product**. 

1. On the **Create product** page in the Product details section, choose the **External** or **Terraform Cloud** product type. Service Catalog uses the *External* product type to support Terraform Community Edition products. 

1. Enter the following product details:
   + **Product name** – **Simple S3 bucket**
   + **Product description** – Terraform product containing an Amazon S3 bucket.
   + **Owner** – **IT**
   + **Distributor** – *(blank)*

1. On the **Version details** pane, choose **upload a template file** and then choose **Choose file**. Select the file you downloaded in [Step 1: Terraform configuration file download](getstarted-template-Terraform.md). 

1. Enter the following:
   + **Version name** – **v1.0**
   + **Version description** – **Base Version**

1. In the **Support details** section, enter the following and then choose **Create product**.
   + **Email contact** – **ITSupport@example.com**
   + **Support link** – **https://wiki.example.com/IT/support**
   + **Support description** – **Contact the IT department for issues deploying or connecting to this product.**

1. Choose **Create product**. 

After successfully creating the product, AWS Service Catalog displays a confirmation banner on the product page. 

# Step 3: Create a AWS Service Catalog portfolio
Step 3: Create a portfolio

You can create a portfolio in your AWS Service Catalog administrator account (hub account) for easy product organization and distribution to end user accounts (spoke accounts). 

**To create a portfolio**

1. Open the AWS Service Catalog console at [https://console.aws.amazon.com/servicecatalog/](https://console.aws.amazon.com/servicecatalog/) and sign in as an administrator. 

1. In the left navigation panel, choose **Portfolios**, and then choose **Create portfolio**. 

1. Enter the following values:
   + **Portfolio name** – **S3 bucket**
   + **Portfolio description** – **Sample portfolio for Terraform configurations. ** 
   + **Owner** – **IT (it@example.com)** 

1. Choose **Create**.

# Step 4: Add product to portfolio
Step 4: Add product to portfolio

After creating a portfolio, you can add the HashiCorp Terraform product you created in Step 2. 

**To add a product to a portfolio**

1.  Navigate to the **Products list** page. 

1.  Select the Simple S3 bucket Terraform product you created in Step 2, and then choose **Actions**. From the drop down menu, choose **Add product to portfolio**. AWS Service Catalog displays the **Add Simple S3 bucket to portfolio** pane. 

1. Select the S3 bucket portfolio, and then turn off **Create launch constraint**. You will create the launch constraint later in the tutorial. 

1. Choose **Add product to portfolio**. 

After successfully adding the product to the portfolio, AWS Service Catalog displays a confirmation banner on the Product list page. 

# Step 5: Create launch roles


In this step, you will create an IAM role (launch role) specifying the permissions that the Terraform provisioning engine and AWS Service Catalog can assume when an end user launches a HashiCorp Terraform product. 

 The IAM role (launch role) that you later assign to your simple Amazon S3 bucket Terraform product as a launch constraint must have the following permissions: 
+ Access to the underlying AWS resources for your Terraform product. In this tutorial, this includes access to the `s3:CreateBucket*`, `s3:DeleteBucket*`, `s3:Get*`, `s3:List*`, and `s3:PutBucketTagging` Amazon S3 operations. 
+ Read access to the Amazon S3 template in a AWS Service Catalog-owned Amazon S3 bucket 
+ Access to the `CreateGroup`, `ListGroupResources`, `DeleteGroup`, and `Tag` resource group operations. These operations enable AWS Service Catalog to manage resource groups and tags

**To create a launch role in the AWS Service Catalog administrator account**

1. While logged in to the AWS Service Catalog administrator account, follow the instructions to [ Create new policies on the JSON tab](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) in the *IAM User guide*. 

1. Create a **policy** for your simple Amazon S3 bucket Terraform product. This policy must be created before you create the launch role, and consists of the following permissions:
   +  `s3`— Allows AWS Service Catalog full permissions to list, read, write, provision, and tag the Amazon S3 product. 
   +  `s3`— Allows access to Amazon S3 buckets owned by AWS Service Catalog. To deploy the product, AWS Service Catalog requires access to provisioning artifacts. 
   +  `resourcegroups`— Allows AWS Service Catalog to create, list, delete, and tag AWS Resource Groups. 
   +  `tag`— Allows AWS Service Catalog tagging permissions. 
**Note**  
 Depending on the underlying resources that you want to deploy, you may need to modify the example JSON policy. 

   Paste the following JSON policy document: 

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "VisualEditor0",
               "Effect": "Allow",
               "Action": "s3:GetObject",
               "Resource": "*",
               "Condition": {
                   "StringEquals": {
                       "s3:ExistingObjectTag/servicecatalog:provisioning": "true"
                   }
               }
           },
           {
               "Action": [
                   "s3:CreateBucket*",
                   "s3:DeleteBucket*",
                   "s3:Get*",
                   "s3:List*",
                   "s3:PutBucketTagging"
               ],
               "Resource": "arn:aws:s3:::*",
               "Effect": "Allow"
           },
           {
               "Action": [
                   "resource-groups:CreateGroup",
                   "resource-groups:ListGroupResources",
                   "resource-groups:DeleteGroup",
                   "resource-groups:Tag"
               ],
               "Resource": "*",
               "Effect": "Allow"
           },
           {
               "Action": [
                   "tag:GetResources",
                   "tag:GetTagKeys",
                   "tag:GetTagValues",
                   "tag:TagResources",
                   "tag:UntagResources"
               ],
               "Resource": "*",
               "Effect": "Allow"
           }
       ]
   }
   ```

------

1. 

   1. Choose **Next**, **Tags**.

   1. Choose **Next,** **Review**.

   1. In the **Review policy** page, for the **Name**, enter **S3ResourceCreationAndArtifactAccessPolicy**.

   1. Choose **Create policy**.

1. In the navigation pane, choose **Roles**, and then choose **Create role**. 

1. For **Select trusted entity**, choose **Custom trust policy** and then enter the following JSON policy:

1. Choose **Next**. 

1. In the **Policies** list, select the `S3ResourceCreationAndArtifactAccessPolicy` you just created. 

1. Choose **Next**. 

1. For **Role name**, enter **SCLaunch-S3product**.
**Important**  
Launch role names **must** begin with "SCLaunch" followed by the desired role name. 

1. Choose **Create role**.
**Important**  
After creating the launch role in your AWS Service Catalog administrator account, you must also create an identical launch role in the AWS Service Catalog end user account. The role in the end user account must have the same name and include the same policy as the role in the administrator account.

**To create a launch role in the AWS Service Catalog end user account**

1. Log in as the administrator to the end user account, and then follow the instructions to [ Create new policies on the JSON tab](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html) in the *IAM User guide*. 

1. Repeat steps 2-10 from *To create a launch role in the AWS Service Catalog administrator account* above. 

**Note**  
When creating a launch role in the AWS Service Catalog end user account, ensure you use the same administrator **AccountId** in the custom trust policy. 

Now that you have created a launch role in both the administrator and end user accounts, you can add a launch constraint to the product. 

# Step 6: Add a Launch constraint to your Terraform product
Step 6: Add a launch constraint

**Important**  
You must create a launch constraint for HashiCorp Terraform products. Without a launch constraint, end users cannot provision the product. 

After creating a launch role in your administrator account, you are ready to associate the launch role to a launch constraint on your External or Terraform Cloud product. 

This launch constraint enables the end user to launch the product and, after launch, manage it as a provisioned product. For more information, see [AWS Service Catalog Launch Constraints](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/constraints-launch.html).

Using a launch constraint allows you follow the IAM best practice of keeping end user IAM permissions to a minimum. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) in the *IAM User Guide*.

**To assign a launch constraint to the product**

1. Open the AWS Service Catalog console at [https://console.aws.amazon.com/servicecatalog](https://console.aws.amazon.com/servicecatalog.).

1. In the left navigation console, choose **Portfolio**. 

1. Choose the **S3 bucket** portfolio.

1. On the **Portfolio details** page, choose the **Constraints** tab, and then choose **Create constraint**.

1. For **Product**, choose **Simple S3 bucket**. AWS Service Catalog automatically selects the **Launch** constraint type.

1. Choose **Enter role name**, and then choose **SCLaunch-S3product**. 

1. Choose ** Create**. 

**Note**  
The given role name must exist in the account that created the launch constraint and the account of the user who launches a product with this launch constraint. 

# Step 7: Grant end user access


After applying the launch constraint to your HashiCorp Terraform product, you are ready to grant access to end users in the spoke account.

In this tutorial, you grant access to end users using Principal Name sharing. Principal Names are names for groups, roles, and users that administrators can specify in a portfolio, and then share with the portfolio. When you share the portfolio, AWS Service Catalog verifies if those Principal Names already exist. If they do exist, AWS Service Catalog automatically associates the matching IAM principals with the shared portfolio to grant access to end users. Review [Sharing a Portfolio](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/catalogs_portfolios_sharing_how-to-share) for more information. 

**Prerequisites**  
If you haven't created an IAM group for the end users, see [Grant permissions to AWS Service Catalog end users](getstarted-iamenduser.md).

**To provide access to the portfolio**

1. Navigate to the **Portfolio** page and choose the **S3 bucket** portfolio. 

1. Choose the **Access** tab, and then choose **Grant access**. 

1. In the **Access type** pane, choose **Principal name**. 

1. In the **Principal name** pane, select the **Principal name** type, and then enter the principal **Name** of the desired end user in the spoke account. 

1. Choose **Grant access**. 

# Step 8: Share portfolio with end user


The AWS Service Catalog administrator can distribute portfolios with end user accounts using either account-to-account sharing or AWS Organizations sharing. In this tutorial, you are sharing your portfolio with the organization from the administrator account (hub account), which is also the management account of the Organization. 

**To share the portfolio from the admin hub account**

1. Open the AWS Service Catalog console at [https://console.aws.amazon.com/servicecatalog/](https://console.aws.amazon.com/servicecatalog/). 

1. On the **Portfolios** page, select the S3 bucket portfolio. In the **Actions** menu, choose **Share**. 

1. Choose **AWS Organizations**, and then filter into your organizational structure. 

1. In the **AWS Organization** pane, choose the end user account (spoke account). 

   You can also select a **Root node** to share the portfolio with the entire organization, a **parent Organizational Unit (OU)**, or a **child OU** within your organization based on your organization structure. For more information, review [Sharing a Portfolio](catalogs_portfolios_sharing_how-to-share.md). 

1. In the **Share settings** pane, choose **Principal sharing**. 

1. Choose **Share**. 

After successfully sharing the portfolio with end users, the next step is to verify the end user experience and provision the Terraform product. 

# Step 9: Test the end user experience


To verify end users can successfully access the end user console view and launch your **Simple S3 bucket** product, sign in to AWS as the end user and perform the tasks below. 

**To verify that the end user can access the end user console**
+ Open the AWS Service Catalog console at [https://console.aws.amazon.com/servicecatalog/](https://console.aws.amazon.com/servicecatalog/) to see:
  + **Products** – The products that the user can use.
  + **Provisioned products** – The provisioned products that the user has launched.

**To verify the end user can launch the Terraform product**

1. In the **Products** section of the console, choose **Simple S3 bucket**.

1. Choose **Launch product** to start the wizard that configures your product.

1. On the **Launch Simple S3 bucket** page, enter **Amazon S3 product** for the provisioned product name.

1. On the **Parameters** page, enter the following and choose **Next**:
   +  **bucket\$1name** – Provide a unique name for the Amazon S3 bucket. For example, **terraform-s3-product**. 

1. Choose **Launch product**. The console displays the stack details page for the Amazon S3 product launch. The initial status of the product is **Under change**. It takes several minutes for AWS Service Catalog to launch the product. To see the current status, refresh your browser. After a successful product launch, the status is **Available**. 

   AWS Service Catalog creates a new Amazon S3 bucket named **terraform-s3-product**. 

# Step 10: Monitoring Terraform provisioning operations
Step 10: Monitoring Terraform provisioning operations

If you want to monitor provisioning operations, you can review Amazon CloudWatch logs and AWS Step Functions for any provisioning workflow. 

There are two state machines for the provisioning workflow: 
+ `ManageProvisionedProductStateMachine` — AWS Service Catalog invokes this state machine when provisioning a new Terraform product and when updating an existing Terraform provisioned product. 
+ `TerminateProvisionedProductStateMachine` — AWS Service Catalog invokes this state machine when terminating an existing Terraform provisioned product. 

**To execute the monitoring state machine**

1. Open the AWS management console and log in as an administrator in the admin hub account where the Terraform provisioning engine is installed.

1. Open **AWS Step Functions**. 

1. In the left navigation panel, choose **State machines**. 

1. Choose **ManageProvisionedProductStateMachine**. 

1. In the **Executions** list, enter the provisioned product ID to locate your execution. 
**Note**  
AWS Service Catalog creates the provisioned product ID when you provision the product. The provisioned product ID is formatted as follows: **pp-1111pwtn[ID number]**. 

1. Choose the **execution ID**. 

On the resulting **Execution details** page, you can view all of the steps in the provisioning workflow. You can also review any failed steps to identify the cause of the failure.