1. Contexte du guide

Le guide a été réalisé pour :

• La plateforme VCF Automation / VMware Aria Automation de l’IM2AG.
• La plateforme accessible via l’URL : https://im2ag-aria-vcfa.u-ga.fr
• L’organisation : ORG-IM2AG-ARIA
• L’élément de catalogue Docker, version 8
• Le provider Terraform vmware/vra, version ~> 0.11
• Un compte utilisateur ayant accès au Service Broker et au projet contenant le catalogue Docker.
• Un projet GitLab contenant les fichiers Terraform

Le blueprint utilisé permet de déployer une VM Debian avec Docker installé dont le modèle ou blueprint dans le langage Aria est déjà défini.
La demande de déploiement est faite par Terraform mais l’orchestration, l’authentification et l’attribution des ressources restent gérées par Aria Automation.

2. Principes généraux

Pour pouvoir interagir avec l’API de ARIA, il est nécessaire de créer un token personnalisé au niveau d’ARIA. Ce token a exactement les mêmes droits que son compte d’utilisateur. Toutes les actions réalisables depuis l’interface graphique peuvent être faites avec un script Terraform grâce à ce token.

Dans Aria Automation, il faut distinguer deux actions différentes :

1. Créer ou publier une source dans le catalogue à partir d’un blueprint (réservée aux administrateurs de la plateforme)
2. Demander un déploiement d’un blueprint déjà présent dans le catalogue (réservée pour les membres du projet auquel appartient le blueprint)

Dans ce test, le blueprint Docker existe déjà et il est visible dans le catalogue pour le compte d’utilisateur utilisé.

3. Création de token d’API ARIA

Connectez-vous à l’interface web de la plateforme via son URL
Vous utiliserez pour cela vos identifiants Agalan.
Cliquez sur votre nom après la connexion puis sous User Settings sur My Account.

Ensuite, cliquez sur API Tokens

Vous pouvez créer votre token depuis cet onglet en cliquant sur New puis en complétant le formulaire et puis Create.

Notez bien ce token de façon sécurisée!

4. Introduction à Terraform

Nous allons présenter Terraform de façon brève ci-dessous. Vous pouvez aller à l’étape suivante pour poursuivre les étapes du guide.

HashiCorp Terraform est un outil IaC (infrastructure as code) qui vous permet de définir des ressources à la fois en cloud et on-prem en utilisant un langage de configuration facilement lisible par un humain. L’IaC permet de versionner, réutiliser et partager ces configurations. Terraform peut gérer des composants bas niveau tels que des VMs, du stockage et des réseaux ainsi que des composants de haut-niveau comme les entrées DNS et des features SaaS.

Il existe des tutoriels en fonction de l’infrastructure que vous utilisez vous pouvez vous rendre à la documentation officielle pour plus de détails.

Comment marche Terraform ?

Terraform crée et gère des ressources sur des plateformes Cloud et d’autres services à travers leurs APIs (application programming interfaces). Les Providers permettent à Terraform d’interagir virtualement avec toute plateformes et service accessible via API. Le flux Terraform consiste en trois étapes:

• Write: on définit les ressources qui pourraient être accessibles via de multiples providers et services Cloud. Par exemple, on peut créer et configurer une VM dans un Cloud privé virtuel (Virtual Private Cloud VPC).
• Plan: Terraform crée un plan d’exécution décrivant l’infrastructure qu’il va créer, mettre à jour ou détruire en se basant sur l’infrastructure existante et sa configuration.
• Apply: lors de l’approbation, Terraform réalise les opérations proposées dans le bon ordre, en respectant les dépendances entre les ressources.

Source de l’image est Terraform.

Vous pouvez trouver des documentations sur la création de ressources via Terraform en suivant les liens ci-dessous:

• Créer une VM EC2 sur AWS.
• Créer une VM sur GCP par Thomas Ropars.

5. Structure d’un projet Terraform ARIA Docker

Le projet Terraform peut être organisé comme le suivant :

docker/
├── v8/
│   ├── versions.tf       # versions Terraform + provider requis
│   ├── provider.tf       # configuration du provider vra
│   ├── variables.tf      # déclaration des variables
│   ├── main.tf           # ressource principale vra_deployment
│   ├── outputs.tf        # valeurs affichées après apply
│   └── terraform.tfvars  # valeurs concrètes des variables
└── .gitlab-ci.yml        # pipeline GitLab CI

