API de l'agent Kubernetes

{{< details >}}

• Édition : Gratuite, GitLab Premium, GitLab Ultimate
• Offre : GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

• API des jetons d'agent introduite dans GitLab 15.0.

{{< /history >}}

Utilisez cette API pour interagir avec l'agent GitLab pour Kubernetes.

Lister tous les agents {#list-all-agents}

Liste tous les agents enregistrés pour le projet.

Vous devez disposer du rôle Developer, Maintainer ou Owner pour utiliser ce point de terminaison.

GET /projects/:id/cluster_agents

Paramètres :

Réponse :

La réponse est une liste d'agents avec les champs suivants :

Exemple de requête :

curl \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents"

Exemple de réponse :

[
  {
    "id": 1,
    "name": "agent-1",
    "config_project": {
      "id": 20,
      "description": "",
      "name": "test",
      "name_with_namespace": "Administrator / test",
      "path": "test",
      "path_with_namespace": "root/test",
      "created_at": "2022-03-20T20:42:40.221Z"
    },
    "created_at": "2022-04-20T20:42:40.221Z",
    "created_by_user_id": 42
  },
  {
    "id": 2,
    "name": "agent-2",
    "config_project": {
      "id": 20,
      "description": "",
      "name": "test",
      "name_with_namespace": "Administrator / test",
      "path": "test",
      "path_with_namespace": "root/test",
      "created_at": "2022-03-20T20:42:40.221Z"
    },
    "created_at": "2022-04-20T20:42:40.221Z",
    "created_by_user_id": 42
  }
]

Récupérer un agent {#retrieve-an-agent}

Récupère les détails d'un agent unique.

Vous devez disposer du rôle Developer, Maintainer ou Owner pour utiliser ce point de terminaison.

GET /projects/:id/cluster_agents/:agent_id

Paramètres :

Réponse :

La réponse est un agent unique avec les champs suivants :

Exemple de requête :

curl \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1"

Exemple de réponse :

{
  "id": 1,
  "name": "agent-1",
  "config_project": {
    "id": 20,
    "description": "",
    "name": "test",
    "name_with_namespace": "Administrator / test",
    "path": "test",
    "path_with_namespace": "root/test",
    "created_at": "2022-03-20T20:42:40.221Z"
  },
  "created_at": "2022-04-20T20:42:40.221Z",
  "created_by_user_id": 42
}

Créer un agent {#create-an-agent}

Crée un nouvel agent pour le projet.

Vous devez disposer du rôle Maintainer ou Owner pour utiliser ce point de terminaison.

POST /projects/:id/cluster_agents

Paramètres :

Réponse :

La réponse est le nouvel agent avec les champs suivants :

Exemple de requête :

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents" \
  --data '{"name":"some-agent"}'

Exemple de réponse :

{
  "id": 1,
  "name": "agent-1",
  "config_project": {
    "id": 20,
    "description": "",
    "name": "test",
    "name_with_namespace": "Administrator / test",
    "path": "test",
    "path_with_namespace": "root/test",
    "created_at": "2022-03-20T20:42:40.221Z"
  },
  "created_at": "2022-04-20T20:42:40.221Z",
  "created_by_user_id": 42
}

Supprimer un agent {#delete-an-agent}

Supprime un enregistrement d'agent existant.

Vous devez disposer du rôle Maintainer ou Owner pour utiliser ce point de terminaison.

DELETE /projects/:id/cluster_agents/:agent_id

Paramètres :

Exemple de requête :

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/1"

Lister tous les jetons d'agent {#list-all-agent-tokens}

{{< history >}}

• Introduit dans GitLab 15.0.

{{< /history >}}

Liste tous les jetons actifs d'un agent.

Vous devez disposer du rôle Developer, Maintainer ou Owner pour utiliser ce point de terminaison.

GET /projects/:id/cluster_agents/:agent_id/tokens

Attributs pris en charge :

Réponse :

La réponse est une liste de jetons avec les champs suivants :

Exemple de requête :

curl \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens"

Exemple de réponse :

[
  {
    "id": 1,
    "name": "abcd",
    "description": "Some token",
    "agent_id": 5,
    "status": "active",
    "created_at": "2022-03-25T14:12:11.497Z",
    "created_by_user_id": 1
  },
  {
    "id": 2,
    "name": "foobar",
    "description": null,
    "agent_id": 5,
    "status": "active",
    "created_at": "2022-03-25T14:12:11.497Z",
    "created_by_user_id": 1
  }
]

[!note] Le champ last_used_at d'un jeton n'est retourné que lors de la récupération d'un seul jeton d'agent.

Récupérer un jeton d'agent {#retrieve-an-agent-token}

{{< history >}}

• Introduit dans GitLab 15.0.

{{< /history >}}

Récupère un seul jeton d'agent.

Vous devez disposer du rôle Developer, Maintainer ou Owner pour utiliser ce point de terminaison.

Retourne un 404 si le jeton d'agent a été révoqué.

GET /projects/:id/cluster_agents/:agent_id/tokens/:token_id

Attributs pris en charge :

Réponse :

La réponse est un seul jeton avec les champs suivants :

Exemple de requête :

curl \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/token/1"

Exemple de réponse :

{
  "id": 1,
  "name": "abcd",
  "description": "Some token",
  "agent_id": 5,
  "status": "active",
  "created_at": "2022-03-25T14:12:11.497Z",
  "created_by_user_id": 1,
  "last_used_at": null
}

Créer un jeton d'agent {#create-an-agent-token}

{{< history >}}

• Introduit dans GitLab 15.0.
• La limite de deux jetons a été introduite dans GitLab 16.1 avec un indicateur nommé cluster_agents_limit_tokens_created.
• La limite de deux jetons est généralement disponible dans GitLab 16.2. L'indicateur de fonctionnalité cluster_agents_limit_tokens_created a été supprimé.

{{< /history >}}

Crée un nouveau jeton pour un agent.

Vous devez disposer du rôle Maintainer ou Owner pour utiliser ce point de terminaison.

Un agent ne peut avoir que deux jetons actifs à la fois.

POST /projects/:id/cluster_agents/:agent_id/tokens

Attributs pris en charge :

Réponse :

La réponse est le nouveau jeton avec les champs suivants :

[!note] Le token n'est retourné que dans la réponse du point de terminaison POST et ne peut pas être récupéré ultérieurement.

Exemple de requête :

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens" \
  --data '{"name":"some-token"}'

Exemple de réponse :

{
  "id": 1,
  "name": "abcd",
  "description": "Some token",
  "agent_id": 5,
  "status": "active",
  "created_at": "2022-03-25T14:12:11.497Z",
  "created_by_user_id": 1,
  "last_used_at": null,
  "token": "qeY8UVRisx9y3Loxo1scLxFuRxYcgeX3sxsdrpP_fR3Loq4xyg"
}

Révoquer un jeton d'agent {#revoke-an-agent-token}

{{< history >}}

• Introduit dans GitLab 15.0.

{{< /history >}}

Révoque un jeton d'agent.

Vous devez disposer du rôle Maintainer ou Owner pour utiliser ce point de terminaison.

DELETE /projects/:id/cluster_agents/:agent_id/tokens/:token_id

Attributs pris en charge :

| Attribut | Type | Requis | Description | |------------|-------------------|----------|---------------------------------------------------------------------------------------------------------------- -| | id | entier ou chaîne | oui | ID ou chemin encodé URL du projet géré par l'utilisateur authentifié. | | agent_id | entier | oui | ID de l'agent. | | token_id | entier | oui | ID du jeton. |

Exemple de requête :

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/tokens/1"

Agents réceptifs {#receptive-agents}

{{< details >}}

• Édition : Ultimate
• Offre : GitLab Self-Managed

{{< /details >}}

{{< history >}}

• Introduit dans GitLab 17.4.

{{< /history >}}

Les agents réceptifs permettent à GitLab de s'intégrer aux clusters Kubernetes qui ne peuvent pas établir de connexion réseau avec l'instance GitLab, mais auxquels GitLab peut se connecter.

Lister toutes les configurations d'URL {#list-all-url-configurations}

Liste toutes les configurations d'URL pour un agent spécifié.

Vous devez disposer du rôle Developer, Maintainer ou Owner pour utiliser ce point de terminaison.

GET /projects/:id/cluster_agents/:agent_id/url_configurations

Attributs pris en charge :

Réponse :

La réponse est une liste de configurations d'URL avec les champs suivants :

Exemple de requête :

curl \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations"

Exemple de réponse :

[
  {
    "id": 1,
    "agent_id": 5,
    "url": "grpcs://agent.example.com:4242",
    "public_key": "..."
  }
]

[!note] Soit public_key soit client_cert est défini, mais jamais les deux.

Récupérer une configuration d'URL {#retrieve-a-url-configuration}

Récupère une configuration d'URL d'agent unique.

Vous devez disposer du rôle Developer, Maintainer ou Owner pour utiliser ce point de terminaison.

GET /projects/:id/cluster_agents/:agent_id/url_configurations/:url_configuration_id

Attributs pris en charge :

Réponse :

La réponse est une configuration d'URL unique avec les champs suivants :

Exemple de requête :

curl \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations/1"

Exemple de réponse :

{
  "id": 1,
  "agent_id": 5,
  "url": "grpcs://agent.example.com:4242",
  "public_key": "..."
}

[!note] Soit public_key soit client_cert est défini, mais jamais les deux.

Créer une configuration d'URL {#create-a-url-configuration}

Crée une nouvelle configuration d'URL pour un agent.

Vous devez disposer du rôle Maintainer ou Owner pour utiliser ce point de terminaison.

Un agent ne peut avoir qu'une seule configuration d'URL à la fois.

POST /projects/:id/cluster_agents/:agent_id/url_configurations

Attributs pris en charge :

Réponse :

La réponse est la nouvelle configuration d'URL avec les champs suivants :

Exemple de requête pour créer une configuration d'URL avec un jeton JWT :

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations" \
  --data '{"url":"grpcs://agent.example.com:4242"}'

Exemple de réponse pour l'authentification JWT :

{
  "id": 1,
  "agent_id": 5,
  "url": "grpcs://agent.example.com:4242",
  "public_key": "..."
}

Exemple de requête pour créer une configuration d'URL avec mTLS à l'aide d'un certificat client et d'une clé provenant des fichiers client.pem et client-key.pem :

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations" \
  --data '{"url":"grpcs://agent.example.com:4242", \
           "client_cert":"'"$(awk -v ORS='\\n' '1' client.pem)"'", \
           "client_key":"'"$(awk -v ORS='\\n' '1' client-key.pem)"'"}'

Exemple de réponse pour mTLS :

{
  "id": 1,
  "agent_id": 5,
  "url": "grpcs://agent.example.com:4242",
  "client_cert": "..."
}

[!note] Si client_cert et client_key ne sont pas fournis, une paire de clés privée-publique est générée et l'authentification JWT est utilisée à la place de mTLS.

Supprimer une configuration d'URL {#delete-a-url-configuration}

Supprime une configuration d'URL d'agent.

Vous devez disposer du rôle Maintainer ou Owner pour utiliser ce point de terminaison.

DELETE /projects/:id/cluster_agents/:agent_id/url_configurations/:url_configuration_id

Attributs pris en charge :

Exemple de requête :

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/20/cluster_agents/5/url_configurations/1