(aws-codebuild)(pipelines) DockerServer property dropped when using _build_env in CDK Pipelines CodeBuild projects #35562
Description
Describe the bug
When using BuildEnvironment with a DockerServer property in standalone CodeBuild projects, the generated CloudFormation template correctly includes the DockerServer configuration.
However, when the same build_environment is passed into a CDK Pipelines build step, the DockerServer property is silently dropped during synthesis. This results in missing configuration in the generated template and causes deployments to fail when attempting to use DockerServer in pipeline-managed CodeBuild projects.
Regression Issue
- Select this option if this issue appears to be a regression.
Last Known Working CDK Library Version
No response
Expected Behavior
Create a docker server for CodeBuild project in CDK pipelines.
Current Behavior
Docker server properties are silently dropped and not included in the synthesized template.
Reproduction Steps
The following works as expected:
build_env = codebuild.BuildEnvironment(
build_image=codebuild.LinuxArmBuildImage.from_ecr_repository(
repository=code_pipeline_repo,
tag_or_digest=asset_hash,
),
compute_type=compute_type,
docker_server=codebuild.DockerServerOptions(
compute_type=codebuild.DockerServerComputeType.MEDIUM,
security_groups=[custom_default_security_group],
),
privileged=True,
build_project = codebuild.Project(
self,
"BuildProject",
build_spec=codebuild.BuildSpec.from_object(
{
"version": "0.2",
"phases": {
"build": {"commands": ["cd sample", "'docker buildx build .'"]}
},
}
),
environment=build_env,
)generates correct Cfn:
"Environment": {
"ComputeType": "BUILD_GENERAL1_SMALL",
"DockerServer": {
"ComputeType": "BUILD_GENERAL1_MEDIUM",
"SecurityGroupIds": ["sg-XXXXX"]
}
}However, when used with CDK pipelines and CodeBuildStep (or similar), this DockerServer is missing from the generated CloudFormation template.
Possible Solution
In standalone projects, the renderEnvironment method [2] correctly includes dockerServer when present.
In CDK Pipelines, the mergeBuildEnvironments function [3] only preserves a subset of properties (buildImage, computeType, environmentVariables, and privileged). All other environment properties, including dockerServer, are discarded.
Workaround is to use Aspects:
from aws_cdk import Aspects, IAspect
import jsii
@jsii.implements(IAspect)
class DockerServerAspect:
def __init__(self, build_step, docker_server_config):
self.build_step = f"/Pipeline/Build/{build_step}/CdkBuildProject/Resource"
self.docker_server_config = docker_server_config
def visit(self, node: IConstruct) -> None:
if self.build_step in node.node.path and isinstance(node, codebuild.CfnProject):
docker_compute_map = {
"SMALL": "BUILD_GENERAL1_SMALL",
"MEDIUM": "BUILD_GENERAL1_MEDIUM",
"LARGE": "BUILD_GENERAL1_LARGE",
}
compute_type_value = docker_compute_map.get(
self.docker_server_config.compute_type._name_, "BUILD_GENERAL1_MEDIUM"
)
node.add_property_override(
"Environment.DockerServer",
{
"ComputeType": compute_type_value,
"SecurityGroupIds": [
sg.security_group_id
for sg in self.docker_server_config.security_groups
],
},
)
# Apply aspect
Aspects.of(self).add(DockerServerAspect("Synth", self._build_env.docker_server))Additional Information/Context
References
1. AWS CDK CodeBuild Project
2. renderEnvironment in project.ts
3. mergeBuildEnvironments in codebuild-factory.ts
4. Aspects in AWS CDK
5. Accelerate CI/CD pipelines with the new AWS CodeBuild Docker Server capability
AWS CDK Library version (aws-cdk-lib)
2.216.0
AWS CDK CLI version
2.1029.2
Node.js Version
v22.15.1
OS
MacOS
Language
Python
Language Version
3.12.8
Other information
No response