# Provision AWS Service Catalog products based on AWS CloudFormation templates by using GitHub Actions
*Ashish Bhatt and Ruchika Modi, Amazon Web Services*
## Summary
This pattern provides organizations with a streamlined approach using [AWS Service Catalog](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/introduction.html) products and portfolios to provision standardized and compliant AWS services across teams. [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) helps to combine essential components in Service Catalog products and portfolios for provisioning base network infrastructure on AWS Cloud. This pattern also promotes DevOps practices by integrating infrastructure as code (IaC) into automated development workflows by using [GitHub Actions](https://github.com/features/actions).
AWS Service Catalog enables organizations to create and manage approved IT services on AWS, offering benefits such as standardization, centralized control, self-service provisioning, and cost management. By automating the deployment of Service Catalog portfolios and products through GitHub Actions, companies can do the following:
+ Achieve consistent and repeatable deployments.
+ Use version control for IaC.
+ Integrate cloud resource management with existing development workflows.
This combination streamlines cloud operations, enforces compliance, and accelerates the delivery of approved services while reducing manual errors and improving overall efficiency.
## Prerequisites and limitations
**Prerequisites **
+ An active AWS account
+ Access to [GitHub repository](https://docs.github.com/en/get-started/quickstart/create-a-repo)
+ Basic understanding of AWS CloudFormation and AWS Service Catalog
+ An Amazon Simple Storage Service (Amazon S3) bucket to host CloudFormation templates
+ An AWS Identity and Access Management (IAM) role named `github-actions` that is used for connectivity between GitHub and AWS
**Limitations **
+ This pattern’s reusable code has been tested only with GitHub Actions.
+ Some AWS services aren’t available in all AWS Regions. For Region availability, see [AWS services by Region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). For specific endpoints, see [Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html), and choose the link for the service.
**Product versions**
This pattern’s solution was created by using the following [GitHub Marketplace](https://github.com/marketplace) actions and their respective versions:
+ `actions/checkout@v4`
+ `aws-actions/configure-aws-credentials@v2`
+ `aws-actions/aws-cloudformation-github-deploy@v1.2.0`
## Architecture
The following diagram shows the architecture for this solution.
1. Administrators or platform engineers push standardized CloudFormation templates to a GitHub repository, where the templates are maintained. The GitHub repo also contains workflows that automate the provisioning of AWS Service Catalog using GitHub Actions.
1. GitHub Actions triggers a workflow that connects to the AWS Cloud using an OpenID Connect (OIDC) provider to provision Service Catalog.
1. Service Catalog contains the portfolio and products that developers can directly use to provision standardized AWS resources. This pattern bundles AWS resources such as virtual private clouds (VPCs), subnets, NAT and internet gateways, and route tables.
1. After the developer creates a Service Catalog product, Service Catalog converts it into pre-configured and standardized AWS resources. As a result, developers save time because they don’t need to provision individual resources and configure them manually.
## Tools
**AWS services**
+ [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) helps you set up AWS resources, provision them quickly and consistently, and manage them throughout their lifecycle across AWS accounts and AWS Regions. It's an infrastructure as code (IaC) service that can be easily used as one of the product types with AWS Service Catalog.
+ [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them.
+ [AWS Service Catalog](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/getstarted.html) helps you centrally manages catalog of IT services that are approved for AWS. End users can quickly deploy only the approved IT services they need, following the constraints set by your organization.
+ [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) is a cloud-based object storage service that helps you store, protect, and retrieve any amount of data.
**Others**
+ [GitHub Actions](https://docs.github.com/en/actions) is a continuous integration and continuous delivery (CI/CD) platform that’s tightly integrated with GitHub repositories. You can use GitHub Actions to automate your build, test, and deployment pipeline.
**Code repository**
The code for this pattern is available in the GitHub [service-catalog-with-github-actions](https://github.com/aws-samples/service-catalog-with-github-actions) repository. The repo contains the following files of interest:
+ `github/workflows`:
+ `e2e-test.yaml` – This file calls `workflow.yaml`, which is the [reusable workflow](https://docs.github.com/en/actions/sharing-automations/reusing-workflows). This workflow is triggered as soon as there is a commit and push on a branch.
+ `workflow.yaml` – This file contains the reusable workflow for this solution and is configured with `workflow_call` as its trigger. As a reusable workflow, `workflow.yaml` can be called from any other workflow.
+ `templates`:
+ `servicecatalog-portfolio.yaml` – This CloudFormation template includes resources that provision the Service Catalog portfolio and Service Catalog product. The template contains a set of parameters that are used while provisioning the Service Catalog portfolio and products. One parameter accepts an Amazon S3 file URL where the template `vpc.yaml` is uploaded. Although this pattern includes the `vpc.yaml` file to provision AWS resources, you can also use the parameter S3 file URL for configuration.
+ `vpc.yaml` – This CloudFormation template contains AWS resources to be added in the Service Catalog product. AWS resources include VPCs, subnets, internet gateways, NAT gateways, and route tables. The `vpc.yaml` template is an example of how you can use any CloudFormation template with a Service Catalog product and portfolio template.
## Best practices
+ See [Security Best Practices for AWS Service Catalog](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/security-best-practices.html) in the AWS Service Catalog documentation.
+ See [Security hardening for GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions) in the GitHub documentation.
## Epics
### Set up local workstation
| Task | Description | Skills required |
| --- | --- | --- |
| Set up Git on your local workstation. | To install and configure Git on your local workstation, use the [Getting Started – Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) instructions in the Git documentation. | App developer |
| Clone the GitHub project repo. | To clone the GitHub project repo, do the following:[See the AWS documentation website for more details](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/provision-aws-service-catalog-products-using-github-actions.html) | DevOps engineer |
### Set up the OIDC provider
| Task | Description | Skills required |
| --- | --- | --- |
| Configure an OIDC provider. | Create an OpenID Connect (OIDC) provider that allows the GitHub Actions workflows to access resources in AWS, without needing to store the AWS credentials as long-lived GitHub secrets. For instructions, see [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) in the GitHub documentation.
After an OIDC provider is configured, the trust policy of the IAM role `github-actions`, mentioned earlier in the [Prerequisites](#provision-aws-service-catalog-products-using-github-actions-prereqs), will be updated. | AWS administrator, AWS DevOps, General AWS |
### Trigger GitHub Actions pipeline to deploy Service Catalog portfolio and products
| Task | Description | Skills required |
| --- | --- | --- |
| Update `e2e-test.yaml`. | The `e2e-test.yaml` file triggers the reusable workflow at `workflow.yaml`. Update and validate the values for the following input parameters in `e2e-test.yaml`:[See the AWS documentation website for more details](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/provision-aws-service-catalog-products-using-github-actions.html) | DevOps engineer |
### Validate deployment
| Task | Description | Skills required |
| --- | --- | --- |
| Validate the Service Catalog resources. | To validate the Service Catalog resources, do the following:[See the AWS documentation website for more details](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/provision-aws-service-catalog-products-using-github-actions.html) | AWS DevOps |
### Clean up resources
| Task | Description | Skills required |
| --- | --- | --- |
| Delete the CloudFormation stack. | To delete the CloudFormation stack, do the following:[See the AWS documentation website for more details](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/provision-aws-service-catalog-products-using-github-actions.html)
For more information, see [Delete a stack from the CloudFormation console](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html) in the CloudFormation documentation | DevOps engineer, AWS administrator |
## Troubleshooting
| Issue | Solution |
| --- | --- |
| `e2e-test`
`Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under '*/home/runner/work/service-catalog-with-github-actions/service-catalog-with-github-actions`
`Did you forget to run actions/checkout before running your local action?` | To make sure that you have the correct repository settings enabled, do the following:[See the AWS documentation website for more details](http://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/provision-aws-service-catalog-products-using-github-actions.html) |
## Related resources
**AWS documentation**
+ [Overview of Service Catalog](https://docs.aws.amazon.com/servicecatalog/latest/adminguide/what-is_concepts.html)
**Other resources**
+ [About events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#about-events-that-trigger-workflows) (GitHub documentation)
+ [Reusing workflows](https://docs.github.com/en/actions/sharing-automations/reusing-workflows) (GitHub documentation)
## Additional information
To see screenshots related to the [Epics](#provision-aws-service-catalog-products-using-github-actions-epics), go to the **Images **folder in this pattern's GitHub repo. The following screenshots are available:
+ [AWS Service Catalog portfolio, Administration section](https://github.com/aws-samples/service-catalog-with-github-actions/blob/main/images/SC_portfolio.png)
+ [AWS Service Catalog product, Administration section](https://github.com/aws-samples/service-catalog-with-github-actions/blob/main/images/SC_Product.png)
+ [AWS Service Catalog product, User/Provisioning section](https://github.com/aws-samples/service-catalog-with-github-actions/blob/main/images/SC_Product_User.png)