Template Operations

/**
 * Validates a CloudFormation template for syntax and parameter errors
 * Returns template parameters, capabilities, and cost estimation URL
 */
class ValidateTemplateCommand {
  constructor(input: ValidateTemplateCommandInput);
}

interface ValidateTemplateCommandInput {
  /** CloudFormation template as JSON/YAML string */
  TemplateBody?: string;
  
  /** S3 URL containing the CloudFormation template */
  TemplateURL?: string;
}

interface ValidateTemplateCommandOutput {
  /** Template parameters with metadata */
  Parameters?: TemplateParameter[];
  
  /** Template description */
  Description?: string;
  
  /** IAM capabilities required by template */
  Capabilities?: Capability[];
  
  /** Reason for required capabilities */
  CapabilitiesReason?: string;
  
  /** Template outputs declared */
  DeclaredTransforms?: string[];
}

interface TemplateParameter {
  /** Parameter name */
  ParameterKey?: string;
  
  /** Parameter default value */
  DefaultValue?: string;
  
  /** Parameter has no echo (sensitive) */
  NoEcho?: boolean;
  
  /** Parameter description */
  Description?: string;
}

import { CloudFormationClient, ValidateTemplateCommand } from "@aws-sdk/client-cloudformation";

const client = new CloudFormationClient({ region: "us-east-1" });

// Validate template with inline content
const validateCommand = new ValidateTemplateCommand({
  TemplateBody: JSON.stringify({
    AWSTemplateFormatVersion: "2010-09-09",
    Parameters: {
      BucketName: {
        Type: "String",
        Description: "Name for the S3 bucket",
        MinLength: 3,
        MaxLength: 63
      }
    },
    Resources: {
      MyBucket: {
        Type: "AWS::S3::Bucket",
        Properties: {
          BucketName: { Ref: "BucketName" }
        }
      }
    }
  })
});

const validation = await client.send(validateCommand);
console.log("Template parameters:", validation.Parameters);
console.log("Required capabilities:", validation.Capabilities);

// Validate template from S3 URL
const validateUrlCommand = new ValidateTemplateCommand({
  TemplateURL: "https://my-bucket.s3.amazonaws.com/template.yaml"
});

const urlValidation = await client.send(validateUrlCommand);

/**
 * Retrieves the CloudFormation template for a stack
 * Returns original or processed template based on stage
 */
class GetTemplateCommand {
  constructor(input: GetTemplateCommandInput);
}

interface GetTemplateCommandInput {
  /** Name or ARN of the stack */
  StackName?: string;
  
  /** Change set name for template retrieval */
  ChangeSetName?: string;
  
  /** Template stage to retrieve (Original or Processed) */
  TemplateStage?: TemplateStage;
}

interface GetTemplateCommandOutput {
  /** CloudFormation template body */
  TemplateBody?: Record<string, any>;
  
  /** Additional metadata about stages available */
  StagesAvailable?: TemplateStage[];
}

type TemplateStage = 
  | "Original"
  | "Processed";

// Get original template for a stack
const getTemplateCommand = new GetTemplateCommand({
  StackName: "my-stack",
  TemplateStage: "Original"
});

const template = await client.send(getTemplateCommand);
console.log("Template:", JSON.stringify(template.TemplateBody, null, 2));

// Get processed template (with transforms applied)
const processedCommand = new GetTemplateCommand({
  StackName: "my-stack", 
  TemplateStage: "Processed"
});

const processedTemplate = await client.send(processedCommand);

/**
 * Retrieves template summary with metadata and resource information
 * Provides overview without full template validation
 */
class GetTemplateSummaryCommand {
  constructor(input: GetTemplateSummaryCommandInput);
}

interface GetTemplateSummaryCommandInput {
  /** CloudFormation template as string */
  TemplateBody?: string;
  
  /** S3 URL containing template */
  TemplateURL?: string;
  
  /** Stack name for existing template */
  StackName?: string;
  
  /** Stack set name for template */
  StackSetName?: string;
  
  /** Call AS for specific account/region context */
  CallAs?: CallAs;
}

interface GetTemplateSummaryCommandOutput {
  /** Template parameters */
  Parameters?: ParameterDeclaration[];
  
  /** Template description */
  Description?: string;
  
  /** IAM capabilities required */
  Capabilities?: Capability[];
  
  /** Reason for capabilities */
  CapabilitiesReason?: string;
  
  /** Resource types used in template */
  ResourceTypes?: string[];
  
  /** Template format version */
  Version?: string;
  
  /** Template metadata */
  Metadata?: Record<string, any>;
  
  /** Declared transforms */
  DeclaredTransforms?: string[];
  
