klug-builds 1.0.2
CLI tool for building and deploying Lambda functions via KLUG Builds API
Requires Python: >=3.8
Keywords: builds, cli, lambda, aws, deployment

# klug-builds

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

## Installation

```bash
pip install klug-builds
```

## Configuration

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

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

For cross-account deployments, you can set:

```bash
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:

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

With cross-account deployment:

```bash
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:

```bash
klug-builds list
```

Filter by system and environment:

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

### Get Build Status

Get status of a specific build:

```bash
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.

```bash
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:

```bash
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:**
```bash
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:**
```bash
klug-builds list --system main --env dev
```

### `status`

Get detailed status of a specific build.

**Arguments:**
- `build_id`: Build ID to query

**Example:**
```bash
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:**
```bash
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