# Google Workspace beheren met Terraform

[[TOC]]

Gebruikers en groepen handmatig in de console beheren werkt, maar het is niet reproduceerbaar, niet auditeerbaar en foutgevoelig. Met infrastructure as code beschrijf je je Workspace-organisatie declaratief, bewaar je het in Git en pas je wijzigingen gecontroleerd toe. Terraform is hiervoor een logische keuze, en er is een provider speciaal voor Workspace.

In dit artikel beheer je je organisatie als code, met een eerlijke blik op de huidige staat van de provider.

:::warn title="De officiele provider is gearchiveerd"
HashiCorp heeft de officiele provider `hashicorp/googleworkspace` op 30 juni 2025 gearchiveerd. De repository is alleen-lezen, issues en pull requests worden niet meer behandeld en er komen geen nieuwe releases. De laatste release is v0.7.0 uit juni 2022. De bestaande binaries en documentatie blijven beschikbaar, dus de provider werkt nog, maar je krijgt geen updates of bugfixes meer.

Weeg dit risico bewust mee. Opties zijn: de v0.7.0-provider blijven gebruiken met een vastgepinde versie, overstappen op een onderhouden community-fork, of bepaalde resources via een ander mechanisme beheren. Controleer altijd de actuele status voordat je dit in productie inzet.
:::

## Waarom Workspace als code

Declaratief beheer brengt grote voordelen voor IT-teams.

- Je organisatiestructuur staat in Git, met volledige historie en review via pull requests.
- Wijzigingen zijn reproduceerbaar tussen omgevingen.
- Drift wordt zichtbaar: Terraform toont verschillen tussen gewenst en werkelijk.
- Onboarding en offboarding worden code-changes in plaats van handmatige klikpaden.

:::info title="Pin altijd je provider-versie"
Juist omdat de provider niet meer actief wordt onderhouden, is het belangrijk om de versie expliciet vast te pinnen in een `required_providers`-blok. Zo voorkom je dat een onverwachte upgrade je configuratie breekt, en blijft je opzet reproduceerbaar.
:::

## Authenticatie opzetten

De provider authenticeert met een service account dat een beheerder impersoneert via domain-wide delegation. Je hebt hiervoor een super admin nodig die de delegation goedkeurt.

:::howto title="Authenticatie configureren"
1. Maak een service account aan in Google Cloud en download de JSON-sleutel.
2. Laat een super admin het service account **domain-wide delegation** geven met de juiste Admin SDK Directory-scopes.
3. Lever de sleutel via de omgevingsvariabele `GOOGLEWORKSPACE_CREDENTIALS`, nooit hardcoded in je code.
4. Configureer de provider met `customer_id` en `impersonated_user_email` (een beheerder met toegang tot de Admin APIs).
5. Draai `terraform init` om de provider te installeren en daarna `terraform plan` op een kleine resource als test.
:::

Een minimale provider-configuratie ziet er zo uit:

```hcl
terraform {
  required_providers {
    googleworkspace = {
      source  = "hashicorp/googleworkspace"
      version = "0.7.0"
    }
  }
}

provider "googleworkspace" {
  customer_id             = "C01abc234"
  impersonated_user_email = "admin@jouwdomein.nl"
  oauth_scopes = [
    "https://www.googleapis.com/auth/admin.directory.user",
    "https://www.googleapis.com/auth/admin.directory.group",
  ]
}
```

## Een gebruiker en groep definieren

In HCL beschrijf je resources declaratief. Terraform bepaalt zelf welke API-calls nodig zijn om de gewenste toestand te bereiken.

```hcl
resource "googleworkspace_user" "jan" {
  primary_email = "jan.jansen@jouwdomein.nl"
  name {
    given_name  = "Jan"
    family_name = "Jansen"
  }
  org_unit_path = "/Verkoop"
}

resource "googleworkspace_group" "verkoop" {
  email = "verkoop@jouwdomein.nl"
  name  = "Verkoopteam"
}
```

:::tip title="Beheer lidmaatschappen apart"
Beheer lidmaatschappen met losse `googleworkspace_group_member`-resources of via een dynamische `for_each` over een lijst. Zo houd je de groepssamenstelling overzichtelijk in code en zie je in elke pull request precies wie wordt toegevoegd of verwijderd.
:::

## State veilig beheren

Terraform houdt de werkelijke toestand bij in een state-bestand. Dat bestand is gevoelig.

:::danger title="State bevat gevoelige gegevens"
Het Terraform-state-bestand kan gevoelige gegevens bevatten, zoals e-mailadressen en interne structuur. Bewaar het nooit lokaal of in Git, maar in een beveiligde remote backend zoals een Cloud Storage-bucket met versioning en encryptie. Beperk de toegang strikt en schakel state-locking in om gelijktijdige wijzigingen te voorkomen.
:::

## De workflow

Een gecontroleerde workflow zorgt dat elke wijziging gereviewd en gedocumenteerd is.

:::howto title="Van wijziging naar productie"
1. Een wijziging begint als een aanpassing in de HCL-bestanden.
2. Je opent een pull request zodat een collega het kan reviewen.
3. `terraform plan` toont exact welke wijzigingen worden doorgevoerd.
4. Na goedkeuring draait `terraform apply`, idealiter in een CI-pijplijn.
5. De state wordt bijgewerkt en de wijziging is gedocumenteerd in Git.
:::

## Veelgestelde vragen

:::faq
### Kan ik bestaande gebruikers importeren in Terraform?
Ja, met `terraform import` koppel je bestaande Workspace-resources aan je configuratie zonder ze opnieuw aan te maken. Voeg eerst het resource-blok toe en importeer daarna op basis van het ID.

### Wat gebeurt er als ik een resource uit de config verwijder?
Bij de volgende `apply` verwijdert Terraform die resource ook in Workspace. Wees hier voorzichtig mee, vooral bij gebruikers, want een verwijderde gebruiker betekent verlies van toegang en mogelijk data.

### Werkt dit voor alle Workspace-instellingen?
Nee. De provider dekt veelgebruikte resources zoals gebruikers, groepen, groepslidmaatschappen, OU's en domeinen, maar niet elke instelling. Controleer de provider-documentatie voordat je iets specifieks verwacht.

### Hoe voorkom ik per ongeluk verwijderen van gebruikers?
Gebruik lifecycle-regels zoals `prevent_destroy` op kritieke resources, en review elke plan-output zorgvuldig voor je `apply` draait.

### Is het verstandig om deze provider nu nog te gebruiken?
Het kan, maar met open ogen. De officiele provider is sinds 30 juni 2025 gearchiveerd en krijgt geen updates. Pin de versie vast, overweeg een onderhouden community-fork en controleer de actuele status voordat je dit in een productieomgeving inzet.

### Wat is een alternatief als ik geen verouderde provider wil?
Je kunt een onderhouden fork zoeken op de Terraform Registry, de Admin SDK rechtstreeks aanspreken via eigen scripts, of bepaalde processen via Workspace-tooling regelen. Welke past, hangt af van je risicobereidheid en hoeveel je declaratief wilt beheren.
:::

Met Terraform beheer je je Workspace-organisatie als code: reproduceerbaar, reviewbaar en met een complete historie in Git. Houd daarbij rekening met de gearchiveerde status van de provider en kies bewust hoe je dat risico opvangt.