> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# What is Buildspecyaml file
> Explains using a buildspec.yml for AWS CodeBuild to build and push Docker images to Amazon ECR, covering phases, env variables, privileged mode, and IAM requirements.
Well, now that we have set up our ECR repository, how do we actually build a Docker image programmatically? CodeBuild runs the build for us, but you need a build specification to tell CodeBuild which steps to execute.
When building a Docker image locally, you run commands in a terminal. For automated builds with AWS CodeBuild, you define those steps in a build specification file named `buildspec.yml` (or `buildspec.yaml`). This YAML file describes the lifecycle of the build and the commands to run in each phase.
Recommendation: Use the `buildspec.yml` filename (lowercase `.yml`) for consistency; `.yaml` is functionally equivalent.
Below is a typical `buildspec.yml` for building a Docker image and pushing it to Amazon ECR. The file is organized into sections: `version`, `env > variables`, and `phases` (including `pre_build`, `build`, and `post_build`).
```yaml theme={null}
version: 0.2
env:
variables:
IMAGE_REPO_NAME: ""
IMAGE_TAG: ""
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
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
```
Summary of the main `buildspec.yml` sections:
| Section | Purpose | Example / Notes |
| ----------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `version` | Declares the buildspec schema version. | `0.2` is current and recommended. |
| `env > variables` | Define static environment variables available during the build. | Replace placeholders like `""` and `""` with your values. |
| `phases` | Breaks the build into lifecycle stages: `pre_build`, `build`, and `post_build`. | Customize these phases for your language or workflow. |
Phases explained:
* pre\_build: Preparation tasks such as authenticating to ECR, installing dependencies, or setting up credentials. The example uses `aws ecr get-login-password` to log Docker in to ECR.
* build: Core build steps — for Docker this includes `docker build` and `docker tag`.
* post\_build: Finalization steps such as pushing the image to ECR, uploading artifacts to S3, or notifying CI/CD systems.
Common requirements and best practices when using Docker with CodeBuild:
* Environment variables:
* Ensure `AWS_ACCOUNT_ID` and `AWS_DEFAULT_REGION` are defined either in the CodeBuild project environment variables or replaced with literal values in the `buildspec.yml`. They are not injected automatically unless configured.
* Privileged mode:
* To execute Docker commands inside CodeBuild, enable "Privileged" mode on the build environment and use an image that includes Docker (or supports Docker-in-Docker).
* Service role permissions:
* The CodeBuild service role must include ECR permissions such as:
* `ecr:GetAuthorizationToken`
* `ecr:BatchCheckLayerAvailability`
* `ecr:PutImage`
* `ecr:InitiateLayerUpload`
* `ecr:UploadLayerPart`
* `ecr:CompleteLayerUpload`
* Add any additional permissions required by your workflow (KMS, S3, CloudWatch Logs, etc.).
Important: Without Privileged mode enabled or the appropriate service-role IAM permissions, Docker commands and pushing to ECR will fail. Verify both the build environment settings and the IAM policy before running the build.
Example variations and tips:
* For language-specific projects (Java, Node, Python), use `pre_build` to install dependencies, `build` to compile/package artifacts, and `post_build` to upload artifacts or publish releases.
* Use environment variables to parameterize repository names and tags so a single `buildspec.yml` can work across environments (dev, staging, prod).
* If you use KMS-encrypted images or private S3 artifacts, ensure the service role has access to KMS/S3 as needed.
Links and References
* [AWS CodeBuild User Guide](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html)
* [Pushing a Docker container image to Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html)
* [CodeBuild buildspec reference](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html)
With this `buildspec.yml` in your repository and a configured CodeBuild project, CodeBuild will run the defined steps and produce your Docker image in ECR automatically.
That's it for this lesson. Speak with you in the next lesson.