Skip to content

Add Geo support for Packages::Debian::ProjectDistribution

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Replicate Debian ProjectDistributions- Blob

This issue is for implementing Geo replication and verification of Debian ProjectDistributions.

For more background, see Geo self-service framework.

In order to implement and test this feature, you need to first set up Geo locally.

There are three main sections below. It is a good idea to structure your merge requests this way as well:

  1. Modify database schemas to prepare to add Geo support for Debian ProjectDistributions
  2. Implement Geo support of Debian ProjectDistributions behind a feature flag
  3. Release Geo support of Debian ProjectDistributions

It is also a good idea to first open a proof-of-concept merge request. It can be helpful for working out kinks and getting initial support and feedback from the Geo team. As an example, see the Proof of Concept to replicate Pipeline Artifacts.

You can look into the following examples of MRs for implementing replication/verification for a new blob type:

Modify database schemas to prepare to add Geo support for Debian ProjectDistributions

Add the registry table to track replication and verification state

Geo secondary sites have a Geo tracking database independent of the main database. It is used to track the replication and verification state of all replicables. Every Model has a corresponding "registry" table in the Geo tracking database.

  • Create the migration file in ee/db/geo/migrate:

    bin/rails generate migration CreatePackagesDebianProjectDistributionRegistry --database geo

  • Replace the contents of the migration file with the following. Note that we cannot add a foreign key constraint on packages_debian_project_distribution_id because the packages_debian_project_distributions table is in a different database. The application code must handle logic such as propagating deletions.

    # frozen_string_literal: true

class CreatePackagesDebianProjectDistributionRegistry < Gitlab::Database::Migration[2.1]
 def change
 create_table :packages_debian_project_distribution_registry, id: :bigserial, force: :cascade do |t|
 t.bigint :packages_debian_project_distribution_id, null: false
 t.datetime_with_timezone :created_at, null: false
 t.datetime_with_timezone :last_synced_at
 t.datetime_with_timezone :retry_at
 t.datetime_with_timezone :verified_at
 t.datetime_with_timezone :verification_started_at
 t.datetime_with_timezone :verification_retry_at
 t.integer :state, default: 0, null: false, limit: 2
 t.integer :verification_state, default: 0, null: false, limit: 2
 t.integer :retry_count, default: 0, limit: 2, null: false
 t.integer :verification_retry_count, default: 0, limit: 2, null: false
 t.boolean :checksum_mismatch, default: false, null: false
 t.binary :verification_checksum
 t.binary :verification_checksum_mismatched
 t.text :verification_failure, limit: 255
 t.text :last_sync_failure, limit: 255

 t.index :packages_debian_project_distribution_id, name: :index_packages_debian_project_distribution_registry_on_packages_debian_project_distribution_id, unique: true
 t.index :retry_at
 t.index :state
 # To optimize performance of PackagesDebianProjectDistributionRegistry.verification_failed_batch
 t.index :verification_retry_at,
 name: :packages_debian_project_distribution_registry_failed_verification,
 order: "NULLS FIRST",
 where: "((state = 2) AND (verification_state = 3))"
 # To optimize performance of PackagesDebianProjectDistributionRegistry.needs_verification_count
 t.index :verification_state,
 name: :packages_debian_project_distribution_registry_needs_verification,
 where: "((state = 2) AND (verification_state = ANY (ARRAY[0, 3])))"
 # To optimize performance of PackagesDebianProjectDistributionRegistry.verification_pending_batch
 t.index :verified_at,
 name: :packages_debian_project_distribution_registry_pending_verification,
 order: "NULLS FIRST",
 where: "((state = 2) AND (verification_state = 0))"
 end
 end
end

  • If deviating from the above example, then be sure to order columns according to our guidelines.

  • Add the new table to the database dictionary defined in ee/db/geo/docs/:

    table_name: packages_debian_project_distribution_registry
description: Description example
introduced_by_url: Merge request link
milestone: Milestone example
feature_categories:
 - Feature category example
classes:
 - Class example
