Développer un provider

Provider et API

Ce chapitre décrit le développement d’un provider customisé à partir du framework de développement fourni par HashiCorp. La découverte du fonctionnement interne d’un provider permet de mieux comprendre le fonctionnement interne de Terraform.

Le cas d’exemple qui sert à l’illustration de ce chapitre s’appuie sur une API nommée SWAPI. SWAPI permet de manipuler les données de planètes d’une célèbre saga. Elle présente une API CRUD (pour Create, Read, Update, Delete) avec une seule ressource manipulable : une planète.

Ce cas d’exemple est simple, mais suffisant pour comprendre le fonctionnement d’un provider et pour pouvoir naviguer dans du code existant ou entamer le développement d’un provider maison !

Pour invoquer l’API SWAPI, le provider aura besoin d’une URL d’accès à l’API, ainsi que d’une API key :

provider "swapi" { 
  endpoint = "http://localhost:8080" 
  api_key = "cd0486bd-288d-4075-8ea9-f4bad20b3c70" 
} 

Le provider pourra aussi être configuré avec des variables d’environnement :

export SWAPI_ENDPOINT=http://localhost:8080 
export SWAPI_APIKEY=cd0486bd-288d-4075-8ea9-f4bad20b3c70 

La déclaration du provider sera alors minimale :...

La structure du code d’un provider

Pour démarrer le développement d’un provider, HashiCorp fournit un framework de développement, sous la forme de modules Go, et un squelette de code disponible sur GitHub. Le squelette de code permet de démarrer le développement rapidement, savoir avoir besoin de configurer les dépendances et outils de builds. Il contient aussi des exemples d’implémentation et de tests, qui sont faciles à éditer pour implémenter son propre provider. Enfin, le squelette de code contient les différents éléments qui sont nécessaires à la publication du provider sur le Registry Terraform, en particulier des workflows GitHub Actions prêts à l’emploi.

Le squelette de code est disponible sur GitHub à l’adresse https://github.com/hashicorp/terraform-provider-scaffolding-framework et contient le code suivant :

. 
├─ .github/ 
├─ CHANGELOG.md 
├─ docs/ 
├─ examples/ 
├─ GNUmakefile 
├─ go.mod 
├─ go.sum 
├─ .golangci.yml 
├─ .goreleaser.yml 
├─ internal/ 
│ └─ provider/ 
│ ├─ example_data_source.go 
│ ├─...

Développer le provider

La première étape consiste à cloner le squelette de projet fourni par HashiCorp.

Les providers Terraform suivent une convention de nommage pour leurs repositories. Dans ce chapitre le provider développé utilisera une API SWAPI, qui permet sert les données des planètes d’une saga bien connue.

Le provider sera donc nommé terraform-provider-swapi.

La création du projet se fait avec un git clone pour récupérer le code :

$ git clone https://github.com/hashicorp/terraform-provider-
scaffolding-framework terraform-provider-swapi 

Une fois le code téléchargé, supprimez le répertoire .git, pour repartir de zéro, en conservant le code du squelette :

$ cd terraform-provider-swapi/ 
$ rm -rf .git/ 
$ git init 
$ git add . 
$ git commit -m "feat: initial commit" 

// Ensure SWAPIProvider satisfies provider interface. 
var _ provider.Provider = &SWAPIProvider{} 
 
// SWAPIProvider defines the provider implementation. 
type SWAPIProvider struct { 
  // version is set to the provider version on release, 
  // "dev" when the provider is built and ran locally, 
  // and "test" when running acceptance testing. 
  version string 
} 

func (p *SwapiProvider) Metadata( 
        ctx context.Context, 
        req provider.MetadataRequest, 
        resp *provider.MetadataResponse) { 
    resp.TypeName = "swapi" 
    resp.Version...

Générer la documentation

Les informations contenues dans les Schema() des types Provider, Resource et DataSource sont utilisées pour générer la documentation du provider au format Markdown.

Il est aussi possible de fournir des exemples de code pour chaque Resource et DataSource, ainsi que pour le provider. Ces exemples doivent être déposés dans le répertoire example, à la racine du code du provider :

tree 
. 
└─ examples 
  ├─ data-sources 
  │ └─ swapi_planet 
  │ └─ data-source.tf 
  ├─ provider 
  │ └─ provider.tf 
  ├─ README.md 
  └─ resources 
     └─ swapi_planet 
         └─ resource.tf 

La page de documentation du provider inclut l’exemple de code défini dans examples/provider/provider.tf :

provider "swapi" { 
  # can be set with SWAPI_ENDPOINT 
  endpoint = "http://localhost:8080" 
  # can be set with SWAPI_APIKEY 
  api_key = "cd0486bd-288d-4075-8ea9-f4bad20b3c70" 
} 

La page de documentation de chaque ressource inclut l’exemple défini...

La publication du provider sur le Terraform Registry

1. Connexion au Registry

Lorsque le provider est développé et sa documentation générée, il peut être déployé sur le Terraform Registry.

Pour déployer un provider, son code doit être déposé sur GitHub, dans un repository nommé terraform-provider-*. Le provider exemple de ce chapitre a été publié sur GitHub à cette adresse : https://github.com/CodeKaio/terraform-provider-swapi

Pour déployer un provider, il faut tout d’abord être authentifié sur le registry.

Une fois à l’adresse https://registry.terraform.io, cliquer sur le bouton Sign-in ouvre une page d’authentification avec un lien qui redirige vers l’authentification de GitHub.

Cliquer sur le lien redirige vers la page d’autorisation de GitHub. Sur cette page, la liste des droits demandés est listée. Si vous êtes membre d’une ou plusieurs organisations GitHub, il est aussi possible d’autoriser les accès au code présent dans ces organisations.

Passé cette étape, l’utilisateur est redirigé vers https://registry.terraform.io. Le menu Publish - Provider permet alors de déclarer la publication d’un module à partir d’un repository Git.

L’étape suivante propose de sélectionner le repository contenant...