fivestarsos/aladdin

Aladdin

什么是Aladdin？

Aladdin受《阿拉丁神灯》启发，是Fivestars构建的命令行工具，旨在简化Kubernetes集群管理与应用开发操作。它整合了kops、k3d、docker、kubectl、helm、awscli和git等多种命令行工具，提供一站式Kubernetes操作体验。

使用Aladdin可实现：

• 创建和管理AWS Kubernetes集群
• 升级AWS Kubernetes集群
• 跨不同环境（含本地）运行和部署组织应用，并支持环境特定配置
• 对应用执行操作类命令（如将应用置于维护模式）

Aladdin工作原理

Aladdin包含两个主要组件：一个运行在主机机器上，另一个在Docker容器中运行，由主机组件启动。

主机组件职责：

• 解析命令行选项
• 执行需在主机运行的命令
• 检查并警告缺失的依赖，或在可能时将依赖安装到~/.aladdin/bin
• 启动k3d（运行Aladdin前确保Docker引擎已启动！）
• 拉取Aladdin镜像
• 运行Aladdin Docker容器（容器组件）

容器组件职责：

• 执行管理AWS Kubernetes集群的命令
• 执行在Kubernetes集群上部署和操作应用的命令

脚本图/架构

[架构图示意，原链接：diagram/diagram.png]

安装Aladdin

只需克隆Aladdin GitHub仓库即可开始设置：

bash
$ git clone git@github.com:fivestars-os/aladdin.git
$ cd aladdin
$ scripts/infra_k8s_check.sh

infra_k8s_check.sh脚本会检查Aladdin的所有依赖是否已安装。根据依赖类型，脚本会警告缺失项，或在可能时将其安装到~/.aladdin/bin。每次运行Aladdin时也会执行此脚本。

推荐使用安装脚本安装Aladdin：

bash
$ ./install-aladdin

该脚本会安装https://github.com/pipxproject/pipx%EF%BC%8C%E5%B9%B6%E9%80%9A%E8%BF%87pipx%E5%9C%A8%E7%8B%AC%E7%AB%8B%E8%99%9A%E6%8B%9F%E7%8E%AF%E5%A2%83%E4%B8%AD%E5%AE%89%E8%A3%85Aladdin%E3%80%82

建议将~/.aladdin/bin添加到环境变量PATH：

bash
$ export PATH=$PATH:~/.aladdin/bin

可将上述命令添加到个人配置文件（如.bashrc、.zshrc）中。

安装后需创建Aladdin配置并链接：

bash
$ aladdin config set config_dir /path/to/aladdin/configuration

配置管理

软件依赖

Aladdin会安装所需软件（如helm、jq、aws cli等）。若符合以下情况，可禁用自动安装：

1. 已有机器配置管理流程
2. 希望继续使用现有工具（脚本、ansible playbook等）
3. 不希望Aladdin安装任何软件

执行以下命令禁用：

bash
aladdin config set manage.software_dependencies false

k3d

Aladdin使用k3d支持本地开发。

本地集群资源配置

当前需通过Docker Desktop UI配置CPU、内存和磁盘：进入偏好设置→资源。推荐配置：2 CPU、8GB内存、60GB磁盘。

创建和管理AWS Kubernetes集群

相关功能已封装在aladdin cluster命令中。

应用与Aladdin集成

需在应用源代码中添加部分配置以集成Aladdin。我们提供了aladdin-demo项目，演示集成步骤及Kubernetes应用开发最佳实践，也可用于验证Aladdin安装是否正常。详见https://github.com/fivestars-os/aladdin-demo%E3%80%82

项目开发

Aladdin提供多个用于开发和部署的命令。执行命令时，需通过-n（命名空间）和-c（集群）标志显式或隐式指定目标。

Aladdin本地开发命令

• aladdin build：本地构建项目Docker镜像（本地标签）
• aladdin start：本地安装或更新项目
• aladdin stop：本地卸载项目
• aladdin restart：本地卸载并重新安装项目
• aladdin publish：将项目Docker镜像推送到ECR，Helm包推送到S3，用于非本地环境部署

Aladdin非本地命令

• aladdin deploy：部署到远程非本地集群
• aladdin undeploy：从远程非本地集群移除项目
• aladdin rollback：回滚到之前的部署版本

Aladdin本地与非本地通用命令

• aladdin cmd：对项目执行命令（如进入维护模式）
• aladdin environment：获取或操作配置映射（ConfigMap）
• aladdin refresh：执行空部署，用于重启部署中的所有Pod
• aladdin scale：调整部署的副本数
• aladdin connect：连接到容器的shell

示例开发工作流

bash
git clone git@github.com:{git账号名}/{项目仓库名}.git
cd {项目仓库名}
git checkout -b {功能分支}
aladdin build
aladdin start
# 开发工作
git commit -m "描述" && git push origin {功能分支}
aladdin publish  # 推送镜像和Helm包，记录哈希值
aladdin -c {远程集成集群} -n {个人命名空间} deploy {项目仓库名} {上述哈希值}
# 应用访问地址：{服务名}.{命名空间}.{集群根域名} 或 {服务名}.{service_dns_suffix}（若配置）
# 测试验证
# 合并功能分支到master
git checkout master && git pull origin master
aladdin publish  # 记录新哈希值
aladdin -c {生产集群} deploy {项目仓库名} {新哈希值}
# 必要时回滚：aladdin -c {生产集群} rollback {项目仓库名}