gitlab_schema: gitlab_geo

  • Run Geo tracking database migrations:

    bin/rake db:migrate:geo

  • Be sure to commit the relevant changes in ee/db/geo/structure.sql and the file created under ee/db/geo/schema_migrations

Add verification state fields on the Geo primary site

The Geo primary site needs to checksum every replicable so secondaries can verify their own checksums. To do this, Geo requires fields on the Model. Add verification state fields to a separate table. Consult a database expert if needed.

Add verification state fields to a new table

  • Create the migration file in db/migrate:

    bin/rails generate migration CreatePackagesDebianProjectDistributionStates

  • Replace the contents of the migration file with:

    # frozen_string_literal: true

class CreatePackagesDebianProjectDistributionStates < Gitlab::Database::Migration[2.1]
 VERIFICATION_STATE_INDEX_NAME = "index_packages_debian_project_distribution_states_on_verification_state"
 PENDING_VERIFICATION_INDEX_NAME = "index_packages_debian_project_distribution_states_pending_verification"
 FAILED_VERIFICATION_INDEX_NAME = "index_packages_debian_project_distribution_states_failed_verification"
 NEEDS_VERIFICATION_INDEX_NAME = "index_packages_debian_project_distribution_states_needs_verification"

 def up
 create_table :packages_debian_project_distribution_states do |t|
 t.datetime_with_timezone :verification_started_at
 t.datetime_with_timezone :verification_retry_at
 t.datetime_with_timezone :verified_at
 t.references :packages_debian_project_distribution,
 null: false,
 index: { unique: true },
 foreign_key: { on_delete: :cascade }
 t.integer :verification_state, default: 0, limit: 2, null: false
 t.integer :verification_retry_count, default: 0, limit: 2, null: false
 t.binary :verification_checksum, using: 'verification_checksum::bytea'
 t.text :verification_failure, limit: 255

 t.index :verification_state, name: VERIFICATION_STATE_INDEX_NAME
 t.index :verified_at,
 where: "(verification_state = 0)",
 order: { verified_at: 'ASC NULLS FIRST' },
 name: PENDING_VERIFICATION_INDEX_NAME
 t.index :verification_retry_at,
 where: "(verification_state = 3)",
 order: { verification_retry_at: 'ASC NULLS FIRST' },
 name: FAILED_VERIFICATION_INDEX_NAME
 t.index :verification_state,
 where: "(verification_state = 0 OR verification_state = 3)",
 name: NEEDS_VERIFICATION_INDEX_NAME
 end
 end

 def down
 drop_table :packages_debian_project_distribution_states
 end
end

  • If deviating from the above example, then be sure to order columns according to our guidelines.

  • If packages_debian_project_distributions is a high-traffic table, follow the database documentation to use with_lock_retries

  • Add the new table to the database dictionary defined in db/docs/:

    ---
table_name: packages_debian_project_distribution_states
description: Separate table for Debian ProjectDistribution verification states
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/XXXXX
milestone: 'XX.Y'
feature_categories:
 - geo_replication
classes:
 - Geo::PackagesDebianProjectDistributionState
gitlab_schema: gitlab_main

  • Run database migrations:

    bin/rake db:migrate

  • Be sure to commit the relevant changes in db/structure.sql and the file under db/schema_migrations

That's all of the required database changes.

Implement Geo support of Debian ProjectDistributions behind a feature flag

Step 1. Implement replication and verification

  • Add the following lines to the packages_debian_project_distribution model to accomplish some important tasks:

    • Include ::Geo::ReplicableModel in the PackagesDebianProjectDistribution class, and specify the Replicator class with_replicator Geo::PackagesDebianProjectDistributionReplicator.
    • Include the ::Geo::VerifiableModel concern.
    • Delegate verification related methods to the packages_debian_project_distribution_state model.
    • For verification, override some scopes to use the packages_debian_project_distribution_states table instead of the model table.
    • Implement the verification_state_object method to return the object that holds the verification details
    • Override some methods to use the packages_debian_project_distribution_states table in verification-related queries.

    At this point the PackagesDebianProjectDistribution class should look like this:

    # frozen_string_literal: true

