serverless-bedrock-agentcore-plugin 0.1.0

package/src/compilers/memory.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const { getResourceName, getLogicalId } = require('../utils/naming');
+
+// Track if deprecation warning has been shown (module-level to show only once)
+let deprecationWarningShown = false;
+
+/**
+ * Reset the deprecation warning flag (for testing purposes)
+ */
+function resetDeprecationWarning() {
+  deprecationWarningShown = false;
+}
+
+/**
+ * Detect if strategy is in legacy format
+ * Legacy format has flat structure with type/name at top level
+ * New format uses typed union like SemanticMemoryStrategy, etc.
+ *
+ * @param {Object} strategy - The strategy configuration
+ * @returns {boolean} True if legacy format
+ */
+function isLegacyFormat(strategy) {
+  // New format has one of these as top-level keys
+  const newFormatKeys = [
+    'SemanticMemoryStrategy',
+    'SummaryMemoryStrategy',
+    'UserPreferenceMemoryStrategy',
+    'CustomMemoryStrategy',
+  ];
+
+  // If any new format key exists, it's new format
+  if (newFormatKeys.some((key) => strategy[key] !== undefined)) {
+    return false;
+  }
+
+  // If it has 'type' property at top level, it's legacy format
+  return strategy.type !== undefined;
+}
+
+/**
+ * Convert legacy strategy format to new typed union format
+ *
+ * @param {Object} strategy - Legacy format strategy
+ * @returns {Object} New format strategy
+ */
+function convertLegacyStrategy(strategy) {
+  const baseConfig = {
+    Name: strategy.name,
+    ...(strategy.description && { Description: strategy.description }),
+    ...(strategy.namespaces && { Namespaces: strategy.namespaces }),
+  };
+
+  const type = (strategy.type || '').toLowerCase();
+
+  switch (type) {
+    case 'semantic':
+      return {
+        SemanticMemoryStrategy: {
+          ...baseConfig,
+          // Note: Managed strategies don't require explicit Type or model configuration
+        },
+      };
+
+    case 'summary':
+    case 'summarization':
+      return {
+        SummaryMemoryStrategy: {
+          ...baseConfig,
+          // Note: Managed strategies don't require explicit Type
+        },
+      };
+
+    case 'userpreference':
+    case 'user_preference':
+      return {
+        UserPreferenceMemoryStrategy: {
+          ...baseConfig,
+          // Note: Managed strategies don't require explicit Type
+        },
+      };
+
+    case 'custom':
+      return {
+        CustomMemoryStrategy: {
+          ...baseConfig,
+          ...(strategy.configuration && { Configuration: strategy.configuration }),
+        },
+      };
+
+    default:
+      throw new Error(`Unknown memory strategy type: ${type}`);
+  }
+}
+
+/**
+ * Build memory strategies configuration
+ * Supports both legacy flat format and new typed union format
+ *
+ * @param {Array} strategies - The strategies configuration from serverless.yml
+ * @returns {Array|null} CloudFormation memory strategies or null
+ */
+function buildMemoryStrategies(strategies) {
+  if (!strategies || strategies.length === 0) {
+    return null;
+  }
+
+  return strategies.map((strategy) => {
+    if (isLegacyFormat(strategy)) {
+      // Emit deprecation warning once per deployment
+      if (!deprecationWarningShown) {
+        console.warn(
+          '\x1b[33m%s\x1b[0m', // Yellow color
+          'DEPRECATION WARNING: Memory strategy format has changed to typed union structure. ' +
+            'Please update your configuration. See documentation for migration guide.'
+        );
+        deprecationWarningShown = true;
+      }
+
+      return convertLegacyStrategy(strategy);
+    }
+
+    // Already in new format - pass through
+    return strategy;
+  });
+}
+
+/**
+ * Compile a Memory resource to CloudFormation
+ *
+ * @param {string} name - The agent name
+ * @param {Object} config - The memory configuration
+ * @param {Object} context - The compilation context
+ * @param {Object} tags - The merged tags
+ * @returns {Object} CloudFormation resource definition
+ */
+function compileMemory(name, config, context, tags) {
+  const { serviceName, stage } = context;
+  const resourceName = getResourceName(serviceName, name, stage);
+  const roleLogicalId = `${getLogicalId(name, 'Memory')}Role`;
+
+  const strategies = buildMemoryStrategies(config.strategies);
+
+  // Default expiry duration to 30 days if not specified
+  const eventExpiryDuration = config.eventExpiryDuration || 30;
+
+  return {
+    Type: 'AWS::BedrockAgentCore::Memory',
+    Properties: {
+      Name: resourceName,
+      EventExpiryDuration: eventExpiryDuration,
+      ...(config.description && { Description: config.description }),
+      ...(config.encryptionKeyArn && { EncryptionKeyArn: config.encryptionKeyArn }),
+      ...(!config.roleArn && { MemoryExecutionRoleArn: { 'Fn::GetAtt': [roleLogicalId, 'Arn'] } }),
+      ...(config.roleArn && { MemoryExecutionRoleArn: config.roleArn }),
+      ...(strategies && { MemoryStrategies: strategies }),
+      ...(Object.keys(tags).length > 0 && { Tags: tags }),
+    },
+  };
+}
+
+module.exports = {
+  compileMemory,
+  buildMemoryStrategies,
+  isLegacyFormat,
+  convertLegacyStrategy,
+  resetDeprecationWarning,
+};

