doc-locale/fr-fr/administration/clusters/kas.md
{{< details >}}
{{< /details >}}
GitLab Relay (KAS) est un composant installé avec GitLab. Il sert de relais de communication central pour la communication gRPC bidirectionnelle entre GitLab et les systèmes externes, notamment :
KAS était anciennement connu sous le nom de Kubernetes Agent Server. Le nom a été modifié pour refléter son rôle élargi au-delà de Kubernetes.
GitLab Relay (KAS) est installé et disponible sur GitLab.com à l'adresse wss://kas.gitlab.com. Si vous utilisez GitLab Self-Managed, GitLab Relay (KAS) est installé et disponible par défaut.
En tant qu'administrateur GitLab, vous pouvez contrôler l'installation de GitLab Relay (KAS) :
GitLab Relay (KAS) pour les installations de package Linux peut être activé sur un seul nœud ou sur plusieurs nœuds à la fois. Par défaut, GitLab Relay (KAS) est activé et disponible à l'adresse ws://gitlab.example.com/-/kubernetes-agent/.
Pour désactiver GitLab Relay (KAS) sur un seul nœud :
Modifiez /etc/gitlab/gitlab.rb :
gitlab_kas['enable'] = false
Les instances KAS communiquent entre elles en enregistrant leurs adresses privées dans Redis à un emplacement bien connu. Chaque KAS doit être configuré pour présenter les détails de son adresse privée afin que les autres instances puissent l'atteindre.
Pour activer KAS sur plusieurs nœuds :
Ajoutez la configuration commune.
Ajoutez la configuration à partir de l'une des options suivantes :
(Facultatif) Si vous utilisez un environnement multi-serveurs avec des nœuds GitLab Rails et Sidekiq séparés, activez KAS sur les nœuds Sidekiq.
Pour chaque nœud KAS, modifiez le fichier situé à /etc/gitlab/gitlab.rb et ajoutez la configuration suivante :
gitlab_kas_external_url 'wss://kas.gitlab.example.com/'
gitlab_kas['api_secret_key'] = '<32_bytes_long_base64_encoded_value>'
gitlab_kas['private_api_secret_key'] = '<32_bytes_long_base64_encoded_value>'
# private_api_listen_address examples, pick one:
gitlab_kas['private_api_listen_address'] = 'A.B.C.D:8155' # Listen on a particular IPv4. Each node must use its own unique IP.
# gitlab_kas['private_api_listen_address'] = '[A:B:C::D]:8155' # Listen on a particular IPv6. Each node must use its own unique IP.
# gitlab_kas['private_api_listen_address'] = 'kas-N.gitlab.example.com:8155' # Listen on all IPv4 and IPv6 interfaces that the DNS name resolves to. Each node must use its own unique domain.
# gitlab_kas['private_api_listen_address'] = ':8155' # Listen on all IPv4 and IPv6 interfaces.
# gitlab_kas['private_api_listen_address'] = '0.0.0.0:8155' # Listen on all IPv4 interfaces.
# gitlab_kas['private_api_listen_address'] = '[::]:8155' # Listen on all IPv6 interfaces.
# Uncomment below to enable KAS to KAS TLS communication
# gitlab_kas['private_api_certificate_file'] = '<path_to_kas_server_crt_file>'
# gitlab_kas['private_api_key_file'] = '<path_to_kas_server_certificate_key>'
gitlab_kas['env'] = {
# 'OWN_PRIVATE_API_HOST' => '<server-name-from-cert>' # Add if you want to use TLS for KAS->KAS communication. This name is used to verify the TLS certificate host name instead of the host in the URL of the destination KAS.
'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/",
}
gitlab_rails['gitlab_kas_external_url'] = 'wss://gitlab.example.com/-/kubernetes-agent/'
gitlab_rails['gitlab_kas_internal_url'] = 'grpc://kas.internal.gitlab.example.com'
gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://gitlab.example.com/-/kubernetes-agent/k8s-proxy/'
Do not private_api_listen_address pour écouter sur une adresse interne, telle que :
localhost127.0.0.1 ou ::1Les autres nœuds KAS ne peuvent pas atteindre ces adresses.
Pour les configurations à nœud unique, vous pouvez définir private_api_listen_address pour écouter sur une adresse interne.
Pour chaque nœud KAS, modifiez le fichier situé à /etc/gitlab/gitlab.rb et définissez explicitement la variable d'environnement OWN_PRIVATE_API_URL :
gitlab_kas['env'] = {
# OWN_PRIVATE_API_URL examples, pick one. Each node must use its own unique IP or DNS name.
# Use grpcs:// when using TLS on the private API endpoint.
'OWN_PRIVATE_API_URL' => 'grpc://A.B.C.D:8155' # IPv4
# 'OWN_PRIVATE_API_URL' => 'grpcs://A.B.C.D:8155' # IPv4 + TLS
# 'OWN_PRIVATE_API_URL' => 'grpc://[A:B:C::D]:8155' # IPv6
# 'OWN_PRIVATE_API_URL' => 'grpc://kas-N-private-api.gitlab.example.com:8155' # DNS name
}
{{< history >}}
OWN_PRIVATE_API_CIDR dans GitLab 17.8.1.{{< /history >}}
Il est possible que vous ne puissiez pas définir une adresse IP ou un nom d'hôte exact dans la variable OWN_PRIVATE_API_URL si, par exemple, l'hôte KAS se voit attribuer dynamiquement une adresse IP et un nom d'hôte.
Si vous ne pouvez pas définir une adresse IP ou un nom d'hôte exact, vous pouvez configurer OWN_PRIVATE_API_CIDR pour que KAS construise dynamiquement OWN_PRIVATE_API_URL en fonction d'un ou plusieurs CIDRs :
Cette approche permet à chaque nœud KAS d'utiliser une configuration statique qui fonctionne tant que le CIDR ne change pas.
Pour chaque nœud KAS, modifiez le fichier situé à /etc/gitlab/gitlab.rb pour construire dynamiquement l'URL OWN_PRIVATE_API_URL :
OWN_PRIVATE_API_URL dans votre configuration commune pour désactiver cette variable.OWN_PRIVATE_API_CIDR pour spécifier les réseaux sur lesquels les nœuds KAS écoutent. Lorsque vous démarrez KAS, il détermine quelle adresse IP privée utiliser en sélectionnant l'adresse d'hôte qui correspond au CIDR spécifié.OWN_PRIVATE_API_PORT pour utiliser un port différent. Par défaut, KAS utilise le port du paramètre private_api_listen_address.OWN_PRIVATE_API_SCHEME=grpcs. Par défaut, KAS utilise le schéma grpc.gitlab_kas['env'] = {
# 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8', # IPv4 example
# 'OWN_PRIVATE_API_CIDR' => '2001:db8:8a2e:370::7334/64', # IPv6 example
# 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8,2001:db8:8a2e:370::7334/64', # multiple CIRDs example
# 'OWN_PRIVATE_API_PORT' => '8155',
# 'OWN_PRIVATE_API_SCHEME' => 'grpc',
}
{{< history >}}
private_api_listen_network.{{< /history >}}
Un nœud KAS peut déterminer les adresses IP disponibles en fonction des paramètres private_api_listen_network et private_api_listen_address :
private_api_listen_address est défini sur une adresse IP fixe et un numéro de port (par exemple, ip:port), il utilise cette adresse IP.private_api_listen_address n'a pas d'adresse IP (par exemple, :8155), ou a une adresse IP non spécifiée (par exemple, [::]:8155 ou 0.0.0.0:8155), KAS attribue toutes les adresses IP non-loopback et non-link-local au nœud. Les adresses IPv4 et IPv6 sont filtrées en fonction de la valeur de private_api_listen_network.private_api_listen_address est un hostname:PORT (par exemple, kas-N-private-api.gitlab.example.com:8155), KAS résout le nom DNS et attribue toutes les adresses IP au nœud. Dans ce mode, KAS écoute uniquement sur la première adresse IP (ce comportement est défini par la bibliothèque standard Go). Les adresses IPv4 et IPv6 sont filtrées en fonction de la valeur de private_api_listen_network.Avant d'exposer l'adresse API privée d'un KAS sur toutes les adresses IP, assurez-vous que cette action n'entre pas en conflit avec la politique de sécurité de votre organisation. Le point de terminaison de l'API privée nécessite un jeton d'authentification valide pour toutes les requêtes.
Pour chaque nœud KAS, modifiez le fichier situé à /etc/gitlab/gitlab.rb :
Exemple 1. Écouter sur toutes les interfaces IPv4 et IPv6 :
# gitlab_kas['private_api_listen_network'] = 'tcp' # this is the default value, no need to set it.
gitlab_kas['private_api_listen_address'] = ':8155' # Listen on all IPv4 and IPv6 interfaces
Exemple 2. Écouter sur toutes les interfaces IPv4 :
gitlab_kas['private_api_listen_network'] = 'tcp4'
gitlab_kas['private_api_listen_address'] = ':8155'
Exemple 3. Écouter sur toutes les interfaces IPv6 :
gitlab_kas['private_api_listen_network'] = 'tcp6'
gitlab_kas['private_api_listen_address'] = ':8155'
Vous pouvez utiliser des variables d'environnement pour remplacer le schéma et le port qui construisent l'URL OWN_PRIVATE_API_URL :
gitlab_kas['env'] = {
# 'OWN_PRIVATE_API_PORT' => '8155',
# 'OWN_PRIVATE_API_SCHEME' => 'grpc',
}
[!warning] Lorsque vous placez un équilibreur de charge ou un proxy inverse devant KAS, configurez des points de terminaison séparés pour le trafic externe et interne afin d'éviter d'exposer l'API interne.
KAS sert le trafic sur différents ports :
Port 8150 (listen_address) : Connexions des agents (WebSocket/gRPC)
Port 8153 (internal_api_listen_address) : API GitLab Rails (gRPC)
[!warning] N'exposez pas le port 8153 publiquement. Bien que le port soit authentifié, il ne doit être accessible qu'aux instances GitLab Rails.
Pour sécuriser KAS lorsque vous utilisez un équilibreur de charge ou un proxy inverse, configurez deux points de terminaison séparés :
Cette séparation garantit que l'API interne reste isolée de l'accès public.
Par exemple, configurez un point de terminaison interne avec des restrictions réseau dans NGINX :
# Internal endpoint (network-restricted)
server {
listen 8443 ssl http2;
server_name kas-internal.example.com;
# Optional: allow 10.0.1.0/24; deny all;
location /gitlab.agent. {
grpc_pass grpc://kas-backend:8153;
}
}
Configurez GitLab pour utiliser les points de terminaison séparés (/etc/gitlab/gitlab.rb) :
gitlab_rails['gitlab_kas_external_url'] = 'wss://kas-external.example.com'
gitlab_rails['gitlab_kas_internal_url'] = 'grpcs://kas-internal.example.com:8443'
gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://kas-external.example.com/k8s-proxy/'
Points de configuration clés :
| Paramètre | Description |
|---|---|
gitlab_kas['private_api_listen_network'] | La famille réseau sur laquelle KAS écoute. La valeur par défaut est tcp pour les réseaux IPv4 et IPv6. Définissez sur tcp4 pour IPv4 ou tcp6 pour IPv6. |
gitlab_kas['private_api_listen_address'] | L'adresse sur laquelle KAS écoute. Définissez sur 0.0.0.0:8155 ou sur une adresse IP et un port accessibles par les autres nœuds du cluster. |
gitlab_kas['api_secret_key'] | Le secret partagé utilisé pour l'authentification entre KAS et GitLab. La valeur doit être encodée en Base64 et faire exactement 32 octets. |
gitlab_kas['private_api_secret_key'] | Le secret partagé utilisé pour l'authentification entre différentes instances KAS. La valeur doit être encodée en Base64 et faire exactement 32 octets. |
gitlab_kas['private_api_certificate_file'] | Chemin complet du fichier de certificat du serveur KAS. Requis lorsque OWN_PRIVATE_API_SCHEME ou OWN_PRIVATE_API_URL est grpcs. |
gitlab_kas['private_api_key_file'] | Chemin complet du fichier de clé de certificat du serveur KAS. Requis lorsque OWN_PRIVATE_API_SCHEME ou OWN_PRIVATE_API_URL est grpcs. |
OWN_PRIVATE_API_SCHEME | Valeur facultative utilisée pour spécifier le schéma à utiliser lors de la construction de OWN_PRIVATE_API_URL. Peut être grpc ou grpcs. |
OWN_PRIVATE_API_URL | La variable d'environnement utilisée par KAS pour la découverte de services. Définissez sur le nom d'hôte ou l'adresse IP du nœud que vous configurez. Le nœud doit être accessible par les autres nœuds du cluster. |
OWN_PRIVATE_API_HOST | Valeur facultative utilisée pour vérifier le nom d'hôte du certificat TLS. <sup>1</sup> Un client compare cette valeur au nom d'hôte dans le fichier de certificat TLS du serveur. |
OWN_PRIVATE_API_PORT | Valeur facultative utilisée pour spécifier le port à utiliser lors de la construction de OWN_PRIVATE_API_URL. |
OWN_PRIVATE_API_CIDR | Valeur facultative utilisée pour spécifier les adresses IP des réseaux disponibles à utiliser lors de la construction de OWN_PRIVATE_API_URL. |
gitlab_kas['client_timeout_seconds'] | Le délai d'attente pour que le client se connecte au KAS. |
gitlab_kas_external_url | L'URL exposée aux utilisateurs pour l'agentk dans le cluster. Peut être un domaine complet ou un sous-domaine, <sup>2</sup> ou une URL externe GitLab. <sup>3</sup> Si vide, prend par défaut une URL externe GitLab. |
gitlab_rails['gitlab_kas_external_url'] | L'URL exposée aux utilisateurs pour l'agentk dans le cluster. Si vide, prend par défaut la valeur de gitlab_kas_external_url. |
gitlab_rails['gitlab_kas_external_k8s_proxy_url'] | L'URL exposée aux utilisateurs pour le proxy de l'API Kubernetes. Si vide, prend par défaut une URL basée sur gitlab_kas_external_url. |
gitlab_rails['gitlab_kas_internal_url'] | L'URL interne utilisée par le backend GitLab pour communiquer avec KAS. |
Remarques :
OWN_PRIVATE_API_URL ou OWN_PRIVATE_API_SCHEME commence par grpcs.wss://kas.gitlab.example.com/.wss://gitlab.example.com/-/kubernetes-agent/.Configurez Omnibus pour exécuter KAS séparément des autres composants.
Sur chaque nœud Rails :
## KAS Config
gitlab_kas['enable'] = false
gitlab_rails['gitlab_kas_enabled'] = true
gitlab_rails['gitlab_kas_external_url'] = 'wss://kas.example.com/-/kubernetes-agent/'
gitlab_rails['gitlab_kas_internal_url'] = 'grpc://<KAS_NODE_IP_OR_DOMAIN>:8153' # If you want to configure multiple KAS nodes that are behind an internal LB, then use 'grpc://<LB_IP_OR_DOMAIN>:<port>'
gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://kas.example.com/-/kubernetes-agent/k8s-proxy/'
Sur chaque nœud KAS :
### External URL
external_url 'https://kas.example.com'
### Avoid running unnecessary services ###
gitaly['enable'] = false
gitlab_workhorse['enable'] = false
nginx['enable'] = true
postgresql['enable'] = false
prometheus['enable'] = false
puma['enable'] = false
redis['enable'] = false
sidekiq['enable'] = false
### Prevent database connections during 'gitlab-ctl reconfigure' ###
gitlab_rails['rake_cache_clear'] = false
gitlab_rails['auto_migrate'] = false
gitlab_kas['redis_password'] = '<redis_password>'
# Uncomment below if using Redis high availability with Sentinel
# gitlab_kas['redis_sentinels'] = [
# {host: '<REDIS_IP>', port: 26379},
# {host: '<REDIS_IP>', port: 26379},
# {host: '<REDIS_IP>', port: 26379},
# ]
# gitlab_kas['redis_sentinels_master_name'] = 'gitlab-redis'
# gitlab_kas['redis_sentinels_password'] = '<redis_sentinels_password>'
### GitLab Relay (KAS) ###
gitlab_kas['enable'] = true
gitlab_kas_external_url 'wss://kas.example.com/-/kubernetes-agent/'
gitlab_kas['api_secret_key'] = '<32_bytes_long_base64_encoded_value>'
gitlab_kas['private_api_secret_key'] = '<32_bytes_long_base64_encoded_value>'
gitlab_kas['private_api_listen_address'] = '<KAS_NODE_PRIVATE_IP>:8155'
gitlab_kas['listen_address'] = '<KAS_NODE_PRIVATE_IP>:8150'
gitlab_kas['observability_listen_address'] = '<KAS_NODE_PRIVATE_IP>:8151'
gitlab_kas['internal_api_listen_address'] = '<KAS_NODE_PRIVATE_IP>:8153'
gitlab_kas['kubernetes_api_listen_address'] = '<KAS_NODE_PRIVATE_IP>:8154'
Consultez comment utiliser le chart GitLab-KAS.
{{< history >}}
kas_user_access et kas_user_access_project. Désactivé par défaut. Désactivé par défaut.kas_user_access et kas_user_access_project ont été activés dans GitLab 16.1.kas_user_access et kas_user_access_project ont été supprimés dans GitLab 16.2.{{< /history >}}
GitLab Relay (KAS) proxy les requêtes de l'API Kubernetes vers l'agent GitLab pour Kubernetes avec :
Pour s'authentifier avec les identifiants de l'utilisateur, Rails définit un cookie pour le frontend GitLab. Ce cookie s'appelle _gitlab_kas et il contient un ID de session chiffré, comme le cookie _gitlab_session. Le cookie _gitlab_kas doit être envoyé au point de terminaison du proxy KAS avec chaque requête pour authentifier et autoriser l'utilisateur.
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Les agents réceptifs permettent à GitLab de s'intégrer aux clusters Kubernetes qui ne peuvent pas établir de connexion réseau vers l'instance GitLab, mais auxquels GitLab peut se connecter.
Prérequis :
Pour activer les agents réceptifs :
{{< history >}}
kas_k8s_api_proxy_response_header_allowlist. Désactivé par défaut. Désactivé par défaut.kas_k8s_api_proxy_response_header_allowlist supprimé.{{< /history >}}
Le proxy de l'API Kubernetes dans KAS utilise une liste d'autorisation pour les en-têtes de réponse. Les en-têtes Kubernetes et HTTP sécurisés et bien connus sont autorisés par défaut.
Pour obtenir la liste des en-têtes de réponse autorisés, consultez la liste d'autorisation des en-têtes de réponse.
Si vous avez besoin d'en-têtes de réponse qui ne figurent pas dans la liste d'autorisation par défaut, vous pouvez ajouter vos en-têtes de réponse dans la configuration KAS.
Pour ajouter des en-têtes de réponse supplémentaires autorisés :
agent:
kubernetes_api:
extra_allowed_response_headers:
- 'X-My-Custom-Header-To-Allow'
La prise en charge de l'ajout de davantage d'en-têtes de réponse est suivie dans le ticket 550614.
Si vous rencontrez des problèmes lors de l'utilisation de GitLab Relay (KAS), consultez les journaux du service en exécutant la commande suivante :
kubectl logs -f -l=app=kas -n <YOUR-GITLAB-NAMESPACE>
Dans les installations de package Linux, les journaux se trouvent dans /var/log/gitlab/gitlab-kas/.
Vous pouvez également résoudre les problèmes avec des agents individuels.
Si vous obtenez le message d'erreur suivant :
time="2020-10-29T04:44:14Z" level=warning msg="Config: failed to fetch" agent_id=2 error="configuration file not found: \".gitlab/agents/test-agent/config.yaml\
Le chemin est incorrect pour l'un des éléments suivants :
Pour résoudre ce problème, assurez-vous que les chemins sont corrects.
dial tcp <GITLAB_INTERNAL_IP>:443: connect: connection refused {#error-dial-tcp-gitlab_internal_ip443-connect-connection-refused}Si vous exécutez GitLab Self-Managed et que :
Lorsque GitLab Relay (KAS) tente de se connecter à l'API GitLab, l'erreur suivante peut se produire :
{"level":"error","time":"2021-08-16T14:56:47.289Z","msg":"GetAgentInfo()","correlation_id":"01FD7QE35RXXXX8R47WZFBAXTN","grpc_service":"gitlab.agent.reverse_tunnel.rpc.ReverseTunnel","grpc_method":"Connect","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": dial tcp 172.17.0.4:443: connect: connection refused"}
Pour résoudre ce problème dans les installations de package Linux, définissez le paramètre suivant dans /etc/gitlab/gitlab.rb. Remplacez gitlab.example.com par le nom d'hôte de votre instance GitLab :
gitlab_kas['gitlab_address'] = 'http://gitlab.example.com'
x509: certificate signed by unknown authority {#error-x509-certificate-signed-by-unknown-authority}Si vous rencontrez cette erreur en essayant d'accéder à l'URL GitLab, cela signifie qu'elle ne fait pas confiance au certificat GitLab.
Vous pourriez voir une erreur similaire dans les journaux KAS de votre serveur d'application GitLab :
{"level":"error","time":"2023-03-07T20:19:48.151Z","msg":"AgentInfo()","grpc_service":"gitlab.agent.agent_configuration.rpc.AgentConfiguration","grpc_method":"GetConfiguration","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": x509: certificate signed by unknown authority"}
Pour corriger cette erreur, installez le certificat public de votre autorité de certification interne dans le répertoire /etc/gitlab/trusted-certs.
Vous pouvez également configurer KAS pour lire le certificat depuis un répertoire personnalisé. Pour ce faire, ajoutez la configuration suivante au fichier situé à /etc/gitlab/gitlab.rb :
gitlab_kas['env'] = {
'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/"
}
Pour appliquer les modifications :
sudo gitlab-ctl reconfigure
gitlab-ctl restart gitlab-kas
GRPC::DeadlineExceeded in Clusters::Agents::NotifyGitPushWorker {#error-grpcdeadlineexceeded-in-clustersagentsnotifygitpushworker}Cette erreur se produit probablement lorsque le client ne reçoit pas de réponse dans le délai d'attente par défaut (5 secondes). Pour résoudre le problème, vous pouvez augmenter le délai d'attente du client en modifiant le fichier de configuration /etc/gitlab/gitlab.rb.
gitlab_kas['client_timeout_seconds'] = "10"
gitlab-ctl reconfigure
Vous pouvez ajuster la valeur du délai d'attente en fonction de vos besoins spécifiques. Il est recommandé d'effectuer des tests pour s'assurer que le problème est résolu sans impact sur les performances du système.
Blocked Kubernetes API proxy response header {#error-blocked-kubernetes-api-proxy-response-header}Si des en-têtes de réponse HTTP sont perdus lors de leur envoi du cluster Kubernetes à l'utilisateur via le proxy de l'API Kubernetes, vérifiez les journaux KAS ou l'instance Sentry pour l'erreur suivante :
Blocked Kubernetes API proxy response header. Please configure extra allowed headers for your instance in the KAS config with `extra_allowed_response_headers` and have a look at the troubleshooting guide at https://docs.gitlab.com/administration/clusters/kas/#troubleshooting.
Cette erreur signifie que le proxy de l'API Kubernetes a bloqué des en-têtes de réponse car ils ne sont pas définis dans la liste d'autorisation des en-têtes de réponse.
Pour plus d'informations sur l'ajout d'en-têtes de réponse, consultez configurer la liste d'autorisation des en-têtes de réponse.
La prise en charge de l'ajout de davantage d'en-têtes de réponse est suivie dans le ticket 550614.