class PackagesDebianProjectDistribution < ApplicationRecord
 ...
 include ::Geo::ReplicableModel
 include ::Geo::VerifiableModel

 delegate(*::Geo::VerificationState::VERIFICATION_METHODS, to: :packages_debian_project_distribution_state)

 with_replicator Geo::PackagesDebianProjectDistributionReplicator

 mount_uploader :file, PackagesDebianProjectDistributionUploader

 has_one :packages_debian_project_distribution_state, autosave: false, inverse_of: :packages_debian_project_distribution, class_name: 'Geo::PackagesDebianProjectDistributionState'

 # Override the `all` default if not all records can be replicated. For an
 # example of an existing Model that needs to do this, see
 # `EE::MergeRequestDiff`.
 # scope :available_replicables, -> { all }

 scope :available_verifiables, -> { joins(:packages_debian_project_distribution_state) }

 scope :checksummed, -> {
 joins(:packages_debian_project_distribution_state).where.not(packages_debian_project_distribution_states: { verification_checksum: nil })
 }

 scope :not_checksummed, -> {
 joins(:packages_debian_project_distribution_state).where(packages_debian_project_distribution_states: { verification_checksum: nil })
 }

 scope :with_verification_state, ->(state) {
 joins(:packages_debian_project_distribution_state)
 .where(packages_debian_project_distribution_states: { verification_state: verification_state_value(state) })
 }

 def verification_state_object
 packages_debian_project_distribution_state
 end
 ...

 class_methods do
 extend ::Gitlab::Utils::Override
 ...

 # @param primary_key_in [Range, PackagesDebianProjectDistribution] arg to pass to primary_key_in scope
 # @return [ActiveRecord::Relation<PackagesDebianProjectDistribution>] everything that should be synced
 # to this node, restricted by primary key
 def replicables_for_current_secondary(primary_key_in)
 # This issue template does not help you write this method.
 #
 # This method is called only on Geo secondary sites. It is called when
 # we want to know which records to replicate. This is not easy to automate
 # because for example:
 #
 # * The "selective sync" feature allows admins to choose which namespaces
 # to replicate, per secondary site. Most Models are scoped to a
 # namespace, but the nature of the relationship to a namespace varies
 # between Models.
 # * The "selective sync" feature allows admins to choose which shards to
 # replicate, per secondary site. Repositories are associated with
 # shards. Most blob types are not, but Project Uploads are.
 # * Remote stored replicables are not replicated, by default. But the
 # setting `sync_object_storage` enables replication of remote stored
 # replicables.
 #
 # Search the codebase for examples, and consult a Geo expert if needed.
 end

 override :verification_state_model_key
 def verification_state_model_key
 :packages_debian_project_distribution_id
 end

 override :verification_state_table_class
 def verification_state_table_class
 PackagesDebianProjectDistributionState
 end
 end

 def packages_debian_project_distribution_state
 super || build_packages_debian_project_distribution_state
 end

 ...
end

  • Implement PackagesDebianProjectDistribution.replicables_for_current_secondary above.

  • Ensure PackagesDebianProjectDistribution.replicables_for_current_secondary is well-tested. Search the codebase for replicables_for_current_secondary to find examples of parameterized table specs. You may need to add more FactoryBot traits.

  • Add the following shared examples to ee/spec/models/ee/packages/debian/project_distribution_spec.rb:

     include_examples 'a verifiable model with a separate table for verification state' do
 let(:verifiable_model_record) { build(:debian_project_distribution) } # add extra params if needed to make sure the record is in `Geo::ReplicableModel.verifiables` scope
 let(:unverifiable_model_record) { build(:debian_project_distribution) } # add extra params if needed to make sure the record is NOT included in `Geo::ReplicableModel.verifiables` scope
 end

  • Create ee/app/replicators/geo/packages_debian_project_distribution_replicator.rb. Implement the #carrierwave_uploader method which should return a CarrierWave::Uploader, and implement the class method .model to return the PackagesDebianProjectDistribution class:

    • Implement the replicable_title and replicable_title_plural methods to return the human-readable singular and pluralized title of the replicable, which will be displayed in the UI and Rails console
    # frozen_string_literal: true

