# Getting Started
You can get started with AWS Service Catalog by using one of the well-architected product templates in the Getting Started Library or by following the steps in one of the getting started tutorials.
In the tutorial, you perform tasks as the catalog administrator and end user. As the catalog administrator, you create a portfolio and then a product. As the end user, you verify that you can access the end user console and launch the product. The product is one of the following:
+ A cloud development environment that runs on Amazon Linux and is based on an CloudFormation template that defines the AWS resources the product can use.
+ An open source environment that runs on a Terraform provisioning engine and is based on a tar.gz configuration file that defines the AWS resources the product can use.
**Note**
Before you begin, make sure that you complete the action items in [Setting Up AWS Service Catalog](setup.md).
**Topics**
+ [Getting Started Library](getstarted-library.md)
+ [Getting started with an CloudFormation product](getstarted-CFN.md)
+ [Getting started with a Terraform product](getstarted-Terraform.md)
# Getting Started Library
AWS Service Catalog provides a Getting Started Library of well-architected product templates so you can get started quickly. You can copy any of the products in our Getting Started Library portfolios to your own account, then customize them to suit your needs.
**Topics**
+ [Prerequisites](#getting-started-library-prereqs)
+ [Learn More](#getting-started-library-learn-more)
## Prerequisites
Before you use the templates in our Getting Started Library, make sure you have the following:
+ The required permissions to use CloudFormation templates. For more information, see [Controlling Access with AWS Identity and Access Management](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html).
+ The required administrator permissions to manage AWS Service Catalog. For more information, see [Identity and Access Management in AWS Service Catalog](controlling_access.md).
## Learn More
For more information about the well-architected framework, see [AWS Well-Architected](https://aws.amazon.com/architecture/well-architected/).
# Getting started with an CloudFormation product
You can get started with AWS Service Catalog by using one of the well-architected product templates in the Getting Started Library or by following the steps in the getting started tutorial.
In the tutorial, you perform tasks as the catalog administrator and end user. As the catalog administrator, you create a porfolio and then a product. As the end user, you verify that you can access the end user console and launch the product. The product is a cloud development environment that runs on Amazon Linux and is based on an CloudFormation template that defines the AWS resources the product can use.
**Note**
Before you begin, make sure that you complete the action items in [Setting Up AWS Service Catalog](setup.md).
**Topics**
+ [Step 1: Download the CloudFormation template](getstarted-template.md)
+ [Step 2: Create a key pair](getstarted-keypair.md)
+ [Step 3: Create a portfolio](getstarted-portfolio.md)
+ [Step 4: Create a new product in the portfolio](getstarted-product.md)
+ [Step 5: Add a template constraint to limit instance size](getstarted-constraint.md)
+ [Step 6: Add a launch constraint to assign an IAM role](getstarted-launchconstraint.md)
+ [Step 7: Grant end users access to the portfolio](getstarted-deploy.md)
+ [Step 8: Test the end user experience](getstarted-verify.md)
# Step 1: Download the CloudFormation template
You can use CloudFormation templates to configure and provision portfolios and products. These templates are text files that can be formatted in JSON or YAML and describe the resources that you want to provision. For more information, see [Template Formats](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-formats.html) in the *CloudFormation User Guide*. You can use the AWS CloudFormation editor or a text editor of your choice to create and save templates. In this tutorial, we provide a simple template, so you can get started. The template launches a single Linux instance that's configured for SSH access.
**Note**
Using CloudFormation templates requires special permissions. Before you begin, make sure that you have the correct permissions. For more information, see the prerequisites in [Getting Started Library](getstarted-library.md).
## Template Download
The sample template provided for this tutorial, `development-environment.template`, is available at [https://awsdocs.s3.amazonaws.com/servicecatalog/development-environment.template](https://awsdocs.s3.amazonaws.com/servicecatalog/development-environment.template).
## Template Overview
The text of the sample template follows:
```
{
"AWSTemplateFormatVersion" : "2010-09-09",
"Description" : "AWS Service Catalog sample template. Creates an Amazon EC2 instance
running the Amazon Linux AMI. The AMI is chosen based on the region
in which the stack is run. This example creates an EC2 security
group for the instance to give you SSH access. **WARNING** This
template creates an Amazon EC2 instance. You will be billed for the
AWS resources used if you create a stack from this template.",
"Parameters" : {
"KeyName": {
"Description" : "Name of an existing EC2 key pair for SSH access to the EC2 instance.",
"Type": "AWS::EC2::KeyPair::KeyName"
},
"InstanceType" : {
"Description" : "EC2 instance type.",
"Type" : "String",
"Default" : "t2.micro",
"AllowedValues" : [ "t2.micro", "t2.small", "t2.medium", "m3.medium", "m3.large",
"m3.xlarge", "m3.2xlarge" ]
},
"SSHLocation" : {
"Description" : "The IP address range that can SSH to the EC2 instance.",
"Type": "String",
"MinLength": "9",
"MaxLength": "18",
"Default": "0.0.0.0/0",
"AllowedPattern": "(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})\\.(\\d{1,3})/(\\d{1,2})",
"ConstraintDescription": "Must be a valid IP CIDR range of the form x.x.x.x/x."
}
},
"Metadata" : {
"AWS::CloudFormation::Interface" : {
"ParameterGroups" : [{
"Label" : {"default": "Instance configuration"},
"Parameters" : ["InstanceType"]
},{
"Label" : {"default": "Security configuration"},
"Parameters" : ["KeyName", "SSHLocation"]
}],
"ParameterLabels" : {
"InstanceType": {"default": "Server size:"},
"KeyName": {"default": "Key pair:"},
"SSHLocation": {"default": "CIDR range:"}
}
}
},
"Mappings" : {
"AWSRegionArch2AMI" : {
"us-east-1" : { "HVM64" : "ami-08842d60" },
"us-west-2" : { "HVM64" : "ami-8786c6b7" },
"us-west-1" : { "HVM64" : "ami-cfa8a18a" },
"eu-west-1" : { "HVM64" : "ami-748e2903" },
"ap-southeast-1" : { "HVM64" : "ami-d6e1c584" },
"ap-northeast-1" : { "HVM64" : "ami-35072834" },
"ap-southeast-2" : { "HVM64" : "ami-fd4724c7" },
"sa-east-1" : { "HVM64" : "ami-956cc688" },
"cn-north-1" : { "HVM64" : "ami-ac57c595" },
"eu-central-1" : { "HVM64" : "ami-b43503a9" }
}
},
"Resources" : {
"EC2Instance" : {
"Type" : "AWS::EC2::Instance",
"Properties" : {
"InstanceType" : { "Ref" : "InstanceType" },
"SecurityGroups" : [ { "Ref" : "InstanceSecurityGroup" } ],
"KeyName" : { "Ref" : "KeyName" },
"ImageId" : { "Fn::FindInMap" : [ "AWSRegionArch2AMI", { "Ref" : "AWS::Region" }, "HVM64" ] }
}
},
"InstanceSecurityGroup" : {
"Type" : "AWS::EC2::SecurityGroup",
"Properties" : {
"GroupDescription" : "Enable SSH access via port 22",
"SecurityGroupIngress" : [ {
"IpProtocol" : "tcp",
"FromPort" : "22",
"ToPort" : "22",
"CidrIp" : { "Ref" : "SSHLocation"}
} ]
}
}
},
"Outputs" : {
"PublicDNSName" : {
"Description" : "Public DNS name of the new EC2 instance",
"Value" : { "Fn::GetAtt" : [ "EC2Instance", "PublicDnsName" ] }
},
"PublicIPAddress" : {
"Description" : "Public IP address of the new EC2 instance",
"Value" : { "Fn::GetAtt" : [ "EC2Instance", "PublicIp" ] }
}
}
}
```
**Template Resources**
The template declares resources to be created when the product is launched. It consists of the following sections:
+ **AWSTemplateFormatVersion** (optional) – The version of the [AWS Template Format](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/format-version-structure.html) used to create this template. The latest template format version is 2010-09-09 and is currently the only valid value.
+ **Description** (optional) – A description of the template.
+ **Parameters** (optional) – The parameters that your user must specify to launch the product. For each parameter, the template includes a description and constraints that must be met by the value typed. For more information about constraints, see [Using AWS Service Catalog Constraints](constraints.md).
The `KeyName` parameter allows you to specify an Amazon Elastic Compute Cloud (Amazon EC2) key pair name that end users must provide when they use AWS Service Catalog to launch your product. You will create the key pair in the next step.
+ **Metadata** (optional) – Objects that provide additional information about the template. The [AWS::CloudFormation::Interface](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-cloudformation-interface.html) key defines how the end user console view displays parameters. The `ParameterGroups` property defines how parameters are grouped and headings for those groups. The `ParameterLabels` property defines friendly parameter names. When a user is specifying parameters to launch a product that is based on this template, the end user console view displays the parameter labeled `Server size:` under the heading `Instance configuration`, and it displays the parameters labeled `Key pair:` and `CIDR range:` under the heading `Security configuration`.
+ **Mappings** (optional) – A mapping of keys and associated values that you can use to specify conditional parameter values, similar to a lookup table. You can match a key to a corresponding value by using the [Fn::FindInMap](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-findinmap.html) intrinsic function in the Resources and Outputs sections. The template above includes a list of AWS Regions and the Amazon Machine Image (AMI) that corresponds to each. AWS Service Catalog uses this mapping to determine which AMI to use based on the AWS Region that the user selects in the AWS Management Console.
+ **Resources** (required) – Stack resources and their properties. You can refer to resources in the **Resources **and **Outputs** sections of the template. In the template above, we specify an EC2 instance running Amazon Linux and a security group that allows SSH access to the instance. The **Properties** section of the EC2 instance resource uses the information that the user types to configure the instance type and a key name for SSH access.
CloudFormation uses the current AWS Region to select the AMI ID from the mappings defined earlier and assigns a security group to it. The security group is configured to allow inbound access on port 22 from the CIDR IP address range that the user specifies.
+ **Outputs** (optional) – Text that tells the user when the product launch is complete. The provided template gets the public DNS name of the launched instance and displays it to the user. The user needs the DNS name to connect to the instance using SSH.
For more information about the Template anatomy page, see [Template reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-reference.html) in the *CloudFormation User Guide*.
# Step 2: Create a key pair
To enable your end users to launch the product that is based on the sample template for this tutorial, you must create an Amazon EC2 key pair. A key pair is a combination of a public key that is used to encrypt data and a private key that is used to decrypt data. For more information about key pairs, ensure you are signed into the AWS console and then review [Amazon EC2 Key Pairs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) in the *Amazon EC2 User Guide*.
The CloudFormation template for this tutorial, `development-environment.template`, includes the `KeyName` parameter:
```
. . .
"Parameters" : {
"KeyName": {
"Description" : "Name of an existing EC2 key pair for SSH access to the EC2 instance.",
"Type": "AWS::EC2::KeyPair::KeyName"
},
. . .
```
End users must specify the name of a key pair when they use AWS Service Catalog to launch the product that is based on the template.
If you already have a key pair in your account that you would prefer to use, you can skip ahead to [Step 3: Create a portfolio](getstarted-portfolio.md). Otherwise, complete the following steps.
**To create a key pair**
1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. In the navigation pane, under **Network & Security**, choose **Key Pairs**.
1. On the **Key Pairs** page, choose **Create Key Pair**.
1. For **Key pair name**, type a name that is easy for you to remember, and then choose **Create**.
1. When the console prompts you to save the private key file, save it in a safe place.
**Important**
This is the only chance for you to save the private key file.
# Step 3: Create a portfolio
To provide users with products, begin by creating a portfolio for those products.
**To create a portfolio**
1. Open the Service Catalog console at [https://console.aws.amazon.com/servicecatalog/](https://console.aws.amazon.com/servicecatalog/).
1. In the left navigation panel, choose **Portfolios**, and then choose **Create portfolio**.
1. Type the following values:
+ **Portfolio name** – **Engineering Tools**
+ **Portfolio description** – **Sample portfolio that contains a single product.**
+ **Owner** – **IT (it@example.com)**
1. Choose **Create**.
# Step 4: Create a new product in the portfolio
After you have created a portfolio, you are ready to create a product within the portfolio. For this tutorial, you will create a product called **Linux Desktop**, a cloud development environment that runs on Amazon Linux, inside of the **Engineering Tool** portfolio.
**To create a product within a portfolio**
1. If you've just completed the previous step, the **Portfolios** page is already displayed. Otherwise, open [https://console.aws.amazon.com/servicecatalog/](https://console.aws.amazon.com/servicecatalog/).
1. Choose and open the **Engineering Tool** portfolio you created in Step 2.
1. Choose **Upload new product.**
1. On the **Create product** page in the Product details section, enter the following:
+ **Product name** – **Linux Desktop**
+ **Product description** – **Cloud development environment configured for engineering staff. Runs AWS Linux.**
+ **Owner** – **IT**
+ **Distributor** – *(blank)*
1. On the **Version details** page, choose **Use a CloudFormation template**. Then choose **Specify an Amazon S3 template URL** and enter the following:
+ **Select template** – **https://awsdocs.s3.amazonaws.com/servicecatalog/development-environment.template**
+ **Version title** – **v1.0**
+ **Description** – **Base Version**
1. In the **Support details** section, enter the following:
+ **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**.
# Step 5: Add a template constraint to limit instance size
Constraints add another layer of control over products at the portfolio level. Constraints can control the launch context of a product (launch constraints), or add rules to the CloudFormation template (template constraints). For more information, see [Using AWS Service Catalog Constraints](constraints.md).
Add a template constraint to the Linux Desktop product that prevents users from selecting large instance types at launch time. The development-environment template allows the user to select from six instance types; this constraint limits valid instance types to the two smallest types, `t2.micro` and `t2.small`. For more information, see [T2 Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/t2-instances.html) in the *Amazon EC2 User Guide*.
**To add a template constraint to the Linux Desktop product**
1. On the **Portfolio details** page, choose **Constraints**, then choose **Create constraint**.
1. In the **Create constraint** page, for **Product,** choose **Linux Desktop**. Then, for **Constraint type**, choose **Template**.
1. In the T**emplate constraint** section, choose **Text editor**.
1. Paste the following into the text editor:
```
{
"Rules": {
"Rule1": {
"Assertions": [
{
"Assert" : {"Fn::Contains": [["t2.micro", "t2.small"], {"Ref": "InstanceType"}]},
"AssertDescription": "Instance type should be t2.micro or t2.small"
}
]
}
}
}
```
1. For **Constraint description**, enter **Small instance sizes**.
1. Choose **Create**.
# Step 6: Add a launch constraint to assign an IAM role
A launch constraint designates an IAM role that AWS Service Catalog assumes when an end user launches a product.
For this step, you add a launch constraint to the Linux Desktop product, so AWS Service Catalog can use the IAM resources that make up the product's AWS CloudFormation template.
The IAM role that you assign to a product as a launch constraint must have the following permissions
1. AWS CloudFormation
1. Services in the AWS CloudFormation template for the product
1. Read access to the AWS CloudFormation template in a service-owned Amazon S3 bucket.
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).
Without a launch constraint, you need to grant additional IAM permissions to your end users before they can use the Linux Desktop product. For example, the `ServiceCatalogEndUserAccess` policy grants the minimum IAM permissions required to access the AWS Service Catalog end user console view.
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 add a launch constraint**
1. 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. Paste the following JSON policy document:
+ `cloudformation`– Allows AWS Service Catalog full permissions to create, read, update, delete, list, and tag CloudFormation stacks.
+ `ec2`— Allows AWS Service Catalog full permissions to list, read, write, provision, and tag Amazon Elastic Compute Cloud (Amazon EC2) resources that are part of the AWS Service Catalog product. Depending on the AWS resource that you want to deploy, this permission might change.
+ `ec2`– Creates a new managed policy for you AWS account and attaches the specified managed policy to the specified IAM role.
+ `s3`— Allows access to Amazon S3 buckets owned by AWS Service Catalog. To deploy the product, AWS Service Catalog requires access to provisioning artifacts.
+ `servicecatalog`— Allows AWS Service Catalog permissions to list, read, write, tag, and launch resources on behalf of the end-user.
+ `sns`— Allows AWS Service Catalog permissions to list, read, write, and tag Amazon SNS topics for the launch constraint.
**Note**
Depending on the underlying resources that you want to deploy, you might need to modify the example JSON policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"cloudformation:CreateStack",
"cloudformation:DeleteStack",
"cloudformation:DescribeStackEvents",
"cloudformation:DescribeStacks",
"cloudformation:GetTemplateSummary",
"cloudformation:SetStackPolicy",
"cloudformation:ValidateTemplate",
"cloudformation:UpdateStack",
"ec2:*",
"servicecatalog:*",
"sns:*"
],
"Resource": "*"
},
{
"Effect":"Allow",
"Action":[
"s3:GetObject"
],
"Resource":"*",
"Condition":{
"StringEquals":{
"s3:ExistingObjectTag/servicecatalog:provisioning":"true"
}
}
}
]
}
```
------
1. Choose **Next**, **Tags**.
1. Choose **Next,** **Review**.
1. In the **Review policy** page, for the **Name**, enter **linuxDesktopPolicy**.
1. Choose **Create policy**.
1. In the navigation pane, choose **Roles**. Then choose **Create role** and do the following:
1. For **Select trusted entity**, choose **AWS service** and then under **Use case for other AWS services **choose **Service Catalog**. Select the Service Catalog use case and then choose **Next**.
1. Search for the **linuxDesktopPolicy** policy and then select the checkbox.
1. Choose **Next**.
1. For **Role name**, type **linuxDesktopLaunchRole**.
1. Choose **Create role**.
1. Open the AWS Service Catalog console at [https://console.aws.amazon.com/servicecatalog](https://console.aws.amazon.com/servicecatalog.).
1. Choose the **Engineering Tools** portfolio.
1. On the **Portfolio details** page, choose the **Constraints** tab, and then choose **Create constraint**.
1. For **Product**, choose **Linux Desktop**, and for **Constraint type**, choose **Launch**.
1. Choose **Select IAM role**. Next choose **linuxDesktopLaunchRole**, and then choose **Create**.
# Step 7: Grant end users access to the portfolio
Now that you have created a portfolio and added a product, you are ready to grant access to end users.
**Prerequisites**
If you haven't created an IAM group for the endusers, see [Grant permissions to AWS Service Catalog end users](getstarted-iamenduser.md).
**To provide access to the portfolio**
1. On the portfolio details page, choose the **Access** tab.
1. Choose **Grant access**.
1. On the **Groups** tab, select the checkbox for the IAM group for the end users.
1. Choose **Add Access**.
# Step 8: Test the end user experience
To verify the end user can successfully access the end user console view and launch your product, sign in to AWS as the end user and perform those tasks.
**To verify that the end user can access the end user console**
1. Follow the instructions to [Sign in as an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/console.html) in the *IAM User guide*.
1. In the menu bar, choose the AWS Region in which you created the `Engineering Tools` portfolio. For this tutorial, choose **us-east-1 region**.
1. 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 Linux Desktop product**
Note that for this tutorial, choose** us-east-1 region**.
1. In the **Products** section of the console, choose **Linux Desktop**.
1. Choose **Launch product** to start the wizard that configures your product.
1. On the **Launch: Linux Desktop** page, enter **Linux-Desktop** for the provisioned product name.
1. On the **Parameters** page, enter the following and choose **Next**:
+ **Server size** – Choose **t2.micro**.
+ **Key pair** – Select the key pair that you created in [Step 2: Create a key pair](getstarted-keypair.md).
+ **CIDR range** – Enter a valid CIDR range for the IP address to connect to the instance. You can use the default value (0.0.0.0/0) to allow access from any IP address, then your IP address, followed by **/32** to restrict access to your IP address only, or something in between.
1. Choose **Launch product **to launch the stack. The console displays the stack details page for the Linux-Desktop stack. 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 the product launches, the status is A**vailable**.
# 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
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
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
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
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
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
**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
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.