CDK Pipeline Construct

A comprehensive AWS CDK construct for creating automated CI/CD pipelines with AWS CodePipeline. This construct supports multiple deployment targets including AWS Fargate, S3 static sites, and generic applications.

Features

• Multi-Source Support: Connect application and infrastructure repositories separately
• Flexible Pipeline Types: Support for Fargate containers, S3 static sites, and generic deployments
• Automated IAM Management: Automatically creates and configures necessary IAM roles
• Secure Artifact Storage: S3 bucket with encryption for pipeline artifacts
• ECR Integration: Optional ECR repository creation for container-based pipelines
• Customizable Build Stages: Flexible build and deploy configurations

Installation

npm install @blend-col/cdk-pipeline-construct-double-rep

Quick Start

Basic Usage

import { PipelineConstruct } from '@blend-col/cdk-pipeline-construct-double-rep';
import { Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';

export class MyPipelineStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    new PipelineConstruct(this, 'MyPipeline', {
      namespace: 'my-app',
      appSourceConfig: {
        owner: 'my-org',
        repo: 'my-app',
        branch: 'main',
        connectionArn: 'arn:aws:codestar-connections:region:account:connection/connection-id'
      },
      infraSourceConfig: {
        owner: 'my-org',
        repo: 'my-infrastructure',
        branch: 'main',
        connectionArn: 'arn:aws:codestar-connections:region:account:connection/connection-id'
      }
    });
  }
}

Pipeline Types

1. Fargate Pipeline

For containerized applications deployed to AWS Fargate:

new PipelineConstruct(this, 'FargatePipeline', {
  namespace: 'my-fargate-app',
  pipelineType: 'fargate',
  ecrRepositoryName: 'my-app-repo', // Creates new ECR repository
  appSourceConfig: {
    owner: 'my-org',
    repo: 'my-app',
    branch: 'main',
    connectionArn: 'arn:aws:codestar-connections:region:account:connection/connection-id'
  },
  infraSourceConfig: {
    owner: 'my-org',
    repo: 'my-infrastructure',
    branch: 'main',
    connectionArn: 'arn:aws:codestar-connections:region:account:connection/connection-id'
  },
  buildConfig: {
    privileged: true, // Required for Docker builds
    environmentVariables: {
      AWS_DEFAULT_REGION: { value: 'us-east-1' },
      AWS_ACCOUNT_ID: { value: '123456789012' }
    }
  }
});

2. S3 Static Site Pipeline

For static websites deployed to S3:

new PipelineConstruct(this, 'StaticSitePipeline', {
  namespace: 'my-static-site',
  pipelineType: 's3Static',
  appSourceConfig: {
    owner: 'my-org',
    repo: 'my-static-site',
    branch: 'main',
    connectionArn: 'arn:aws:codestar-connections:region:account:connection/connection-id'
  },
  infraSourceConfig: {
    owner: 'my-org',
    repo: 'my-infrastructure',
    branch: 'main',
    connectionArn: 'arn:aws:codestar-connections:region:account:connection/connection-id'
  },
  buildConfig: {
    buildSpec: {
      version: '0.2',
      phases: {
        install: {
          'runtime-versions': {
            nodejs: '18'
          }
        },
        pre_build: {
          commands: ['npm ci']
        },
        build: {
          commands: ['npm run build']
        }
      },
      artifacts: {
        files: ['**/*'],
        'base-directory': 'dist'
      }
    }
  }
});

3. Generic Pipeline

For general-purpose applications:

new PipelineConstruct(this, 'GenericPipeline', {
  namespace: 'my-generic-app',
  pipelineType: 'generic',
  appSourceConfig: {
    owner: 'my-org',
    repo: 'my-app',
    branch: 'main',
    connectionArn: 'arn:aws:codestar-connections:region:account:connection/connection-id'
  },
  infraSourceConfig: {
    owner: 'my-org',
    repo: 'my-infrastructure',
    branch: 'main',
    connectionArn: 'arn:aws:codestar-connections:region:account:connection/connection-id'
  }
});

Configuration Reference

Required Properties

namespace

• Type: string
• Description: Prefix for all resources created by the construct

appSourceConfig

Configuration for the application source repository:

interface AppSourceConfig {
  owner: string;              // GitHub repository owner
  repo: string;               // Repository name
  branch: string;             // Branch to monitor
  connectionArn: string;      // CodeStar connection ARN
  triggerOnPush?: boolean;    // Enable automatic triggering (default: true)
}

