Toegang tot modulebronnen op GitHub Enterprise

Sommige Terraform-code die het platform draait (bijvoorbeeld de spoke-extensies voor GitHub) laadt zijn modules uit Git-repositories op een GitHub Enterprise-host. Terraform moet zich bij die host authenticeren als het terraform init draait. Deze pagina laat de opties zien, welke je moet gebruiken en hoe je uitzoekt waarom toegang faalt.

Waarom dit nodig is

Terraform staat geen variabelen toe in de source van een module. De URL staat dus vast in de code, en de credentials moeten van buiten komen, via Git. Een modulebron ziet er zo uit (placeholders):

source = "git::https://<github host>/<organization>/<module repository>.git//src?ref=<version>"

Terraform roept Git aan om hem te clonen. Heeft Git geen credentials voor de host, dan faalt terraform init met een authenticatiefout of een "repository not found"-fout.

Kies een methode

Methode	Gebruik wanneer	Opmerkingen
HTTPS met een Git-credential (aanbevolen)	Pipelines en agents	Een kortlevend installatietoken van een GitHub App in een Git-credential. De onderstaande secties laten zien hoe.
SSH	Je beheert al SSH-keys op de agents	Wijzig de modulebron naar de vorm git::ssh://. Vereist een key die de repositories mag lezen, als secret aan de agent toegevoegd.
Lokaal modulepad	De modules zijn naar je eigen repository gekopieerd	Gebruik een relatief pad in source. Je bent dan zelf verantwoordelijk voor het bijwerken van de kopie.
Een andere registry	Je organisatie heeft een module registry	De bron verandert dienovereenkomstig.

Gebruik HTTPS met een token voor pipelines. Tokens kunnen kortlevend en beperkt zijn, en er hoeft niets op de agent te worden geïnstalleerd.

HTTPS met Git-credentials

Het token

De platformworkflows gebruiken een installatietoken van een GitHub App. Het wordt in de workflow gemaakt uit de app-ID en de private key (Spoke-integraties voorbereiden). Het verloopt vanzelf, dus een gelekt token heeft beperkt nut.

• Sla de app-ID op als organization-variabele en de private key als organization-secret.
• Beperk toegang tot alleen de configuratierepositories.
• De app moet geïnstalleerd zijn in de organisatie die de modules bevat, en die repositories mogen lezen. De permissies staan in Spoke-integraties voorbereiden.

GitHub Actions

Maak het token en geef Git de credential vóór terraform init. Een ingekorte workflow:

- name: Create GitHub App token
  id: app_token
  uses: actions/create-github-app-token@v2
  with:
    app-id: ${{ vars.cloud_platform_gh_app_id }}
    private-key: ${{ secrets.cloud_platform_gh_app_private_key }}
    owner: ${{ github.repository_owner }}

- name: Configure Git credentials
  run: |
    git config --global credential.helper store
    echo "https://${{ steps.app_token.outputs.token }}@<github host>" > ~/.git-credentials

- name: Terraform init
  run: terraform init
  env:
    TF_VAR_github_token: ${{ steps.app_token.outputs.token }}

Azure DevOps

Bewaar het token in een variable group of een pipeline-secret, en schrijf de credential in een scriptstap vóór terraform init:

steps:
- script: |
    git config --global credential.helper store
    echo "https://$(GITHUB_TOKEN)@<github host>" > ~/.git-credentials
  displayName: Configure Git credentials

- script: terraform init
  displayName: Terraform init
  env:
    TF_VAR_github_token: $(GITHUB_TOKEN)

Laat geen tokens achter op gedeelde agents

Het bestand ~/.git-credentials bevat het token in platte tekst. Verwijder het bestand op self-hosted agents die worden hergebruikt zodra de job eindigt, of gebruik een ephemeral agent. Een token dat langer dan de job op een agent blijft staan, is een lek dat staat te wachten.

Andere manieren om Git een credential te geven

Voor iemand die op een werkstation test, is hetzelfde resultaat te bereiken met Git-configuratie:

• een credential helper die voor de host is geconfigureerd (credential.<url>.username en .helper), of
• een .netrc-bestand met machine, login en password (permissies 600), of
• omgevingsvariabelen die je eigen credentialscript leest.

Gebruik deze niet op gedeelde build agents.

SSH

Wijzig de bron naar de SSH-vorm:

source = "git::ssh://git@<github host>/<organization>/<module repository>.git//src?ref=<version>"

Maak een key pair, voeg de public key toe aan een account (of als deploy key) dat de repositories kan lezen, en voeg de private key als secret aan de pipeline toe. Laat de agent de host vertrouwen. In GitHub Actions kan een SSH-agent-action de key laden.

Lokale kopieën

Kopieer de modules naar de repository en verwijs ernaar met een relatief pad:

source = "../../../modules/<module name>/src"

Gebruik dit als de host helemaal niet bereikbaar is. Voeg het bijwerken van de kopie toe aan je upgradeprocedure (Nieuwe versie).

Testen en troubleshooten

Test eerst met Git, daarna met Terraform:

git ls-remote https://<github host>/<organization>/<module repository>.git
terraform init -backend=false

Symptoom	Controleer
Authenticatie mislukt	De app is geïnstalleerd in de organisatie en heeft de juiste permissies. Het token is niet verlopen. De credential is voor de juiste hostnaam geschreven.
Repository niet gevonden	De repository bestaat op de enterprise-host. De app mag hem lezen. Een ontbrekende permissie kan als "not found" verschijnen.
Netwerkfout of timeout	De agent kan de host bereiken (firewallregels, proxy). Zie Netwerktoegang van de agents.
init werkt lokaal maar niet in de pipeline	De credentialstap draait vóór terraform init, in dezelfde job en gebruikerscontext.

Gerelateerde pagina's

• Spoke-integraties voorbereiden
• GitHub voorbereiden