package/src/compilers/runtime.js

@@ -0,0 +1,234 @@
+'use strict';
+
+const { getResourceName, getLogicalId } = require('../utils/naming');
+
+/**
+ * Build the artifact configuration for the runtime
+ *
+ * @param {Object} artifact - The artifact configuration from serverless.yml
+ * @returns {Object} CloudFormation artifact configuration
+ */
+function buildArtifact(artifact) {
+  if (artifact.containerImage) {
+    return {
+      ContainerConfiguration: {
+        ContainerUri: artifact.containerImage,
+      },
+    };
+  }
+
+  if (artifact.s3) {
+    return {
+      S3Configuration: {
+        S3BucketName: artifact.s3.bucket,
+        S3ObjectKey: artifact.s3.key,
+      },
+    };
+  }
+
+  throw new Error('Artifact must specify either containerImage or s3 configuration');
+}
+
+/**
+ * Build network configuration for the runtime
+ *
+ * @param {Object} network - The network configuration from serverless.yml
+ * @returns {Object} CloudFormation network configuration
+ */
+function buildNetworkConfiguration(network = {}) {
+  const networkMode = network.networkMode || 'PUBLIC';
+
+  const config = {
+    NetworkMode: networkMode,
+  };
+
+  // Add VPC configuration if VPC mode
+  if (networkMode === 'VPC' && network.vpcConfig) {
+    config.VpcConfiguration = {
+      ...(network.vpcConfig.subnetIds && { SubnetIds: network.vpcConfig.subnetIds }),
+      ...(network.vpcConfig.securityGroupIds && {
+        SecurityGroupIds: network.vpcConfig.securityGroupIds,
+      }),
+    };
+  }
+
+  return config;
+}
+
+/**
+ * Build authorizer configuration for the runtime
+ * Supports NONE, AWS_IAM, and CustomJWTAuthorizer
+ *
+ * @param {Object} authorizer - The authorizer configuration from serverless.yml
+ * @returns {Object|null} CloudFormation authorizer configuration or null
+ */
+function buildAuthorizerConfiguration(authorizer) {
+  if (!authorizer) {
+    return null;
+  }
+
+  // Handle CustomJWTAuthorizer - uses OIDC discovery URL
+  if (authorizer.customJwtAuthorizer) {
+    const jwtConfig = authorizer.customJwtAuthorizer;
+
+    // DiscoveryUrl is required for CustomJWTAuthorizer
+    if (!jwtConfig.discoveryUrl) {
+      throw new Error('CustomJWTAuthorizer requires discoveryUrl');
+    }
+
+    return {
+      CustomJWTAuthorizer: {
+        DiscoveryUrl: jwtConfig.discoveryUrl,
+        ...(jwtConfig.allowedAudience && { AllowedAudience: jwtConfig.allowedAudience }),
+        ...(jwtConfig.allowedClients && { AllowedClients: jwtConfig.allowedClients }),
+      },
+    };
+  }
+
+  // Handle legacy format with type field
+  if (authorizer.type === 'CUSTOM_JWT' && authorizer.jwtConfiguration) {
+    // Convert legacy format to new format
+    const discoveryUrl =
+      authorizer.jwtConfiguration.discoveryUrl || authorizer.jwtConfiguration.issuer;
+
+    if (!discoveryUrl) {
+      throw new Error('CustomJWTAuthorizer requires discoveryUrl or issuer');
+    }
+
+    return {
+      CustomJWTAuthorizer: {
+        DiscoveryUrl: discoveryUrl,
+        ...(authorizer.jwtConfiguration.allowedAudience && {
+          AllowedAudience: authorizer.jwtConfiguration.allowedAudience,
+        }),
+        ...(authorizer.jwtConfiguration.allowedClients && {
+          AllowedClients: authorizer.jwtConfiguration.allowedClients,
+        }),
+        // Legacy support: audience -> allowedAudience
+        ...(authorizer.jwtConfiguration.audience && {
+          AllowedAudience: Array.isArray(authorizer.jwtConfiguration.audience)
+            ? authorizer.jwtConfiguration.audience
+            : [authorizer.jwtConfiguration.audience],
+        }),
+      },
+    };
+  }
+
+  // Return null for NONE or AWS_IAM (handled at runtime level, not in AuthorizerConfiguration)
+  return null;
+}
+
+/**
+ * Build lifecycle configuration for the runtime
+ *
+ * @param {Object} lifecycle - The lifecycle configuration from serverless.yml
+ * @returns {Object|null} CloudFormation lifecycle configuration or null
+ */
+function buildLifecycleConfiguration(lifecycle) {
+  if (!lifecycle) {
+    return null;
+  }
+
+  return {
+    ...(lifecycle.idleTimeout !== undefined && { IdleTimeoutSeconds: lifecycle.idleTimeout }),
+    ...(lifecycle.maxConcurrency !== undefined && { MaxConcurrency: lifecycle.maxConcurrency }),
+  };
+}
+
+/**
+ * Build protocol configuration for the runtime
+ * ProtocolConfiguration is a string enum: HTTP, MCP, or A2A
+ *
+ * @param {string} protocol - The protocol type (HTTP, MCP, A2A)
+ * @returns {string|null} Protocol string or null
+ */
+function buildProtocolConfiguration(protocol) {
+  if (!protocol) {
+    return null;
+  }
+
+  // ProtocolConfiguration is just the protocol string, not an object
+  return protocol;
+}
+
+/**
+ * Build environment variables for the runtime
+ *
+ * @param {Object} environment - Environment variables object
+ * @returns {Object|null} Environment variables or null
+ */
+function buildEnvironmentVariables(environment) {
+  if (!environment || Object.keys(environment).length === 0) {
+    return null;
+  }
+
+  return environment;
+}
+
+/**
+ * Build request header configuration for the runtime
+ * Allows specific headers to be forwarded to the agent
+ *
+ * @param {Object} requestHeaders - The request headers configuration from serverless.yml
+ * @returns {Object|null} CloudFormation RequestHeaderConfiguration or null
+ */
+function buildRequestHeaderConfiguration(requestHeaders) {
+  if (!requestHeaders || !requestHeaders.allowlist || requestHeaders.allowlist.length === 0) {
+    return null;
+  }
+
+  return {
+    RequestHeaderAllowlist: requestHeaders.allowlist,
+  };
+}
+
+/**
+ * Compile a Runtime resource to CloudFormation
+ *
+ * @param {string} name - The agent name
+ * @param {Object} config - The runtime configuration
+ * @param {Object} context - The compilation context
+ * @param {Object} tags - The merged tags
+ * @returns {Object} CloudFormation resource definition
+ */
+function compileRuntime(name, config, context, tags) {
+  const { serviceName, stage } = context;
+  const resourceName = getResourceName(serviceName, name, stage);
+  const roleLogicalId = `${getLogicalId(name, 'Runtime')}Role`;
+
+  const artifact = buildArtifact(config.artifact);
+  const networkConfig = buildNetworkConfiguration(config.network);
+  const authorizerConfig = buildAuthorizerConfiguration(config.authorizer);
+  const lifecycleConfig = buildLifecycleConfiguration(config.lifecycle);
+  const protocolConfig = buildProtocolConfiguration(config.protocol);
+  const envVars = buildEnvironmentVariables(config.environment);
+  const requestHeaderConfig = buildRequestHeaderConfiguration(config.requestHeaders);
+
+  return {
+    Type: 'AWS::BedrockAgentCore::Runtime',
+    Properties: {
+      AgentRuntimeName: resourceName,
+      AgentRuntimeArtifact: artifact,
+      NetworkConfiguration: networkConfig,
+      RoleArn: config.roleArn || { 'Fn::GetAtt': [roleLogicalId, 'Arn'] },
+      ...(config.description && { Description: config.description }),
+      ...(authorizerConfig && { AuthorizerConfiguration: authorizerConfig }),
+      ...(lifecycleConfig && { LifecycleConfiguration: lifecycleConfig }),
+      ...(protocolConfig && { ProtocolConfiguration: protocolConfig }),
+      ...(envVars && { EnvironmentVariables: envVars }),
+      ...(requestHeaderConfig && { RequestHeaderConfiguration: requestHeaderConfig }),
+      ...(Object.keys(tags).length > 0 && { Tags: tags }),
+    },
+  };
+}
+
+module.exports = {
+  compileRuntime,
+  buildArtifact,
+  buildNetworkConfiguration,
+  buildAuthorizerConfiguration,
+  buildLifecycleConfiguration,
+  buildProtocolConfiguration,
+  buildEnvironmentVariables,
+  buildRequestHeaderConfiguration,
+};