infraSourceConfig

Configuration for the infrastructure source repository:

interface InfraSourceConfig {
  owner: string;              // GitHub repository owner
  repo: string;               // Repository name
  branch: string;             // Branch to monitor
  connectionArn: string;      // CodeStar connection ARN
  triggerOnPush?: boolean;    // Enable automatic triggering (default: true)
}

Optional Properties

pipelineType

• Type: 'fargate' | 's3Static' | 'generic'
• Default: 'generic'
• Description: Type of pipeline to create

pipelineName

• Type: string
• Default: Uses namespace value
• Description: Custom name for the pipeline

ecrRepository

• Type: ecr.IRepository
• Description: Existing ECR repository (for Fargate pipelines)

ecrRepositoryName

• Type: string
• Description: Name for new ECR repository (for Fargate pipelines)

buildConfig

Configuration for the build stage:

interface BuildConfig {
  buildSpec?: any;                           // Custom BuildSpec
  environmentVariables?: { [key: string]: BuildEnvironmentVariable };
  computeImage?: IBuildImage;                // Build environment image
  computeType?: ComputeType;                 // Compute type
  privileged?: boolean;                      // Privileged mode (for Docker)
}

deployConfig

Configuration for the deploy stage:

interface DeployConfig {
  buildSpec?: any;                           // Custom BuildSpec for deploy
  environmentVariables?: { [key: string]: BuildEnvironmentVariable };
  computeImage?: IBuildImage;                // Deploy environment image
  computeType?: ComputeType;                 // Compute type
  privileged?: boolean;                      // Privileged mode
}

artifactBucketConfig

Configuration for the artifact storage bucket:

interface ArtifactBucketConfig {
  bucket?: IBucket;                          // Existing bucket
  bucketName?: string;                       // Name for new bucket
  removalPolicy?: RemovalPolicy;             // Removal policy
  encryption?: boolean;                      // Enable encryption (default: true)
}

tags

• Type: { [key: string]: string }
• Description: Tags to apply to all resources

Advanced Usage

Custom Build Specifications

const customBuildSpec = {
  version: '0.2',
  phases: {
    install: {
      'runtime-versions': {
        nodejs: '18',
        docker: '20'
      }
    },
    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'
      ]
    },
    build: {
      commands: [
        'echo Build started on `date`',
        'echo Building the Docker image...',
        'docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG .',
        'docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG'
      ]
    },
    post_build: {
      commands: [
        'echo Build completed on `date`',
        'echo Pushing the Docker image...',
        'docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG'
      ]
    }
  }
};

new PipelineConstruct(this, 'CustomBuildPipeline', {
  namespace: 'my-custom-app',
  pipelineType: 'fargate',
  ecrRepositoryName: 'my-app',
  buildConfig: {
    buildSpec: customBuildSpec,
    privileged: true,
    environmentVariables: {
      IMAGE_REPO_NAME: { value: 'my-app' },
      IMAGE_TAG: { value: 'latest' }
    }
  },
  // ... other configuration
});

Using Existing Resources

import { Repository } from 'aws-cdk-lib/aws-ecr';
import { Bucket } from 'aws-cdk-lib/aws-s3';

// Use existing ECR repository
const existingRepo = Repository.fromRepositoryName(this, 'ExistingRepo', 'my-existing-repo');

// Use existing S3 bucket
const existingBucket = Bucket.fromBucketName(this, 'ExistingBucket', 'my-existing-bucket');

new PipelineConstruct(this, 'ExistingResourcesPipeline', {
  namespace: 'my-app',
  pipelineType: 'fargate',
  ecrRepository: existingRepo,
  artifactBucketConfig: {
    bucket: existingBucket
  },
  // ... other configuration
});

Prerequisites

1. AWS CDK: Ensure you have AWS CDK installed and configured
2. CodeStar Connections: Create CodeStar connections for your GitHub repositories
3. IAM Permissions: Ensure your deployment role has necessary permissions for CodePipeline, CodeBuild, ECR, and S3

Setting Up CodeStar Connections

1. Go to the AWS CodePipeline console
2. Navigate to "Settings" � "Connections"
3. Create a new connection to GitHub
4. Complete the authorization flow
5. Use the connection ARN in your construct configuration

Examples

Check the examples/ directory for complete working examples of different pipeline types and configurations.

Contributing

This construct is maintained by Blend Colombia. For issues and contributions, please refer to the repository guidelines.

License

This project is licensed under the MIT License.