Aller au contenu principal

Administration Guides

Gestion et visibilité des zones​

Un nouvel utilisateur est créé dans Gitlab lorsqu'un utilisateur valide se connecte via SSO. Par défaut, ce nouvel utilisateur ne fait partie d'aucun groupe.

Initialisation de la zone​

Ajout d'une zone​

Afin de créer une zone, vous devrez créer des sous-groupes dans les groupes Bac a Sable & Projets.

Pour cela, depuis la page d'accueil :

  • Panneau de gauche > Groupes
  • Pour le groupe Projets :
    • Cliquez sur le groupe Projets
    • Cliquez sur Nouveau sous-groupe
    • Nommez le groupe du nom de votre zone et mettez sa visibilité à Privé.
    • Validez la création avec le bouton Créer un sous-groupe
  • Pour le groupe Bac a Sable :
    • Cliquez sur le groupe Bac a Sable
    • Cliquez sur Nouveau sous-groupe
    • Nommez le groupe du nom de votre zone et mettez sa visibilité à Privé.
    • Validez la création avec le bouton Créer un sous-groupe
    • Dans le nouveau sous-groupe de ce tenant :
      • Créez un sous-groupe appelé Agents pour stocker les configurations d'agents
      • Créez un ou plusieurs sous-groupes afin de séparer (ou non) vos différentes équipes.
Ajouter des variables CI/CD à la zone​

Pour configurer les variables CI/CD de la zone, depuis la page d'accueil :

  • Panneau de gauche > Groupes
  • Choisissez la zone que vous souhaitez configurer (tenant0) dans le groupe racine Bac a Sable.
  • Panneau de gauche > Paramètres > CI/CD
  • Allez dans la section Variables
  • Ajoutez les variables suivantes avec le bouton Ajouter une variable :
    • ACI_TENANT : mettez le nom de votre tenant en minuscules
      • Désactivez les 2 options de la section Flags
      • Cette variable sera utilisée pour générer le nom des images produites par la CI (ex: <registry>/athea/ksandboxk/tenant0/<image-name>)
    • ACI_TENANT_ID : mettez le nom technique de votre zone
      • La commande suivante peut-être utilisée pour le récupérer kubectl get ns <namespace> -ojsonpath={".metadata.labels.field\.cattle\.io\/projectId"}
        • remplacer l'ancre <namespace> par un de vos namespaces
      • Désactivez les 2 options de la section Flags
      • Cette variable sera utilisée pour pousser vers le SAS vos packages

D'autres variables sont à créer dont voici une liste non exhaustive :

  • Le contexte d'agent à utiliser tel que décrit dans la section agent.
    • AGENT_CTX
  • Le nom d'utilisateur et le mot de passe pour contacter la registry OCI tel que décrit dans la documentation associée
    • ACI_CONTAINER_REGISTRY_USERNAME: Nom d'utilisateur utilisé pour pull depuis la registry OCI
      • Désactivez les 2 options de la section Flags
    • ACI_CONTAINER_REGISTRY_PASSWORD: Mot de passe utilisé pour pull depuis la registry OCI
      • Désactivez les 2 options de la section Flags
      • Configurez la visibilité comme Masquée
  • Les variables nécessaires au contact avec le registre de dépôts qui dépendent en partie des langages que vous souhaitez utiliser
    • RM_USERNAME & RM_PASSWORD au minimum seront à créer
    • Les autres variables dépendront des langages que vous souhaitez utiliser et si vous souhaitez utiliser.
  • Le Personal Access Token (PAT) gitlab nécessaire pour les actions sur les projets gitlab
    • ACI_GITLAB_TOKEN_NAME: Nom de l'utilisateur associé au PAT gitlab
    • ACI_GITLAB_TOKEN_VALUE: Valeur du PAT gitlab

Ajouter un administrateur de zone​

Pour ajouter un administrateur accès à votre zone :

  • Panneau de gauche > Groupes
  • Choisissez la zone que vous souhaitez configurer (tenant0) dans le groupe racine Bac a Sable.
  • Panneau de gauche > Gestion > Membres
  • Cliquez sur Inviter des membres
  • Trouvez votre administrateur de zone et donnez lui le role Propriétaire
    • Optionnellement, fournissez une date d'expiration
  • Finalisez le processus en appuyant sur le bouton Inviter

