Skip to content

Commit c57484a

Browse files
dineshSajwandineshSajwan
authored
feat(agentcore): add agentcore runtime L2 construct (#35623)
### Issue # (if applicable) Related to aws/aws-cdk-rfcs#785 ### Reason for this change Adding bedrock agent core runtime and runtime endpoint ### Description of changes - Added a new L2 construct for runtime in aws -bedrock-agentcore-alpha package. - Added a new L2 construct for runtime endpoint - Added test cases - Added documentation ### Describe any new or updated permissions being added The runtime creates a role with permission to ecr repo, cloudwatch , xray . ### Description of how you validated changes Unit tests, integration tests, manual tests ### Checklist - [Yes] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md) ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
1 parent 6a55bda commit c57484a

File tree

47 files changed

+8564
-3
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+8564
-3
lines changed

‎packages/@aws-cdk/aws-bedrock-agentcore-alpha/README.md‎

Lines changed: 413 additions & 0 deletions
Large diffs are not rendered by default.

‎packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/index.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,16 @@
44
export * from './network/network-configuration';
55

66
// ===================================
7+
// Runtime
8+
// ===================================
9+
export * from './runtime/perms';
10+
export * from './runtime/types';
11+
export * from './runtime/runtime-base';
12+
export * from './runtime/runtime-artifact';
13+
export * from './runtime/runtime-authorizer-configuration';
14+
export * from './runtime/runtime-endpoint-base';
15+
export * from './runtime/runtime-endpoint';
16+
export * from './runtime/runtime';
717
// Tools
818
// ===================================
919
export * from './tools/code-interpreter';

‎packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/network/network-configuration.ts‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1+
/* eslint-disable @cdklabs/no-throw-default-error */
12
import * as ec2 from 'aws-cdk-lib/aws-ec2';
23
// Internal Libs
3-
import { CfnBrowserCustom, CfnCodeInterpreterCustom } from 'aws-cdk-lib/aws-bedrockagentcore';
4+
import { CfnBrowserCustom, CfnCodeInterpreterCustom, CfnRuntime } from 'aws-cdk-lib/aws-bedrockagentcore';
45
import { Construct } from 'constructs';
56

67
/**
@@ -221,3 +222,42 @@ export class CodeInterpreterNetworkConfiguration extends NetworkConfiguration {
221222
};
222223
}
223224
}
225+
226+
/**
227+
* Network configuration for the Runtime.
228+
*/
229+
export class RuntimeNetworkConfiguration extends NetworkConfiguration {
230+
/**
231+
* Creates a public network configuration. PUBLIC is the default network mode.
232+
* @returns A RuntimeNetworkConfiguration.
233+
* Run the runtime in a public environment with internet access, suitable for less sensitive or open-use scenarios.
234+
*/
235+
public static usingPublicNetwork(): RuntimeNetworkConfiguration {
236+
return new RuntimeNetworkConfiguration('PUBLIC');
237+
}
238+
239+
/**
240+
* Creates a network configuration from a VPC configuration.
241+
* @param scope - The construct scope for creating resources.
242+
* @param vpcConfig - The VPC configuration.
243+
* @returns A RuntimeNetworkConfiguration.
244+
*/
245+
public static usingVpc(scope: Construct, vpcConfig: VpcConfigProps): RuntimeNetworkConfiguration {
246+
return new RuntimeNetworkConfiguration('VPC', scope, vpcConfig);
247+
}
248+
249+
/**
250+
* Renders the network configuration as a CloudFormation property.
251+
* @param runtimeConnections - The connections object to the runtime.
252+
* @internal This is an internal core function and should not be called directly.
253+
*/
254+
public _render(_runtimeConnections?: ec2.Connections): CfnRuntime.NetworkConfigurationProperty {
255+
return {
256+
networkMode: this.networkMode,
257+
networkModeConfig: (this.networkMode == 'VPC' && _runtimeConnections) ? {
258+
subnets: this.vpcSubnets?.subnets?.map(subnet => subnet.subnetId) ?? [],
259+
securityGroups: _runtimeConnections?.securityGroups?.map(s=> s.securityGroupId) ?? [],
260+
}: undefined,
261+
};
262+
}
263+
}

‎packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/perms.ts‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
/******************************************************************************
2+
* Data Plane Permissions
3+
*****************************************************************************/
4+
/**
5+
* Permissions to invoke the agent runtime
6+
*/
7+
export const RUNTIME_INVOKE_PERMS = ['bedrock-agentcore:InvokeAgentRuntime'];
8+
9+
/**
10+
* Permissions to invoke the agent runtime on behalf of a user
11+
* Required when using the X-Amzn-Bedrock-AgentCore-Runtime-User-Id header
12+
*/
13+
export const RUNTIME_INVOKE_USER_PERMS = ['bedrock-agentcore:InvokeAgentRuntimeForUser'];
14+
15+
/******************************************************************************
16+
* Control Plane Permissions
17+
*****************************************************************************/
18+
/**
19+
* Grants control plane operations to manage the runtime (CRUD)
20+
*/
21+
export const RUNTIME_ADMIN_PERMS = [
22+
'bedrock-agentcore:CreateAgentRuntime',
23+
'bedrock-agentcore:CreateAgentRuntimeEndpoint',
24+
'bedrock-agentcore:DeleteAgentRuntime',
25+
'bedrock-agentcore:DeleteAgentRuntimeEndpoint',
26+
'bedrock-agentcore:GetAgentRuntime',
27+
'bedrock-agentcore:GetAgentRuntimeEndpoint',
28+
'bedrock-agentcore:ListAgentRuntimes',
29+
'bedrock-agentcore:ListAgentRuntimeVersions',
30+
'bedrock-agentcore:ListAgentRuntimeEndpoints',
31+
'bedrock-agentcore:UpdateAgentRuntime',
32+
'bedrock-agentcore:UpdateAgentRuntimeEndpoint',
33+
];
34+
35+
/******************************************************************************
36+
* Execution Role Permissions
37+
*****************************************************************************/
38+
39+
/**
40+
* ECR permissions for pulling container images
41+
* Used to download container images from ECR repositories
42+
*/
43+
export const RUNTIME_ECR_IMAGE_ACTIONS = [
44+
'ecr:BatchGetImage',
45+
'ecr:GetDownloadUrlForLayer',
46+
];
47+
48+
/**
49+
* ECR authorization token permissions
50+
* Required to authenticate with ECR (must use * resource)
51+
*/
52+
export const RUNTIME_ECR_TOKEN_ACTIONS = ['ecr:GetAuthorizationToken'];
53+
54+
/**
55+
* CloudWatch Logs permissions for log group operations
56+
* Used to create and describe log groups for runtime logs
57+
*/
58+
export const RUNTIME_LOGS_GROUP_ACTIONS = [
59+
'logs:DescribeLogStreams',
60+
'logs:CreateLogGroup',
61+
];
62+
63+
/**
64+
* CloudWatch Logs describe permissions
65+
* Used to list and describe all log groups
66+
*/
67+
export const RUNTIME_LOGS_DESCRIBE_ACTIONS = ['logs:DescribeLogGroups'];
68+
69+
/**
70+
* CloudWatch Logs permissions for log stream operations
71+
* Used to create log streams and write log events
72+
*/
73+
export const RUNTIME_LOGS_STREAM_ACTIONS = [
74+
'logs:CreateLogStream',
75+
'logs:PutLogEvents',
76+
];
77+
78+
/**
79+
* X-Ray tracing permissions
80+
* Required for distributed tracing (must use * resource)
81+
*/
82+
export const RUNTIME_XRAY_ACTIONS = [
83+
'xray:PutTraceSegments',
84+
'xray:PutTelemetryRecords',
85+
'xray:GetSamplingRules',
86+
'xray:GetSamplingTargets',
87+
];
88+
89+
/**
90+
* CloudWatch metrics permissions
91+
* Used to publish custom metrics
92+
*/
93+
export const RUNTIME_CLOUDWATCH_METRICS_ACTIONS = ['cloudwatch:PutMetricData'];
94+
95+
/**
96+
* Bedrock AgentCore workload identity permissions
97+
* Used to obtain access tokens for workload identity
98+
*/
99+
export const RUNTIME_WORKLOAD_IDENTITY_ACTIONS = [
100+
'bedrock-agentcore:GetWorkloadAccessToken',
101+
'bedrock-agentcore:GetWorkloadAccessTokenForJWT',
102+
'bedrock-agentcore:GetWorkloadAccessTokenForUserId',
103+
];
104+
/**
105+
* CloudWatch namespace for metrics
106+
* Used as a condition for CloudWatch metrics permissions
107+
*/
108+
export const RUNTIME_CLOUDWATCH_NAMESPACE = 'bedrock-agentcore';

‎packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-artifact.ts‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
/**
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
5+
* with the License. A copy of the License is located at
6+
*
7+
* http://www.apache.org/licenses/LICENSE-2.0
8+
*
9+
* or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
10+
* OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
11+
* and limitations under the License.
12+
*/
13+
14+
import * as ecr from 'aws-cdk-lib/aws-ecr';
15+
import * as assets from 'aws-cdk-lib/aws-ecr-assets';
16+
import { CfnRuntime } from 'aws-cdk-lib/aws-bedrockagentcore';
17+
import { md5hash } from 'aws-cdk-lib/core/lib/helpers-internal';
18+
import { Construct } from 'constructs';
19+
import { Runtime } from './runtime';
20+
import { ValidationError } from './validation-helpers';
21+
22+
/**
23+
* Abstract base class for agent runtime artifacts.
24+
* Provides methods to reference container images from ECR repositories or local assets.
25+
*/
26+
export abstract class AgentRuntimeArtifact {
27+
/**
28+
* Reference an image in an ECR repository
29+
*/
30+
public static fromEcrRepository(repository: ecr.IRepository, tag: string = 'latest'): AgentRuntimeArtifact {
31+
return new EcrImage(repository, tag);
32+
}
33+
34+
/**
35+
* Reference an agent runtime artifact that's constructed directly from sources on disk
36+
* @param directory The directory where the Dockerfile is stored
37+
* @param options The options to further configure the selected image
38+
*/
39+
public static fromAsset(directory: string, options: assets.DockerImageAssetOptions = {}): AgentRuntimeArtifact {
40+
return new AssetImage(directory, options);
41+
}
42+
43+
/**
44+
* Called when the image is used by a Runtime to handle side effects like permissions
45+
*/
46+
public abstract bind(scope: Construct, runtime: Runtime): void;
47+
48+
/**
49+
* Render the artifact configuration for CloudFormation
50+
* @internal
51+
*/
52+
public abstract _render(): CfnRuntime.AgentRuntimeArtifactProperty;
53+
}
54+
55+
class EcrImage extends AgentRuntimeArtifact {
56+
private bound = false;
57+
58+
constructor(private readonly repository: ecr.IRepository, private readonly tag: string) {
59+
super();
60+
}
61+
62+
public bind(_scope: Construct, runtime: Runtime): void {
63+
// Handle permissions (only once)
64+
if (!this.bound && runtime.role) {
65+
this.repository.grantPull(runtime.role);
66+
this.bound = true;
67+
}
68+
}
69+
70+
public _render(): CfnRuntime.AgentRuntimeArtifactProperty {
71+
// Return container configuration directly as expected by the runtime
72+
// The runtime wraps this in containerConfiguration
73+
return {
74+
containerUri: this.repository.repositoryUriForTag(this.tag),
75+
} as any;
76+
}
77+
}
78+
79+
class AssetImage extends AgentRuntimeArtifact {
80+
private asset?: assets.DockerImageAsset;
81+
private bound = false;
82+
83+
constructor(private readonly directory: string, private readonly options: assets.DockerImageAssetOptions = {}) {
84+
super();
85+
}
86+
87+
public bind(scope: Construct, runtime: Runtime): void {
88+
// Create the asset if not already created
89+
if (!this.asset) {
90+
const hash = md5hash(this.directory);
91+
this.asset = new assets.DockerImageAsset(scope, `AgentRuntimeArtifact${hash}`, {
92+
directory: this.directory,
93+
...this.options,
94+
});
95+
}
96+
97+
// Grant permissions (only once)
98+
if (!this.bound) {
99+
this.asset.repository.grantPull(runtime.role);
100+
this.bound = true;
101+
}
102+
}
103+
104+
public _render(): CfnRuntime.AgentRuntimeArtifactProperty {
105+
if (!this.asset) {
106+
throw new ValidationError('Asset not initialized. Call bind() before _render()');
107+
}
108+
109+
// Return container configuration directly as expected by the runtime
110+
// The runtime wraps this in containerConfiguration
111+
return {
112+
containerUri: this.asset.imageUri,
113+
} as any;
114+
}
115+
}

0 commit comments

Comments
 (0)