aws4embeddedlinux-ci

This cdk IaC library helps you to deploy AWS cloud infrastructure to allow embedded Linux builds for your project.

Architecture

API documentation

API documentation generated by npm run doc

Setting Up

In order to use this library, you must set up the CDK, including installing the CDK tool and bootstrapping the account you wish to deploy to. Additionally, you must have Node installed.

Note

This library is tested against Node Versions 16, 18, and 20. If these versions are not available for your system, we recommend using NVM to install a compatible version

Quickstart

Use the examples in our examples repo.

Setting Up A New Project

1. Create a CDK project. More details can be found in the CDK Getting Started Documentation.

   mkdir my-project
   cd my-project
   cdk init app --language typescript
   

2. Add the cdk library with npm install aws4embeddedlinux/aws4embeddedlinux-ci.
3. Create your application using the library. Refer to the API Documentation and the Examples for more details.
4. Deploy your application using cdk deploy.
5. After the application is deployed, the 'Build Image' Pipeline needs to be run. This will create an Ubuntu based container for building Yocto. This container is used by the other pipelines. If the other pipelines are run before this container is created and pushed to ECR, they will fail. This Build Image Pipeline will run weekly by default to keep this container patched.
6. Now the application pipeline can be run. This will push the contents of the Yocto deploy directory into S3.

Viewing Changes

The cdk diff command can be used to preview changes before deployment. This will allow the user to review what is being created.

Development Setup

You can use npm link to develop with a local copy of this repo.

In this library repo:

npm install

In your-project folder:

npm install
npm link ../aws4embeddedlinux-ci

This will link through the system node_modules install. When using a system node install on Linux, this can require sudo access. To avoid this, use a node version manager or set a node prefix.

Known issues

• Windows is currently not supported.
• When using AWS Cloud9 a micro instance type will run out of memory.
• Deletion of stacks while a CodePipeline is running can lead to unexpected failures.

Security

See SECURITY for more information about reporting issues with this project.

Git Credentials and Build Time Secrets

AWS Secrets Manager is the preferred method of adding secrets to your pipeline. This service provides a structured means of access and avoids the pitfalls of putting secrets in environment variables, source repos, etc.

1. Create a Secret in Secrets Manager and add your secret value.
2. Grant access permissions to the CodeBuild pipeline project.
3. Create a Policy Statement which allows secretsmanager:GetSecretValue for your secret.
4. Add this policy statement to the buildPolicyAdditions props for the EmbeddedLinuxPipelineStack. e.g.

import * as iam from "aws-cdk-lib/aws-iam";

const pipeline = new EmbeddedLinuxPipelineStack(app, "MyPokyPipeline", {
  imageRepo: buildImageRepo.repository,
  imageTag: ImageKind.Ubuntu22_04,
  vpc: vpc.vpc,
  buildPolicyAdditions: [
    iam.PolicyStatement.fromJson({
      Effect: "Allow",
      Action: "secretsmanager:GetSecretValue",
      Resource:
        "arn:aws:secretsmanager:us-west-2:123456789012:secret:my-secret-??????",
    }),
  ],
});

The secret can then be used in the CodeBuild Project by adding it to the BuildSpec. See the CodeBuild Documentation for more details.

env:
    secrets-manager:
        SECRET_VALUE: "<Secret ARN>"

CVE Checking With Yocto

CVE checking is enabled in the reference implementations. Details on this can be found in the yocto documentation.

Contributing

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.