Registry OpenTofu, .tofurc et distribution OCI

Quand tofu init telecharge un provider ou un module, il ne travaille pas “dans le vide”. Il s’appuie sur une combinaison de source addresses, de registry hostnames, de configuration CLI et, de plus en plus souvent, de miroirs ou de registries OCI. C’est une zone importante d’OpenTofu parce qu’elle conditionne la repetabilite de vos builds, la rapidite de vos initialisations et la facon dont vous gerez les depots internes ou isoles.

Cette page remet de l’ordre dans ces notions. Vous allez voir ce que signifie vraiment hashicorp/aws, ou vit le fichier .tofurc, comment fonctionne provider_installation, quand activer un plugin cache, et comment OpenTofu sait lire des modules via oci://. L’objectif est simple : savoir d’ou viennent vos artefacts et comment reprendre le controle quand l’acces direct au registry public ne suffit plus.

Ce que vous allez apprendre

comprendre le role de registry.opentofu.org dans les adresses de providers ;
configurer .tofurc pour les credentials, le cache et les methodes d’installation ;
distinguer registry de modules, mirror de providers et OCI registry ;
utiliser des sources OCI pour les modules ;
choisir entre acces direct, cache local, filesystem mirror, network mirror et oci_mirror.

Le point de depart - d’ou viennent providers et modules

OpenTofu n’embarque pas la plupart des providers. Pendant tofu init, il doit :

resoudre les providers demandes par votre configuration ;
telecharger les modules declares ;
ecrire un lockfile pour figer les choix de versions et de checksums.

Pour les providers, une adresse comme hashicorp/aws est un raccourci pour registry.opentofu.org/hashicorp/aws.

Pour les modules, une source comme acme/network/aws designe un module publie via un module registry compatible, public ou prive.

Registry OpenTofu et adresses de providers

Le registry public d’OpenTofu est registry.opentofu.org. Si vous omettez l’hostname dans une adresse de provider, OpenTofu considere cet hote par defaut.

Exemples equivalents :

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }
}

et :

terraform {
  required_providers {
    aws = {
      source  = "registry.opentofu.org/hashicorp/aws"
      version = "~> 6.0"
    }
  }
}

Le second format rend l’origine plus explicite. Le premier reste pratique et lisible.

Ou se trouve `.tofurc`

Le fichier de configuration CLI d’OpenTofu se nomme :

.tofurc sur Linux, macOS et les autres systemes Unix ;
tofu.rc sur Windows.

Sur Linux, il peut vivre soit dans votre home, soit dans un repertoire XDG comme $XDG_CONFIG_HOME/opentofu/tofurc. Vous pouvez aussi pointer vers un autre fichier avec la variable d’environnement TF_CLI_CONFIG_FILE.

Cette configuration est globale a l’utilisateur, pas a un depot precis. Elle sert a piloter le comportement general de la CLI.

Ce que `.tofurc` peut configurer

Les usages les plus utiles pour une equipe sont :

le cache de plugins ;
les credentials pour les services OpenTofu-specifiques ;
les methodes d’installation de providers via provider_installation ;
certains reglages de protocoles registry ;
les credentials ou configurations necessaires pour les workflows OCI.

Exemple minimal avec cache local :

plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

Le cache reduit les telechargements repetes entre plusieurs depots. Il doit exister avant usage, et ne doit pas etre confondu avec un vrai mirror d’entreprise.

Credentials dans `.tofurc`

Pour les services OpenTofu-specifiques, les credentials se configurent avec des blocs credentials ou via des variables d’environnement TF_TOKEN_....

Exemple :

credentials "app.opentofu.org" {
  token = "xxxxxx.atlasv1.zzzzzzzzzzzzz"
}

En pratique, si vous pouvez eviter d’ecrire le token en clair dans le fichier, preferez les variables d’environnement de type TF_TOKEN_app_opentofu_org.

`provider_installation` - reprendre le controle des providers

Le bloc provider_installation permet de dire a OpenTofu ou chercher les providers et dans quel ordre.

Exemple simple avec un filesystem mirror pour certains providers et acces direct pour le reste :

provider_installation {
  filesystem_mirror {
    path    = "/srv/opentofu/providers"
    include = ["registry.opentofu.org/hashicorp/*"]
  }

  direct {
    exclude = ["registry.opentofu.org/hashicorp/*"]
  }
}

Cette configuration dit :

