Pré-requis

Auparavant, vous pouvez installer l’agent sur votre cluster. Vous aurez besoin:

  • Un cluster Kubernetes. Si vous n’en avez pas, vous pouvez en créer un chez un cloud provider tel que GCP, AWS ou DigitalOcean.
  • Sur une instance auto-gérée de Gitlab, l’administrateur de l’instance devra configurer l’Agent Server. C’est disponible par défaut à wss://gitlab.dietlin.eu/-/kubernetes-agent/.

Les étapes d’installation

Pour installer l’agent dans votre cluster:Facultatif. Personnalisez l’installation de Helm. Si vous installez l’agent sur un système de production, vous devez personnaliser l’installation de Helm pour restreindre les autorisations du compte de service. Consultez Comment déployer l’agent GitLab pour Kubernetes avec des autorisations limitées.

  1. Créer un fichier de configuration d’agent.
  2. Enregistrer l’agent avec Gitlab.
  3. Installer l’agent dans votre cluster.

Créer un fichier de configuration d’agent

Pour les paramètres de configuration, l’agent utilise un fichier YAML dans le projet Gitlab. Vous devez créer ce fichier sidebar:

  • Vous utilisez le Workflow GitOps.
  • Vous utilisez le Workflow de CI/CD Gitlab et vous voulez autoriser différents projets à utiliser l’agent.
  • Vous autorisez un projet spécifique ou des membres d’un groupe à accéder à Kubernetes.

Dans mon cas personnel sur ce homelab, je me contente d’utiliser le Workflow CI/CD.

Pour créer un fichier de configuration d’un agent:

  1. Choisir un nom à votre agent. Le nom de l’agent respecte la RFC1123. Le nom doit:
  • Etre unique dans le projet
  • Contenir au plus, 63 caractères
  • Contenir uniquement des caractères alphanumérique en minuscule ou -
  • Commencer par un caractère alphanumérique.
  • Terminer par un caractère alphanumérique.
  1. Dans le dépôt git, dans la branche par défaut, créer un fichier de configuration d’agent à la racine:
.gitlab/agents/<nom-de-lagent>/config.yaml

Vous pouvez laisser le fichier vide pour le moment, et le configurer plus tard.

Enregister l’agent avec Gitlab

Pré-requis:

Vous devez enregistrer un agent avzant de pouvoir l’installer dans votre cluster. Pour enregistrer un agent:

  1. Sur le menu de gauche, sélectionnez Search or got to et trouvez votre projet. Si vous avez un fichier de configuration d’agent, il doit être dans ce projet. Les fichiers manifest de votre cluster doivent également figurer dans ce projet.
  2. Sectionnez Operate > Kubernetes clusters.
  3. Sectionnez Connect a cluster (agent).
  • Si vous souhaitez créer une configuration avec les valeurs par défaut CI/CD, saisissez un nom.
  • Si vous disposez déjà d’un fichier de configuration d’agent (voir plus haut), sélectionnez-le dans la liste.
  1. Sélectionnez Register an agent.
  2. GitLab génère un jeton d’accès pour l’agent. Vous avez besoin de ce jeton pour installer l’agent dans votre cluster.
Stockez en toute sécurité le jeton d’accès de l’agent. Un acteur malveillant peut utiliser ce token pour accéder au code source du projet de configuration de l’agent, accéder au code source de n’importe quel projet public sur l’instance GitLab, ou même, dans des conditions très spécifiques, obtenir un manifeste Kubernetes.
  1. Copiez la commande sous Méthode d’installation recommandée. Vous en avez besoin lorsque vous utilisez la méthode d’installation en une seule ligne pour installer l’agent dans votre cluster.

Installer l’agent dans le cluster

Pour connecter votre cluster à Gitlab, installer l’agent enregistré dans votre cluster. Vous pouvez soit:

  • Installer l’agent avec Helm.
  • Ou, suivre la méthode d’installation avancée.

Si vous ne savez pas laquelle choisir, nous vous recommandons de commencer avec Helm.

Installer l’agent avec Helm

Pour plus de simplicité, la configuration par défaut du graphique Helm configure un compte de service pour l’agent avec des droits d’administrateur de cluster. Vous ne devez pas l’utiliser sur les systèmes de production. Pour déployer sur un système de production, suivez les instructions dans Personnaliser l’installation Helm pour créer un compte de service avec les autorisations minimales requises pour votre déploiement et spécifiez-le lors de l’installation.

Pour installer l’agent dans votre cluster en utilisant Helm:

  1. Installer Helm
  2. Dans votre ordinateur, ouvrir un termina et connectez vous à votre cluster.
  3. Exécuter la commande que vous avez copiée lorsque vous avez enregistré votre auprès auprès de Gitlab. La commande devrait ressembler à :
helm repo add gitlab https://charts.gitlab.io
helm repo update
helm upgrade --install test gitlab/gitlab-agent \
    --namespace gitlab-agent-test \
    --create-namespace \
    --set image.tag=<current agentk version> \
    --set config.token=<your_token> \
    --set config.kasAddress=<address_to_GitLab_KAS_instance>
  1. Facultatif. Personnalisez l’installation de Helm. Si vous installez l’agent sur un système de production, vous devez personnaliser l’installation de Helm pour restreindre les autorisations du compte de service. Consultez Comment déployer l’agent GitLab pour Kubernetes avec des autorisations limitées.

Personaliser l’installation Helm

Par défaut, la commande d’installation Helm générée par Gitlab:

  • Créer un namespace gitlab-agent pour le deployment (--namespace gitlab-agent). Vous pouvez passer la création du namespace en omettant le flag --create-namespacewss://gitlab.dietlin.eu/-/kubernetes-agent/
  • Configure un compte de service pour l’agent et lui assigne le rôle cluster-admin. Vous pouvez:
    • Passer la création du compte de service par l’ajout du flag --set serviceAccount.create=false à la commande helm install. Dans ce cas, vous devez paramètrer serviceAccount.name avec un compte de service pré-existant.
    • Personnaliser le rôle assigné au compte de service par l’ajout de --set rbac.useExistingRole <votre_nom_de_role> à la commande helm install. Dans ce cas, vous devrez avoir un rôle pré-existant avec des permissions resteintes qui peut être utilisé par le compte de service.
    • Ignorez complètement l’attribution de rôle en ajoutant --set rbac.create=false à votre commande helm install. Dans ce cas, vous devez créer ClusterRoleBinding manuellement.
  • Crée une ressource Secret pour le jeton d’accès de l’agent. Pour apporter votre propre secret avec un jeton, omettez le jeton (--set token=...) et utilisez plutôt --set config.secretName=<votre nom secret>.
  • Crée une ressource Deployment pour le pod agentk.

Utiliser l’agent quand KAS est derrière un certificat auto-signé

Lorsque KAS se trouve derrière un certificat auto-signé, vous pouvez définir la valeur de config.kasCaCert sur le certificat. Par exemple:

helm mise à niveau --install gitlab-agent gitlab/gitlab-agent \
  --set-file config.kasCaCert=my-custom-ca.pem

Dans cet exemple, my-custom-ca.pem est le chemin d’accès à un fichier local contenant le certificat CA utilisé par KAS. Le certificat est automatiquement stocké dans une carte de configuration et monté dans le pod agentk.

Si KAS est installé avec le graphique GitLab et que le graphique est configuré pour fournir un certificat générique auto-signé généré automatiquement, vous pouvez extraire le certificat CA du secret RELEASE-wildcard-tls-ca.