Google Workspace module

Setup

Configure credentials via environment variables. We recommend sourcing them through 1Password or your secrets manager rather than committing them to the shell rc.

Official API reference

weave commands for this module are checked against the vendor's published API.

Admin SDK Directory API

Variable	Description	Status
GOOGLE_WORKSPACE_TOKEN	Required for authentication.	required
GOOGLE_WORKSPACE_CLIENT_EMAIL	Required for authentication.	required
GOOGLE_WORKSPACE_PRIVATE_KEY	Required for authentication.	required
GOOGLE_WORKSPACE_ADMIN_EMAIL	Required for authentication.	required
GOOGLE_WORKSPACE_CUSTOMER_ID	Customer ID for domain-wide delegation (when not inferable from token).	optional
GOOGLE_WORKSPACE_ADMIN_EMAIL	Admin user to impersonate for domain-wide delegation.	optional

Sanity-check the wiring:

weave secrets check
weave googleworkspace --help
weave doctor   # reports GOOGLE_WORKSPACE_TOKEN status

Capabilities

What this module can do, by entity and verb. ✓ means a working CLI surface; · means not (yet) wired.

Entity	find	list	show	do	snapshot	diff	apply
admin-roles	·	·	·	·	✓	·	·
chrome-devices	·	·	·	·	✓	·	·
domains	·	·	·	·	✓	·	·
group	·	✓	·	·	✓	✓	✓
mobile-devices	·	·	·	·	✓	·	·
org-units	·	·	·	·	✓	·	·
ou	·	✓	·	·	·	·	·
user	✓	✓	·	✓	✓	·	·

Commands

Every registered CLI command, grouped by verb. Each example uses placeholder arguments — substitute real values for your environment.

find (1)

find user

read

Find a user by email or id.

weave googleworkspace find user <identifier>

list (3)

list groups

read

List groups for a customer or domain.

weave googleworkspace list groups <arg>

list ous

read

List org units for a customer.

weave googleworkspace list ous <arg>

list users

read

List Workspace users.

weave googleworkspace list users <arg>

do (3)

do sign-out

write

Invalidate all OAuth tokens (force re-auth everywhere).

weave googleworkspace do sign-out <email>

do suspend

write

Suspend a user.

weave googleworkspace do suspend <email>

do unsuspend

write

Unsuspend a previously suspended user.

weave googleworkspace do unsuspend <email>

snapshot / diff / apply are generated automatically from the State Kinds declared on this module — see the State kinds section below for per-kind details. Workflow: snapshot → edit YAML → diff → apply --yes (or confirm interactively; apply --dry-run previews the same diff).

State kinds

Resources this module can snapshot and diff; apply where the kind supports live writes (see Round-trip per kind). Always run diff before apply; use --yes in automation after review. Files live under .weave-state/googleworkspace/.

This module is on the thinner integration path — use snapshot / diff for audit; confirm apply per kind below before relying on writes.

groups

snapshot diff apply

All Workspace groups with their member emails (keyed by primary email).

Scope: —
Round-trip: Full round-trip — snapshot, diff, apply.

State file skeleton

module: googleworkspace
kind: groups
items:
  - # <fields specific to this kind — see snapshot output>

users

snapshot diff apply

All Workspace users (snapshot-only; lifecycle is upstream).

Scope: —
Round-trip: Snapshot only.

State file skeleton

module: googleworkspace
kind: users
items:
  - # <fields specific to this kind — see snapshot output>

org-units

snapshot diff apply

OU tree (snapshot-only).

Scope: —
Round-trip: Snapshot only.

State file skeleton

module: googleworkspace
kind: org-units
items:
  - # <fields specific to this kind — see snapshot output>

admin-roles

snapshot diff apply

Admin role assignments — who has Super Admin, Groups Admin, etc.

Scope: —
Round-trip: Snapshot only.

State file skeleton

module: googleworkspace
kind: admin-roles
items:
  - # <fields specific to this kind — see snapshot output>

domains

snapshot diff apply

Verified domains for the customer (snapshot-only).

Scope: —
Round-trip: Snapshot only.

State file skeleton

module: googleworkspace
kind: domains
items:
  - # <fields specific to this kind — see snapshot output>

chrome-devices

snapshot diff apply

Chrome OS managed devices (snapshot-only).

Scope: —
Round-trip: Snapshot only.

State file skeleton

module: googleworkspace
kind: chrome-devices
items:
  - # <fields specific to this kind — see snapshot output>

mobile-devices

snapshot diff apply

Workspace-managed mobile devices (snapshot-only).

Scope: —
Round-trip: Snapshot only.

State file skeleton

module: googleworkspace
kind: mobile-devices
items:
  - # <fields specific to this kind — see snapshot output>

Workflows

End-to-end recipes from operators who already run this module in production. Copy, adapt, and put under change-control.

Git-review Google Group membership

weave googleworkspace snapshot groups
$EDITOR .weave-state/googleworkspace/groups.yaml
weave googleworkspace diff groups
weave googleworkspace apply groups --yes

Offboard a user (suspend + sign-out)

weave googleworkspace find user jane@company.com
weave googleworkspace do suspend jane@company.com --yes
weave googleworkspace do sign-out jane@company.com --yes

Re-enable after leave

weave googleworkspace do unsuspend jane@company.com --yes

OU inventory before reorg

weave googleworkspace list users
weave googleworkspace list groups
weave googleworkspace list ous

Terraform parity

For each Terraform resource in the canonical provider, here's the equivalent live-API verb in weave. Use this as a migration cheat-sheet, not a 1:1 contract — weave deliberately stays in the live-state lane, not the desired-state lane.

Terraform resource	weave equivalent
googleworkspace_group / google_group	weave googleworkspace snapshot/diff/apply groups + list groups Use the HashiCorp googleworkspace provider for OU structure; weave covers live membership.
googleworkspace_user	weave googleworkspace find/list user + do suspend/unsuspend/sign-out User create/delete not exposed — lifecycle verbs focus on suspend and session revoke.
googleworkspace_org_unit	weave googleworkspace list ous OU moves are read-only today.

Troubleshooting & source

Missing credentials

Run weave doctor — it reports which env vars (including GOOGLE_WORKSPACE_TOKEN) are set and which are blank.

Unexpected behaviour from a state apply

Re-run weave googleworkspace diff <kind> to confirm the controller's current state, then re-snapshot before the next apply. The driver always re-snapshots before diffing.

Open the source

The module lives at https://github.com/andy-broyles/weavewhatever/tree/main/src/weave/modules/googleworkspace. File a bug or feature request at https://github.com/andy-broyles/weavewhatever/issues.