Ajouter un utilisateur à la zone​

Pour ajouter un utilisateur à votre zone :

  • Panneau de gauche > Groupes
  • Choisissez la zone que vous souhaitez configurer (tenant0) dans le groupe racine Bac a Sable.
  • Panneau de gauche > Gestion > Membres
  • Cliquez sur Inviter des membres
  • Trouvez votre utilisateur et donnez lui le role Rapporteur
    • Optionnellement, fournissez une date d'expiration
  • Finalisez le processus en appuyant sur le bouton Inviter

Si votre nouvel utilisateur nécessite plus de permission (ex: un développeur dans un des sous groupes dédiés aux équipes) :

  • Panneau de gauche > Groupes
  • Choisissez la zone que vous souhaitez configurer (tenant0) dans le groupe racine Bac a Sable.
  • Optionnellement, choisissez votre sous groupe si vous souhaitez ajouter des droits plus fins
  • Panneau de gauche > Gestion > Membres
  • Cliquez sur Inviter des membres
  • Trouvez votre utilisateur et donnez-lui le rôle nécessaire à ses besoins (eg: Développeur, Chargé de maintenance, ...)
    • Optionnellement, fournissez une date d'expiration
  • Finalisez le processus en appuyant sur le bouton Inviter
info

Dans gitlab les permissions sont héritées et ne peuvent pas être diminuées par héritage. Ainsi, si un utilisateur est Développeur dans le groupe A, ceci s'applique à tous les sous-groupes du groupe A et il ne sera pas possible de lui donner un role plus bas (ex: Invité) dans un sous groupe de A. Si vous souhaitez éviter de donner trop d'accès à un utilisateur, il vaut donc mieux lui donner des droits au plus proche du projet/groupe dont il a besoin.

Ajout d'un Runner de zone​

Introduction​

Un runner est un pod qui génère d'autres pods lorsque des pipelines CI/CD sont soumis dans l'interface utilisateur de Gitlab. L'ajout d'un runner de zone permet à ce dernier de disposer d'un exécuteur Gitlab dédié à ses besoins CI/CD.

Création initiale du runner dans l'IHM Gitlab​

Pour créer un runner, depuis la page d'accueil :

  • Panneau de gauche > Groupes
  • Choisissez la zone que vous souhaitez configurer (tenant0) dans le groupe racine Bac a Sable.
  • Panneau de gauche > Compilations > Runners
  • Cliquez sur le bouton Nouvel runner du groupe
  • Configurez votre runner en suivant la doc officielle
  • Faites attention au jeton d'authentification du runner affiché, il ne sera plus jamais affiché une fois que vous quittez la page et il est nécessaire pour les étapes suivantes.

Instancier le runner dans le cluster​

Le runner peut être déployé via Helm dans le cluster grâce au graphique Helm de gitlab.

Plusieurs exemples de values Helm sont fournis dans la livraison platform-provisionner (dans values/gitlab/samples) :

  • runner-values.yaml : Runner simple avec le minimum de permissions
  • runner-values-no-empty-dir.yaml : Similaire à celui du dessus, mais avec tous les volumes de type emptyDir remplacés par des volumes éphémères de type PersistentVolumeClaim
    • La taille des PersistentVolumeClaim est en dur dans les exemples, pensez à adapter à vos besoins/limitations
  • runner-values-privileged.yaml : Runner privilégié utilisé pour produire des images de conteneurs
  • runner-values-privileged-no-empty-dir.yaml : Similaire à celui du dessus, mais avec tous les volumes de type emptyDir remplacés par des volumes éphémères de type PersistentVolumeClaim
    • La taille des PersistentVolumeClaim est en dur dans les exemples, pensez à adapter à vos besoins/limitations

Une partie du contenu de ces fichiers doit cependant être adapté à votre plateforme & votre runner :

  • Placez le jeton d'authentification du runner dans le champ gitlab-runner.runnerToken.
  • Si vous utilisez des certificats auto-signés, vous devez :
    • Décommenter le secret nommé gitlab-tls-secret du champ gitlab-runner.runners.extraObjects et changez le contenu de sa clef stringData.ca.crt avec la CA de votre plateforme
      • Supprimer aussi la liste vide ([]) qui sert de valeur par défaut à gitlab-runner.runners.extraObjects.
      • La CA de la plateforme peut être trouvée dans n'importe quel secret tls généré par cert-manager :
        • Choisir un secret : kubectl get secret -A | grep "tls-secret"
        • Récupérer la CA : kubectl get secret <secret-name> -n <namespace> -ojsonpath={".data.ca\.crt"} | base64 -d
