# AWS CodeBuild

AWS CodeBuild provides managed Docker environments with excellent container support, making it perfect for KushoAI testing in AWS-native CI/CD pipelines.

## Prerequisites

1. **AWS Account**: Active AWS account with CodeBuild access
2. **IAM Permissions**: Appropriate permissions for CodeBuild and ECR access
3. **Docker Environment**: CodeBuild provides managed Docker environments
4. **Parameter Store** (recommended): For secure credential management

## Docker Image

All execution uses the Kusho test runner Docker image:
```
public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
```

## Setup Instructions

### 1. Create buildspec.yml

Create a `buildspec.yml` file in your repository root:

### 2. Basic Build Configuration

```yaml
version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2

phases:
  pre_build:
    commands:
      - echo "Starting Kusho API tests..."
      - echo "Build started on `date`"
      - echo "Git commit SHA: $CODEBUILD_RESOLVED_SOURCE_VERSION"

  build:
    commands:
      - echo "Running Kusho test suite..."
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e TEST_SUITE_UUID="$TEST_SUITE_UUID" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

  post_build:
    commands:
      - echo "Build completed on `date`"
      - echo "Test execution finished"
```

### 3. Configure AWS Systems Manager Parameter Store

Store your sensitive data in Parameter Store:

```bash
# Create secure string parameter
aws ssm put-parameter \
    --name "/kusho/api-key" \
    --value "your-kusho-api-key" \
    --type "SecureString" \
    --description "Kusho API key for CI/CD testing"
```

### 4. Create CodeBuild Project

Using AWS CLI:
```bash
aws codebuild create-project \
    --name "kusho-api-tests" \
    --source type=GITHUB,location=https://github.com/your-org/your-repo \
    --artifacts type=NO_ARTIFACTS \
    --environment type=LINUX_CONTAINER,image=aws/codebuild/amazonlinux2-x86_64-standard:3.0,computeType=BUILD_GENERAL1_MEDIUM \
    --service-role arn:aws:iam::account:role/service-role/codebuild-service-role
```

## Execution Methods

### 1. Execute by Test Suite UUID

```yaml
version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2
    TEST_SUITE_UUID: "uuid1,uuid2,uuid3"

phases:
  build:
    commands:
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e TEST_SUITE_UUID="$TEST_SUITE_UUID" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
```

### 2. Execute by Group ID

```yaml
version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2
    GROUP_ID: 87

phases:
  build:
    commands:
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e GROUP_ID="$GROUP_ID" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
```

### 3. Execute by Tags

```yaml
version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2
    TEST_TAGS: "smoke,regression"

phases:
  build:
    commands:
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e TAGS="$TEST_TAGS" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
```

### 4. Execute E2E Workflows by UUID

```yaml
version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2
    E2E_TEST_SUITE_UUID: "e5d1b703-a798-4bd9-becb-8977bc2a1ec3"
    EXECUTION_PROFILE_UUID: "profile-uuid-here"

phases:
  build:
    commands:
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e E2E_TEST_SUITE_UUID="$E2E_TEST_SUITE_UUID" \
          -e EXECUTION_PROFILE_UUID="$EXECUTION_PROFILE_UUID" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
```

### 5. Execute E2E Workflows by Tags

```yaml
version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    ENVIRONMENT_ID: 2
    E2E_TEST_SUITE_TAGS: "smoke,critical"
    E2E_PROFILE_TAGS: "fast,regression"

phases:
  build:
    commands:
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e E2E_TEST_SUITE_TAGS="$E2E_TEST_SUITE_TAGS" \
          -e E2E_PROFILE_TAGS="$E2E_PROFILE_TAGS" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
```

## Complete Pipeline Examples

### Multi-Phase Testing Pipeline

```yaml
version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
  variables:
    BASE_URL: https://be.kusho.ai
    STAGING_ENV_ID: 2
    PRODUCTION_ENV_ID: 1

phases:
  pre_build:
    commands:
      - echo "Logging in to Amazon ECR..."
      - echo "Build started on `date`"
      - echo "Testing commit $CODEBUILD_RESOLVED_SOURCE_VERSION"

  build:
    commands:
      - echo "Running smoke tests on staging..."
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$STAGING_ENV_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="Smoke tests for commit $CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e TAGS="smoke" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
      
      - echo "Running integration tests on staging..."
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$STAGING_ENV_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="Integration tests for commit $CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e TAGS="integration" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest

  post_build:
    commands:
      - |
        if [ "$CODEBUILD_WEBHOOK_HEAD_REF" = "refs/heads/main" ]; then
          echo "Running production smoke tests..."
          docker run --rm \
            -e BASE_URL="$BASE_URL" \
            -e ENVIRONMENT_ID="$PRODUCTION_ENV_ID" \
            -e API_KEY="$KUSHO_API_KEY" \
            -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
            -e CI_COMMIT_MESSAGE="Production tests for commit $CODEBUILD_RESOLVED_SOURCE_VERSION" \
            -e TAGS="smoke" \
            public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
        else
          echo "Skipping production tests - not main branch"
        fi
      - echo "Build completed on `date`"
```