module Geo
 class PackagesDebianProjectDistributionReplicator < Gitlab::Geo::Replicator
 include ::Geo::BlobReplicatorStrategy
 extend ::Gitlab::Utils::Override

 def self.model
 ::PackagesDebianProjectDistribution
 end

 # @return [String] human-readable title.
 def self.replicable_title
 s_('Geo|Debian ProjectDistribution')
 end

 # @return [String] pluralized human-readable title.
 def self.replicable_title_plural
 s_('Geo|Debian ProjectDistributions')
 end

 def carrierwave_uploader
 model_record.file
 end

 override :verification_feature_flag_enabled?
 def self.verification_feature_flag_enabled?
 # We are adding verification at the same time as replication, so we
 # don't need to toggle verification separately from replication. When
 # the replication feature flag is off, then verification is also off
 # (see `VerifiableReplicator.verification_enabled?`)
 true
 end
 end
end

  • Generate the feature flag definition file by running the feature flag commands and following the command prompts:

    bin/feature-flag --ee geo_packages_debian_project_distribution_replication --type development --group 'group::geo'

  • Add this replicator class to the method replicator_classes in ee/lib/gitlab/geo.rb:

    REPLICATOR_CLASSES = [
 ::Geo::PackageFileReplicator,
 ::Geo::PackagesDebianProjectDistributionReplicator
]

  • Create ee/spec/replicators/geo/packages_debian_project_distribution_replicator_spec.rb and perform the necessary setup to define the model_record variable for the shared examples:

    # frozen_string_literal: true

require 'spec_helper'

RSpec.describe Geo::PackagesDebianProjectDistributionReplicator, feature_category: :geo_replication do
 let(:model_record) { build(:debian_project_distribution) }

 include_examples 'a blob replicator'
end

  • Create ee/app/models/geo/packages_debian_project_distribution_registry.rb:

    # frozen_string_literal: true

module Geo
 class PackagesDebianProjectDistributionRegistry < Geo::BaseRegistry
 include ::Geo::ReplicableRegistry
 include ::Geo::VerifiableRegistry

 MODEL_CLASS = ::PackagesDebianProjectDistribution
 MODEL_FOREIGN_KEY = :packages_debian_project_distribution_id

 belongs_to :packages_debian_project_distribution, class_name: 'PackagesDebianProjectDistribution'
 end
end

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

  • Add a custom factory name if needed in def model_class_factory_name in ee/spec/support/helpers/ee/geo_helpers.rb.

  • Update it 'creates missing registries for each registry class' in ee/spec/workers/geo/secondary/registry_consistency_worker_spec.rb.

  • Add packages_debian_project_distribution_registry to ActiveSupport::Inflector.inflections in config/initializers_before_autoloader/000_inflections.rb.

  • Create ee/spec/factories/geo/packages_debian_project_distribution_registry.rb:

    # frozen_string_literal: true

FactoryBot.define do
 factory :geo_packages_debian_project_distribution_registry, class: 'Geo::PackagesDebianProjectDistributionRegistry' do
 packages_debian_project_distribution # This association should have data, like a file or repository
 state { Geo::PackagesDebianProjectDistributionRegistry.state_value(:pending) }

 trait :synced do
 state { Geo::PackagesDebianProjectDistributionRegistry.state_value(:synced) }
 last_synced_at { 5.days.ago }
 end

 trait :failed do
 state { Geo::PackagesDebianProjectDistributionRegistry.state_value(:failed) }
 last_synced_at { 1.day.ago }
 retry_count { 2 }
 retry_at { 2.hours.from_now }
 last_sync_failure { 'Random error' }
 end

 trait :started do
 state { Geo::PackagesDebianProjectDistributionRegistry.state_value(:started) }
 last_synced_at { 1.day.ago }
 retry_count { 0 }
 end

 trait :verification_succeeded do
 synced
 verification_checksum { 'e079a831cab27bcda7d81cd9b48296d0c3dd92ef' }
 verification_state { Geo::PackagesDebianProjectDistributionRegistry.verification_state_value(:verification_succeeded) }
 verified_at { 5.days.ago }
 end

 trait :verification_failed do
 synced
 verification_failure { 'Could not calculate the checksum' }
 verification_state { Geo::PackagesDebianProjectDistributionRegistry.verification_state_value(:verification_failed) }
 verification_retry_count { 1 }
 verification_retry_at { 2.hours.from_now }
 end
 end