## Helms dans la kosmos-registry
# exemple privilégiée
helm install -n <tenant_namespace> <name> oci://kosmos-registry.<domain>/athea/hauler/gitlab -f ./values/gitlab/samples/runner-values-privileged.yaml
# exemple standard
helm install -n <tenant_namespace> <name> oci://kosmos-registry.<domain>/athea/hauler/gitlab -f ./values/gitlab/samples/runner-values.yaml

## Helms locaux dans le platform provisionner
# exemple privilégiée
helm install -n <tenant_namespace> <name> ../../gitlab/gitlab -f ../../gitlab/values/samples/runner-values-privileged.yaml
# exemple standard
helm install -n <tenant_namespace> <name> ../../gitlab/gitlab -f ../../gitlab/values/samples/runner-values.yaml

Une fois le runner démarré il contactera gitlab et vous le verrez En Ligne dans la liste des runners.

info

Si vous utilisez un runner privilégié (eg: pour générer des images docker) vous devez labelliser le namespace avec le label pod-security.kubernetes.io/enforce: privileged sinon celui-ci ne pourra pas démarrer. Si vous ne voulez pas que d'autres ressources Kubernetes puissent avoir une élévation de privilège, isolez ce runner privilégié dans un namespace à part.

Ajouter un agent kube de zone​

Introduction​

Un agent est un pod permettant aux exécuteurs d'interagir avec un cluster Kubernetes avec des règles RBAC spécifiques. L'ajout d'un agent Tenant permet au Tenant de disposer d'un agent Gitlab dédié pour ses besoins CI/CD.

Par exemple, considérons que :

  • Votre zone est tenant0 avec l'ID bas/tenant0
  • L'identifiant de votre agent est agent0 et créé dans le projet agent-config placé dans le sous-groupe Agents de votre zone
  • Votre namespace est tenant0-dev

Créer les règles RBAC​

Les permissions accordées à l'agent dans un cluster sont définies par les règles RBAC Kubernetes attribuées à l'agent ServiceAccount.

Un exemple de règles RBAC est trouvable dans la livraison platform-provisionner (in values/gitlab/samples).

Le fichier peut petre utilisé avec la commande kubectl apply -f <file> -n <namespace_agent>

attention
  • les règles sur les ressources de type events & leases sont nécessaires au bon fonctionnement de l'agent.
  • Comme expliqué dans l'exemple minimal, vous aurez besoin d'avoir des droits sur la ressource Kubernetes de type Secrets si vous souhaitez utiliser l'agent pour faire des commandes Helm.
  • Ne donnez pas de permissions sur les ressources de type namespace/serviceAccount/role/rolebinding.
  • Si vous renommez le ServiceAccount, vous aurez besoin plus tard de le préciser dans un fichier de values Helm.

Création initiale de l'agent dans l'IHM Gitlab​

Pour créer l'agent, il va falloir créer un nouveau projet (ex: agent-config) dans la zone, depuis la page d'accueil :

  • Panneau de gauche > Groupes
  • Choisissez la zone que vous souhaitez configurer (tenant0) dans le groupe racine Bac a Sable.
  • Cliquez sur le sous-groupe Agents
  • Cliquez sur le bouton Nouveau projet et donnez un nom à ce projet (ex: agent-config)
  • Dans ce nouveau projet, créez le fichier .gitlab/agents/agent0/config.yaml avec le contenu présenté ci-dessous (ou adaptez à votre cas)
    • agent0 est le nom de votre agent
    • L'exemple fourni donne accès à cet agent dans l'ensemble des CIs de votre zone. Il est possible de limiter à certains sous-groupes uniquement.
    • Pour des droits plus fins, référez-vous à la documentation officielle
ci_access:
  groups:
    - id: bas/tenant0
      default_namespace: "tenant0-dev"
      access_as:
        agent: {}