Ci-dessous la configuration concernant un projet Docker qui se trouve sur ARIA de l’IM2AG. Pour utiliser d’autres projet rendez vous sur le dépot Gitlab afin de récupérer les fichiers de configuration correspondants à votre type de Deploiement.

Les fichiers de configurations de Terraform sont des fichiers textes écrits avec le langage de configuration d’HashiCorp (HashiCorp Configuration Language HCL) utilisant l’extension .tf
Lorsqu’on réalise des opérations avec l’interface en ligne de commande Terraform CLI, Terraform charge toutes les configurations qui se trouvent dans le répertoire courant de travail et résout automatiquement les dépendances. Cela permet d’organiser les configurations en multiples fichiers dans l’ordre que vous définissez.
Les configurations Terraform sont organisées par des blocs qui permet de configurer Terraform, ses providers et les ressources et les data sources qui componsent l’infrastructure.

Le bloc terraform:

Le bloc terraform {} permet de configurer Terraform en soi, cela inclut quels providers à installer, quelle version de Terraform à utiliser pour approvisionner l’infrastructure. L’utilisation d’un fichier cohérent avec une structure claire rend la maintenance des projets Terraform plus facile. Il est donc recommandé de configurer un bloc Terraform dans un fichier dédié terraform.tf. La documentation du bloc terraform se trouve ici.

# terraform.tf
# Dans notre cas, comme on utilise VMWare Aria VRA on définit:
terraform {
  required_providers {
    vra = {
      source  = "vmware/vra"
      version = "~> 0.11"
    }
  }
}

Terraform utilise des plugins binaires appelés providers pour gérer les ressources en faisant des appels à l’API du fournisseur de cloud.
Les providers Terraform sont distribués et versionnés séparément du client Terraform.
En découplant les providers du binaire Terraform, Terraform peut prendre en charge toute infrastructure qui fournit une API.
Le bloc required_providers permet de définir les providers en ajoutant des contraintes de source et de version sur les providers utilisés dans les configurations.
HashiCorp maintient un Registre Terraform, depuis ce registre on peut obtenir des fournisseurs et des modules Terraform publics.

L’argument source spécifie un hostname (optionnel), namespace, et un nom de provider. Dans l’exemple, on utilise la source provider vra de vmware/vra, qui est un raccourci du registry.terraform.io/vmware/vra, l’adresse du provider se trouve dans le Registre Terraform. La documentation des arguments de cette interface avec différents exemples se trouvent ici.

L’argument version fixe la contrainte de version sur le provider AWS. Si ce n’est pas précisé, alors Terraform choisit celle par défaut qui est la plus récente version du provider.
Il est recommandé de spécifier une version pour être sûr que Terraform n’installe une version du provider qui n’a pas été testée avec les configurations du projet. La chaine de caractères ~> 5.92 signifie que les configurations supportent toute version de provider qui a une version majeure de 5 et version mineure supérieure ou égale à 92.

Exemples de versions autorisées :
5.92.0
5.92.3
5.93.1
5.99.0
Exemple de version refusée :
6.0.0
Dans le versioning classique :
MAJEURE.MINEURE.CORRECTIF
5       .92      .1
majeure = changements potentiellement incompatibles
mineure = nouvelles fonctionnalités compatibles
correctif = bugfix
Donc ~> 5.92 signifie: rester dans la famille 5.x, à partir de 5.92.

L’idée est d’autoriser les mises à jour mineures et correctifs mais éviter une grosse mise à jour majeure (6.x) qui pourrait casser la compatibilité.

L’exemple de configuration définit également la version requise de Terraform. La mention >= 1.2 indique que votre configuration est compatible avec toute version de Terraform supérieure ou égale à 1.2. Lors de l’installation de Terraform, vous avez probablement installé la dernière version disponible.

Vous pouvez vérifier votre version actuelle de Terraform en exécutant la commande terraform -version.

terraform -version
# Terraform v1.15.1
# on linux_amd64

Le bloc provider:

La documentation des arguments de cette interface avec différents exemples se trouvent ici.

provider "vra" {
  url           = var.vcfa_url # Le lien vers l'endpoint VMware Aria Automation
  organization  = var.vcfa_organization # Le nom de l'organisation qui est obligatoire puisqu'on utilise VCF Automation
  refresh_token = var.vcfa_refresh_token # Votre Token personnel
  insecure      = var.vcfa_insecure # Désactive ou non la validation TLS des certificats HTTPS
}

Le bloc resource vra_deployement:

La documentation des arguments de cette interface avec différents exemples se trouvent ici.

Dans ce guide, l’objectif n’est pas de créer directement une VM vSphere avec Terraform. Terraform crée une ressource vra_deployment, c’est-à-dire une demande de déploiement envoyée au catalogue Aria Automation.

Pour rappel, une ressource est un élément qui peut être CRUD (créé, déplacé, mis à jour et supprimé). Un objet d’une ressource est unique (un nom/identificant unique) dans un même module.
La documentation du bloc ressource se trouve ici.

La signature générale d’une ressource Terraform est :

resource "<type_de_ressource>" "<nom_ressouce_terraform" {
  ...
}

# main.tf
resource "vra_deployment" "docker" {
  name        = var.deployment_name
  description = "Docker deployment created from Terraform"

  catalog_item_id      = var.catalog_item_id
  catalog_item_version = var.catalog_item_version
  project_id           = var.project_id

  inputs = {
    username = var.vm_username
    password = var.vm_password
    cpu_var  = var.cpu_var
    mem_var  = var.mem_var
  }

  timeouts {
    create = "60m"
    update = "60m"
    delete = "60m"
  }
}

Le nom logique Terraform de la ressource est docker. Il sert à identifier la ressource dans le state Terraform et à la référencer dans les autres fichiers, par exemple dans outputs.tf.

Les champs catalog_item_id, catalog_item_version et project_id indiquent quel élément du catalogue doit être déployé, dans quelle version et dans quel projet Aria. Le nom visible dans Aria Automation est défini avec name = var.deployment_name.

Le dictionnaire inputs correspond aux inputs techniques déclarés dans le blueprint Docker. Ces clés doivent être reprises exactement depuis le blueprint.

Les blocs output

Le fichier outputs.tf permet d’afficher des informations utiles après un terraform apply. Dans la configuration Docker actuelle, l’output disponible est l’identifiant du déploiement Aria :

# outputs.tf
output "deployment_id" {
  value = vra_deployment.docker.id
}
output "docker_vm" {
  value = {
    for r in vra_deployment.docker.resources :
    jsondecode(r.properties_json).resourceName => {
      id = r.id
      ip = jsondecode(r.properties_json).address
    }
    if r.type == "Cloud.vSphere.Machine"
  }
}

A la fin de la création du déploiement, vous pouvez obtenir une trace de ce type :

# Exemple output
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

deployment_id = "b6dcafa3-a30b-421d-9ab7-4cd5f307006c"
docker_vm = {
  "Docker-testimde-438" = {
    "id" = "6111b728-4fd2-4e01-ab6a-5b13a3a38952"
    "ip" = "10.0.22.35"
  }
}

Les blocs variable

Les variables Terraform rendent le code dynamique et réutilisable. Elles sont utilisées pour variabiliser les informations de connexion à VMware Aria, les identifiants du catalogue, le nom du déploiement et les paramètres du blueprint Docker.

# variables.tf
variable "vcfa_url" {
  type = string
}

variable "deployment_name" {
  type = string
}

variable "vm_username" {
  type    = string
  default = "ecloud"
}
...
...
variable "cpu_var" {
  type    = number
  default = 2
}

variable "mem_var" {
  type    = number
  default = 2048
}

Le fichier terraform.tfvars :

Le fichier terraform.tfvars permet de définir les valeurs utilisées par les variables Terraform sans modifier directement le code principal. Ce fichier contient les informations de connexion à VMware Aria, le token API personnel, les identifiants du projet et du catalogue et les paramètres du blueprint.
Les paramètres disponibles dans ce fichier dépendent directement des inputs définis dans le blueprint VMware Aria Automation. Par conséquent, seules les valeurs autorisées par le blueprint peuvent être utilisées.
Les contraintes définies dans le blueprint (enum, tailles minimales/maximales, types, etc.) restent appliquées. Une valeur non supportée entraînera une erreur lors du terraform apply.

# Par exemple, si le blueprint autorise uniquement :
cpu_var:
  type: integer
  enum:
    - 2
    - 4
  default: 2
# Alors une valeur comme cpu_var = 8 sera refusée par VMware Aria Automation.

La valeur cpu_var = 8 n’est pas disponible dans le blueprint Docker. Même si Terraform accepte syntaxiquement la valeur sans validation locale, Aria Automation peut refuser la demande parce que la valeur n’existe pas dans les options autorisées.

Pour éviter ce problème, ajoutez des validations Terraform dans variables.tf.

