Skip to content

Commit

Permalink
docs: comprehensive documentation cleanup and refresh
Browse files Browse the repository at this point in the history 
- Remove obsolete documentation files:
  - MIGRATION.md (superseded by CLOUDFORMATION_CUSTOM_RESOURCE_MIGRATION.md)
  - docs/tf-native*.md (unused Terraform-native migration planning)
  - docs/callnotes.md/txt (old meeting notes)
  - docs/gitlab-migration.md (GitLab provider already implemented)
  - template_automation/ROADMAP.md (empty placeholder)
  - template_automation/old.py (dead code, unused)
  - test_service_catalog.py (references old ServiceCatalogInput class)

- Remove stale test events:
  - events/service-catalog-event.json (old EventBridge format)
  - events/test-event.json (old EventBridge format)
  - Keep events/cloudformation-create-event.json (current format)

- Update docs to reflect CloudFormation Custom Resource architecture:
  - DEPLOYMENT.md: remove API Gateway reference
  - PACKER_UPDATES.md: replace EventBridge references with Custom Resource
  - design-docs/README.md: update architecture descriptions
  - design-docs/CUSTOM_TEMPLATES.MD: use CloudFormation template examples
  - design-docs/REPO_VARS_AND_SECRETS.md: update event format examples

- Fix Sphinx documentation build:
  - docs/source/conf.py: fix Pydantic v2 compatibility with napoleon
  - docs/source/index.rst: fix RST underline lengths, update content
  - docs/source/modules/lambda_handler.rst: update exported members
  • Loading branch information
Your Name committed Feb 6, 2026
1 parent 79e60a2 commit 83a0b96
Show file tree
Hide file tree
Showing 22 changed files with 181 additions and 1,851 deletions.
174 changes: 39 additions & 135 deletions DEPLOYMENT.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Deployment Guide: Service Catalog Repository Generator

This guide walks through deploying the Lambda function that Service Catalog will invoke to create GitHub repositories.
This guide walks through deploying the Lambda function that Service Catalog will invoke (via CloudFormation Custom Resource) to create GitHub repositories.

## Overview

The deployment has three main steps:
The deployment has three main stages:
1. **Create ECR Repository** - Where the Lambda container image will be stored
2. **Build & Push Container** - Build the Lambda code into a container and push to ECR
3. **Deploy Lambda Function** - Deploy the Lambda and EventBridge integration using Terraform
3. **Deploy Lambda Function** - Deploy the Lambda function using Terraform

## Prerequisites

Expand All @@ -19,7 +19,7 @@ The deployment has three main steps:
- `csvd-template-automation-builds` (for build artifacts)
- `image-pipeline-assets-dev` (for Packer binaries)

## Step 1: Create ECR Repository
## Step 1: Create ECR Repository (Infrastructure)

```bash
cd /home/a/arnol377/git/lambda-template-repo-generator
Expand All @@ -34,7 +34,7 @@ terraform apply

**Output**: ECR repository at `229685449397.dkr.ecr.us-gov-west-1.amazonaws.com/service-catalog-repo-generator/lambda`

## Step 2: Build and Push Lambda Container
## Step 2: Build and Push Lambda Container (Pipeline)

```bash
cd /home/a/arnol377/git/lambda-template-repo-generator
Expand All @@ -57,7 +57,7 @@ aws ecr describe-images \
--region us-gov-west-1
```

## Step 3: Deploy Lambda Function
## Step 3: Deploy Lambda Function (Application)

### 3a. Configure Deployment Variables

Expand Down Expand Up @@ -86,117 +86,54 @@ terraform init
# Review the plan
terraform plan

# Deploy the Lambda function and EventBridge rule
# Deploy the Lambda function and CloudFormation permissions
terraform apply
```

This creates:
- ✅ Lambda function using your container image
- ✅ IAM roles and policies
- ✅ SSM parameters for configuration
- ✅ EventBridge rule to trigger from Service Catalog
- ✅ Lambda permissions for EventBridge
- ✅ API Gateway (if you want direct invocation as well)
- ✅ Lambda permissions for CloudFormation to invoke it (as Custom Resource)

**Important**: Note the `lambda_function_arn` output. You will need this for your Service Catalog CloudFormation template.

## Step 4: Create Service Catalog Product

Now you need to create a Service Catalog product that triggers your Lambda. You have two options:
Now you need to create a Service Catalog product that uses the Lambda as a CloudFormation Custom Resource.

### Option A: CloudFormation with Lambda-backed Custom Resource
### Use the Provided Template

Create a CloudFormation template:
A complete CloudFormation template is available at `cloudformation-template.yaml`.

```yaml
AWSTemplateFormatVersion: '2010-09-09'
Description: 'Service Catalog Product: Create GitHub Repository'

Parameters:
ProjectName:
Type: String
Description: Name of the repository to create
OwningTeam:
Type: String
Description: GitHub team that should own the repository
Default: tf-module-admins
Environment:
Type: String
Description: Environment (dev, staging, prod)
AllowedValues:
- development
- staging
- production
AwsRegion:
Type: String
Description: AWS region for the project
Default: us-gov-west-1
1. **Update the Template**: ensuring the `ServiceToken` points to your deployed Lambda ARN.
2. **Upload to Service Catalog**: Create a new product of type "CloudFormation Template" and upload this file.

### Custom Resource Definition

If you are writing your own template, the resource definition looks like this:

```yaml
Resources:
TriggerLambda:
Type: Custom::RepositoryCreator
Properties:
ServiceToken: !Sub 'arn:aws-us-gov:lambda:us-gov-west-1:229685449397:function:service-catalog-repo-gen-template-automation'
ServiceToken: !Sub 'arn:aws-us-gov:lambda:${AWS::Region}:${AWS::AccountId}:function:service-catalog-repo-gen-template-automation'
ProjectName: !Ref ProjectName
OwningTeam: !Ref OwningTeam
Environment: !Ref Environment
AwsRegion: !Ref AwsRegion