end

  • Create ee/spec/models/geo/packages_debian_project_distribution_registry_spec.rb:

    # frozen_string_literal: true

require 'spec_helper'

RSpec.describe Geo::PackagesDebianProjectDistributionRegistry, :geo, type: :model, feature_category: :geo_replication do
 let_it_be(:registry) { create(:geo_packages_debian_project_distribution_registry) }

 specify 'factory is valid' do
 expect(registry).to be_valid
 end

 include_examples 'a Geo framework registry'
end

  • Add the following to ee/spec/factories/packages/debian/distribution.rb:

    # frozen_string_literal: true

FactoryBot.modify do
 factory :debian_project_distribution do
 trait :verification_succeeded do
 with_file
 verification_checksum { 'abc' }
 verification_state { PackagesDebianProjectDistribution.verification_state_value(:verification_succeeded) }
 end

 trait :verification_failed do
 with_file
 verification_failure { 'Could not calculate the checksum' }
 verification_state { PackagesDebianProjectDistribution.verification_state_value(:verification_failed) }

 #
 # Geo::VerifiableReplicator#after_verifiable_update tries to verify
 # the replicable async and marks it as verification started when the
 # model record is created/updated.
 #
 after(:create) do |instance, _|
 instance.verification_failed!
 end
 end
 end
end

    If there is not an existing factory for the object in spec/factories/packages/debian/distribution.rb, wrap the traits in FactoryBot.create instead of FactoryBot.modify

[ ] Make sure the factory supports the :remote_store trait. If not, add something like

trait :remote_store do
 file_store { PackagesDebianProjectDistribution::FileUploader::Store::REMOTE }
end

  • Make sure the factory also allows setting a project attribute. If the model does not have a direct relation to a project, you can use a transient attribute. Check out spec/factories/merge_request_diffs.rb for an example.

  • Following the example of Merge Request Diffs add a Geo::PackagesDebianProjectDistributionState model in ee/app/models/geo/packages_debian_project_distribution_state.rb:

    # frozen_string_literal: true

module Geo
 class PackagesDebianProjectDistributionState < ApplicationRecord
 include ::Geo::VerificationStateDefinition

 self.primary_key = :packages_debian_project_distribution_id

 belongs_to :packages_debian_project_distribution, inverse_of: :packages_debian_project_distribution_state

 validates :verification_state, :packages_debian_project_distribution, presence: true
 end
end

  • Add a factory for packages_debian_project_distribution_state, in ee/spec/factories/geo/packages_debian_project_distribution_states.rb:

    # frozen_string_literal: true

FactoryBot.define do
 factory :geo_packages_debian_project_distribution_state, class: 'Geo::PackagesDebianProjectDistributionState' do
 packages_debian_project_distribution

 trait :checksummed do
 verification_checksum { 'abc' }
 end

 trait :checksum_failure do
 verification_failure { 'Could not calculate the checksum' }
 end
 end
end

  • Add [:packages_debian_project_distribution, :remote_store] to skipped in spec/support/shared_examples/lint_factories_shared_examples.rb

Step 2. Implement metrics gathering

