Geo self-service framework (alpha)

Geo self-service framework (alpha)

注意：本文档可能会随时更改. 这是我们正在研究的建议，一旦实施完成，此文档将得到更新. 跟随进度.注意： Geo 自助服务框架当前处于 Alpha 状态. 如果您需要复制新的数据类型，请与 Geo 小组联系以讨论选项. 您可以在 Slack 的与他们联系，或在问题或合并请求中提及@geo-team .

Geo 提供了一个 API，使跨 Geo 节点轻松复制数据类型成为可能. 该 API 以 Ruby 域特定语言（DSL）的形式呈现，旨在使创建数据类型的工程师只需花费很少的精力即可复制数据.

在深入研究 API 之前，开发人员需要了解一些特定于地理位置的命名约定.

Model

模型是活动模型，在整个 Rails 代码库中都是如此. 它通常与数据库表绑定. 从地理角度来看，模型可以具有一个或多个资源.

Resource

资源是属于模型的一条数据，由 GitLab 功能生成. 使用存储机制将其持久化. 默认情况下，资源不可复制.

Data type

Data type is how a resource is stored. Each resource should fit in one of the data types Geo supports: :- Git repository :- Blob :- Database

有关更多详细信息，请参见数据类型 .

Geo Replicable

可复制资源是 Geo 希望在 Geo 节点之间同步的资源. 受支持的可复制数据类型有限. 实现属于已知数据类型之一的资源的复制所需的工作量很小.

Geo Replicator

地理复制器是知道如何复制可复制对象的对象. 它负责：：-触发事件（生产者）：-消费事件（消费者）

它与 Geo Replicable 数据类型相关. 所有复制器都有一个公共接口，可用于处理（即产生和使用）事件. 它负责主节点（产生事件的地方）和次节点（消耗事件的地方）之间的通信. 想要将 Geo 纳入其功能的工程师将使用复制器的 API 来实现这一目标.

Geo Domain-Specific Language

语法糖使工程师可以轻松指定应复制哪些资源以及如何复制.

首先，您需要编写一个复制器. 复制器位于 . 对于每个需要复制的资源，即使多个资源绑定到同一模型，也应指定一个单独的复制器.

例如，以下复制器复制软件包文件：

类名应该是唯一的. 它还与注册表的表名紧密相关，因此在此示例中，注册表表将为package_file_registry .

要将此复制器绑定到模型，需要在模型代码中添加以下内容：

  1. class Packages::PackageFile < ApplicationRecord
  2.   include ::Gitlab::Geo::ReplicableModel
  4.   with_replicator Geo::PackageFileReplicator
  5. end

设置好后，可以通过模型轻松访问复制器：

  1. package_file = Packages::PackageFile.find(4) # just a random id as example
  2. replicator = package_file.replicator

或者从复制器取回模型：

  1. replicator.model_record
  2. => <Packages::PackageFile id:4>

复制器可用于生成事件，例如在 ActiveRecord 挂钩中：

  1.  after_create_commit -> { replicator.publish_created_event }

Library

所有这些背后的框架位于 .

在编写一种新的复制器策略之前，请检查以下内容，以查看现有策略之一是否已经可以处理您的资源. 如果不确定，请咨询地理团队.

使用Geo::BlobReplicatorStrategy模块，Geo 可以轻松支持使用CarrierWave 的 Uploader::Base模型.

首先，每个文件应具有其自己的主要 ID 和模型. Geo 强烈建议将每个文件都视为头等公民，因为根据我们的经验，这大大简化了跟踪复制和验证状态.

例如，要添加对具有Widget widgets表的Widget模型引用的文件的支持，您将执行以下步骤：