Aladdin可选参数

• -h/--help：显示帮助信息
• -c/--cluster：指定集群，默认LOCAL
• -n/--namespace：指定命名空间，默认default
• --init：强制初始化（拉取最新Aladdin镜像、测试AWS配置、初始化Helm等），每小时对每个集群/命名空间组合自动强制一次
• --dev：将主机Aladdin目录挂载到容器，用于Aladdin开发
• --skip-prompts：跳过执行过程中的确认提示，适用于自动化命令
• --non-terminal：非终端模式运行Aladdin容器

在同一集群/命名空间组合中运行多个Aladdin命令

Aladdin支持在同一集群/命名空间组合中运行多个命令，无需重复初始化。通过aladdin bash进入容器shell，所有容器命令会被别名化，无需前缀aladdin：

bash
$ aladdin bash
     . . .
Launching bash shell. Press CTRL+D to exit.
此shell包含多个辅助函数
可参考aladdin中的scripts/bash_profile.bash
LOCAL:default> build  # 等效于aladdin build
Building aladdin-demo docker image (~30秒)
docker build -t aladdin-demo:local -f app/Dockerfile .
Sending build context to Docker daemon  28.16kB
     . . .
Successfully tagged aladdin-demo-commands:local
LOCAL:default> start  # 等效于aladdin start
INFO:Found cluster values file
     . . .
LOCAL:default> refresh aladdin-demo-server  # 等效于aladdin refresh aladdin-demo-server
INFO:Refreshing deployment aladdin-demo-server
LOCAL:default>

测试

Aladdin提供端到端测试：aladdin test-local（本地测试）和aladdin test-remote（远程测试）。测试需配置文件，示例见https://github.com/fivestars-os/aladdin-e2e-tests-config%E3%80%82%E9%9C%80%E4%BF%AE%E6%94%B9%E9%85%8D%E7%BD%AE%E4%BB%A5%E5%85%81%E8%AE%B8%E5%9C%A8AWS%E8%B4%A6%E6%88%B7%E5%88%9B%E5%BB%BA/%E9%94%80%E6%AF%81%E4%B8%B4%E6%97%B6%E9%9B%86%E7%BE%A4%EF%BC%9A

bash
aladdin config set config_dir /path/to/your/e2e/tests/config
aladdin test-local
aladdin test-remote

贡献Aladdin的最佳方式之一是添加测试！

插件

Aladdin支持用户插件，目录结构需如下：

插件文件夹名/
  container/
    插件名-1/
      插件名-1（必须与目录名一致）
      插件名-1-helper-1
      插件名-1-helper-2
    插件名-2/
      插件名-2（必须与目录名一致）
    插件名-3/
      插件名-3（必须与目录名一致）
      插件名-3-helper-1
  host/
    插件名-4/
      插件名-4（必须与目录名一致）
      插件名-4-helper-1
      插件名-4-helper-2
    插件名-5/
      插件名-5（必须与目录名一致）
    插件名-6/
      插件名-6（必须与目录名一致）
      插件名-6-helper-1

配置并使用插件：

bash
aladdin config set plugin_dir /path/to/插件文件夹名
aladdin 插件名-2  # 执行插件2
aladdin 插件名-5  # 执行插件5

插件适用于添加个人常用轻量级辅助功能。若无法满足需求，可扩展Aladdin：创建自定义Docker镜像并更新配置使用该镜像。若插件具有普适性，建议提交PR集成到Aladdin主项目。

其他功能

命名空间级Ingress功能

Aladdin支持命名空间级Ingress功能（默认关闭）。推荐在共享开发集群中启用，以减少ELB数量。启用步骤：

1. 拉取https://github.com/fivestars-os/ingress-nginx%EF%BC%8C%E4%BF%AE%E6%94%B9values%E6%96%87%E4%BB%B6%E9%80%82%E9%85%8D%E7%BB%84%E7%BB%87%E9%9C%80%E6%B1%82%EF%BC%8C%E9%80%9A%E8%BF%87Aladdin%E6%8E%A8%E9%80%81%E5%88%B0ECR%E3%80%82
2. 在集群config.json中添加：

json
    "namespace_init": [
        {"project": "ingress-nginx", "ref": "<已推送的ref>"}
    ],
    "ingress_info": {
        "use_ingress_per_namespace": true,
        "ingress_controller_service_name": "ingress-nginx",
        "ingress_name": "ingress"
    }

namespace_init字段指示Aladdin在创建命名空间时安装ingress-nginx（远程集群需要，本地集群因k3d自带无需）。ingress_info字段配置Ingress同步。启用后，集群上的服务建议将服务类型设为NodePort（而非LoadBalancer），可在集群目录的values.yaml中添加：

yaml
  service:
    publicServiceType: "NodePort"

并在服务yaml中引用{{ service.publicServiceType }}。

故障排除

常见问题及解决方案