Metrics are gathered by Geo::MetricsUpdateWorker, persisted in GeoNodeStatus for display in the UI, and sent to Prometheus:

  • Add the following fields to Geo Node Status example responses in doc/api/geo_nodes.md:

    • packages_debian_project_distributions_count
    • packages_debian_project_distributions_checksum_total_count
    • packages_debian_project_distributions_checksummed_count
    • packages_debian_project_distributions_checksum_failed_count
    • packages_debian_project_distributions_synced_count
    • packages_debian_project_distributions_failed_count
    • packages_debian_project_distributions_registry_count
    • packages_debian_project_distributions_verification_total_count
    • packages_debian_project_distributions_verified_count
    • packages_debian_project_distributions_verification_failed_count
    • packages_debian_project_distributions_synced_in_percentage
    • packages_debian_project_distributions_verified_in_percentage

  • Add the same fields to GET /geo_nodes/status example response in ee/spec/fixtures/api/schemas/public_api/v4/geo_node_status.json and ee/spec/fixtures/api/schemas/public_api/v4/geo_site_status.json.

  • Add the following fields to the Sidekiq metrics table in doc/administration/monitoring/prometheus/gitlab_metrics.md:

    | `geo_packages_debian_project_distributions` | Gauge | XX.Y | Number of Debian ProjectDistributions on primary | `url` |
| `geo_packages_debian_project_distributions_checksum_total` | Gauge | XX.Y | Number of Debian ProjectDistributions to checksum on primary | `url` |
| `geo_packages_debian_project_distributions_checksummed` | Gauge | XX.Y | Number of Debian ProjectDistributions that successfully calculated the checksum on primary | `url` |
| `geo_packages_debian_project_distributions_checksum_failed` | Gauge | XX.Y | Number of Debian ProjectDistributions that failed to calculate the checksum on primary | `url` |
| `geo_packages_debian_project_distributions_synced` | Gauge | XX.Y | Number of syncable Debian ProjectDistributions synced on secondary | `url` |
| `geo_packages_debian_project_distributions_failed` | Gauge | XX.Y | Number of syncable Debian ProjectDistributions failed to sync on secondary | `url` |
| `geo_packages_debian_project_distributions_registry` | Gauge | XX.Y | Number of Debian ProjectDistributions in the registry | `url` |
| `geo_packages_debian_project_distributions_verification_total` | Gauge | XX.Y | Number of Debian ProjectDistributions to attempt to verify on secondary | `url` |
| `geo_packages_debian_project_distributions_verified` | Gauge | XX.Y | Number of Debian ProjectDistributions successfully verified on secondary | `url` |
| `geo_packages_debian_project_distributions_verification_failed` | Gauge | XX.Y | Number of Debian ProjectDistributions that failed verification on secondary | `url` |

  • Run the rake task geo:dev:ssf_metrics and commit the changes to ee/config/metrics/object_schemas/geo_node_usage.json

Debian ProjectDistribution replication and verification metrics should now be available in the API, the Admin > Geo > Sites view, and Prometheus.

Step 3. Implement the GraphQL API

The GraphQL API is used by Admin > Geo > Replication Details views, and is directly queryable by administrators.

  • Add a new field to GeoNodeType in ee/app/graphql/types/geo/geo_node_type.rb:

    field :packages_debian_project_distribution_registries, ::Types::Geo::PackagesDebianProjectDistributionRegistryType.connection_type,
 null: true,
 resolver: ::Resolvers::Geo::PackagesDebianProjectDistributionRegistriesResolver,
 description: 'Find Debian ProjectDistribution registries on this Geo node. '\
 'Ignored if `geo_packages_debian_project_distribution_replication` feature flag is disabled.',
 experiment: { milestone: '15.5' } # Update the milestone

  • Add the new packages_debian_project_distribution_registries field name to the expected_fields array in ee/spec/graphql/types/geo/geo_node_type_spec.rb.

  • Create ee/app/graphql/resolvers/geo/packages_debian_project_distribution_registries_resolver.rb:

    # frozen_string_literal: true

module Resolvers
 module Geo
 class PackagesDebianProjectDistributionRegistriesResolver < BaseResolver
 type ::Types::Geo::GeoNodeType.connection_type, null: true

 include RegistriesResolver
 end
 end
