Skip to main content

让开发人员使用 Gitops 丰富服务内容

本指南只需 10 分钟即可完成，旨在展示 Port 在使用 Gitops 时的灵活性。

先决条件
  • 本指南假定您已拥有 Port 账户，并已完成onboarding process 。我们将使用Onboarding过程中创建的 "服务 "蓝图。
  • 您需要一个 Git 仓库(Github、GitLab 或 Bitbucket)，您可以在其中放置我们将在本指南中使用的工作流/Pipelines。如果没有，建议创建一个名为 "Port-actions "的新仓库。

本指南的目标​

在本指南中，我们将使用 Gitops 丰富 Port 中的一项服务。 实际上，开发人员可以利用这一点，独立地为 Port 添加有关其服务的更多有价值的数据。

完成这项工作后，你就会了解它如何使你的组织中的不同角色受益:

  • 开发人员将能够丰富自己的服务，而无需唠叨开发工程师。
  • 平台工程师将能够为开发人员创建受 RBAC 控制的操作，增强他们的独立性。
  • 研发经理将能够跟踪有关组织内服务的更多有价值的数据。

为你的 Service 蓝图添加新属性​

让我们先在 Service蓝图中添加两个新属性，稍后我们将使用 Gitops 填充这两个属性。

  1. 进入Builder ，展开 "服务 "蓝图，点击 "新建属性"。
  2. 第一个属性将是从预定义选项列表中选择的服务类型。像这样填写表格，然后点击 "创建":


3.第二个属性是服务的生命周期状态，也是从预定义的选项列表中选择的。像这样填写表格，然后点击 "创建":

注意输入的颜色，这将使您更容易在目录中看到服务的生命周期_ 😎



###您的服务的示范域

共享业务目的的服务(如支付、运输)通常使用域分组。 让我们创建一个蓝图来表示 Port 中的域:

  1. 在Builder 中，点击右上角的 "添加 "按钮，然后选择 "自定义蓝图":


2.点击右上角的 "编辑 JSON "按钮，用以下定义替换内容，然后点击 "创建":

Blueprint JSON (click to expand)
{
  "identifier": "domain",
  "title": "Domain",
  "icon": "TwoUsers",
  "schema": {
    "properties": {
      "architecture": {
        "title": "Architecture",
        "type": "string",
        "format": "url",
        "spec": "embedded-url"
      }
    },
    "required": []
  },
  "mirrorProperties": {},
  "calculationProperties": {},
  "relations": {}
}

将您的服务与它们的域连接起来​

现在我们有了一个代表域的蓝图，让我们把它连接到我们的服务。 我们将通过在 Service 蓝图中添加一个关系来实现这一点:

  1. 进入Builder ，展开 "服务 "蓝图，点击 "新建关系":


2.像这样填写表格，然后点击 "创建":



通过 Gitops 创建域名​

现在我们有了 "域 "蓝图，可以在 Port 中创建一些域。 这可以通过用户界面手动完成，也可以通过 Gitops 完成，本指南将采用这种方法。

  1. 在您的 Port-actions(或同等文件)Github 代码库中，在根目录下新建一个名为 port.yml 的文件，并使用以下代码段作为其内容:
port.yml (click to expand)
- identifier: payment
  title: Payment
  blueprint: domain
  properties:
    architecture: https://lucid.app/documents/embedded/c3d64493-a5fe-4b18-98d5-66d355080de3
- identifier: shipping
  title: Shipping
  blueprint: domain
  properties:
    architecture: https://lucid.app/documents/embedded/c3d64493-a5fe-4b18-98d5-66d355080de3

2.返回software catalog ，您会看到 Port 创建了两个新的 "域 "实体:

架构 "属性是指向 Lucidchart 图表的 URL。 这是一种在软件目录中跟踪域架构的便捷方法。


创建一个action来丰富服务​

作为平台工程师，我们希望让开发人员能够自行执行某些操作。 让我们创建一个操作，开发人员可以用它将数据添加到服务中，并将其分配到域中。

设置动作的前端​

Onboarding

作为Onboarding流程的一部分，您的self-service tab 中应该已经有一个名为 "丰富服务 "的操作。在这种情况下，您可以跳到Define backend type 步骤。

如果您跳过了***登录，或者您想从头开始创建操作，请完成以下步骤 1-5。

Create the action's frontend (steps 1-5)
  1. 进入Self-service page ，然后点击右上角的 "+ 新操作 "按钮。
  2. 从下拉菜单中选择 "服务 "蓝图。
  3. 像这样填写基本信息，然后点击下一步:


4.我们希望开发人员能够选择将服务分配给哪个域。点击 "新输入"，像这样填写表格，然后点击 "下一步":



5.让我们为新服务属性添加两个输入--"类型 "和 "生命周期"。创建两个新输入，像这样填写表格，然后单击 "下一步":




定义后端类型​

现在我们来定义动作的后端。 Port 支持多种引用类型，本教程中我们将使用 "Github 工作流"、"GitLab 管道 "或 "Jenkins 管道"(如果使用 Bitbucket，请选择此选项)。

  • 您需要在 Github 组织(包含您要使用的版本库的组织)中安装Port's Github app 。
  • 用您的 Values 替换 Organization 和 Repository 值(这是工作流将驻留和运行的位置)。
  • 将工作流命名为 portEnrichService.yaml。
  • 像这样填写表单的其余部分，然后单击 下一步:

最后一步是自定义动作的权限。 为简单起见，我们将使用默认设置。 欲了解更多信息，请参阅permissions 页面。 点击 "创建"。

设置动作的后端​

我们的操作将在服务的资源库中创建一个 pull-request，其中包含一个 port.yml 文件，该文件将向 Port 中的服务添加数据。 在下面选择后端类型以设置工作流:

  1. 首先，让我们创建必要的 token 和 secrets。如果您已经完成了scaffold a new service guide ，则应该已经配置了这些内容，可以跳过这一步。
  • 访问Github tokens page ，创建一个具有 repo 和 admin:org 范围的个人访问令牌，并将其复制(从我们的工作流中创建拉取请求需要该令牌) 。
  • 访问Port application ，点击右上角的"..."，然后点击 "凭据"。复制您的 客户 ID 和 客户 secret。

2.在Port-actions(或相应的)Github 代码库中，在Settings->Secrets and variables->Actions 下创建 3 个新secret:

  • ORG_ADMIN_TOKEN` - 您在上一步中创建的个人访问令牌。
  • PORT_CLIENT_ID - 从 Port 应用程序复制的客户端 ID。
  • PORT_CLIENT_SECRET` - 从 Port 应用程序复制的客户机secret。

现在我们将创建一个 YML 文件，作为服务的 port.yml 配置文件的模板。

  • 在版本库的 /templates/下创建一个名为 enrichService.yml 的文件(其路径应为 /templates/enrichService.yml)。
  • 复制以下代码段并粘贴到文件内容中:
enrichService.yml (click to expand)
# enrichService.yml

- identifier: "{{ service_identifier }}"
  blueprint: service
  properties:
    type: "{{ service_type }}"
    lifecycle: "{{ service_lifecycle }}"
  relations:
    domain: "{{ domain_identifier }}"

现在，让我们创建一个包含逻辑的文件:

在.github/workflows下的同一版本库中，新建一个名为portEnrichService.yml的文件，并将以下代码段作为其内容:

Github workflow (click to expand)
name: Enrich service
on:
  workflow_dispatch:
    inputs:
      domain:
        required: true
        description: The domain to which the service will be assigned
        type: string
      type:
        required: true
        description: The service's type
        type: string
      lifecycle:
        required: true
        description: The service's lifecycle
        type: string
      port_payload:
        required: true
        description: Port's payload, including details for who triggered the action and general context
        type: string
jobs:
  enrichService:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/checkout@v3
        with:
          repository: "${{ github.repository_owner }}/${{fromJson(inputs.port_payload).context.entity}}"
          path: ./targetRepo
          token: ${{ secrets.ORG_ADMIN_TOKEN }}
      - name: Copy template yml file
        run: |
          cp templates/enrichService.yml ./targetRepo/port.yml
      - name: Update new file data
        run: |
          sed -i 's/{{ service_identifier }}/${{fromJson(inputs.port_payload).context.entity}}/' ./targetRepo/port.yml
          sed -i 's/{{ domain_identifier }}/${{ inputs.domain }}/' ./targetRepo/port.yml
          sed -i 's/{{ service_type }}/${{ inputs.type }}/' ./targetRepo/port.yml
          sed -i 's/{{ service_lifecycle }}/${{ inputs.lifecycle }}/' ./targetRepo/port.yml
      - name: Open a pull request
        uses: peter-evans/create-pull-request@v5
        with:
          token: ${{ secrets.ORG_ADMIN_TOKEN }}
          path: ./targetRepo
          commit-message: Enrich service - ${{fromJson(inputs.port_payload).context.entity}}
          committer: GitHub <[email protected]>
          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
          signoff: false
          branch: add-port-yml
          delete-branch: true
          title: Create port.yml - ${{fromJson(inputs.port_payload).context.entity}}
          body: |
            Add port.yaml to enrich service in Port.
          draft: false
      - name: Create a log message
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          operation: PATCH_RUN
          runId: ${{fromJson(inputs.port_payload).context.runId}}
          logMessage: Pull request to add port.yml created successfully for service "${{fromJson(inputs.port_payload).context.entity}}" 🚀

该操作已准备就绪 🚀

执行操作​

  1. 创建动作后，它将出现在Self-service page 下。找到新的 "丰富服务 "动作，点击 "执行"。
  2. 从下拉菜单中选择一个服务、一个要将其分配给的域，以及其类型和生命周期的任何 Values，然后单击执行:


3.弹出一个小窗口，点击 "查看详情":



该页面提供了操作运行的详细信息。 我们可以看到后端返回了 "Success"(成功)，拉取请求已成功创建。

4.前往你的服务仓库，你会看到创建了一个新的拉取请求:


5.合并拉取请求，然后返回software catalog 。 6.找到您的服务，点击其标识符。这将带您进入服务的目录页面，在那里您可以看到用数据填充的新属性:



全部完成！ 💪🏽

可能的日常整合​

  • 从 Sentry 项目中获取数据并反映在软件目录中。
  • 只需从开发人员门户点击几下，即可创建和上线服务。

结论​

Gitops 是现代软件开发中的一种常见做法，因为它能确保基础架构的状态始终与代码库同步。 Port 可让您轻松地将 Gitops 实践与软件目录集成，反映基础架构的状态，并允许您通过受控操作赋予开发人员权力。

更多指南和教程即将推出，在此期间如有任何问题，请随时通过community slack 或Github project 联系我们。