Outputs:
RepositoryUrl:
Description: URL of the created repository
Value: !GetAtt TriggerLambda.repository_url
PullRequestUrl:
Description: URL of the configuration pull request
Value: !GetAtt TriggerLambda.pull_request_url
```
### Option B: EventBridge Pattern (Already configured!)
The EventBridge rule created in Step 3 already listens for Service Catalog events. Simply:
1. Create a CloudFormation template that provisions **any** resource
2. Add your parameters (project_name, owning_team, etc.)
3. When Service Catalog provisions this product, it emits an event
4. Your EventBridge rule catches it and triggers the Lambda
**Simple CloudFormation for this:**
```yaml
AWSTemplateFormatVersion: '2010-09-09'
Description: 'Trigger repository creation via Service Catalog'

Parameters:
ProjectName:
Type: String
Description: Name of the repository to create
OwningTeam:
Type: String
Description: GitHub team that should own the repository
Default: tf-module-admins

Resources:
# This is just a placeholder - the real work is done by the Lambda
DummyParameter:
Type: AWS::SSM::Parameter
Properties:
Name: !Sub '/service-catalog/repositories/${ProjectName}'
Type: String
Value: !Ref ProjectName
Description: !Sub 'Service Catalog provisioned repository: ${ProjectName}'

Outputs:
Message:
Value: !Sub 'Repository creation triggered for ${ProjectName}. Check GitHub/Lambda logs for details.'
# Add any other parameters you need
```

## Step 5: Test the Integration

### Manual Lambda Test

```bash
# Invoke Lambda directly with a test event
# Invoke Lambda directly with a Custom Resource test event
aws lambda invoke \
--function-name service-catalog-repo-gen-template-automation \
--payload file://events/service-catalog-event.json \
--payload file://events/cloudformation-create-event.json \
--region us-gov-west-1 \
response.json

Expand All @@ -206,10 +143,9 @@ cat response.json
### Service Catalog Test

1. Go to AWS Service Catalog console
2. Create a portfolio and add your product
3. Provision the product with test parameters
4. Watch CloudWatch Logs for the Lambda execution
5. Check GitHub for the new repository
2. Provision the product you created in Step 4
3. Wait for the stack to complete (the Lambda runs synchronously)
4. Check the "Outputs" tab of the provisioned product for the Repository URL.

## Monitoring and Troubleshooting

Expand All @@ -222,43 +158,13 @@ aws logs tail /aws/lambda/service-catalog-repo-gen-template-automation \
--region us-gov-west-1
```

### Verify EventBridge Rule
### Response Handling

```bash
# Check if the rule is enabled
aws events describe-rule \
--name service-catalog-repo-provisioning \
--region us-gov-west-1
```
The Lambda must send a response back to CloudFormation (using the pre-signed URL in the event) for the stack to proceed. If the Lambda times out or crashes before sending a response, the stack will hang until the timeout (usually 1 hour).

### Test Event Pattern

```bash
# Send a test event to EventBridge
aws events put-events \
--entries file://test-event.json \
--region us-gov-west-1
```

## Updating the Lambda

When you make code changes:

```bash
# 1. Rebuild the container
cd /home/a/arnol377/git/lambda-template-repo-generator
packer-pipeline build --config config_packer.hcl

# 2. Update Lambda to use the new image
cd deploy
terraform apply -target=module.service_catalog_repo_generator.aws_lambda_function.this

# Or force Lambda to pull the latest image
aws lambda update-function-code \
--function-name service-catalog-repo-gen-template-automation \
--image-uri 229685449397.dkr.ecr.us-gov-west-1.amazonaws.com/service-catalog-repo-generator/lambda:latest \
--region us-gov-west-1
```
If your stack is stuck:
1. Check Lambda logs for errors
2. Manually signal failure if needed using `curl` to the ResponseURL found in the CloudWatch logs.

## Architecture Diagram

Expand All @@ -267,22 +173,20 @@ User → Service Catalog UI
↓
Provisions Product
↓
CloudFormation runs
CloudFormation Stack Creates
↓
EventBridge emits event
Custom Resource Invokes Lambda
↓
Lambda Function triggered
Lambda Creates GitHub Repository
↓
Creates GitHub Repository
Lambda Responds SUCCESS to CloudFormation
↓
Writes config.json
↓
Opens Pull Request
Stack Completes with Outputs
```

## Next Steps

1. Create Service Catalog portfolio and products
2. Set up proper IAM permissions for users to provision products
3. Configure SNS notifications for repository creation
4. Add additional template repositories for different project types
3. Add constraints to Service Catalog product versions

0 comments on commit 83a0b96

Please sign in to comment.