Replication

  1. 在Widget类中包含Gitlab::Geo::ReplicableModel ，并使用with_replicator Geo::WidgetReplicator指定 Replicator 类.

    此时， Widget类应如下所示：

    1. # frozen_string_literal: true
    3. class Widget < ApplicationRecord
    4.   include ::Gitlab::Geo::ReplicableModel
    6.   with_replicator Geo::WidgetReplicator
    8.   mount_uploader :file, WidgetUploader
    10.   def self.replicables_for_geo_node
    11.     # Should be implemented. The idea of the method is to restrict
    12.     # the set of synced items depending on synchronization settings
    13.   end
    14.   ...
    15. end

  2. 创建ee/app/replicators/geo/widget_replicator.rb . 实现#carrierwave_uploader方法，该方法应返回CarrierWave::Uploader . 并实现类方法.model以返回Widget类.

    1. # frozen_string_literal: true
    3. module Geo
    4.   class WidgetReplicator < Gitlab::Geo::Replicator
    5.     include ::Geo::BlobReplicatorStrategy
    7.     def self.model
    8.       ::Widget
    9.     end
    11.     def carrierwave_uploader
    12.       model_record.file
    13.     end
    14.   end
    15. end

  3. 创建ee/spec/replicators/geo/widget_replicator_spec.rb并执行必要的设置，以定义共享示例的model_record变量.

    1. # frozen_string_literal: true
    3. require 'spec_helper'
    5. RSpec.describe Geo::WidgetReplicator do
    6.   let(:model_record) { build(:widget) }
    8.   it_behaves_like 'a blob replicator'
    9. end

  4. 创建widget_registry表，以便 Geo 次要对象可以跟踪每个 Widget 文件的同步和验证状态：

  5. Create ee/app/models/geo/widget_registry.rb:

    1. # frozen_string_literal: true
    3. class Geo::WidgetRegistry < Geo::BaseRegistry
    4.   include Geo::ReplicableRegistry
    5.   MODEL_CLASS = ::Widget
    6.   MODEL_FOREIGN_KEY = :widget_id
    8.   belongs_to :widget, class_name: 'Widget'
    9. end

    方法has_create_events? 在大多数情况下应该返回true . 但是，如果您添加的实体没有创建事件，则根本不要添加该方法.

  6. Update REGISTRY_CLASSES in ee/app/workers/geo/secondary/registry_consistency_worker.rb.

  7. Create ee/spec/factories/geo/widget_registry.rb:

    1. # frozen_string_literal: true
    3. FactoryBot.define do
    4.   factory :geo_widget_registry, class: 'Geo::WidgetRegistry' do
    5.     widget
    8.     trait :synced do
    9.       state { Geo::WidgetRegistry.state_value(:synced) }
    10.       last_synced_at { 5.days.ago }
    11.     end
    13.     trait :failed do
    14.       state { Geo::WidgetRegistry.state_value(:failed) }
    15.       last_synced_at { 1.day.ago }
    16.       retry_count { 2 }
    17.       last_sync_failure { 'Random error' }
    18.     end
    20.     trait :started do
    21.       state { Geo::WidgetRegistry.state_value(:started) }
    22.       last_synced_at { 1.day.ago }
    23.       retry_count { 0 }
    24.     end
    25.   end
    26. end

  8. Create ee/spec/models/geo/widget_registry_spec.rb:

    1. # frozen_string_literal: true
    3. require 'spec_helper'
    5. RSpec.describe Geo::WidgetRegistry, :geo, type: :model do
    6.   let_it_be(:registry) { create(:geo_widget_registry) }
    8.   specify 'factory is valid' do
    9.     expect(registry).to be_valid
    10.   end
    12.   include_examples 'a Geo framework registry'
    14.   describe '.find_registry_differences' do
    15.     ... # To be implemented
    16.   end
    17. end

小部件现在应该由 Geo 复制！

Verification

    1. # frozen_string_literal: true
    3. class AddVerificationStateToWidgets < ActiveRecord::Migration[6.0]
    4.   DOWNTIME = false
    6.   def change
    7.     add_column :widgets, :verification_retry_at, :datetime_with_timezone
    8.     add_column :widgets, :verified_at, :datetime_with_timezone
    9.     add_column :widgets, :verification_checksum, :binary, using: 'verification_checksum::bytea'
    10.     add_column :widgets, :verification_failure, :string
    11.     add_column :widgets, :verification_retry_count, :integer
    12.   end
    13. end

  2. 在verification_failure和verification_checksum上添加部分索引，以确保可以高效执行重新验证：

    1. # frozen_string_literal: true
    3. class AddVerificationFailureIndexToWidgets < ActiveRecord::Migration[6.0]
    4.   include Gitlab::Database::MigrationHelpers
    6.   DOWNTIME = false
    8.   disable_ddl_transaction!
    10.   def up
    11.     add_concurrent_index :widgets, :verification_failure, where: "(verification_failure IS NOT NULL)", name: "widgets_verification_failure_partial"
    12.     add_concurrent_index :widgets, :verification_checksum, where: "(verification_checksum IS NOT NULL)", name: "widgets_verification_checksum_partial"
    13.   end
    15.   def down
    16.     remove_concurrent_index :widgets, :verification_failure
    17.     remove_concurrent_index :widgets, :verification_checksum
    18.   end
    19. end

要做的事情：在二级服务器上添加验证. 这应作为以下内容的一部分完成

小部件现在应由 Geo 验证！

Metrics