package/src/compilers/runtimeEndpoint.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const { getResourceName } = require('../utils/naming');
+
+/**
+ * Compile a RuntimeEndpoint resource to CloudFormation
+ *
+ * @param {string} agentName - The parent agent name
+ * @param {string} endpointName - The endpoint name
+ * @param {Object} config - The endpoint configuration
+ * @param {string} runtimeLogicalId - The logical ID of the parent Runtime resource
+ * @param {Object} context - The compilation context
+ * @param {Object} tags - The merged tags
+ * @returns {Object} CloudFormation resource definition
+ */
+function compileRuntimeEndpoint(agentName, endpointName, config, runtimeLogicalId, context, tags) {
+  const { serviceName, stage } = context;
+
+  // Generate endpoint name: {service}_{agent}_{endpoint}_{stage}
+  const resourceName = getResourceName(serviceName, `${agentName}_${endpointName}`, stage);
+
+  return {
+    Type: 'AWS::BedrockAgentCore::RuntimeEndpoint',
+    DependsOn: [runtimeLogicalId],
+    Properties: {
+      Name: resourceName,
+      AgentRuntimeId: { 'Fn::GetAtt': [runtimeLogicalId, 'AgentRuntimeId'] },
+      ...(config.version && { AgentRuntimeVersion: config.version }),
+      ...(config.description && { Description: config.description }),
+      ...(Object.keys(tags).length > 0 && { Tags: tags }),
+    },
+  };
+}
+
+module.exports = {
+  compileRuntimeEndpoint,
+};

