這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

進階 CDK Toolkit Library 範例

了解如何透過實際範例使用 AWS CDK Toolkit Library 的進階功能。本指南提供詳細的程式碼範例，用於錯誤處理、部署監控和雲端組件管理，這些範例以其他章節涵蓋的基本概念為基礎。

整合 功能

下列範例示範如何結合雲端組件來源、自訂 io 主機實作和部署選項：

import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';

async function deployApplication(appPath, environment, options = {}) {
  // Create toolkit with custom message handling
  const toolkit = new Toolkit({
    ioHost: {
      notify: async (msg) => {
        // Add environment to all messages
        console.log(`[${environment}][${msg.time}] ${msg.level}: ${msg.message}`);
      },
      requestResponse: async (msg) => {
        // In production environments, use default responses
        if (environment === 'production') {
          console.log(`Auto-approving for production: ${msg.message}`);
          return msg.defaultResponse;
        }

        // For other environments, implement custom approval logic
        return promptForApproval(msg);
      }
    } as IIoHost
  });

  try {
    // Create cloud assembly source from the CDK app
    console.log(`Creating cloud assembly source from ${appPath}`);
    const cloudAssemblySource = await toolkit.fromCdkApp(appPath);

    // Synthesize the cloud assembly
    console.log(`Synthesizing cloud assembly`);
    const cloudAssembly = await toolkit.synth(cloudAssemblySource);

    try {
      // Deploy with environment-specific options
      console.log(`Deploying to ${environment} environment`);
      return await toolkit.deploy(cloudAssembly, {
        stacks: options.stacks || { strategy: StackSelectionStrategy.ALL_STACKS },
        parameters: options.parameters || {},
        tags: {
          Environment: environment,
          DeployedBy: 'CDK-Toolkit-Library',
          DeployTime: new Date().toISOString()
        }
      });
    } finally {
      // Always dispose when done
      await cloudAssembly.dispose();
    }
  } catch (error) {
    console.error(`Deployment to ${environment} failed:`, error);
    throw error;
  }
}

// Example usage
await deployApplication('ts-node app.ts', 'staging', {
  parameters: {
    MyStack: {
      InstanceType: 't3.small'
    }
  }
});

追蹤部署進度

使用詳細的狀態更新追蹤部署進度：

import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';

// Create a progress tracker
class DeploymentTracker {
  private startTime: Date;
  private resources = new Map<string, string>();

  constructor() {
    this.startTime = new Date();
  }

  onStackEvent(stackName: string, event: string, timestamp: string) {
    // Calculate elapsed time if needed, or use the provided timestamp
    const elapsed = (new Date().getTime() - this.startTime.getTime()) / 1000;
    console.log(`[${timestamp}] (${elapsed.toFixed(1)}s elapsed) Stack ${stackName}: ${event}`);
  }

  onResourceEvent(resourceId: string, status: string) {
    this.resources.set(resourceId, status);
    this.printProgress();
  }

  private printProgress() {
    console.log('\nResource Status:');
    for (const [id, status] of this.resources.entries()) {
      console.log(`- ${id}: ${status}`);
    }
    console.log();
  }
}

// Use the tracker with the toolkit
const tracker = new DeploymentTracker();
const toolkit = new Toolkit({
  ioHost: {
    notify: async (msg) => {
      if (msg.code.startsWith('CDK_DEPLOY')) {
        // Track deployment events
        if (msg.data && 'stackName' in msg.data) {
          tracker.onStackEvent(msg.data.stackName, msg.message, msg.time);
        }
      } else if (msg.code.startsWith('CDK_RESOURCE')) {
        // Track resource events
        if (msg.data && 'resourceId' in msg.data) {
          tracker.onResourceEvent(msg.data.resourceId, msg.message);
        }
      }
    }
  } as IIoHost
});

