diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-19 01:45:44 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-09-19 01:45:44 +0000 |
commit | 85dc423f7090da0a52c73eb66faf22ddb20efff9 (patch) | |
tree | 9160f299afd8c80c038f08e1545be119f5e3f1e1 /doc/development/internal_api.md | |
parent | 15c2c8c66dbe422588e5411eee7e68f1fa440bb8 (diff) | |
download | gitlab-ce-85dc423f7090da0a52c73eb66faf22ddb20efff9.tar.gz |
Add latest changes from gitlab-org/gitlab@13-4-stable-ee
Diffstat (limited to 'doc/development/internal_api.md')
-rw-r--r-- | doc/development/internal_api.md | 81 |
1 files changed, 79 insertions, 2 deletions
diff --git a/doc/development/internal_api.md b/doc/development/internal_api.md index c51bf66be46..4b46787c2c3 100644 --- a/doc/development/internal_api.md +++ b/doc/development/internal_api.md @@ -26,8 +26,8 @@ file, and include the token Base64 encoded in a `secret_token` parameter or in the `Gitlab-Shared-Secret` header. NOTE: **Note:** -The internal API used by GitLab Pages uses a different kind of -authentication. +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 @@ -370,3 +370,80 @@ Example response: "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`. + +CAUTION: **Caution:** +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 currently 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/README.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| yes | The number to increase the `gitops_sync_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" +``` |