feat(agentcore): add agentcore runtime L2 construct

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

@@ -4,6 +4,16 @@
 export * from './network/network-configuration';
 
 // ===================================
+// Runtime
+// ===================================
+export * from './runtime/perms';
+export * from './runtime/types';
+export * from './runtime/runtime-base';
+export * from './runtime/runtime-artifact';
+export * from './runtime/runtime-authorizer-configuration';
+export * from './runtime/runtime-endpoint-base';
+export * from './runtime/runtime-endpoint';
+export * from './runtime/runtime';
 // Tools
 // ===================================
 export * from './tools/code-interpreter';

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

@@ -1,6 +1,7 @@
+/* eslint-disable @cdklabs/no-throw-default-error */
 import * as ec2 from 'aws-cdk-lib/aws-ec2';
 // Internal Libs
-import { CfnBrowserCustom, CfnCodeInterpreterCustom } from 'aws-cdk-lib/aws-bedrockagentcore';
+import { CfnBrowserCustom, CfnCodeInterpreterCustom, CfnRuntime } from 'aws-cdk-lib/aws-bedrockagentcore';
 import { Construct } from 'constructs';
 
 /**
@@ -221,3 +222,42 @@ export class CodeInterpreterNetworkConfiguration extends NetworkConfiguration {
     };
   }
 }
+
+/**
+ * Network configuration for the Runtime.
+ */
+export class RuntimeNetworkConfiguration extends NetworkConfiguration {
+  /**
+   * Creates a public network configuration. PUBLIC is the default network mode.
+   * @returns A RuntimeNetworkConfiguration.
+   * Run the runtime in a public environment with internet access, suitable for less sensitive or open-use scenarios.
+   */
+  public static usingPublicNetwork(): RuntimeNetworkConfiguration {
+    return new RuntimeNetworkConfiguration('PUBLIC');
+  }
+
+  /**
+   * Creates a network configuration from a VPC configuration.
+   * @param scope - The construct scope for creating resources.
+   * @param vpcConfig - The VPC configuration.
+   * @returns A RuntimeNetworkConfiguration.
+   */
+  public static usingVpc(scope: Construct, vpcConfig: VpcConfigProps): RuntimeNetworkConfiguration {
+    return new RuntimeNetworkConfiguration('VPC', scope, vpcConfig);
+  }
+
+  /**
+   * Renders the network configuration as a CloudFormation property.
+   * @param runtimeConnections - The connections object to the runtime.
+   * @internal This is an internal core function and should not be called directly.
+   */
+  public _render(_runtimeConnections?: ec2.Connections): CfnRuntime.NetworkConfigurationProperty {
+    return {
+      networkMode: this.networkMode,
+      networkModeConfig: (this.networkMode == 'VPC' && _runtimeConnections) ? {
+        subnets: this.vpcSubnets?.subnets?.map(subnet => subnet.subnetId) ?? [],
+        securityGroups: _runtimeConnections?.securityGroups?.map(s=> s.securityGroupId) ?? [],
+      }: undefined,
+    };
+  }
+}

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

@@ -0,0 +1,108 @@
+/******************************************************************************
+ *                         Data Plane Permissions
+ *****************************************************************************/
+/**
+ * Permissions to invoke the agent runtime
+ */
+export const RUNTIME_INVOKE_PERMS = ['bedrock-agentcore:InvokeAgentRuntime'];
+
+/**
+ * Permissions to invoke the agent runtime on behalf of a user
+ * Required when using the X-Amzn-Bedrock-AgentCore-Runtime-User-Id header
+ */
+export const RUNTIME_INVOKE_USER_PERMS = ['bedrock-agentcore:InvokeAgentRuntimeForUser'];
+
+/******************************************************************************
+ *                         Control Plane Permissions
+ *****************************************************************************/
+/**
+ * Grants control plane operations to manage the runtime (CRUD)
+ */
+export const RUNTIME_ADMIN_PERMS = [
+  'bedrock-agentcore:CreateAgentRuntime',
+  'bedrock-agentcore:CreateAgentRuntimeEndpoint',
+  'bedrock-agentcore:DeleteAgentRuntime',
+  'bedrock-agentcore:DeleteAgentRuntimeEndpoint',
+  'bedrock-agentcore:GetAgentRuntime',
+  'bedrock-agentcore:GetAgentRuntimeEndpoint',
+  'bedrock-agentcore:ListAgentRuntimes',
+  'bedrock-agentcore:ListAgentRuntimeVersions',
+  'bedrock-agentcore:ListAgentRuntimeEndpoints',
+  'bedrock-agentcore:UpdateAgentRuntime',
+  'bedrock-agentcore:UpdateAgentRuntimeEndpoint',
+];
+
+/******************************************************************************
+ *                    Execution Role Permissions
+ *****************************************************************************/
+
+/**
+ * ECR permissions for pulling container images
+ * Used to download container images from ECR repositories
+ */
+export const RUNTIME_ECR_IMAGE_ACTIONS = [
+  'ecr:BatchGetImage',
+  'ecr:GetDownloadUrlForLayer',
+];
+
+/**
+ * ECR authorization token permissions
+ * Required to authenticate with ECR (must use * resource)
+ */
+export const RUNTIME_ECR_TOKEN_ACTIONS = ['ecr:GetAuthorizationToken'];
+
+/**
+ * CloudWatch Logs permissions for log group operations
+ * Used to create and describe log groups for runtime logs
+ */
+export const RUNTIME_LOGS_GROUP_ACTIONS = [
+  'logs:DescribeLogStreams',
+  'logs:CreateLogGroup',
+];
+
+/**
+ * CloudWatch Logs describe permissions
+ * Used to list and describe all log groups
+ */
+export const RUNTIME_LOGS_DESCRIBE_ACTIONS = ['logs:DescribeLogGroups'];
+
+/**
+ * CloudWatch Logs permissions for log stream operations
+ * Used to create log streams and write log events
+ */
+export const RUNTIME_LOGS_STREAM_ACTIONS = [
+  'logs:CreateLogStream',
+  'logs:PutLogEvents',
+];
+
+/**
+ * X-Ray tracing permissions
+ * Required for distributed tracing (must use * resource)
+ */
+export const RUNTIME_XRAY_ACTIONS = [
+  'xray:PutTraceSegments',
+  'xray:PutTelemetryRecords',
+  'xray:GetSamplingRules',
+  'xray:GetSamplingTargets',
+];
+
+/**
+ * CloudWatch metrics permissions
+ * Used to publish custom metrics
+ */
+export const RUNTIME_CLOUDWATCH_METRICS_ACTIONS = ['cloudwatch:PutMetricData'];
+
+/**
+ * Bedrock AgentCore workload identity permissions
+ * Used to obtain access tokens for workload identity
+ */
+export const RUNTIME_WORKLOAD_IDENTITY_ACTIONS = [
+  'bedrock-agentcore:GetWorkloadAccessToken',
+  'bedrock-agentcore:GetWorkloadAccessTokenForJWT',
+  'bedrock-agentcore:GetWorkloadAccessTokenForUserId',
+];
+/**
+ * CloudWatch namespace for metrics
+ * Used as a condition for CloudWatch metrics permissions
+ */
+export const RUNTIME_CLOUDWATCH_NAMESPACE = 'bedrock-agentcore';

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