end

  • Create ee/spec/graphql/resolvers/geo/packages_debian_project_distribution_registries_resolver_spec.rb:

    # frozen_string_literal: true

require 'spec_helper'

RSpec.describe Resolvers::Geo::PackagesDebianProjectDistributionRegistriesResolver, feature_category: :geo_replication do
 it_behaves_like 'a Geo registries resolver', :geo_packages_debian_project_distribution_registry
end

  • Create ee/app/finders/geo/packages_debian_project_distribution_registry_finder.rb:

    # frozen_string_literal: true

module Geo
 class PackagesDebianProjectDistributionRegistryFinder
 include FrameworkRegistryFinder
 end
end

  • Create ee/spec/finders/geo/packages_debian_project_distribution_registry_finder_spec.rb:

    # frozen_string_literal: true

require 'spec_helper'

RSpec.describe Geo::PackagesDebianProjectDistributionRegistryFinder, feature_category: :geo_replication do
 it_behaves_like 'a framework registry finder', :geo_packages_debian_project_distribution_registry
end

  • Create ee/app/graphql/types/geo/packages_debian_project_distribution_registry_type.rb:

    # frozen_string_literal: true

module Types
 module Geo
 # rubocop:disable Graphql/AuthorizeTypes -- because it is included
 class PackagesDebianProjectDistributionRegistryType < BaseObject
 graphql_name 'PackagesDebianProjectDistributionRegistry'

 include ::Types::Geo::RegistryType

 description 'Represents the Geo replication and verification state of a packages_debian_project_distribution'

 field :packages_debian_project_distribution_id, GraphQL::Types::ID, null: false, description: 'ID of the Debian ProjectDistribution.'
 end
 # rubocop:enable Graphql/AuthorizeTypes
 end
end

  • Create ee/spec/graphql/types/geo/packages_debian_project_distribution_registry_type_spec.rb:

    # frozen_string_literal: true

require 'spec_helper'

RSpec.describe GitlabSchema.types['PackagesDebianProjectDistributionRegistry'], feature_category: :geo_replication do
 it_behaves_like 'a Geo registry type'

 it 'has the expected fields (other than those included in RegistryType)' do
 expected_fields = %i[packages_debian_project_distribution_id]

 expect(described_class).to have_graphql_fields(*expected_fields).at_least
 end
end

  • Add integration tests for providing PackagesDebianProjectDistribution registry data to the frontend via the GraphQL API, by duplicating and modifying the following shared examples in ee/spec/requests/api/graphql/geo/registries_spec.rb:

    it_behaves_like 'gets registries for', {
 field_name: 'packagesDebianProjectDistributionRegistries',
 registry_class_name: 'PackagesDebianProjectDistributionRegistry',
 registry_factory: :geo_packages_debian_project_distribution_registry,
 registry_foreign_key_field_name: 'packagesDebianProjectDistributionId'
}

To allow the new replicable to resync and reverify via GraphQL:

  • Add the PackagesDebianProjectDistributionRegistryType to the GEO_REGISTRY_TYPE constant in ee/app/graphql/types/geo/registrable_type.rb:

     GEO_REGISTRY_TYPES = {
 ::Geo::PackagesDebianProjectDistributionRegistry => Types::Geo::PackagesDebianProjectDistributionRegistryType
 }

  • Include the PackagesDebianProjectDistributionRegistry in the let(:registry_classes) variable of ee/spec/graphql/types/geo/registry_class_enum_spec.rb:

     let(:registry_classes) do
 %w[
 PACKAGES_DEBIAN_PROJECT_COMPONENT_FILE_REGISTRY
 ]
 end

  • Include the new registry in the Rspec parameterized table of ee/spec/support/shared_contexts/graphql/geo/registries_shared_context.rb:

     # frozen_string_literal: true

 RSpec.shared_context 'with geo registries shared context' do
 using RSpec::Parameterized::TableSyntax

 where(:registry_class, :registry_type, :registry_factory) do
 Geo::PackagesDebianProjectDistributionRegistry | Types::Geo::PackagesDebianProjectDistributionRegistryType | :geo_packages_debian_project_distribution_registry
 end
 end

  • Update the GraphQL reference documentation:

    bundle exec rake gitlab:graphql:compile_docs

