klug-builds

CLI tool for building and deploying Lambda functions via the KLUG Builds API.

Installation

pip install klug-builds

Configuration

Set the API endpoint (optional, defaults to production):

export KLUG_BUILDS_API_ENDPOINT=https://your-api-endpoint.com/prod

For cross-account deployments, you can set:

export KLUG_BUILDS_TARGET_ROLE_ARN=arn:aws:iam::TARGET_ACCOUNT:role/role-name
export KLUG_BUILDS_TARGET_REGION=eu-west-3

Usage

Build and Deploy

Build and deploy Lambda functions from API and layers directories:

klug-builds build api/ layers/ --system main --env dev

With cross-account deployment:

klug-builds build api/ layers/ \
    --system main \
    --env dev \
    --account-id 123456789012 \
    --target-role-arn arn:aws:iam::123456789012:role/klug-builds-role \
    --target-region eu-west-3

List Builds

List all builds:

klug-builds list

Filter by system and environment:

klug-builds list --system main --env dev

Get Build Status

Get status of a specific build:

klug-builds status <build-id>

Setup Cross-Account Role

Create an IAM role in a target AWS account for cross-account deployments. The role allows the klug-autocloud account (372315927986) to assume it and deploy resources.

klug-builds setup-role \
    --target-account-id 987654321098 \
    --profile target-account-profile

The role name defaults to klug-builds-role if not specified. You can customize it:

klug-builds setup-role \
    --role-name my-custom-role \
    --target-account-id 987654321098

What it does:

• Creates an IAM role in the target account with all necessary permissions
• Allows the klug-autocloud account (372315927986) to assume the role
• Includes permissions for:
  • Lambda: Create, update, delete functions and layers
  • API Gateway: Create, update, deploy APIs
  • S3: Read/write for code storage
  • IAM: Pass role for Lambda execution
  • CloudWatch Logs: Create log groups and streams

Commands

build

Build and deploy Lambda functions.

Arguments:

• api_path: Path to API code directory
• layers_path: Path to layers code directory

Options:

• --system: System ID (required)
• --env: Environment name (required)
• --account-id: Target AWS account ID (optional)
• --target-role-arn: ARN of IAM role to assume in target account (optional)
• --target-region: AWS region for target account (optional)

Example:

klug-builds build api/ layers/ --system main --env dev

list

List all builds with optional filtering.

Options:

• --system: Filter by system ID
• --env: Filter by environment name
• --account-id: Filter by account ID

Example:

klug-builds list --system main --env dev

status

Get detailed status of a specific build.

Arguments:

• build_id: Build ID to query

Example:

klug-builds status abc123-def456-ghi789

setup-role

Create IAM role in target AWS account for cross-account deployments.

Options:

• --role-name: Name of the IAM role to create (default: klug-builds-role)
• --target-account-id: Target AWS account ID (required)
• --profile: AWS profile for target account (optional, will prompt for credentials if not provided)
• --region: AWS region for target account (default: eu-west-3)

Example:

klug-builds setup-role \
    --role-name klug-builds-deployment-role \
    --target-account-id 987654321098 \
    --build-service-profile build-service \
    --profile target-account

Build Process

The build process follows these steps:

1. Step 1: Check 3rd party layer → invoke Docker Lambda
2. Step 2: Check main layer → upload to S3, invoke ZIP Lambda if needed
3. Step 3: Lambda Functions:
   • 3.1: Create missing functions
   • 3.2: Delete unused functions
   • 3.3-3.5: Update existing functions (code, config, layers)
4. Step 4: API Gateway → invoke ZIP Lambda
5. Step 5: Add permissions → direct calls

All operations are idempotent and atomic.

Requirements

• Python 3.8+
• AWS credentials configured (for cross-account role setup)
• Access to KLUG Builds API

License

MIT