pour les providers hashicorp/*, lire le mirror local ;
pour les autres, telecharger directement depuis leur origine.

Les principales methodes disponibles

Methode	Usage type
`direct`	acces standard au registry d’origine
`filesystem_mirror`	miroir sur disque local ou partage monte
`network_mirror`	miroir HTTP(s) interne
`oci_mirror`	distribution de providers via registry OCI
`dev_overrides`	developpement de providers, pas usage general

Quand utiliser un mirror plutot que l’acces direct

Un mirror devient utile si :

vos runners n’ont pas acces a Internet ;
vous voulez reduire les telechargements repetes ;
vous devez figer plus strictement la provenance des binaires ;
votre organisation impose un point de controle central.

Le plugin cache accelere, mais il ne remplace pas un vrai miroir. Le cache est un confort local. Le miroir est un choix d’architecture.

Les modules - registry, Git et OCI

Pour les modules, OpenTofu supporte plusieurs types de sources :

registry natif ;
GitHub, Git generique, Mercurial ;
archives HTTP, S3, GCS ;
OCI registries.

Exemple de module depuis un registry :

module "network" {
  source  = "acme/network/aws"
  version = "1.4.2"
}

Exemple de module OCI :

module "network" {
  source = "oci://registry.example.com/platform/network?tag=v1.4.2"
}

Vous pouvez aussi cibler un digest plutot qu’un tag :

module "network" {
  source = "oci://registry.example.com/platform/network?digest=sha256:0123456789abcdef"
}

Et, comme pour d’autres packages, viser un sous-repertoire avec // :

module "network" {
  source = "oci://registry.example.com/platform/modules//network?tag=v1.4.2"
}

Ce que change OCI dans le quotidien

Le protocole OCI permet de reutiliser une brique d’infrastructure deja courante dans beaucoup d’organisations : le registry d’images ou d’artefacts. C’est utile si vous voulez publier des modules sans monter un registry de modules specifique ou si votre entreprise maitrise deja son chemin d’acces OCI.

L’idee importante est de ne pas melanger deux usages :

modules via oci:// dans la configuration ;
providers via oci_mirror dans .tofurc.

Les deux utilisent OCI, mais pas au meme niveau de la pile.

Exemple de `.tofurc` plus complet

plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"

provider_installation {
  filesystem_mirror {
    path    = "/srv/opentofu/providers"
    include = ["hashicorp/*"]
  }

  oci_mirror {
    repository_prefix = "registry.example.com/opentofu-providers"
    include           = ["examplecorp/*"]
  }

  direct {
    exclude = ["hashicorp/*", "examplecorp/*"]
  }
}

registry_protocols {
  retry_count             = 1
  request_timeout_seconds = 10
}

Ce type de configuration devient interessant dans une plateforme interne avec plusieurs runners et plusieurs depots.

Ce qu’il faut surveiller dans le lockfile

Apres tofu init, OpenTofu met a jour .terraform.lock.hcl. Ce fichier doit etre versionne pour garder des installations repetables.

Le bon comportement en equipe est simple :

committer le lockfile ;
relire ses changements lors d’un init -upgrade ;
ne pas laisser la CI installer des versions differentes selon les postes.

Depannage

Symptome	Cause probable	Solution
provider introuvable	hostname, namespace ou type incorrect	verifier l’adresse complete et le registry vise
la CI telecharge encore depuis Internet	`direct` encore actif pour le provider concerne	ajouter `exclude` ou retirer la methode directe
cache inefficace	repertoire de cache absent ou mal configure	creer le dossier et verifier `plugin_cache_dir`
module OCI non resolu	source `oci://` mal formee ou tag absent	verifier repository, tag ou digest
token ignore	hostname different entre source et credentials	aligner le hostname entre `.tofurc` et la source reellement utilisee

A retenir

hashicorp/aws est un raccourci pour registry.opentofu.org/hashicorp/aws.
.tofurc pilote la CLI globale : cache, credentials, mirrors, installation methods.
Le plugin cache accelere, mais ne remplace pas un mirror d’entreprise.
Un module OCI se refere via oci://..., tandis que les providers peuvent etre servis par oci_mirror dans la config CLI.
Le lockfile .terraform.lock.hcl reste une piece essentielle de la repetabilite apres tofu init.

Prochaines etapes

Variables dans init Relier ensuite registry et modules au moment ou OpenTofu evalue vars et locals des init.

Migrer depuis Terraform Replacer `.tofurc`, le lockfile et les miroirs dans une migration globale de depot.

Utiliser un module du Registry Revoir le fonctionnement general des modules versionnes si vous avez besoin des bases communes.

Refactor, import et removed Voir comment ces choix d'installation se combinent ensuite a des configurations qui evoluent dans le temps.