  /** Resource identifier summaries */
  ResourceIdentifierSummaries?: ResourceIdentifierSummary[];
  
  /** Warnings about template */
  Warnings?: TemplateWarning[];
}

interface ParameterDeclaration {
  /** Parameter name */
  ParameterKey?: string;
  
  /** Parameter default value */
  DefaultValue?: string;
  
  /** Parameter type */
  ParameterType?: string;
  
  /** Parameter has no echo */
  NoEcho?: boolean;
  
  /** Parameter description */
  Description?: string;
  
  /** Parameter constraints */
  ParameterConstraints?: ParameterConstraints;
}

interface ResourceIdentifierSummary {
  /** Resource type */
  ResourceType?: string;
  
  /** Logical resource IDs */
  LogicalResourceIds?: string[];
  
  /** Resource identifiers */
  ResourceIdentifiers?: string[];
}

interface TemplateWarning {
  /** Warning type */
  Type?: string;
  
  /** Warning reason */
  Reason?: string;
}

interface ParameterConstraints {
  /** Allowed values */
  AllowedValues?: string[];
}

type CallAs = 
  | "SELF"
  | "DELEGATED_ADMIN";

// Get template summary for inline template
const summaryCommand = new GetTemplateSummaryCommand({
  TemplateBody: JSON.stringify({
    AWSTemplateFormatVersion: "2010-09-09",
    Description: "Creates S3 bucket with Lambda function",
    Parameters: {
      Environment: {
        Type: "String",
        AllowedValues: ["dev", "staging", "prod"],
        Default: "dev"
      }
    },
    Resources: {
      MyBucket: { Type: "AWS::S3::Bucket" },
      MyFunction: { Type: "AWS::Lambda::Function" }
    }
  })
});

const summary = await client.send(summaryCommand);
console.log("Resource types:", summary.ResourceTypes);
console.log("Parameters:", summary.Parameters);
console.log("Warnings:", summary.Warnings);

// Get summary for existing stack
const stackSummaryCommand = new GetTemplateSummaryCommand({
  StackName: "my-existing-stack"
});

const stackSummary = await client.send(stackSummaryCommand);

/**
 * Estimates monthly cost for resources defined in template
 * Returns URL to AWS Simple Monthly Calculator
 */
class EstimateTemplateCostCommand {
  constructor(input: EstimateTemplateCostCommandInput);
}

interface EstimateTemplateCostCommandInput {
  /** CloudFormation template as string */
  TemplateBody?: string;
  
  /** S3 URL containing template */
  TemplateURL?: string;
  
  /** Parameter values for cost calculation */
  Parameters?: Parameter[];
}

interface EstimateTemplateCostCommandOutput {
  /** URL to cost estimation in Simple Monthly Calculator */
  Url?: string;
}

// Estimate cost for template with parameters
const costCommand = new EstimateTemplateCostCommand({
  TemplateBody: JSON.stringify({
    AWSTemplateFormatVersion: "2010-09-09",
    Parameters: {
      InstanceType: { Type: "String", Default: "t3.micro" },
      VolumeSize: { Type: "Number", Default: 20 }
    },
    Resources: {
      MyInstance: {
        Type: "AWS::EC2::Instance",
        Properties: {
          InstanceType: { Ref: "InstanceType" },
          BlockDeviceMappings: [{
            DeviceName: "/dev/xvda",
            Ebs: { VolumeSize: { Ref: "VolumeSize" } }
          }]
        }
      }
    }
  }),
  Parameters: [
    { ParameterKey: "InstanceType", ParameterValue: "t3.medium" },
    { ParameterKey: "VolumeSize", ParameterValue: "50" }
  ]
});

const cost = await client.send(costCommand);
console.log("Cost estimation URL:", cost.Url);

interface Parameter {
  /** Parameter name */
  ParameterKey?: string;
  
  /** Parameter value */
  ParameterValue?: string;
  
  /** Use previous parameter value */
  UsePreviousValue?: boolean;
  
  /** Resolved parameter value */
  ResolvedValue?: string;
}

type Capability = 
  | "CAPABILITY_IAM"
  | "CAPABILITY_NAMED_IAM" 
  | "CAPABILITY_AUTO_EXPAND";

// Template validation errors
try {
  await client.send(validateCommand);
} catch (error) {
  if (error.name === 'ValidationError') {
    console.error('Template validation failed:', error.message);
  }
}

// Template not found errors  
try {
  await client.send(getTemplateCommand);
} catch (error) {
  if (error.name === 'StackNotFoundException') {
    console.error('Stack not found for template retrieval');
  }
}