### Environment-Specific Pipeline

```yaml
version: 0.2

env:
  parameter-store:
    KUSHO_API_KEY: /kusho/api-key
    STAGING_TEST_SUITE_UUID: /kusho/staging/test-suite-uuid
    PRODUCTION_TEST_SUITE_UUID: /kusho/production/test-suite-uuid
  variables:
    BASE_URL: https://be.kusho.ai

phases:
  pre_build:
    commands:
      - |
        if [ "$CODEBUILD_WEBHOOK_HEAD_REF" = "refs/heads/main" ]; then
          export TARGET_ENV="production"
          export ENVIRONMENT_ID="1"
          export TEST_SUITE_UUID="$PRODUCTION_TEST_SUITE_UUID"
        else
          export TARGET_ENV="staging"
          export ENVIRONMENT_ID="2" 
          export TEST_SUITE_UUID="$STAGING_TEST_SUITE_UUID"
        fi
      - echo "Targeting $TARGET_ENV environment"

  build:
    commands:
      - echo "Running tests against $TARGET_ENV..."
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$TARGET_ENV tests for $CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e TEST_SUITE_UUID="$TEST_SUITE_UUID" \
          public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
```

## AWS CodeBuild Features

### Built-in Environment Variables

CodeBuild provides several useful environment variables:
- `$CODEBUILD_RESOLVED_SOURCE_VERSION` - Git commit SHA
- `$CODEBUILD_WEBHOOK_HEAD_REF` - Git branch reference
- `$CODEBUILD_PROJECT_NAME` - CodeBuild project name
- `$CODEBUILD_BUILD_NUMBER` - Build number
- `$CODEBUILD_START_TIME` - Build start time

### Build Phases

CodeBuild supports multiple phases for organized execution:
- `install` - Install runtime dependencies
- `pre_build` - Pre-build setup commands
- `build` - Main build commands
- `post_build` - Post-build cleanup and notifications

### Conditional Execution

```yaml
phases:
  build:
    commands:
      - |
        if [ "$CODEBUILD_WEBHOOK_HEAD_REF" = "refs/heads/main" ]; then
          echo "Running production tests..."
          # Production test commands
        elif [[ "$CODEBUILD_WEBHOOK_HEAD_REF" == *"feature/"* ]]; then
          echo "Running feature branch tests..."
          # Feature branch test commands
        else
          echo "Running standard tests..."
          # Standard test commands
        fi
```

## AWS-Specific Integrations

### ECR Image Caching

```yaml
version: 0.2

env:
  variables:
    AWS_DEFAULT_REGION: us-east-1
    AWS_ACCOUNT_ID: 123456789012
    IMAGE_REPO_NAME: kusho-test-runner
    IMAGE_TAG: latest

phases:
  pre_build:
    commands:
      - echo "Logging in to Amazon ECR..."
      - aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com
      
      - echo "Checking if image exists in ECR..."
      - |
        if aws ecr describe-images --repository-name $IMAGE_REPO_NAME --image-ids imageTag=$IMAGE_TAG >/dev/null 2>&1; then
          echo "Using cached image from ECR"
          export DOCKER_IMAGE="$AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG"
        else
          echo "Pulling and caching image"
          docker pull public.ecr.aws/y5g4u6y7/kusho-test-runner:latest
          docker tag public.ecr.aws/y5g4u6y7/kusho-test-runner:latest $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
          docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG
          export DOCKER_IMAGE="$AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG"
        fi

  build:
    commands:
      - echo "Running tests with image: $DOCKER_IMAGE"
      - |
        docker run --rm \
          -e BASE_URL="$BASE_URL" \
          -e ENVIRONMENT_ID="$ENVIRONMENT_ID" \
          -e API_KEY="$KUSHO_API_KEY" \
          -e CI_COMMIT_SHA="$CODEBUILD_RESOLVED_SOURCE_VERSION" \
          -e CI_COMMIT_MESSAGE="$CODEBUILD_WEBHOOK_HEAD_REF" \
          -e TEST_SUITE_UUID="$TEST_SUITE_UUID" \
          $DOCKER_IMAGE
```