variable "cpu_var" {
  type    = number
  default = 2

  validation {
    condition     = contains([2, 4], var.cpu_var)
    error_message = "cpu_var must be 2 or 4."
  }
}

Ainsi, si un utilisateur demande une configuration absente du catalogue, l’erreur apparaît dès terraform plan.

terraform plan
# Sortie attendue en cas de valeur invalide :
# Error: Invalid value for variable
# cpu_var must be 2 or 4.

6. Adaptation aux inputs du blueprint Docker

Les noms techniques des inputs Docker sont :

username
password
cpu_var
mem_var

Ces noms sont ceux définis dans le blueprint Docker. Ils doivent être repris exactement comme clés dans le champ inputs de la ressource Terraform vra_deployment. Dans la configuration Terraform, les variables peuvent avoir un nom différent, mais la clé envoyée à Aria doit rester identique au blueprint.

inputs = {
  username = var.vm_username
  password = var.vm_password
  cpu_var  = var.cpu_var
  mem_var  = var.mem_var
}

Dans cet exemple :

• username est le nom technique attendu par le blueprint.
• var.vm_username est le nom de la variable Terraform locale.
• password est le nom technique attendu par le blueprint.
• var.vm_password est le nom de la variable Terraform locale.

7. Exécution Terraform

Placez-vous dans le répertoire qui contient les fichiers Terraform Docker :

cd docker/v8

Initialisation du projet :

terraform init

Formatage :

terraform fmt

Validation :

terraform validate

Prévisualisation du déploiement :

terraform plan

Application :

terraform apply

Suppression du déploiement :

terraform destroy

Merci de bien supprimer tous les déploiements que vous avez créés à la fin de la séance afin d’éviter toute consommation inutile.

8. Pipeline GitLab CI

Une fois le projet Terraform poussé dans GitLab, il est possible d’exécuter les commandes Terraform via une pipeline.

Exemple de fichier .gitlab-ci.yml :

stages:
  - apply

image:
  name: hashicorp/terraform:1.8
  entrypoint: [""]

variables:
  TF_ROOT: "."
  TF_IN_AUTOMATION: "true"
  HTTP_PROXY: "http://www-cache.u-ga.fr:3128"
  HTTPS_PROXY: "http://www-cache.u-ga.fr:3128"
  NO_PROXY: "im2ag-aria-vcfa.u-ga.fr"

apply:
  stage: apply
  script:
    - terraform --version
    - terraform init
    - terraform plan
    - terraform apply -auto-approve

Les valeurs sensibles doivent être placées dans les variables CI/CD GitLab :

TF_VAR_vcfa_refresh_token
TF_VAR_vm_password

Les autres valeurs peuvent aussi être injectées par GitLab avec le préfixe TF_VAR_, par exemple :

TF_VAR_deployment_name
TF_VAR_vm_username
TF_VAR_cpu_var
TF_VAR_mem_var

Si vous voulez créer votre deploiement avec une Pipeline Gitlab, vous devez penser à récupérer le fichier state généré avec Terraform pour pouvoir manipuler avec Terraform votre déploiement depuis un ordinateur connecté au VPN de l’université.
Si ce n’est pas fait, vous pouvez récupérer l’identifiant de votre déploiement sur l’interface graphique d’Aria.

Résumé et remarques

Terraform permet de déclencher un déploiement Docker depuis le catalogue Aria Automation en utilisant la ressource vra_deployment de façon automatisée.

Les points importants à retenir sont :

1. Le provider VMware Aria nécessite une URL, une organisation et un token.
2. Le modèle Docker est identifié via project_id, catalog_item_id et catalog_item_version.
3. Les inputs Terraform doivent correspondre exactement aux inputs du blueprint Docker : username, password, cpu_var, mem_var.
4. Les valeurs envoyées doivent respecter les contraintes définies dans le catalogue : CPU 2 ou 4, mémoire 2048, 4096 ou 8192.
5. Les secrets doivent être protégés, en particulier vcfa_refresh_token et vm_password.
6. GitLab CI/CD permet d’automatiser le déploiement de votre infrastructure.
7. Le GitLab Runner doit disposer d’un accès réseau valide vers VMware Aria Automation.
8. Il exsite un dépôt Gitlab avec les configurations Terraform correspondantes à chaque modèle d’infrastructure.
9. Pensez à supprimer tous les déploiements que vous avez créés à la fin de la séance afin d’éviter toute consommation inutile.