指标由Geo::MetricsUpdateWorker收集，保存在GeoNodeStatus以显示在 UI 中，然后发送给 Prometheus.

  1. 将相同的字段添加到ee/app/models/geo_node_status.rb GeoNodeStatus#PROMETHEUS_METRICS哈希中.
  2. 将相同字段添加到doc/administration/monitoring/prometheus/gitlab_metrics.md Sidekiq metrics表中.
  3. 将相同的字段添加到doc/api/geo_nodes.md GET /geo_nodes/status示例响应中.
  4. 将相同的字段添加到ee/spec/models/geo_node_status_spec.rb和ee/spec/factories/geo_node_statuses.rb .

  5. Set in GeoNodeStatus#load_data_from_current_node:

    1. self.widget_count = Geo::WidgetReplicator.primary_total_count

  6. 添加GeoNodeStatus#load_widgets_data来设置widget_synced_count ， widget_failed_count和widget_registry_count ：

    1. def load_widget_data
    2.   self.widget_synced_count = Geo::WidgetReplicator.synced_count
    3.   self.widget_failed_count = Geo::WidgetReplicator.failed_count
    4.   self.widget_registry_count = Geo::WidgetReplicator.registry_count
    5. end

  7. Call GeoNodeStatus#load_widgets_data in GeoNodeStatus#load_secondary_data.

  8. Set widget_checksummed_count and widget_checksum_failed_count in GeoNodeStatus#load_verification_data:

小部件复制和验证指标现在应该可以在 API，管理区域 UI 和 Prometheus 中使用！

GraphQL API

  1. 在ee/app/graphql/types/geo/geo_node_type.rb向GeoNodeType添加一个新字段：

    1. field :widget_registries, ::Types::Geo::WidgetRegistryType.connection_type,
    2.       null: true,
    3.       resolver: ::Resolvers::Geo::WidgetRegistriesResolver,
    4.       description: 'Find widget registries on this Geo node',
    5.       feature_flag: :geo_self_service_framework

  2. 新添加widget_registries字段名的expected_fields在阵列ee/spec/graphql/types/geo/geo_node_type_spec.rb .

  3. Create ee/app/graphql/resolvers/geo/widget_registries_resolver.rb:

    1. # frozen_string_literal: true
    3. module Resolvers
    4.   module Geo
    5.     class WidgetRegistriesResolver < BaseResolver
    6.       include RegistriesResolver
    7.     end
    8.   end
    9. end

  4. Create ee/spec/graphql/resolvers/geo/widget_registries_resolver_spec.rb:

    1. # frozen_string_literal: true
    3. require 'spec_helper'
    5. RSpec.describe Resolvers::Geo::WidgetRegistriesResolver do
    6.   it_behaves_like 'a Geo registries resolver', :geo_widget_registry
    7. end

  5. Create ee/app/finders/geo/widget_registry_finder.rb:

    1. # frozen_string_literal: true
    3. module Geo
    4.   class WidgetRegistryFinder
    5.     include FrameworkRegistryFinder
    6.   end
    7. end

  6. Create ee/spec/finders/geo/widget_registry_finder_spec.rb:

    1. # frozen_string_literal: true
    3. require 'spec_helper'
    5. RSpec.describe Geo::WidgetRegistryFinder do
    6.   it_behaves_like 'a framework registry finder', :geo_widget_registry
    7. end

  7. Create ee/app/graphql/types/geo/widget_registry_type.rb:

    1. # frozen_string_literal: true
    3. module Types
    4.   module Geo
    5.     # rubocop:disable Graphql/AuthorizeTypes because it is included
    6.     class WidgetRegistryType < BaseObject
    7.       include ::Types::Geo::RegistryType
    9.       graphql_name 'WidgetRegistry'
    10.       description 'Represents the sync and verification state of a widget'
    12.       field :widget_id, GraphQL::ID_TYPE, null: false, description: 'ID of the Widget'
    13.     end
    14.   end
    15. end

  8. Create ee/spec/graphql/types/geo/widget_registry_type_spec.rb:

    1. # frozen_string_literal: true
    3. require 'spec_helper'
    5. RSpec.describe GitlabSchema.types['WidgetRegistry'] do
    6.   it_behaves_like 'a Geo registry type'
    8.   it 'has the expected fields (other than those included in RegistryType)' do
    9.     expected_fields = %i[widget_id]
    11.     expect(described_class).to have_graphql_fields(*expected_fields).at_least
    12.   end
    13. end

现在应该可以通过 GraphQL API 获得各个小部件同步和验证数据！

  1. 注意复制”更新”事件. Geo Framework 目前不支持复制”更新”事件，因为此时添加到框架的所有实体都是不可变的. 如果您要添加的实体属于这种情况，请遵循https://gitlab.com/gitlab-org/gitlab/-/issues/118743和作为添加新事件类型的示例. 添加通知后，请同时删除它.

Admin UI

要做的事情：这应该作为《 一部分完成：实现自助服务框架可复制的前端