Maintenant que votre fichier de configuration existe, il est temps de créer l'agent lui-même, depuis la page de votre projet (ex: agent-config) :

  • Panneau de gauche > Opération > Cluster Kubernetes
  • Cliquez sur Connecter un cluster
  • Nommez votre agent en cohérence du fichier créé précédemment (ex: agent0) et cliquez sur Créer et enregistrer
  • Faites attention au jeton d'accès de l'agent affiché, il ne sera plus jamais affiché une fois que vous quittez la page et il est nécessaire pour les étapes suivantes.

Instancier l'agent dans le cluster​

L'agent peut être déployé via Helm dans le cluster à l'aide du graphique Helm gitlab-agent.

Un exemple de values Helm est fourni dans la livraison platform-provisionner (dans values/gitlab/samples), mais certaines modifications doivent être apportées :

  • Mettez le jeton d'accès de l'agent dans le champ config.token
  • Mettez dans le champ serviceAccount.name le nom que vous avez choisi pour le ServiceAccount dans l'étape Creating the RBAC rules.
  • Si vous utilisez des certificats auto-signés, vous devez :
    • Décommenter le champ config.kasCaCert et y placer la CA de votre platform 
## Helms dans la kosmos-registry
helm install -n <tenant_namespace> <name> oci://kosmos-registry.<domain>/athea/hauler/gitlab-agent -f ./values/gitlab/samples/agent-values.yaml

## Helms locaux dans le platform provisionner
helm install -n <tenant_namespace> <name> ../../gitlab/gitlab-agent -f ../../gitlab/values/samples/agent-values.yaml
info

Vous devrez isoler votre agent dans un namespace afin d'éviter que les actions CIs n'aient un impact sur d'autres ressources que vous avez installées.

Vérifier que l'agent est disponible​

Vous pouvez vérifier la disponibilité de votre agent dans tout projet qui y a accès, depuis la page du projet :

  • Panneau de gauche > Opération > Cluster Kubernetes
  • Cliquez sur votre agent

Avec la configuration par défaut fournie ci-dessus, votre agent doit apparaître dans n'importe quel projet de la zone tenant0.

Utiliser l'agent dans vos pipelines​

Vous pouvez créer une nouvelle variable CI/CD qui contient le nom de contexte kubernetes pour faciliter son utilisation auprès des Développeurs/Chargés de maintenance, depuis la page d'accueil :

  • Panneau de gauche > Groupes
  • Choisissez la zone que vous souhaitez configurer (tenant0) dans le groupe racine Bac a Sable.
  • Panneau de gauche > Paramètres > CI/CD
  • Allez dans la section Variables
  • Ajoutez la variable suivante avec le bouton Ajouter une variable :
    • AGENT_CTX :
      • La valeur est de la forme <agent_config_project_path>:<agent_name>
        • <agent_config_project_path> : Ceci doit correspondre au PATH http qui permet d'accéder à votre agent dans gitlab
          • ex: https://gitlab.kosmos.athea/bas/tenant0/Agents/agent-config -> bas/tenant0/agents/agent-config
        • <agent_name> : Ceci doit correspondre au nom de votre agent
        • Dans notre exemple la valeur est : bas/tenant0/agents/agent-config:agent0
      • Désactivez les 2 options de la section Flags

Créez un nouveau projet (eg: test-agent) dans votre zone ou un de ses sous-groupes afin de créer un pipeline de test utilisant kubectl.

Depuis la page d'accueil :

  • Panneau de gauche > Groupes
  • Choisissez la zone que vous souhaitez configurer (tenant0) dans le groupe racine Bac a Sable.
  • Optionnellement, allez dans un des sous-groupes de votre zone
  • Créez un nouveau projet et nommez-le (ex: test-agent)
  • Panneau de gauche > Compilation > Editeur de pipeline
  • Cliquez sur le bouton Configurer le pipeline afin de créer le fichier de configuration de pipeline
  • Copiez/Collez l'exemple fourni ci-dessous puis cliquez sur Valider les modifications

Le pipeline doit se terminer avec succès et les pods dans le namespace de votre agent (ex: tenant0-dev) doivent être listés dans les logs.

stages:
  - deploy

deploy-job:
  stage: deploy
  image:
      name: docker.io/alpine/k8s:1.32.1
      entrypoint: ['']
  script:
    - kubectl config get-contexts
    - kubectl config use-context $AGENT_CTX # $AGENT_CTX == 'bas/tenant0/agents/agent-config:agent0' in our example
    - kubectl get pods