Geo Nodes API

To interact with Geo node endpoints, you must authenticate yourself as an administrator.

Create a new Geo node

Creates a new Geo node.

POST /geo_nodes

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/geo_nodes" \
     --request POST \
     -d "name=himynameissomething" \
     -d "url=https://another-node.example.com/"
Attribute Type Required Description
primary boolean no Specifying whether this node should be primary. Defaults to false.
enabled boolean no Flag indicating if the Geo node is enabled. Defaults to true.
name string yes The unique identifier for the Geo node. Must match geo_node_name if it is set in gitlab.rb, otherwise it must match external_url
url string yes The user-facing URL for the Geo node.
internal_url string no The URL defined on the primary node that secondary nodes should use to contact it. Returns url if not set.
files_max_capacity integer no Control the maximum concurrency of LFS/attachment backfill for this secondary node. Defaults to 10.
repos_max_capacity integer no Control the maximum concurrency of repository backfill for this secondary node. Defaults to 25.
verification_max_capacity integer no Control the maximum concurrency of repository verification for this node. Defaults to 100.
container_repositories_max_capacity integer no Control the maximum concurrency of container repository sync for this node. Defaults to 10.
sync_object_storage boolean no Flag indicating if the secondary Geo node should replicate blobs in Object Storage. Defaults to false.
selective_sync_type string no Limit syncing to only specific groups or shards. Valid values: "namespaces", "shards", or null.
selective_sync_shards array no The repository storage for the projects synced if selective_sync_type == shards.
selective_sync_namespace_ids array no The IDs of groups that should be synced, if selective_sync_type == namespaces.
minimum_reverification_interval integer no The interval (in days) in which the repository verification is valid. Once expired, it is reverified. This has no effect when set on a secondary node.

Example response:

{
  "id": 3,
  "name": "Test Node 1",
  "url": "https://secondary.example.com/",
  "internal_url": "https://secondary.example.com/",
  "primary": false,
  "enabled": true,
  "current": false,
  "files_max_capacity": 10,
  "repos_max_capacity": 25,
  "verification_max_capacity": 100,
  "selective_sync_type": "namespaces",
  "selective_sync_shards": [],
  "selective_sync_namespace_ids": [1, 25],
  "minimum_reverification_interval": 7,
  "container_repositories_max_capacity": 10,
  "sync_object_storage": false,
  "clone_protocol": "http",
  "web_edit_url": "https://primary.example.com/admin/geo/sites/3/edit",
  "web_geo_projects_url": "https://secondary.example.com/admin/geo/projects",
  "web_geo_replication_details_url": "https://secondary.example.com/admin/geo/sites/3/replication/lfs_objects",
  "_links": {
     "self": "https://primary.example.com/api/v4/geo_nodes/3",
     "status": "https://primary.example.com/api/v4/geo_nodes/3/status",
     "repair": "https://primary.example.com/api/v4/geo_nodes/3/repair"
  }
}
caution
The web_geo_projects_url attribute is in its end-of-life process. It is deprecated in GitLab 14.9.

Retrieve configuration about all Geo nodes 

GET /geo_nodes

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/geo_nodes"

Example response:

[
  {
    "id": 1,
    "name": "us-node",
    "url": "https://primary.example.com/",
    "internal_url": "https://internal.example.com/",
    "primary": true,
    "enabled": true,
    "current": true,
    "files_max_capacity": 10,
    "repos_max_capacity": 25,
    "container_repositories_max_capacity": 10,
    "verification_max_capacity": 100,
    "selective_sync_type": "namespaces",
    "selective_sync_shards": [],
    "selective_sync_namespace_ids": [1, 25],
    "minimum_reverification_interval": 7,
    "clone_protocol": "http",
    "web_edit_url": "https://primary.example.com/admin/geo/sites/1/edit",
    "_links": {
      "self": "https://primary.example.com/api/v4/geo_nodes/1",
      "status":"https://primary.example.com/api/v4/geo_nodes/1/status",
      "repair":"https://primary.example.com/api/v4/geo_nodes/1/repair"
    }
  },
  {
    "id": 2,
    "name": "cn-node",
    "url": "https://secondary.example.com/",
    "internal_url": "https://secondary.example.com/",
    "primary": false,
    "enabled": true,
    "current": false,
    "files_max_capacity": 10,
    "repos_max_capacity": 25,
    "container_repositories_max_capacity": 10,
    "verification_max_capacity": 100,
    "selective_sync_type": "namespaces",
    "selective_sync_shards": [],
    "selective_sync_namespace_ids": [1, 25],
    "minimum_reverification_interval": 7,
    "sync_object_storage": true,
    "clone_protocol": "http",
    "web_edit_url": "https://primary.example.com/admin/geo/sites/2/edit",
    "web_geo_projects_url": "https://secondary.example.com/admin/geo/projects",
    "web_geo_replication_details_url": "https://secondary.example.com/admin/geo/sites/2/replication/lfs_objects",
    "_links": {
      "self":"https://primary.example.com/api/v4/geo_nodes/2",
      "status":"https://primary.example.com/api/v4/geo_nodes/2/status",
      "repair":"https://primary.example.com/api/v4/geo_nodes/2/repair"
    }
  }
]
caution
The web_geo_projects_url attribute is in its end-of-life process. It is deprecated in GitLab 14.9.

Retrieve configuration about a specific Geo node 

GET /geo_nodes/:id

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://primary.example.com/api/v4/geo_nodes/1"

Example response:

{
  "id": 1,
  "name": "us-node",
  "url": "https://primary.example.com/",
  "internal_url": "https://primary.example.com/",
  "primary": true,
  "enabled": true,
  "current": true,
  "files_max_capacity": 10,
  "repos_max_capacity": 25,
  "container_repositories_max_capacity": 10,
  "verification_max_capacity": 100