@@ -0,0 +1,115 @@
+/**
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+ *  with the License. A copy of the License is located at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+ *  OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+ *  and limitations under the License.
+ */
+
+import * as ecr from 'aws-cdk-lib/aws-ecr';
+import * as assets from 'aws-cdk-lib/aws-ecr-assets';
+import { CfnRuntime } from 'aws-cdk-lib/aws-bedrockagentcore';
+import { md5hash } from 'aws-cdk-lib/core/lib/helpers-internal';
+import { Construct } from 'constructs';
+import { Runtime } from './runtime';
+import { ValidationError } from './validation-helpers';
+
+/**
+ * Abstract base class for agent runtime artifacts.
+ * Provides methods to reference container images from ECR repositories or local assets.
+ */
+export abstract class AgentRuntimeArtifact {
+  /**
+   * Reference an image in an ECR repository
+   */
+  public static fromEcrRepository(repository: ecr.IRepository, tag: string = 'latest'): AgentRuntimeArtifact {
+    return new EcrImage(repository, tag);
+  }
+
+  /**
+   * Reference an agent runtime artifact that's constructed directly from sources on disk
+   * @param directory The directory where the Dockerfile is stored
+   * @param options The options to further configure the selected image
+   */
+  public static fromAsset(directory: string, options: assets.DockerImageAssetOptions = {}): AgentRuntimeArtifact {
+    return new AssetImage(directory, options);
+  }
+
+  /**
+   * Called when the image is used by a Runtime to handle side effects like permissions
+   */
+  public abstract bind(scope: Construct, runtime: Runtime): void;
+
+  /**
+   * Render the artifact configuration for CloudFormation
+   * @internal
+   */
+  public abstract _render(): CfnRuntime.AgentRuntimeArtifactProperty;
+}
+
+class EcrImage extends AgentRuntimeArtifact {
+  private bound = false;
+
+  constructor(private readonly repository: ecr.IRepository, private readonly tag: string) {
+    super();
+  }
+
+  public bind(_scope: Construct, runtime: Runtime): void {
+    // Handle permissions (only once)
+    if (!this.bound && runtime.role) {
+      this.repository.grantPull(runtime.role);
+      this.bound = true;
+    }
+  }
+
+  public _render(): CfnRuntime.AgentRuntimeArtifactProperty {
+    // Return container configuration directly as expected by the runtime
+    // The runtime wraps this in containerConfiguration
+    return {
+      containerUri: this.repository.repositoryUriForTag(this.tag),
+    } as any;
+  }
+}
+
+class AssetImage extends AgentRuntimeArtifact {
+  private asset?: assets.DockerImageAsset;
+  private bound = false;
+
+  constructor(private readonly directory: string, private readonly options: assets.DockerImageAssetOptions = {}) {
+    super();
+  }
+
+  public bind(scope: Construct, runtime: Runtime): void {
+    // Create the asset if not already created
+    if (!this.asset) {
+      const hash = md5hash(this.directory);
+      this.asset = new assets.DockerImageAsset(scope, `AgentRuntimeArtifact${hash}`, {
+        directory: this.directory,
+        ...this.options,
+      });
+    }
+
+    // Grant permissions (only once)
+    if (!this.bound) {
+      this.asset.repository.grantPull(runtime.role);
+      this.bound = true;
+    }
+  }
+
+  public _render(): CfnRuntime.AgentRuntimeArtifactProperty {
+    if (!this.asset) {
+      throw new ValidationError('Asset not initialized. Call bind() before _render()');
+    }
+
+    // Return container configuration directly as expected by the runtime
+    // The runtime wraps this in containerConfiguration
+    return {
+      containerUri: this.asset.imageUri,
+    } as any;
+  }
+}