Individual Debian ProjectDistribution replication and verification data should now be available via the GraphQL API.

Step 4. Handle batch destroy

If batch destroy logic is implemented for a replicable, then that logic must be "replicated" by Geo secondaries. The easiest way to do this is use Geo::BatchEventCreateWorker to bulk insert a delete event for each replicable.

For example, if FastDestroyAll is used, then you may be able to use begin_fast_destroy and finalize_fast_destroy hooks, like we did for uploads.

Or if a special service is used to batch delete records and their associated data, then you probably need to hook into that service, like we did for job artifacts.

As illustrated by the above two examples, batch destroy logic cannot be handled automatically by Geo secondaries without restricting the way other teams perform batch destroys. It is up to you to produce Geo::BatchEventCreateWorker attributes before the records are deleted, and then enqueue Geo::BatchEventCreateWorker after the records are deleted.

  • Ensure that any batch destroy of this replicable is replicated to secondary sites
  • Regardless of implementation details, please verify in specs that when the parent object is removed, the new Geo::Event records are created:
 describe '#destroy' do
 subject { create(:debian_project_distribution) }

 context 'when running in a Geo primary node' do
 let_it_be(:primary) { create(:geo_node, :primary) }
 let_it_be(:secondary) { create(:geo_node) }

 it 'logs an event to the Geo event log when bulk removal is used', :sidekiq_inline do
 stub_current_geo_node(primary)

 expect { subject.project.destroy! }.to change(Geo::Event.where(replicable_name: :packages_debian_project_distribution, event_name: :deleted), :count).by(1)

 payload = Geo::Event.where(replicable_name: :packages_debian_project_distribution, event_name: :deleted).last.payload

 expect(payload['model_record_id']).to eq(subject.id)
 expect(payload['blob_path']).to eq(subject.relative_path)
 expect(payload['uploader_class']).to eq('PackagesDebianProjectDistributionUploader')
 end
 end
 end

Code Review

When requesting review from database reviewers:

  • Include a comment mentioning that the change is based on a documented template.
  • replicables_for_current_secondary and available_replicables may differ per Model. If their queries are new, then add query plans to the MR description. An easy place to gather SQL queries is your GDK's log/test.log when running tests of these methods.

Release Geo support of Debian ProjectDistributions

  • In the rollout issue you created when creating the feature flag, modify the Roll Out Steps:

    • Cross out any steps related to testing on production GitLab.com, because Geo is not running on production GitLab.com at the moment.
    • Add a step to Test replication and verification of Debian ProjectDistributions on a non-GDK-deployment. For example, using GitLab Environment Toolkit.
    • Add a step to Ping the Geo PM and EM to coordinate testing. For example, you might add steps to generate Debian ProjectDistributions, and then a Geo engineer may take it from there.

  • In ee/config/feature_flags/development/geo_packages_debian_project_distribution_replication.yml, set default_enabled: true

  • In ee/app/graphql/types/geo/geo_node_type.rb, remove the alpha option for the released type:

    field :packages_debian_project_distribution_registries, ::Types::Geo::PackagesDebianProjectDistributionRegistryType.connection_type,
 null: true,
 resolver: ::Resolvers::Geo::PackagesDebianProjectDistributionRegistriesResolver,
 description: 'Find Debian ProjectDistribution registries on this Geo node. '\
 'Ignored if `geo_packages_debian_project_distribution_replication` feature flag is disabled.',
 experiment: { milestone: '15.5' } # Update the milestone

  • Run bundle exec rake gitlab:graphql:compile_docs after the step above to regenerate the GraphQL docs.

  • Add a row for Debian ProjectDistributions to the Data types table in Geo data types support

  • Add a row for Debian ProjectDistributions to the Limitations on replication/verification table in Geo data types support. If the row already exists, then update it to show that Replication and Verification is released in the current version.

Edited by 🤖 GitLab Bot 🤖