package/src/compilers/workloadIdentity.js

@@ -0,0 +1,36 @@
+'use strict';
+
+const { getResourceName } = require('../utils/naming');
+
+/**
+ * Compile a WorkloadIdentity resource to CloudFormation
+ *
+ * @param {string} name - The workload identity name
+ * @param {Object} config - The workload identity configuration
+ * @param {Object} context - The compilation context
+ * @param {Object} tags - The merged tags
+ * @returns {Object} CloudFormation resource definition
+ */
+function compileWorkloadIdentity(name, config, context, tags) {
+  const { serviceName, stage } = context;
+  // WorkloadIdentity name pattern: [A-Za-z0-9_.-]+
+  // Replace underscores with hyphens to match the pattern better
+  const resourceName = getResourceName(serviceName, name, stage).replace(/_/g, '-');
+
+  // Convert tags object to array format for WorkloadIdentity
+  // WorkloadIdentity uses Array[Tag] format instead of Object format
+  const tagArray = Object.entries(tags).map(([Key, Value]) => ({ Key, Value }));
+
+  return {
+    Type: 'AWS::BedrockAgentCore::WorkloadIdentity',
+    Properties: {
+      Name: resourceName,
+      ...(config.oauth2ReturnUrls && { AllowedResourceOauth2ReturnUrls: config.oauth2ReturnUrls }),
+      ...(tagArray.length > 0 && { Tags: tagArray }),
+    },
+  };
+}
+
+module.exports = {
+  compileWorkloadIdentity,
+};