// Example usage with progress tracking
async function deployWithTracking(cloudAssemblySource: any) {
  try {
    // Synthesize the cloud assembly
    const cloudAssembly = await toolkit.synth(cloudAssemblySource);

    try {
      // Deploy using the cloud assembly
      await toolkit.deploy(cloudAssembly, {
        stacks: {
          strategy: StackSelectionStrategy.ALL_STACKS
        }
      });
    } finally {
      // Always dispose when done
      await cloudAssembly.dispose();
    }
  } catch (error) {
    // Display the error message
    console.error("Operation failed:", error.message);
    throw error;
  }
}

使用復原處理錯誤

使用復原策略實作強大的錯誤處理：

import { Toolkit, ToolkitError, StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

async function deployWithRetry(toolkit: Toolkit, cloudAssemblySource: any) {
  try {
    // Synthesize the cloud assembly
    const cloudAssembly = await toolkit.synth(cloudAssemblySource);

    try {
      // Deploy using the cloud assembly
      await toolkit.deploy(cloudAssembly, {
        stacks: {
          strategy: StackSelectionStrategy.ALL_STACKS
        }
      });
    } finally {
      // Always dispose when done
      await cloudAssembly.dispose();
    }
  } catch (error) {
    // Simply show the error to the user
    console.error("Operation failed:", error.message);
    throw error;
  }
}

// Example usage
try {
  await deployWithRetry(toolkit, cloudAssemblySource);
} catch (error) {
  console.error("Operation failed:", error.message);
  process.exit(1);
}

與 CI/CD 管道整合

將 CDK Toolkit Library 整合到 CI/CD 管道：

import { Toolkit, StackSelectionStrategy, IIoHost } from '@aws-cdk/toolkit-lib';
import * as fs from 'fs';
import * as path from 'path';

async function cicdDeploy() {
  // Create a non-interactive toolkit for CI/CD environments
  const toolkit = new Toolkit({
    ioHost: {
      notify: async (msg) => {
        // Write to both console and log file
        const logMessage = `${msg.time} [${msg.level}] ${msg.message}`;
        console.log(logMessage);

        // Append to deployment log file
        fs.appendFileSync('deployment.log', logMessage + '\n');
      },
      requestResponse: async (msg) => {
        // Always use default responses in CI/CD
        console.log(`Auto-responding to: ${msg.message} with: ${msg.defaultResponse}`);
        return msg.defaultResponse;
      }
    } as IIoHost
  });

  // Determine environment from CI/CD variables
  const environment = process.env.DEPLOYMENT_ENV || 'development';

  // Load environment-specific parameters
  const paramsPath = path.join(process.cwd(), `params.${environment}.json`);
  const parameters = fs.existsSync(paramsPath)
    ? JSON.parse(fs.readFileSync(paramsPath, 'utf8'))
    : {};

  try {
    // Use pre-synthesized cloud assembly from build step
    const cloudAssemblySource = await toolkit.fromAssemblyDirectory('cdk.out');

    // Synthesize the cloud assembly
    const cloudAssembly = await toolkit.synth(cloudAssemblySource);

    try {
      // Deploy with CI/CD specific options
      const result = await toolkit.deploy(cloudAssembly, {
        stacks: { strategy: StackSelectionStrategy.ALL_STACKS },
        parameters,
        tags: {
          Environment: environment,
          BuildId: process.env.BUILD_ID || 'unknown',
          CommitHash: process.env.COMMIT_HASH || 'unknown'
        }
      });

      // Write outputs to a file for subsequent pipeline steps
      fs.writeFileSync(
        'stack-outputs.json',
        JSON.stringify(result.outputs, null, 2)
      );

      return result;
    } finally {
      // Always dispose when done
      await cloudAssembly.dispose();
    }
  } catch (error) {
    // Display the error message
    console.error("Operation failed:", error.message);
    process.exit(1);
  }
}

// Run the CI/CD deployment
cicdDeploy().then(() => {
  console.log('CI/CD deployment completed successfully');
});

其他資源

如需這些範例中使用之特定元件的詳細資訊，請參閱：