From a5b37e971aa4002fb79f6dde9dff2e38441dfa14 Mon Sep 17 00:00:00 2001 From: glimsdal Date: Tue, 21 Nov 2023 11:22:42 -0600 Subject: [PATCH] Readme proofreading updates. --- README.md | 73 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 43 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 095d777..de5e77d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # aws4embeddedlinux-ci -This [cdk](https://github.com/aws/aws-cdk) IaC library help you to deploy AWS cloud infrastructure to allow embedded Linux builds for your project. +This [cdk](https://github.com/aws/aws-cdk) IaC library helps you to deploy AWS cloud infrastructure to allow embedded Linux builds for your project. ## Architecture ![architecture overview](images/architecture.svg "Architecture") @@ -17,33 +17,42 @@ Use the [examples](https://github.com/aws4embeddedlinux/aws4embeddedlinux-ci-exa ## Setting Up A New Project 1. Create a CDK project. More details can be found in the [CDK Getting Started Documentation](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html). -``` -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](https://aws4embeddedlinux.github.io/aws4embeddedlinux-ci) and the [Examples](github.com/aws4embeddedlinux/aws4embeddedlinux-ci-examples) for more details. + ``` + 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](https://aws4embeddedlinux.github.io/aws4embeddedlinux-ci) + and the [Examples](github.com/aws4embeddedlinux/aws4embeddedlinux-ci-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](https://aws.amazon.com/ecr/), they will fail. This Build Image Pipeline will run weekly by default to keep this container patched. -6. Now the application pipeline is able to be run. This will push contents of the Yocto deploy directory into S3. +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](https://aws.amazon.com/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. ## Development Setup You can use [`npm link`](https://docs.npmjs.com/cli/v10/commands/npm-link) to develop with a local copy of this repo. ### In this library repo: ```bash -$ npm link -$ cd your-project +npm install +npm link ``` ### In your-project folder: ```bash -$ npm link aws4embeddedlinux-ci +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](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm#using-a-node-version-manager-to-install-nodejs-and-npm) or [set a node prefix](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). +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](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm#using-a-node-version-manager-to-install-nodejs-and-npm) +or [set a node prefix](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally). +## Known issues +- Windows is currently not supported ## Security @@ -51,24 +60,27 @@ This will link through the system `node_modules` install. When using a system no See [SECURITY](SECURITY.md) for more information about reporting issues with this project. ### Git Credentials and Build Time Secrets -[AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) is the preferred method of adding secrets to your pipeline. This service provides a structured means of access and avoids pitfalls with putting secrets in environment variables, source repos, etc. +[AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 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. 1. Grant access permissions to the CodeBuild pipeline project. -- 1. Find the IAM role for the CodeBuild Project in the CodeBuild console page under the "Build Details". This is also called the "Service Role". -- 1. In the IAM console page, add a new policy, replacing \ with the ARN of the secret created. -```json -{ - "Version": "2012-10-17", - "Statement": [ { - "Effect": "Allow", - "Action": "secretsmanager:GetSecretValue", - "Resource": "" - } ] -} -``` - -The secret can then be used in the CodeBuild Project by adding it to the BuildSpec. See the [CodeBuild Documentation](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) for more details. + 1. Find the IAM role for the CodeBuild Project in the CodeBuild console page under the "Build Details". This is also called the "Service Role". + 1. In the IAM console page, add a new policy, replacing \ with the ARN of the secret created. + ```json + { + "Version": "2012-10-17", + "Statement": [ { + "Effect": "Allow", + "Action": "secretsmanager:GetSecretValue", + "Resource": "" + } ] + } + ``` + +The secret can then be used in the CodeBuild Project by adding it to the BuildSpec. See +the [CodeBuild Documentation](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html) for more details. ```yaml env: secrets-manager: @@ -77,7 +89,8 @@ env: ### CVE Checking With Yocto -CVE checking is enabled in the reference implementations. Details for this can be found in the [yocto documentation](https://docs.yoctoproject.org/4.0.13/singleindex.html#checking-for-vulnerabilities). +CVE checking is enabled in the reference implementations. Details on this can be found in +the [yocto documentation](https://docs.yoctoproject.org/4.0.13/singleindex.html#checking-for-vulnerabilities). ## Contributing