theonestack/cfhighlander

Cfhighlander Docker镜像文档

镜像概述和主要用途

Cfhighlander是一款面向CloudFormation模板开发者的功能丰富的DSL工具，旨在通过组件化方式简化AWS基础设施的编码工作。它允许开发者将AWS资源或资源集抽象为组件，通过Cfhighlander DSL和https://github.com/cfndsl/cfndsl%E8%BF%9B%E8%A1%8C%E6%8F%8F%E8%BF%B0%EF%BC%8C%E6%94%AF%E6%8C%81%E7%BB%84%E4%BB%B6%E7%9A%84%E7%BB%A7%E6%89%BF%E4%B8%8E%E7%BB%84%E5%90%88%EF%BC%8C%E5%AE%9E%E7%8E%B0%E6%A8%A1%E6%9D%BF%E7%9A%84%E9%AB%98%E6%95%88%E7%94%9F%E6%88%90%E3%80%81%E9%AA%8C%E8%AF%81%E5%92%8C%E5%8F%91%E5%B8%83%E3%80%82

核心功能和特性

• 组件化抽象：将AWS资源或资源集抽象为可复用组件，通过DSL进行定义和配置
• 继承与组合：支持组件的扩展（继承）和嵌套（组合），实现复杂基础设施的模块化构建
• 多源组件发现：支持从本地文件系统、Git仓库、S3桶等多源发现和使用组件
• 描述性DSL：相比指令式方法，提供更具描述性的DSL语法，简化模板编写
• 自动化参数传递：自动处理组件间参数传递，无需手动编写跨栈引用代码
• 多阶段处理：通过配置处理、参数连接、Cfndsl模板生成、CloudFormation模板生成四个阶段构建最终模板

使用场景和适用范围

适用于需要管理复杂AWS基础设施的开发者，尤其适合：

• 构建可复用的CloudFormation组件库
• 管理多环境（开发、测试、生产）的基础设施配置
• 实现基础设施即代码（IaC）的模块化和标准化
• 简化跨栈资源依赖管理和参数传递

详细使用方法和配置说明

安装方法

通过RubyGems安装：

shell
gem install cfhighlander

基本使用示例

创建application.cfhighlander.rb文件：

ruby
CfhighlanderTemplate do
  # 显式配置VPC组件
  vpc_config = { 'maximum_availability_zones' => 2 }

  # 声明VPC组件并传递参数
  Component name: 'vpc',
        template: 'vpc@master.snapshot',
        config: vpc_config do
    parameter name: 'Az0', value: FnSelect(0, FnGetAZs())
    parameter name: 'Az1', value: FnSelect(1, FnGetAZs())
    parameter name: 'DnsDomain', value: 'example.com'
    parameter name: 'StackMask', value: '16'
  end

  # 编译后的CloudFormation模板会自动将VPC的计算子网传递给ECS集群
  Component name: 'ecs', template:'ecs@master.snapshot' do
    parameter name: 'DnsDomain', value: 'example.com'
  end

  # 添加环境类型映射
  addMapping('EnvironmentType',{
    'development' => {
      'MaxNatGateways'=>'1',
      'EcsAsgMin' => 1,
      'EcsAsgMax' => 1,
      'KeyName' => 'default',
      'InstanceType' => 't2.large',
      'SingleNatGateway' => true
    }
  })
end

编译模板：

shell
cfcompile application

查看生成的模板中自动处理的子网参数传递：

shell
cat out/yaml/application.compiled.yaml | grep  -A3 SubnetCompute0

组件库

theonestack组织提供了多个公开可用的组件：

