写点什么

平台工程: 用 Backstage 构建开发者门户 - 1

作者:俞凡
  • 2024-01-27
    上海
  • 本文字数:4993 字

    阅读完需:约 16 分钟

本文介绍了如何使用开源 Backstage 构建自己的开发者门户,并基于此实践平台工程。原文: Platform Engineering: Building Your Developer Portal with Backstage — Part 1



在上一篇文章(平台工程与安全)中,我们介绍了什么是平台工程,为何如此重要,和 DevOps 做了比较,以及介绍了平台工程如何帮助提高安全性。


今天我们来动手从头开始构建一个开发者门户。

1. 当我们谈论开发者门户时,我们在谈论什么

由于平台工程都是自助服务的,内部开发者门户在新范式中至关重要,在该范式中实现了所有自助服务功能和集成。


考虑到开发者门户的重要性,在构建之前,需要弄清楚我们对它的期望到底是什么。通常,为了最大限度利用平台工程,开发者门户将包含一些关键功能,例如:


  • 服务目录: 让开发人员可以鸟瞰所有项目、服务、部署状态、文档、所有权,甚至是值班计划和事件等;

  • 某种资源库脚手架/项目生成工具: 例如 Cookiecutter 这样的工具,能让开发人员从门户网站直接启动新服务;

  • 定制: 也许你希望将使用的任何工具链集成到开发者门户中,使其成为真正统一的一站式体验,可能的集成包括 Kubernetes、CI/CD 状态、值班计划、事件管理系统、secrets 管理器等。


此时,门户网站可以处理一切事务,如获取服务信息、待命计划、触发事件、部署工作以及处理事件管理。有了这些功能,开发人员就能获得真正统一的体验,在一个地方创建服务,随后跟踪和操作/维护这些服务,最大限度的发挥开发者门户的潜力。

2. 选择工具:Backstage

既然知道了开发者门户网站的真正需求,那就来构建吧。


由于它将具有多种功能,设计/编码部分本身就是一个庞大的项目,不是所有团队都能承担得起。因此需要一个工具来快速构建门户网站,幸运的是,我们已经有了这样的工具--Backstage


Backstage 是用于构建开发者门户网站的开放平台。Backstage 本身并不是开发者门户,而是用于构建开发者门户的工具。想想"create-react-app"和用它创建的实际 react 应用的区别就知道了。开箱即用的 Backstage 包括:


  • 软件目录: 用于管理所有软件,如微服务、库、数据管道、网站和 ML 模型;

  • 软件模板: 用于快速启动新项目,并根据组织的最佳实践对工具进行标准化;

  • 文档: 采用"像编写代码一样编写文档"的方法,轻松创建、维护、查找和使用技术文档;

  • 不断发展的开源插件生态系统,进一步扩展了 Backstage 的可定制性和功能。


Backstage 的架构非常灵活: 前端使用 React/TypeScript 编写,后端使用 Node.js,还可以通过添加插件来扩展功能。


更重要的是,Backstage(由 Spotify 创建)现在由云原生计算基金会(CNCF)作为孵化级项目托管,这意味着我们可以获得想要的所有社区支持。它还设有办公时间,可以在每周四参加互动,准确了解开源平台如何提高开发人员的效率和体验。


说得够多了。今天我们将从头开始,自己构建一个开发者门户。完成本教程后,可以使用带有内置安全 CI 工作流的模板来引导一个新服务,检查 CI 状态,并在同一个地方查看该服务的文档。


废话少说,开始吧。

3. 构建门户网站

3.1. 前提条件

不多,可能所有 DevOps 工程师都已经具备:


  • 基于 Unix 的操作系统。例如,可以在 macOS、Linux 或 Windows Subsystem for Linux (WSL) 上运行。

  • curl、git、Docker

  • Node.js, yarn

3.2. 创建门户网站

运行:


npx @backstage/create-app@0.5.2-next.3
复制代码


作者注:

我们之所以使用 backstage/create-app@0.5.2-next.3 而不是 backstage/create-app@latest,是因为我们需要这项功能在 GitHub 中创建 secrets,以便在 GitHub Actions 工作流中使用。该功能已经开发完成,但截至目前(2023 年 6 月 18 日),尚未集成到最新版本的 backstage/create-app 中。

如果稍后阅读本文时,最新版本已指向 2023 年 6 月(或更晚)发布的版本,就可以安全的运行 npx @backstage/create-app@latest 而无需指定奇怪的版本。


该命令提供互动模式,只需要输入名称,例如 "my-portal",回车,然后等待应用程序完成。


进入目录并运行:


