Skip to content

G
gitlab-ce
Commit dc5164a7 authored by Fiona Neill's avatar Fiona Neill
Browse files
Options

Merge branch 'aqualls-move-internal-api-page' into 'master' 

Move internal API page into its own subdirectory

See merge request gitlab-org/gitlab!74097
parents e2ee03df 4d0f3ca4
Hide whitespace changes
Inline Side-by-side
Showing with 842 additions and 833 deletions
doc/administration/gitaly/troubleshooting.md
View file @ dc5164a7
......@@ -157,7 +157,7 @@ Confirm the following are all true:
successfully creates the project but doesn't create the README.
- When [tailing the logs](https://docs.gitlab.com/omnibus/settings/logs.html#tail-logs-in-a-console-on-the-server)
on a Gitaly client and reproducing the error, you get `401` errors
when reaching the [`/api/v4/internal/allowed`](../../development/internal_api.md) endpoint:
when reaching the [`/api/v4/internal/allowed`](../../development/internal_api/index.md) endpoint:
```shell
# api_json.log
......
doc/administration/maintenance_mode/index.md
View file @ dc5164a7
......@@ -119,7 +119,7 @@ For most JSON requests, POST, PUT, PATCH, and DELETE are blocked, and the API re
| POST | `/admin/session`, `/admin/session/destroy` | To allow [Administrator mode for GitLab administrators](https://gitlab.com/groups/gitlab-org/-/epics/2158) |
| POST | Paths ending with `/compare`| Git revision routes. |
| POST | `.git/git-upload-pack` | To allow Git pull/clone. |
| POST | `/api/v4/internal` | [internal API routes](../../development/internal_api.md) |
| POST | `/api/v4/internal` | [internal API routes](../../development/internal_api/index.md) |
| POST | `/admin/sidekiq` | To allow management of background jobs in the Admin UI |
| POST | `/admin/geo` | To allow updating Geo Nodes in the administrator UI |
| POST | `/api/v4/geo_replication`| To allow certain Geo-specific administrator UI actions on secondary sites |
......
doc/administration/troubleshooting/debug.md
View file @ dc5164a7
......@@ -258,7 +258,7 @@ separate Rails process to debug the issue:
### GitLab: API is not accessible
This often occurs when GitLab Shell attempts to request authorization via the
[internal API](../../development/internal_api.md) (for example, `http://localhost:8080/api/v4/internal/allowed`), and
[internal API](../../development/internal_api/index.md) (for example, `http://localhost:8080/api/v4/internal/allowed`), and
something in the check fails. There are many reasons why this may happen:
1. Timeout connecting to a database (for example, PostgreSQL or Redis)
......@@ -275,7 +275,7 @@ strace -ttTfyyy -s 1024 -p <PID of puma worker> -o /tmp/puma.txt
If you cannot isolate which Unicorn worker is the issue, try to run `strace`
on all the Unicorn workers to see where the
[`/internal/allowed`](../../development/internal_api.md) endpoint gets stuck:
[`/internal/allowed`](../../development/internal_api/index.md) endpoint gets stuck:
```shell
ps auwx | grep puma | awk '{ print " -p " $2}' | xargs strace -ttTfyyy -s 1024 -o /tmp/puma.txt
......
doc/development/api_styleguide.md
View file @ dc5164a7
......@@ -240,7 +240,7 @@ it's own file in the [`validators`](https://gitlab.com/gitlab-org/gitlab/-/blob/
## Internal API
The [internal API](internal_api.md) is documented for internal use. Please keep it up to date so we know what endpoints
The [internal API](internal_api/index.md) is documented for internal use. Please keep it up to date so we know what endpoints
different components are making use of.
## Avoiding N+1 problems
......
doc/development/architecture.md
View file @ dc5164a7
......@@ -976,12 +976,12 @@ in Rails, scheduled to run whenever an SSH key is modified by a user.
instead of keys. In this case, `AuthorizedKeysCommand` is replaced with an
`AuthorizedPrincipalsCommand`. This extracts a username from the certificate
without using the Rails internal API, which is used instead of `key_id` in the
[`/api/internal/allowed`](internal_api.md) call later.
[`/api/internal/allowed`](internal_api/index.md) call later.
GitLab Shell also has a few operations that do not involve Gitaly, such as
resetting two-factor authentication codes. These are handled in the same way,
except there is no round-trip into Gitaly - Rails performs the action as part
of the [internal API](internal_api.md) call, and GitLab Shell streams the
of the [internal API](internal_api/index.md) call, and GitLab Shell streams the
response back to the user directly.
## System layout
......
doc/development/internal_api.md
View file @ dc5164a7
---
stage: Create
group: Source Code
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
type: reference, api
redirect_to: 'internal_api/index.md'
remove_date: '2022-02-09'
---
# Internal API **(FREE)**
This document was moved to [another location](internal_api/index.md).
The internal API is used by different GitLab components, it can not be
used by other consumers. This documentation is intended for people
working on the GitLab codebase.
This documentation does not yet include the internal API used by
GitLab Pages.
## Adding new endpoints
API endpoints should be externally accessible by default, with proper authentication and authorization.
Before adding a new internal endpoint, consider if the API would potentially be
useful to the wider GitLab community and can be made externally accessible.
One reason we might favor internal API endpoints sometimes is when using such an endpoint requires
internal data that external actors can not have. For example, in the internal Pages API we might use
a secret token that identifies a request as internal or sign a request with a public key that is
not available to a wider community.
Another reason to separate something into an internal API is when request to such API endpoint
should never go through an edge (public) load balancer. This way we can configure different rate
limiting rules and policies around how the endpoint is being accessed, because we know that only
internal requests can be made to that endpoint going through an internal load balancer.
## Authentication
These methods are all authenticated using a shared secret. This secret
is stored in a file at the path configured in `config/gitlab.yml` by
default this is in the root of the rails app named
`.gitlab_shell_secret`
To authenticate using that token, clients read the contents of that
file, and include the token Base64 encoded in a `secret_token` parameter
or in the `Gitlab-Shared-Secret` header.
NOTE:
The internal API used by GitLab Pages, and GitLab Kubernetes Agent Server (`kas`) uses JSON Web Token (JWT)
authentication, which is different from GitLab Shell.
## Git Authentication
This is called by [Gitaly](https://gitlab.com/gitlab-org/gitaly) and
[GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) to check access to a
repository.
- **When called from GitLab Shell**: No changes are passed, and the internal
API replies with the information needed to pass the request on to Gitaly.
- **When called from Gitaly in a `pre-receive` hook**: The changes are passed
and validated to determine if the push is allowed.
Calls are limited to 50 seconds each.
```plaintext
POST /internal/allowed
```
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | string | no | ID of the SSH-key used to connect to GitLab Shell |
| `username` | string | no | Username from the certificate used to connect to GitLab Shell |
| `project` | string | no (if `gl_repository` is passed) | Path to the project |
| `gl_repository` | string | no (if `project` is passed) | Repository identifier, such as `project-7` |
| `protocol` | string | yes | SSH when called from GitLab Shell, HTTP or SSH when called from Gitaly |
| `action` | string | yes | Git command being run (`git-upload-pack`, `git-receive-pack`, `git-upload-archive`) |
| `changes` | string | yes | `<oldrev> <newrev> <refname>` when called from Gitaly, the magic string `_any` when called from GitLab Shell |
| `check_ip` | string | no | IP address from which call to GitLab Shell was made |
Example request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" \
--data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" \
"http://localhost:3001/api/v4/internal/allowed"
```
Example response:
```json
{
"status": true,
"gl_repository": "project-3",
"gl_project_path": "gnuwget/wget2",
"gl_id": "user-1",
"gl_username": "root",
"git_config_options": [],
"gitaly": {
"repository": {
"storage_name": "default",
"relative_path": "@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce.git",
"git_object_directory": "",
"git_alternate_object_directories": [],
"gl_repository": "project-3",
"gl_project_path": "gnuwget/wget2"
},
"address": "unix:/Users/bvl/repos/gitlab/gitaly.socket",
"token": null
},
"gl_console_messages": []
}
```
### Known consumers
- Gitaly
- GitLab Shell
## LFS Authentication
This is the endpoint that gets called from GitLab Shell to provide
information for LFS clients when the repository is accessed over SSH.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | string | no | ID of the SSH-key used to connect to GitLab Shell |
| `username`| string | no | Username from the certificate used to connect to GitLab Shell |
| `project` | string | no | Path to the project |
Example request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" \
--data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate"
```
```json
{
"username": "root",
"lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM",
"repository_http_path": "http://localhost:3001/gnuwget/wget2.git",
"expires_in": 1800
}
```
### Known consumers
- GitLab Shell
## Authorized Keys Check
This endpoint is called by the GitLab Shell authorized keys
check. Which is called by OpenSSH for [fast SSH key
lookup](../administration/operations/fast_ssh_key_lookup.md).
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key` | string | yes | SSH key as passed by OpenSSH to GitLab Shell |
```plaintext
GET /internal/authorized_keys
```
Example request:
```shell
curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/authorized_keys?key=<key as passed by OpenSSH>"
```
Example response:
```json
{
"id": 11,
"title": "admin@example.com",
"key": "ssh-rsa ...",
"created_at": "2019-06-27T15:29:02.219Z"
}
```
### Known consumers
- GitLab Shell
## Get user for user ID or key
This endpoint is used when a user performs `ssh git@gitlab.com`. It
discovers the user associated with an SSH key.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
| `username` | string | no | Username of the user being looked up, used by GitLab Shell when authenticating using a certificate |
```plaintext
GET /internal/discover
```
Example request:
```shell
curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/discover?key_id=7"
```
Example response:
```json
{
"id": 7,
"name": "Dede Eichmann",
"username": "rubi"
}
```
### Known consumers
- GitLab Shell
## Instance information
This gets some generic information about the instance. This is used
by Geo nodes to get information about each other.
```plaintext
GET /internal/check
```
Example request:
```shell
curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/check"
```
Example response:
```json
{
"api_version": "v4",
"gitlab_version": "12.3.0-pre",
"gitlab_rev": "d69c988e6a6",
"redis": true
}
```
### Known consumers
- GitLab Geo
- GitLab Shell's `bin/check`
- Gitaly
## Get new 2FA recovery codes using an SSH key
This is called from GitLab Shell and allows users to get new 2FA
recovery codes based on their SSH key.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
| `user_id` | integer | no | **Deprecated** User_id for which to generate new recovery codes |
```plaintext
GET /internal/two_factor_recovery_codes
```
Example request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
--data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes"
```
Example response:
```json
{
"success": true,
"recovery_codes": [
"d93ee7037944afd5",
"19d7b84862de93dd",
"1e8c52169195bf71",
"be50444dddb7ca84",
"26048c77d161d5b7",
"482d5c03d1628c47",
"d2c695e309ce7679",
"dfb4748afc4f12a7",
"0e5f53d1399d7979",
"af04d5622153b020"
]
}
```
### Known consumers
- GitLab Shell
## Get new personal access-token
This is called from GitLab Shell and allows users to generate a new
personal access token.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `name` | string | yes | The name of the new token |
| `scopes` | string array | yes | The authorization scopes for the new token, these must be valid token scopes |
| `expires_at` | string | no | The expiry date for the new token |
| `key_id` | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
| `user_id` | integer | no | User ID for which to generate the new token |
```plaintext
POST /internal/personal_access_token
```
Example request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
--data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" \
"http://localhost:3001/api/v4/internal/personal_access_token"
```
Example response:
```json
{
"success": true,
"token": "Hf_79B288hRv_3-TSD1R",
"scopes": ["read_user","read_repository"],
"expires_at": "2020-07-24"
}
```
### Known consumers
- GitLab Shell
## Incrementing counter on pre-receive
This is called from the Gitaly hooks increasing the reference counter
for a push that might be accepted.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `gl_repository` | string | yes | repository identifier for the repository receiving the push |
```plaintext
POST /internal/pre_receive
```
Example request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
--data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive"
```
Example response:
```json
{
"reference_counter_increased": true
}
```
## PostReceive
Called from Gitaly after a receiving a push. This triggers the
`PostReceive`-worker in Sidekiq, processes the passed push options and
builds the response including messages that need to be displayed to
the user.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `identifier` | string | yes | `user-[id]` or `key-[id]` Identifying the user performing the push |
| `gl_repository` | string | yes | identifier of the repository being pushed to |
| `push_options` | string array | no | array of push options |
| `changes` | string | no | refs to be updated in the push in the format `oldrev newrev refname\n`. |
```plaintext
POST /internal/post_receive
```
Example Request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
--data "gl_repository=project-7" --data "identifier=user-1" \
--data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" \
"http://localhost:3001/api/v4/internal/post_receive"
```
Example response:
```json
{
"messages": [
{
"message": "Hello from post-receive",
"type": "alert"
}
],
"reference_counter_decreased": true
}
```
## Kubernetes agent endpoints
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41045) in GitLab 13.4.
> - This feature is not deployed on GitLab.com
> - It's not recommended for production use.
The following endpoints are used by the GitLab Kubernetes Agent Server (`kas`)
for various purposes.
These endpoints are all authenticated using JWT. The JWT secret is stored in a file
specified in `config/gitlab.yml`. By default, the location is in the root of the
GitLab Rails app in a file called `.gitlab_kas_secret`.
WARNING:
The Kubernetes agent is under development and is not recommended for production use.
### Kubernetes agent information
Called from GitLab Kubernetes Agent Server (`kas`) to retrieve agent
information for the given agent token. This returns the Gitaly connection
information for the agent's project in order for `kas` to fetch and update
the agent's configuration.
```plaintext
GET /internal/kubernetes/agent_info
```
Example Request:
```shell
curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
--header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"
```
### Kubernetes agent project information
Called from GitLab Kubernetes Agent Server (`kas`) to retrieve project
information for the given agent token. This returns the Gitaly
connection for the requested project. GitLab `kas` uses this to configure
the agent to fetch Kubernetes resources from the project repository to
sync.
Only public projects are supported. For private projects, the ability for the
agent to be authorized is [not yet implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/220912).
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../api/index.md#namespaced-path-encoding) |
```plaintext
GET /internal/kubernetes/project_info
```
Example Request:
```shell
curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
--header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"
```
### Kubernetes agent usage metrics
Called from GitLab Kubernetes Agent Server (`kas`) to increase the usage
metric counters.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `gitops_sync_count` | integer| no | The number to increase the `gitops_sync_count` counter by |
| `k8s_api_proxy_request_count` | integer| no | The number to increase the `k8s_api_proxy_request_count` counter by |
```plaintext
POST /internal/kubernetes/usage_metrics
```
Example Request:
```shell
curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Content-Type: application/json" \
--data '{"gitops_sync_count":1}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics"
```
### Kubernetes agent alert metrics
Called from GitLab Kubernetes Agent Server (KAS) to save alerts derived from Cilium on Kubernetes
Cluster.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `alert` | Hash | yes | Alerts detail. Same format as [3rd party alert](../operations/incident_management/integrations.md#customize-the-alert-payload-outside-of-gitlab). |
```plaintext
POST internal/kubernetes/modules/cilium_alert
```
Example Request:
```shell
curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" \
--header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
--data '"{\"alert\":{\"title\":\"minimal\",\"message\":\"network problem\",\"evalMatches\":[{\"value\":1,\"metric\":\"Count\",\"tags\":{}}]}}"' \
"http://localhost:3000/api/v4/internal/kubernetes/modules/cilium_alert"
```
### Create Starboard vulnerability
Called from the GitLab Kubernetes Agent Server (`kas`) to create a security vulnerability
from a Starboard vulnerability report. This request is idempotent. Multiple requests with the same data
create a single vulnerability.
| Attribute | Type | Required | Description |
|:----------------|:-------|:---------|:------------|
| `vulnerability` | Hash | yes | Vulnerability data matching the security report schema [`vulnerability` field](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/src/security-report-format.json). |
| `scanner` | Hash | yes | Scanner data matching the security report schema [`scanner` field](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/src/security-report-format.json). |
```plaintext
PUT internal/kubernetes/modules/starboard_vulnerability
```
Example Request:
```shell
curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT token>" \
--header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
--url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \
--data '{
"vulnerability": {
"name": "CVE-123-4567 in libc",
"severity": "high",
"confidence": "unknown",
"location": {
"kubernetes_resource": {
"namespace": "production",
"kind": "deployment",
"name": "nginx",
"container": "nginx"
}
},
"identifiers": [
{
"type": "cve",
"name": "CVE-123-4567",
"value": "CVE-123-4567"
}
]
},
"scanner": {
"id": "starboard_trivy",
"name": "Trivy (via Starboard Operator)",
"vendor": "GitLab"
}
}'
```
## Subscriptions
The subscriptions endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
in order to apply subscriptions including trials, and add-on purchases, for personal namespaces or top-level groups within GitLab.com.
### Creating a subscription
Use a POST to create a subscription.
```plaintext
POST /namespaces/:id/gitlab_subscription
```
| Attribute | Type | Required | Description |
|:------------|:--------|:---------|:------------|
| `start_date` | date | yes | Start date of subscription |
| `end_date` | date | no | End date of subscription |
| `plan_code` | string | no | Subscription tier code |
| `seats` | integer | no | Number of seats in subscription |
| `max_seats_used` | integer | no | Highest number of active users in the last month |
| `auto_renew` | boolean | no | Whether subscription auto-renews on end date |
| `trial` | boolean | no | Whether subscription is a trial |
| `trial_starts_on` | date | no | Start date of trial |
| `trial_ends_on` | date | no | End date of trial |
Example request:
```shell
curl --request POST --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="premium"&seats=10"
```
Example response:
```json
{
"plan": {
"code":"premium",
"name":"premium",
"trial":false,
"auto_renew":null,
"upgradable":false
},
"usage": {
"seats_in_subscription":10,
"seats_in_use":1,
"max_seats_used":0,
"seats_owed":0
},
"billing": {
"subscription_start_date":"2020-07-15",
"subscription_end_date":null,
"trial_ends_on":null
}
}
```
### Updating a subscription
Use a PUT command to update an existing subscription.
```plaintext
PUT /namespaces/:id/gitlab_subscription
```
| Attribute | Type | Required | Description |
|:------------|:--------|:---------|:------------|
| `start_date` | date | no | Start date of subscription |
| `end_date` | date | no | End date of subscription |
| `plan_code` | string | no | Subscription tier code |
| `seats` | integer | no | Number of seats in subscription |
| `max_seats_used` | integer | no | Highest number of active users in the last month |
| `auto_renew` | boolean | no | Whether subscription auto-renews on end date |
| `trial` | boolean | no | Whether subscription is a trial |
| `trial_starts_on` | date | no | Start date of trial. Required if trial is true. |
| `trial_ends_on` | date | no | End date of trial |
Example request:
```shell
curl --request PUT --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0"
```
Example response:
```json
{
"plan": {
"code":"premium",
"name":"premium",
"trial":false,
"auto_renew":null,
"upgradable":false
},
"usage": {
"seats_in_subscription":80,
"seats_in_use":82,
"max_seats_used":0,
"seats_owed":2
},
"billing": {
"subscription_start_date":"2020-07-15",
"subscription_end_date":"2021-07-15",
"trial_ends_on":null
}
}
```
### Retrieving a subscription
Use a GET command to view an existing subscription.
```plaintext
GET /namespaces/:id/gitlab_subscription
```
Example request:
```shell
curl --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription"
```
Example response:
```json
{
"plan": {
"code":"premium",
"name":"premium",
"trial":false,
"auto_renew":null,
"upgradable":false
},
"usage": {
"seats_in_subscription":80,
"seats_in_use":82,
"max_seats_used":82,
"seats_owed":2
},
"billing": {
"subscription_start_date":"2020-07-15",
"subscription_end_date":"2021-07-15",
"trial_ends_on":null
}
}
```
### Known consumers
- CustomersDot
## CI minute provisioning
The CI Minute endpoints are used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
to apply additional packs of CI minutes, for personal namespaces or top-level groups within GitLab.com.
### Creating an additional pack
Use a POST to create additional packs.
```plaintext
POST /namespaces/:id/minutes
```
| Attribute | Type | Required | Description |
|:------------|:--------|:---------|:------------|
| `packs` | array | yes | An array of purchased minutes packs |
| `packs[expires_at]` | date | yes | Expiry date of the purchased pack|
| `packs[number_of_minutes]` | integer | yes | Number of additional minutes |
| `packs[purchase_xid]` | string | yes | The unique ID of the purchase |
Example request:
```shell
curl --request POST \
--url "http://localhost:3000/api/v4/namespaces/123/minutes" \
--header 'Content-Type: application/json' \
--header 'PRIVATE-TOKEN: <admin access token>' \
--data '{
"packs": [
{
"number_of_minutes": 10000,
"expires_at": "2022-01-01",
"purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
}
]
}'
```
Example response:
```json
[
{
"namespace_id": 123,
"expires_at": "2022-01-01",
"number_of_minutes": 10000,
"purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
}
]
```
### Moving additional packs
Use a PATCH to move additional packs from one namespace to another.
```plaintext
PATCH /namespaces/:id/minutes/move/:target_id
```
| Attribute | Type | Required | Description |
|:------------|:--------|:---------|:------------|
| `id` | string | yes | The ID of the namespace to transfer packs from |
| `target_id` | string | yes | The ID of the target namespace to transfer the packs to |
Example request:
```shell
curl --request PATCH \
--url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \
--header 'PRIVATE-TOKEN: <admin access token>'
```
Example response:
```json
{
"message": "202 Accepted"
}
```
### Known consumers
- CustomersDot
## Upcoming reconciliations
The `upcoming_reconciliations` endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
to update upcoming reconciliations for namespaces.
### Updating `upcoming_reconciliations`
Use a PUT command to update `upcoming_reconciliations`.
```plaintext
PUT /internal/upcoming_reconciliations
```
| Attribute | Type | Required | Description |
|:-------------------|:-----------|:---------|:------------|
| `upcoming_reconciliations` | array | yes | Array of upcoming reconciliations |
Each array element contains:
| Attribute | Type | Required | Description |
|:-------------------|:-----------|:---------|:------------|
| `namespace_id` | integer | yes | ID of the namespace to be reconciled |
| `next_reconciliation_date` | date | yes | Date when next reconciliation will happen |
| `display_alert_from` | date | yes | Start date to display alert of upcoming reconciliation |
Example request:
```shell
curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" --header "Content-Type: application/json" \
--data '{"upcoming_reconciliations": [{"namespace_id": 127, "next_reconciliation_date": "13 Jun 2021", "display_alert_from": "06 Jun 2021"}, {"namespace_id": 129, "next_reconciliation_date": "12 Jun 2021", "display_alert_from": "05 Jun 2021"}]}' \
"https://gitlab.com/api/v4/internal/upcoming_reconciliations"
```
Example response:
```plaintext
200
```
### Known consumers
- CustomersDot
<!-- This redirect file can be deleted after <YYYY-MM-DD>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
doc/development/internal_api/index.md 0 → 100644
View file @ dc5164a7
---
stage: Create
group: Source Code
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
type: reference, api
---
# Internal API **(FREE)**
The internal API is used by different GitLab components, it can not be
used by other consumers. This documentation is intended for people
working on the GitLab codebase.
This documentation does not yet include the internal API used by
GitLab Pages.
## Adding new endpoints
API endpoints should be externally accessible by default, with proper authentication and authorization.
Before adding a new internal endpoint, consider if the API would potentially be
useful to the wider GitLab community and can be made externally accessible.
One reason we might favor internal API endpoints sometimes is when using such an endpoint requires
internal data that external actors can not have. For example, in the internal Pages API we might use
a secret token that identifies a request as internal or sign a request with a public key that is
not available to a wider community.
Another reason to separate something into an internal API is when request to such API endpoint
should never go through an edge (public) load balancer. This way we can configure different rate
limiting rules and policies around how the endpoint is being accessed, because we know that only
internal requests can be made to that endpoint going through an internal load balancer.
## Authentication
These methods are all authenticated using a shared secret. This secret
is stored in a file at the path configured in `config/gitlab.yml` by
default this is in the root of the rails app named
`.gitlab_shell_secret`
To authenticate using that token, clients read the contents of that
file, and include the token Base64 encoded in a `secret_token` parameter
or in the `Gitlab-Shared-Secret` header.
NOTE:
The internal API used by GitLab Pages, and GitLab Kubernetes Agent Server (`kas`) uses JSON Web Token (JWT)
authentication, which is different from GitLab Shell.
## Git Authentication
This is called by [Gitaly](https://gitlab.com/gitlab-org/gitaly) and
[GitLab Shell](https://gitlab.com/gitlab-org/gitlab-shell) to check access to a
repository.
- **When called from GitLab Shell**: No changes are passed, and the internal
API replies with the information needed to pass the request on to Gitaly.
- **When called from Gitaly in a `pre-receive` hook**: The changes are passed
and validated to determine if the push is allowed.
Calls are limited to 50 seconds each.
```plaintext
POST /internal/allowed
```
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | string | no | ID of the SSH-key used to connect to GitLab Shell |
| `username` | string | no | Username from the certificate used to connect to GitLab Shell |
| `project` | string | no (if `gl_repository` is passed) | Path to the project |
| `gl_repository` | string | no (if `project` is passed) | Repository identifier, such as `project-7` |
| `protocol` | string | yes | SSH when called from GitLab Shell, HTTP or SSH when called from Gitaly |
| `action` | string | yes | Git command being run (`git-upload-pack`, `git-receive-pack`, `git-upload-archive`) |
| `changes` | string | yes | `<oldrev> <newrev> <refname>` when called from Gitaly, the magic string `_any` when called from GitLab Shell |
| `check_ip` | string | no | IP address from which call to GitLab Shell was made |
Example request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" \
--data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" \
"http://localhost:3001/api/v4/internal/allowed"
```
Example response:
```json
{
"status": true,
"gl_repository": "project-3",
"gl_project_path": "gnuwget/wget2",
"gl_id": "user-1",
"gl_username": "root",
"git_config_options": [],
"gitaly": {
"repository": {
"storage_name": "default",
"relative_path": "@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce.git",
"git_object_directory": "",
"git_alternate_object_directories": [],
"gl_repository": "project-3",
"gl_project_path": "gnuwget/wget2"
},
"address": "unix:/Users/bvl/repos/gitlab/gitaly.socket",
"token": null
},
"gl_console_messages": []
}
```
### Known consumers
- Gitaly
- GitLab Shell
## LFS Authentication
This is the endpoint that gets called from GitLab Shell to provide
information for LFS clients when the repository is accessed over SSH.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | string | no | ID of the SSH-key used to connect to GitLab Shell |
| `username`| string | no | Username from the certificate used to connect to GitLab Shell |
| `project` | string | no | Path to the project |
Example request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded token>" \
--data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate"
```
```json
{
"username": "root",
"lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM",
"repository_http_path": "http://localhost:3001/gnuwget/wget2.git",
"expires_in": 1800
}
```
### Known consumers
- GitLab Shell
## Authorized Keys Check
This endpoint is called by the GitLab Shell authorized keys
check. Which is called by OpenSSH for [fast SSH key
lookup](../../administration/operations/fast_ssh_key_lookup.md).
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key` | string | yes | SSH key as passed by OpenSSH to GitLab Shell |
```plaintext
GET /internal/authorized_keys
```
Example request:
```shell
curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/authorized_keys?key=<key as passed by OpenSSH>"
```
Example response:
```json
{
"id": 11,
"title": "admin@example.com",
"key": "ssh-rsa ...",
"created_at": "2019-06-27T15:29:02.219Z"
}
```
### Known consumers
- GitLab Shell
## Get user for user ID or key
This endpoint is used when a user performs `ssh git@gitlab.com`. It
discovers the user associated with an SSH key.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
| `username` | string | no | Username of the user being looked up, used by GitLab Shell when authenticating using a certificate |
```plaintext
GET /internal/discover
```
Example request:
```shell
curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/discover?key_id=7"
```
Example response:
```json
{
"id": 7,
"name": "Dede Eichmann",
"username": "rubi"
}
```
### Known consumers
- GitLab Shell
## Instance information
This gets some generic information about the instance. This is used
by Geo nodes to get information about each other.
```plaintext
GET /internal/check
```
Example request:
```shell
curl --request GET --header "Gitlab-Shared-Secret: <Base64 encoded secret>" "http://localhost:3001/api/v4/internal/check"
```
Example response:
```json
{
"api_version": "v4",
"gitlab_version": "12.3.0-pre",
"gitlab_rev": "d69c988e6a6",
"redis": true
}
```
### Known consumers
- GitLab Geo
- GitLab Shell's `bin/check`
- Gitaly
## Get new 2FA recovery codes using an SSH key
This is called from GitLab Shell and allows users to get new 2FA
recovery codes based on their SSH key.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `key_id` | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
| `user_id` | integer | no | **Deprecated** User_id for which to generate new recovery codes |
```plaintext
GET /internal/two_factor_recovery_codes
```
Example request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
--data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes"
```
Example response:
```json
{
"success": true,
"recovery_codes": [
"d93ee7037944afd5",
"19d7b84862de93dd",
"1e8c52169195bf71",
"be50444dddb7ca84",
"26048c77d161d5b7",
"482d5c03d1628c47",
"d2c695e309ce7679",
"dfb4748afc4f12a7",
"0e5f53d1399d7979",
"af04d5622153b020"
]
}
```
### Known consumers
- GitLab Shell
## Get new personal access-token
This is called from GitLab Shell and allows users to generate a new
personal access token.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `name` | string | yes | The name of the new token |
| `scopes` | string array | yes | The authorization scopes for the new token, these must be valid token scopes |
| `expires_at` | string | no | The expiry date for the new token |
| `key_id` | integer | no | The ID of the SSH key used as found in the authorized-keys file or through the `/authorized_keys` check |
| `user_id` | integer | no | User ID for which to generate the new token |
```plaintext
POST /internal/personal_access_token
```
Example request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
--data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" \
"http://localhost:3001/api/v4/internal/personal_access_token"
```
Example response:
```json
{
"success": true,
"token": "Hf_79B288hRv_3-TSD1R",
"scopes": ["read_user","read_repository"],
"expires_at": "2020-07-24"
}
```
### Known consumers
- GitLab Shell
## Incrementing counter on pre-receive
This is called from the Gitaly hooks increasing the reference counter
for a push that might be accepted.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `gl_repository` | string | yes | repository identifier for the repository receiving the push |
```plaintext
POST /internal/pre_receive
```
Example request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
--data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive"
```
Example response:
```json
{
"reference_counter_increased": true
}
```
## PostReceive
Called from Gitaly after a receiving a push. This triggers the
`PostReceive`-worker in Sidekiq, processes the passed push options and
builds the response including messages that need to be displayed to
the user.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `identifier` | string | yes | `user-[id]` or `key-[id]` Identifying the user performing the push |
| `gl_repository` | string | yes | identifier of the repository being pushed to |
| `push_options` | string array | no | array of push options |
| `changes` | string | no | refs to be updated in the push in the format `oldrev newrev refname\n`. |
```plaintext
POST /internal/post_receive
```
Example Request:
```shell
curl --request POST --header "Gitlab-Shared-Secret: <Base64 encoded secret>" \
--data "gl_repository=project-7" --data "identifier=user-1" \
--data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" \
"http://localhost:3001/api/v4/internal/post_receive"
```
Example response:
```json
{
"messages": [
{
"message": "Hello from post-receive",
"type": "alert"
}
],
"reference_counter_decreased": true
}
```
## Kubernetes agent endpoints
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/41045) in GitLab 13.4.
> - This feature is not deployed on GitLab.com
> - It's not recommended for production use.
The following endpoints are used by the GitLab Kubernetes Agent Server (`kas`)
for various purposes.
These endpoints are all authenticated using JWT. The JWT secret is stored in a file
specified in `config/gitlab.yml`. By default, the location is in the root of the
GitLab Rails app in a file called `.gitlab_kas_secret`.
WARNING:
The Kubernetes agent is under development and is not recommended for production use.
### Kubernetes agent information
Called from GitLab Kubernetes Agent Server (`kas`) to retrieve agent
information for the given agent token. This returns the Gitaly connection
information for the agent's project in order for `kas` to fetch and update
the agent's configuration.
```plaintext
GET /internal/kubernetes/agent_info
```
Example Request:
```shell
curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
--header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"
```
### Kubernetes agent project information
Called from GitLab Kubernetes Agent Server (`kas`) to retrieve project
information for the given agent token. This returns the Gitaly
connection for the requested project. GitLab `kas` uses this to configure
the agent to fetch Kubernetes resources from the project repository to
sync.
Only public projects are supported. For private projects, the ability for the
agent to be authorized is [not yet implemented](https://gitlab.com/gitlab-org/gitlab/-/issues/220912).
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../../api/index.md#namespaced-path-encoding) |
```plaintext
GET /internal/kubernetes/project_info
```
Example Request:
```shell
curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
--header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"
```
### Kubernetes agent usage metrics
Called from GitLab Kubernetes Agent Server (`kas`) to increase the usage
metric counters.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `gitops_sync_count` | integer| no | The number to increase the `gitops_sync_count` counter by |
| `k8s_api_proxy_request_count` | integer| no | The number to increase the `k8s_api_proxy_request_count` counter by |
```plaintext
POST /internal/kubernetes/usage_metrics
```
Example Request:
```shell
curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Content-Type: application/json" \
--data '{"gitops_sync_count":1}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics"
```
### Kubernetes agent alert metrics
Called from GitLab Kubernetes Agent Server (KAS) to save alerts derived from Cilium on Kubernetes
Cluster.
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `alert` | Hash | yes | Alerts detail. Same format as [3rd party alert](../../operations/incident_management/integrations.md#customize-the-alert-payload-outside-of-gitlab). |
```plaintext
POST internal/kubernetes/modules/cilium_alert
```
Example Request:
```shell
curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" \
--header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
--data '"{\"alert\":{\"title\":\"minimal\",\"message\":\"network problem\",\"evalMatches\":[{\"value\":1,\"metric\":\"Count\",\"tags\":{}}]}}"' \
"http://localhost:3000/api/v4/internal/kubernetes/modules/cilium_alert"
```
### Create Starboard vulnerability
Called from the GitLab Kubernetes Agent Server (`kas`) to create a security vulnerability
from a Starboard vulnerability report. This request is idempotent. Multiple requests with the same data
create a single vulnerability.
| Attribute | Type | Required | Description |
|:----------------|:-------|:---------|:------------|
| `vulnerability` | Hash | yes | Vulnerability data matching the security report schema [`vulnerability` field](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/src/security-report-format.json). |
| `scanner` | Hash | yes | Scanner data matching the security report schema [`scanner` field](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/src/security-report-format.json). |
```plaintext
PUT internal/kubernetes/modules/starboard_vulnerability
```
Example Request:
```shell
curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT token>" \
--header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
--url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \
--data '{
"vulnerability": {
"name": "CVE-123-4567 in libc",
"severity": "high",
"confidence": "unknown",
"location": {
"kubernetes_resource": {
"namespace": "production",
"kind": "deployment",
"name": "nginx",
"container": "nginx"
}
},
"identifiers": [
{
"type": "cve",
"name": "CVE-123-4567",
"value": "CVE-123-4567"
}
]
},
"scanner": {
"id": "starboard_trivy",
"name": "Trivy (via Starboard Operator)",
"vendor": "GitLab"
}
}'
```
## Subscriptions
The subscriptions endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
in order to apply subscriptions including trials, and add-on purchases, for personal namespaces or top-level groups within GitLab.com.
### Creating a subscription
Use a POST to create a subscription.
```plaintext
POST /namespaces/:id/gitlab_subscription
```
| Attribute | Type | Required | Description |
|:------------|:--------|:---------|:------------|
| `start_date` | date | yes | Start date of subscription |
| `end_date` | date | no | End date of subscription |
| `plan_code` | string | no | Subscription tier code |
| `seats` | integer | no | Number of seats in subscription |
| `max_seats_used` | integer | no | Highest number of active users in the last month |
| `auto_renew` | boolean | no | Whether subscription auto-renews on end date |
| `trial` | boolean | no | Whether subscription is a trial |
| `trial_starts_on` | date | no | Start date of trial |
| `trial_ends_on` | date | no | End date of trial |
Example request:
```shell
curl --request POST --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="premium"&seats=10"
```
Example response:
```json
{
"plan": {
"code":"premium",
"name":"premium",
"trial":false,
"auto_renew":null,
"upgradable":false
},
"usage": {
"seats_in_subscription":10,
"seats_in_use":1,
"max_seats_used":0,
"seats_owed":0
},
"billing": {
"subscription_start_date":"2020-07-15",
"subscription_end_date":null,
"trial_ends_on":null
}
}
```
### Updating a subscription
Use a PUT command to update an existing subscription.
```plaintext
PUT /namespaces/:id/gitlab_subscription
```
| Attribute | Type | Required | Description |
|:------------|:--------|:---------|:------------|
| `start_date` | date | no | Start date of subscription |
| `end_date` | date | no | End date of subscription |
| `plan_code` | string | no | Subscription tier code |
| `seats` | integer | no | Number of seats in subscription |
| `max_seats_used` | integer | no | Highest number of active users in the last month |
| `auto_renew` | boolean | no | Whether subscription auto-renews on end date |
| `trial` | boolean | no | Whether subscription is a trial |
| `trial_starts_on` | date | no | Start date of trial. Required if trial is true. |
| `trial_ends_on` | date | no | End date of trial |
Example request:
```shell
curl --request PUT --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0"
```
Example response:
```json
{
"plan": {
"code":"premium",
"name":"premium",
"trial":false,
"auto_renew":null,
"upgradable":false
},
"usage": {
"seats_in_subscription":80,
"seats_in_use":82,
"max_seats_used":0,
"seats_owed":2
},
"billing": {
"subscription_start_date":"2020-07-15",
"subscription_end_date":"2021-07-15",
"trial_ends_on":null
}
}
```
### Retrieving a subscription
Use a GET command to view an existing subscription.
```plaintext
GET /namespaces/:id/gitlab_subscription
```
Example request:
```shell
curl --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription"
```
Example response:
```json
{
"plan": {
"code":"premium",
"name":"premium",
"trial":false,
"auto_renew":null,
"upgradable":false
},
"usage": {
"seats_in_subscription":80,
"seats_in_use":82,
"max_seats_used":82,
"seats_owed":2
},
"billing": {
"subscription_start_date":"2020-07-15",
"subscription_end_date":"2021-07-15",
"trial_ends_on":null
}
}
```
### Known consumers
- CustomersDot
## CI minute provisioning
The CI Minute endpoints are used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
to apply additional packs of CI minutes, for personal namespaces or top-level groups within GitLab.com.
### Creating an additional pack
Use a POST to create additional packs.
```plaintext
POST /namespaces/:id/minutes
```
| Attribute | Type | Required | Description |
|:------------|:--------|:---------|:------------|
| `packs` | array | yes | An array of purchased minutes packs |
| `packs[expires_at]` | date | yes | Expiry date of the purchased pack|
| `packs[number_of_minutes]` | integer | yes | Number of additional minutes |
| `packs[purchase_xid]` | string | yes | The unique ID of the purchase |
Example request:
```shell
curl --request POST \
--url "http://localhost:3000/api/v4/namespaces/123/minutes" \
--header 'Content-Type: application/json' \
--header 'PRIVATE-TOKEN: <admin access token>' \
--data '{
"packs": [
{
"number_of_minutes": 10000,
"expires_at": "2022-01-01",
"purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
}
]
}'
```
Example response:
```json
[
{
"namespace_id": 123,
"expires_at": "2022-01-01",
"number_of_minutes": 10000,
"purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
}
]
```
### Moving additional packs
Use a PATCH to move additional packs from one namespace to another.
```plaintext
PATCH /namespaces/:id/minutes/move/:target_id
```
| Attribute | Type | Required | Description |
|:------------|:--------|:---------|:------------|
| `id` | string | yes | The ID of the namespace to transfer packs from |
| `target_id` | string | yes | The ID of the target namespace to transfer the packs to |
Example request:
```shell
curl --request PATCH \
--url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \
--header 'PRIVATE-TOKEN: <admin access token>'
```
Example response:
```json
{
"message": "202 Accepted"
}
```
### Known consumers
- CustomersDot
## Upcoming reconciliations
The `upcoming_reconciliations` endpoint is used by [CustomersDot](https://gitlab.com/gitlab-org/customers-gitlab-com) (`customers.gitlab.com`)
to update upcoming reconciliations for namespaces.
### Updating `upcoming_reconciliations`
Use a PUT command to update `upcoming_reconciliations`.
```plaintext
PUT /internal/upcoming_reconciliations
```
| Attribute | Type | Required | Description |
|:-------------------|:-----------|:---------|:------------|
| `upcoming_reconciliations` | array | yes | Array of upcoming reconciliations |
Each array element contains:
| Attribute | Type | Required | Description |
|:-------------------|:-----------|:---------|:------------|
| `namespace_id` | integer | yes | ID of the namespace to be reconciled |
| `next_reconciliation_date` | date | yes | Date when next reconciliation will happen |
| `display_alert_from` | date | yes | Start date to display alert of upcoming reconciliation |
Example request:
```shell
curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" --header "Content-Type: application/json" \
--data '{"upcoming_reconciliations": [{"namespace_id": 127, "next_reconciliation_date": "13 Jun 2021", "display_alert_from": "06 Jun 2021"}, {"namespace_id": 129, "next_reconciliation_date": "12 Jun 2021", "display_alert_from": "05 Jun 2021"}]}' \
"https://gitlab.com/api/v4/internal/upcoming_reconciliations"
```
Example response:
```plaintext
200
```
### Known consumers
- CustomersDot
doc/development/maintenance_mode.md
View file @ dc5164a7
......@@ -13,7 +13,7 @@ GitLab Maintenance Mode **only** blocks writes from HTTP and SSH requests at the
- [the read-only database method](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/database.rb#L13), which toggles special behavior when we are not allowed to write to the database. [Search the codebase for `Gitlab::Database.read_only?`.](https://gitlab.com/search?search=Gitlab%3A%3ADatabase.read_only%3F&group_id=9970&project_id=278964&scope=blobs&search_code=false&snippets=false&repository_ref=)
- [the read-only middleware](https://gitlab.com/gitlab-org/gitlab/-/blob/master/ee/lib/ee/gitlab/middleware/read_only/controller.rb), where HTTP requests that cause database writes are blocked, unless explicitly allowed.
- [Git push access via SSH is denied](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/git_access.rb#L13) by returning 401 when `gitlab-shell` POSTs to [`/internal/allowed`](internal_api.md) to [check if access is allowed](internal_api.md#git-authentication).
- [Git push access via SSH is denied](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/lib/ee/gitlab/git_access.rb#L13) by returning 401 when `gitlab-shell` POSTs to [`/internal/allowed`](internal_api/index.md) to [check if access is allowed](internal_api/index.md#git-authentication).
- [Container registry authentication service](https://gitlab.com/gitlab-org/gitlab/-/blob/2425e9de50c678413ceaad6ee3bf66f42b7e228c/ee/app/services/ee/auth/container_registry_authentication_service.rb#L12), where updates to the container registry are blocked.
The database itself is not in read-only mode (except in a Geo secondary site) and can be written by sources other than the ones blocked.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7