### SNS Notifications

```yaml
version: 0.2

env:
  variables:
    SNS_TOPIC_ARN: arn:aws:sns:us-east-1:123456789012:kusho-test-notifications

phases:
  post_build:
    commands:
      - |
        if [ $CODEBUILD_BUILD_SUCCEEDING -eq 1 ]; then
          SUBJECT="✅ Kusho Tests Passed - Build $CODEBUILD_BUILD_NUMBER"
          MESSAGE="All Kusho API tests passed successfully for commit $CODEBUILD_RESOLVED_SOURCE_VERSION"
        else
          SUBJECT="❌ Kusho Tests Failed - Build $CODEBUILD_BUILD_NUMBER"
          MESSAGE="Kusho API tests failed for commit $CODEBUILD_RESOLVED_SOURCE_VERSION. Check build logs for details."
        fi
      - |
        aws sns publish \
          --topic-arn $SNS_TOPIC_ARN \
          --subject "$SUBJECT" \
          --message "$MESSAGE"
```

### CloudWatch Metrics

```yaml
phases:
  post_build:
    commands:
      - |
        aws cloudwatch put-metric-data \
          --namespace "Kusho/Tests" \
          --metric-data MetricName=TestExecution,Value=1,Unit=Count,Dimensions=Project=$CODEBUILD_PROJECT_NAME,Status=$([[ $CODEBUILD_BUILD_SUCCEEDING -eq 1 ]] && echo "Success" || echo "Failure")
```

## Integration with AWS CodePipeline

### Pipeline Configuration

Create a CodePipeline that includes CodeBuild:

```json
{
  "pipeline": {
    "name": "kusho-testing-pipeline",
    "stages": [
      {
        "name": "Source",
        "actions": [
          {
            "name": "SourceAction",
            "actionTypeId": {
              "category": "Source",
              "owner": "AWS",
              "provider": "GitHub",
              "version": "1"
            },
            "configuration": {
              "Owner": "your-github-org",
              "Repo": "your-repo",
              "Branch": "main",
              "OAuthToken": ""
            },
            "outputArtifacts": [{"name": "SourceOutput"}]
          }
        ]
      },
      {
        "name": "Test",
        "actions": [
          {
            "name": "KushoTests",
            "actionTypeId": {
              "category": "Build",
              "owner": "AWS",
              "provider": "CodeBuild",
              "version": "1"
            },
            "configuration": {
              "ProjectName": "kusho-api-tests"
            },
            "inputArtifacts": [{"name": "SourceOutput"}]
          }
        ]
      }
    ]
  }
}
```

## Best Practices

### Security
- Use Parameter Store or Secrets Manager for sensitive data
- Implement least-privilege IAM policies
- Enable CloudTrail for audit logging

### Performance
- Use ECR for image caching to reduce build times
- Choose appropriate compute types for your workload
- Implement build caching strategies

### Cost Optimization
- Use spot instances for non-critical builds
- Implement build timeouts to prevent runaway costs
- Monitor build metrics and optimize resource usage

### Organization
- Use consistent naming conventions for projects
- Implement build templates for reusability
- Use environment variables for configuration

## Troubleshooting

### Common Issues

1. **IAM Permission Issues**
   - Ensure CodeBuild service role has necessary permissions
   - Verify Parameter Store read permissions
   - Check ECR pull permissions

2. **Docker Pull Issues**
   - Verify network connectivity to ECR registry
   - Check VPC configuration if using VPC mode
   - Ensure adequate disk space for Docker images

3. **Environment Variable Issues**
   - Verify Parameter Store parameter names and paths
   - Check parameter permissions and encryption
   - Ensure proper variable naming conventions

### Debug Commands

```yaml
phases:
  pre_build:
    commands:
      - echo "Debug Information:"
      - echo "Build ID: $CODEBUILD_BUILD_ID"
      - echo "Project Name: $CODEBUILD_PROJECT_NAME"
      - echo "Source Version: $CODEBUILD_RESOLVED_SOURCE_VERSION"
      - echo "Webhook Head Ref: $CODEBUILD_WEBHOOK_HEAD_REF"
      - docker --version
      - aws --version
      - env | grep CODEBUILD | sort
```

### CloudWatch Logs

Enable detailed logging in your CodeBuild project configuration:
- CloudWatch Logs: Enabled
- Log Group Name: `/aws/codebuild/kusho-api-tests`
- Stream Name Prefix: `build-logs`

Monitor logs for:
- Docker pull progress
- Test execution output
- Error messages and stack traces
- Build phase timing information