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 rapidité de vos initialisations et la façon dont vous gérez les dépôts internes ou isolés.

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'où viennent vos artefacts et comment reprendre le contrôle quand l'accès 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 méthodes d'installation ;
distinguer registry de modules, mirror de providers et OCI registry ;
utiliser des sources OCI pour les modules ;
choisir entre accès direct, cache local, filesystem mirror, network mirror et oci_mirror.

Le point de départ - d'où viennent providers et modules

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

résoudre les providers demandes par votre configuration ;
télécharger les modules déclarés ;
écrire 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 désigne 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 hôte par défaut.

Exemples équivalents :

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 systèmes Unix ;
tofu.rc sur Windows.

Sur Linux, il peut vivre soit dans votre home, soit dans un répertoire 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 dépôt précis. Elle sert a piloter le comportement general de la CLI.

Ce que `.tofurc` peut configurer

Les usages les plus utiles pour une équipe sont :

le cache de plugins ;
les credentials pour les services OpenTofu-specifiques ;
les méthodes d'installation de providers via provider_installation ;
certains réglages de protocoles registry ;
les credentials ou configurations nécessaires pour les workflows OCI.

Exemple minimal avec cache local :

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

Le cache réduit les telechargements repetes entre plusieurs dépôts. Il doit exister avant usage, et ne doit pas être 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 éviter d'écrire le token en clair dans le fichier, préférez les variables d'environnement de type TF_TOKEN_app_opentofu_org.

`provider_installation` - reprendre le contrôle 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 accès 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, télécharger directement depuis leur origine.

Les principales méthodes disponibles

Méthode	Usage type
`direct`	accès 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`	développement de providers, pas usage general

Quand utiliser un mirror plutôt que l'accès direct

Un mirror devient utile si :

vos runners n'ont pas accès a Internet ;
vous voulez réduire les telechargements repetes ;
vous devez figer plus strictement la provenance des binaires ;
votre organisation impose un point de contrôle central.

Le plugin cache accélère, 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 générique, 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 plutôt qu'un tag :

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

Et, comme pour d'autres packages, viser un sous-répertoire 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 réutiliser une brique d'infrastructure déjà 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 spécifique ou si votre entreprise maitrise déjà son chemin d'accès OCI.

L'idée importante est de ne pas mélanger deux usages :

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

Les deux utilisent OCI, mais pas au même 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 dépôts.

Ce qu'il faut surveiller dans le lockfile

Après tofu init, OpenTofu met a jour .terraform.lock.hcl. Ce fichier doit être versionne pour garder des installations repetables.

Le bon comportement en équipe est simple :

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

Dépannage

Symptôme	Cause probable	Solution
provider introuvable	hostname, namespace ou type incorrect	vérifier l'adresse complète et le registry vise
la CI telecharge encore depuis Internet	`direct` encore actif pour le provider concerne	ajouter `exclude` ou retirer la méthode directe
cache inefficace	répertoire de cache absent ou mal configure	créer le dossier et vérifier `plugin_cache_dir`
module OCI non résolu	source `oci://` mal formee ou tag absent	vérifier repository, tag ou digest
token ignore	hostname different entre source et credentials	aligner le hostname entre `.tofurc` et la source réellement utilisée

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 accélère, mais ne remplace pas un mirror d'entreprise.
Un module OCI se refere via oci://..., tandis que les providers peuvent être servis par oci_mirror dans la config CLI.
Le lockfile .terraform.lock.hcl reste une pièce essentielle de la repetabilite après tofu init.

Prochaines étapes

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 dépôt.

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

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