package/src/docker/builder.js

@@ -0,0 +1,236 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+/**
+ * Execute a shell command synchronously
+ */
+function execCommand(command, options = {}) {
+  try {
+    return execSync(command, {
+      encoding: 'utf-8',
+      stdio: options.silent ? 'pipe' : 'inherit',
+      ...options,
+    });
+  } catch (error) {
+    if (options.ignoreError) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+/**
+ * Docker image builder for AgentCore runtimes
+ * Follows similar patterns to Serverless Framework's ECR image handling
+ */
+class DockerBuilder {
+  constructor(serverless, log, progress) {
+    this.serverless = serverless;
+    this.log = log;
+    this.progress = progress;
+    this.provider = serverless.getProvider('aws');
+  }
+
+  /**
+   * Check if Docker is available
+   */
+  checkDocker() {
+    try {
+      execCommand('docker --version', { silent: true });
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get AWS account ID
+   */
+  async getAccountId() {
+    return this.provider.getAccountId();
+  }
+
+  /**
+   * Get the region
+   */
+  getRegion() {
+    return this.provider.getRegion();
+  }
+
+  /**
+   * Authenticate with ECR
+   */
+  async ecrLogin(accountId, region) {
+    this.log.info('Authenticating with ECR...');
+
+    const ecrUri = `${accountId}.dkr.ecr.${region}.amazonaws.com`;
+
+    try {
+      // Get ECR login password and pipe to docker login
+      const password = execCommand(`aws ecr get-login-password --region ${region}`, {
+        silent: true,
+      }).trim();
+
+      execCommand(`docker login --username AWS --password-stdin ${ecrUri}`, {
+        input: password,
+        silent: true,
+      });
+
+      this.log.info('ECR authentication successful');
+
+      return ecrUri;
+    } catch (error) {
+      throw new Error(`ECR login failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Ensure ECR repository exists, create if not
+   */
+  async ensureRepository(repositoryName, region) {
+    this.log.info(`Checking ECR repository: ${repositoryName}`);
+
+    try {
+      execCommand(
+        `aws ecr describe-repositories --repository-names ${repositoryName} --region ${region}`,
+        { silent: true }
+      );
+      this.log.info('Repository exists');
+    } catch {
+      this.log.info('Creating ECR repository...');
+      execCommand(
+        `aws ecr create-repository --repository-name ${repositoryName} --region ${region}`,
+        { silent: true }
+      );
+      this.log.info('Repository created');
+    }
+  }
+
+  /**
+   * Build Docker image
+   */
+  async buildImage(imageTag, dockerConfig, servicePath) {
+    const dockerfile = dockerConfig.file || 'Dockerfile';
+    const context = dockerConfig.path || '.';
+    // Bedrock AgentCore requires arm64 architecture
+    const platform = dockerConfig.platform || 'linux/arm64';
+
+    const dockerfilePath = path.resolve(servicePath, context, dockerfile);
+    const contextPath = path.resolve(servicePath, context);
+
+    this.log.info(`Building Docker image: ${imageTag}`);
+    this.log.info(`  Dockerfile: ${dockerfilePath}`);
+    this.log.info(`  Context: ${contextPath}`);
+    this.log.info(`  Platform: ${platform}`);
+
+    // Build the docker command
+    let buildCmd = `docker build --platform ${platform} -t ${imageTag}`;
+
+    // Add build args if specified
+    if (dockerConfig.buildArgs) {
+      for (const [key, value] of Object.entries(dockerConfig.buildArgs)) {
+        buildCmd += ` --build-arg ${key}="${value}"`;
+      }
+    }
+
+    // Add cache from if specified
+    if (dockerConfig.cacheFrom) {
+      for (const cache of dockerConfig.cacheFrom) {
+        buildCmd += ` --cache-from ${cache}`;
+      }
+    }
+
+    // Add any additional build options
+    if (dockerConfig.buildOptions) {
+      buildCmd += ` ${dockerConfig.buildOptions.join(' ')}`;
+    }
+
+    buildCmd += ` -f ${dockerfilePath} ${contextPath}`;
+
+    try {
+      execCommand(buildCmd);
+      this.log.info('Docker build complete');
+    } catch (error) {
+      throw new Error(`Docker build failed: ${error.message}`);
+    }
+  }
+
+  /**
+   * Tag and push image to ECR
+   */
+  async pushImage(localTag, ecrUri, repositoryName, tag) {
+    const ecrImage = `${ecrUri}/${repositoryName}:${tag}`;
+
+    this.log.info(`Tagging image: ${ecrImage}`);
+    execCommand(`docker tag ${localTag} ${ecrImage}`);
+
+    this.log.info(`Pushing image to ECR...`);
+    execCommand(`docker push ${ecrImage}`);
+
+    this.log.info('Push complete');
+
+    return ecrImage;
+  }
+
+  /**
+   * Build and push image for a runtime agent
+   * Returns the ECR image URI to use in CloudFormation
+   */
+  async buildAndPushForRuntime(agentName, imageConfig, context) {
+    const { serviceName, stage, region } = context;
+    const accountId = await this.getAccountId();
+    const servicePath = this.serverless.serviceDir;
+
+    // Determine repository name
+    const repositoryName = imageConfig.repository || `${serviceName}-${agentName}`;
+
+    // Determine tag (use stage or specified tag)
+    const tag = imageConfig.tag || stage;
+
+    // Local image tag
+    const localTag = `${repositoryName}:${tag}`;
+
+    // Ensure repository exists
+    await this.ensureRepository(repositoryName, region);
+
+    // Login to ECR
+    const ecrUri = await this.ecrLogin(accountId, region);
+
+    // Build image
+    await this.buildImage(localTag, imageConfig, servicePath);
+
+    // Push to ECR
+    const ecrImage = await this.pushImage(localTag, ecrUri, repositoryName, tag);
+
+    return ecrImage;
+  }
+
+  /**
+   * Process all images defined in provider.ecr.images
+   * Returns a map of image names to ECR URIs
+   */
+  async processImages(imagesConfig, context) {
+    const imageUris = {};
+
+    for (const [imageName, imageConfig] of Object.entries(imagesConfig)) {
+      // If URI is already specified, use it directly
+      if (imageConfig.uri) {
+        imageUris[imageName] = imageConfig.uri;
+        continue;
+      }
+
+      // Otherwise, build and push
+      if (imageConfig.path) {
+        const uri = await this.buildAndPushForRuntime(imageName, imageConfig, context);
+        imageUris[imageName] = uri;
+      }
+    }
+
+    return imageUris;
+  }
+}
+
+module.exports = { DockerBuilder };