yarn dev
复制代码


现在应该已经建立并运行了门户网站!就这么简单!现在可以浏览一下,感受一下软件目录、模板、文档和其他东西:



不过目前还没什么用。我们继续配置。

4. GitHub 认证与集成

由于开发者门户将负责引导新仓库,因此需要 GitHub 的操作权限,这也是我们需要进行 GitHub 认证和集成的原因。

4.1. 用于集成的个人访问令牌

虽然使用 GitHub 应用程序可能是设置集成的最佳方式,因为它的权限设置非常精细,但在本教程中,我们将使用个人访问令牌,以便更快开始使用:


  • 打开 GitHub 令牌创建页面,创建个人访问令牌。

  • 使用一个名称来标识此令牌,并将其写入备注栏,选择过期天数。

  • 如果很难选择特定数字,建议选择 7 天,这是一个幸运数字:)。(我们将只在本地进行测试,不会在生产环境中运行)。

  • 在本教程中,我们先将范围设置为最大,这样就不会因为纠结于 GitHub 权限而影响体验。不过请注意,千万不要在生产环境中这样做!


然后,将令牌作为环境变量导出:


export GITHUB_TOKEN=xxx
复制代码


app-config.yaml 文件中,将 integrations 部分更改为以下内容:


integrations:  github:    - host: github.com      token: ${GITHUB_TOKEN} # leave it like this, read values from env var
复制代码
4.2. 创建 GitHub OAuth 应用程序

访问 https://github.com/settings/applications/new 创建 OAuth 应用程序。主页 URL 应指向 Backstage 的前台,在本教程中是 http://localhost:3000。授权回调 URL 将指向授权后台,很可能是 http://localhost:7007/api/auth/github/handler/frame。



然后,再次打开 app-config.yaml 文件,将 auth 部分更新为以下内容,配置身份验证:


auth:  environment: development  providers:    github:      development:        clientId: YOUR CLIENT ID # put your values here        clientSecret: YOUR CLIENT SECRET # put your values here
复制代码


请注意,将客户端 secrets 作为硬编码 secrets 存储在配置文件中有违安全最佳实践,只能用于本地开发。对于生产使用,我们可以按照 12 要素应用规则,从环境变量中读取。


更改配置后,必须停止 yarn dev 服务器并重新运行 yarn dev

5. 创建模板

接下来准备软件模板,用于快速启动一项新服务。


模板应包含以下内容:


  • 服务通用的基本源代码/目录结构

  • 一些文档

  • 测试/构建/部署服务的 CI 工作流


本教程将以我创建的模板 https://github.com/IronCore864/backstage-test-template 为例。


目录结构相对简单,只有两个部分:


  • 一个 skeleton 文件夹

  • 一个 template.yaml 文件

5.1. skeleton 文件夹

skeleton文件夹包含使用此模板创建新服务时将呈现的所有模板,变量的格式为 ${{ values.varName }}


如果你熟悉 Helm、YAML 或 Go 模板(或几乎所有模板工具),你会发现这种格式很容易阅读和理解,而且没有额外开销。


唯一值得一提的是 Backstage 使用的名为 catalog-info.yaml 的文件,该文件必须存在,否则就无法将创建的服务注册为门户中的组件。


如你所见,在模板中已经内置了一些 GitHub Actions 工作流,其中一个将测试拉取请求并推送到主分支,另一个将使用 ggshield 扫描软件仓库中的硬编码 secrets。


这样我们就可以将所有的 CI/CD 最佳实践放入模板中,当其他人启动新服务时,就已经拥有了所需的一切,并默认启用了安全功能。

5.2. template.yaml 文件

template.yaml 文件定义了模板在门户界面中的外观和实际操作。


文件很长,乍一看似乎让人不知所措,但一旦仔细阅读,就会发现它非常简单明了:


  • 语法类似于 Kubernetes 的自定义资源;

  • 有两大部分,一部分是参数,另一部分是步骤;

  • 参数定义了使用该模板时所需的输入及其类型;

  • 步骤定义了执行该模板时实际发生的情况,看起来非常像 GitHub 的 Actions 工作流。


参数示例:


parameters:  - title: Provide some simple information    required:      - service_name      - owner    properties:      service_name:        title: Name        type: string        description: Unique name of the service.        ui:field: EntityNamePicker      description:        title: Description        type: string        description: Help others understand what this service is for; optional.      owner:        title: Owner        type: string        description: Owner of the component        ui:field: OwnerPicker        ui:options:          allowedKinds:            - Group  ...
复制代码


步骤示例:


steps:
- id: template name: Fetch Skeleton + Template action: fetch:template input: url: ./skeleton copyWithoutTemplating: - .github/workflows/\* values: serviceName: ${{ parameters.service_name }} description: ${{ parameters.description }} destination: ${{ parameters.repoUrl | parseRepoUrl }} owner: ${{ parameters.owner }} ...
复制代码


我们可以从上述文件中推断出它究竟定义了什么:


  • 首先需要输入两个输入参数: 服务名称(service_name)和所有者(owner);

  • 需要选择一个带有额外参数(GITGUARDIAN_API_KEY,用于 CI 流水线)的版本库位置;

  • 然后,它会获取模板、渲染模板、将模板发布到 GitHub 并在我们的门户网站上注册。

5.3. 注册模板

最后,把模板添加到门户目录中,这样其他人就可以使用这个模板了。


目录最直接的配置是声明添加指向 YAML 文件的位置,并进行静态位置配置。位置会添加到 app-config.yaml 文件的 catalog.locations 关键字下的目录中:


catalog:  locations:    - type: url      target: https://github.com/IronCore864/backstage-test-template/blob/main/template.yaml      rules:        - allow: [Template]
复制代码


上述规则允许我们从指定的 URL 添加模板。


记得重启 yarn dev 服务器。

6. 把所有东西放在一起

现在,我们已经准备好了一切,是时候一睹魔法的风采了。


访问 http://localhost:3000,点击 "Create" 按钮,选择我们的模板:



输入必要信息。关于 GitGuardian API 密钥,请在此处创建:https://dashboard.gitguardian.com/api/personal-access-tokens


一切就绪后,点击 "下一步",神奇的事情就会发生:



现在一切都应该创建好了。


我们可以在目录中查看:



我们还创建并提供了文档:



最后看看 CI 的状态:



流水线似乎已经成功完成,我们可以点击查看更多细节,包括详细步骤和日志。如果你更喜欢在 CI 软件(这里是 GitHub Actions)中查看,可以点击相应链接跳转。


上述示例完整源码可以参考Github仓库


这意味着无论团队使用什么工具链,团队成员都不必记住 10 个不同工具的 10 个不同 URL,也不必一直打开这 10 个标签页。当他们需要某些信息时,只要进入开发者门户,就能获得所有信息,这正是内部开发者门户的强大之处。

7. 小结

在教程的第一部分,我们介绍了开发者门户网站的功能,学习如何使用开源 Backstage 工具创建自己的门户网站,使用 GitHub 配置门户网站,创建软件模板,并从中启动一项服务。


如果集成越来越多,开发者门户的功能可能远不止于此。想象一下,如果你在 Kubernetes 中部署服务,使用 Argo CD 进行 GitOps 部署,使用 HashiCorp Vault 进行 secrets 管理,而所有都集成在门户中。当你需要检查部署状态时,当你想查看 K8s 中的实际资源时,不必访问 Vault、Argo CD 和 K8s Dashboard。你甚至不必记住它们的 URL,甚至不知道这些东西的存在,因为有一个工具可以统治它们,那就是开发者门户。


本教程仅适用于本地快速启动,在生产中使用时有许多问题需要考虑。例如,我们现在使用的是静态配置,没有什么是持久化的,如果重新启动开发服务器,目录信息就会丢失。为此,我们需要为门户配置 Postgres。再比如,我们使用 "yarn dev"来启动前端和后端,对于生产应用,可能希望将前端和后端分开,将它们作为容器部署在 K8s 中,并为它们创建 Ingress 等。


在本教程的下一部分,我们将了解 Backstage 插件的机制,看看如何将其功能扩展到更高水平。




你好,我是俞凡,在 Motorola 做过研发,现在在 Mavenir 做技术工作,对通信、网络、后端架构、云原生、DevOps、CICD、区块链、AI 等技术始终保持着浓厚的兴趣,平时喜欢阅读、思考,相信持续学习、终身成长,欢迎一起交流学习。为了方便大家以后能第一时间看到文章,请朋友们关注公众号"DeepNoMind",并设个星标吧,如果能一键三连(转发、点赞、在看),则能给我带来更多的支持和动力,激励我持续写下去,和大家共同成长进步!

发布于: 2024-01-27阅读数: 3
用户头像

俞凡

关注

公众号:DeepNoMind 2017-10-18 加入

俞凡,Mavenir Systems研发总监,关注高可用架构、高性能服务、5G、人工智能、区块链、DevOps、Agile等。公众号:DeepNoMind

评论

发布
暂无评论
平台工程: 用Backstage构建开发者门户 - 1_平台工程_俞凡_InfoQ写作社区