• https://github.com/theonestack/hl-component-vpc - 包含公有和私有子网分离，可配置NAT网关数量
• https://github.com/theonestack/hl-component-ecs - 部署在VPC计算子网中的ECS集群
• https://github.com/theonestack/hl-component-bastion - 部署在VPC公有子网的堡垒机
• https://github.com/theonestack/hl-component-ecs-service - 在ECS集群上部署容器化应用
• https://github.com/theonestack/hl-component-load*** - ALB、ELB或NLB负载均衡器
• https://github.com/theonestack/hl-component-sns - SNS主题，包含发送Slack消息的Lambda函数
• https://github.com/theonestack/hl-component-efs - 可与ECS集群配合使用的弹性文件系统
• https://github.com/theonestack/hl-component-rds-mysql - MySQL引擎的RDS组件
• https://github.com/theonestack/hl-component-rds-postgres - PostgreSQL引擎的RDS组件
• https://github.com/theonestack/hl-component-aurora-mysql - MySQL兼容的Aurora组件
• https://github.com/theonestack/hl-component-aurora-postgres - PostgreSQL兼容的Aurora组件
• https://github.com/theonestack/hl-component-elasticache-memcache - Memcache引擎的ElastiCache组件
• https://github.com/theonestack/hl-component-elasticache-redis - Redis引擎的ElastiCache组件
• https://github.com/theonestack/hl-component-asg - 自动扩展组组件
• https://github.com/theonestack/hl-component-cognito - Cognito用户池、自定义域名和客户端

工作原理

Cfhighlander DSL通过四个阶段生成CloudFormation模板：

1. 处理引用组件的配置并解析配置导出
2. 将参数从组件连接到其内部组件
3. 为所有组件和子组件生成Cfndsl模板作为中间步骤
4. 使用前两个阶段生成的配置和模板生成最终的CloudFormation模板

命令行使用

安装后可通过cfhighlander命令使用，主要命令包括：

bash
cfhighlander commands:
  cfhighlander cfcompile component[@version] -f, --format=FORMAT   # 编译Highlander组件为CloudFormation模板
  cfhighlander cfpublish component[@version] -f, --format=FORMAT   # 发布CloudFormation模板及其引用的子组件
  cfhighlander configcompile component[@version]                   # 编译Highlander组件配置
  cfhighlander dslcompile component[@version] -f, --format=FORMAT  # 编译组件配置并创建cfndsl模板
  cfhighlander help [COMMAND]                                      # 显示命令帮助
  cfhighlander publish component[@version] [-v published_version]  # 发布组件源代码

关键命令说明

• cfcompile：生成指定格式（默认yaml）的CloudFormation模板，可通过--validate选项验证模板

  shell
  cfcompile application --format yaml --validate
  

• cfpublish：生成并发布模板到S3，自动创建启动CloudFormation栈的URL

  shell
  cfpublish vpc@1.2.0 --dstbucket my-templates-bucket --dstprefix published-templates
  

组件配置层级

组件配置有四个层级（优先级从低到高）：

1. 组件本地配置文件：component.config.yaml
2. 外部组件配置文件：外部组件的配置文件中通过components键或单独的component.config.yaml文件
3. 外部组件显式配置：通过Component语句的config参数
4. 其他组件导出的配置：通过config_export导出的全局或组件特定配置

组件DSL核心语法

声明组件

ruby
CfhighlanderTemplate do
  # 基本用法
  Component 'vpc'
  
  # 指定版本和名称
  Component name: 'ecs_cluster', template: 'ecs@master.snapshot'
  
  # 条件组件（功能开关）
  Component name: 'optional_bastion', template: 'bastion', conditional: true, enabled: false
end

参数定义

ruby
CfhighlanderTemplate do
  Parameters do
    # 组件参数（可从外部组件传入或自动连接）
    ComponentParam 'BucketName', 'default-value', isGlobal: true
    
    # 映射参数（从外部组件映射中获取值）
    MappingParam 'InstanceType' do
      map 'EnvironmentType'
      key 'Environment'
      attribute 'InstanceType'
    end
  end
end

组件渲染模式

• Substack模式（默认）：为组件创建独立的CloudFormation子栈
• Inline模式：将组件资源内联到外部组件模板中

ruby
# Inline模式示例
Component name: 'vpc', template: 'vpc@latest', render: 'Inline'