How kunalpandey1/usernaut works
1. Overall shape
Usernaut is a Kubernetes Operator-style service that continuously reconciles a custom Group resource into external identity/team systems. The core runtime is a single Go manager process, packaged as a container and deployed with Kustomize manifests.
2. Primary control plane boundary
The Kubernetes API is the main source of truth. The api/v1alpha1 package defines the Group CRD schema, and config/crd contains the generated CRD manifest. Cluster operators create/update Group objects; Usernaut watches them and drives reconciliation from there.
3. Controller layer
The main reconciliation logic lives in internal/controller/group_controller.go. This controller is responsible for reading group definitions, resolving membership, and syncing the desired state to downstream systems. A second controller, periodic_tasks_controller.go, exists to run scheduled maintenance work rather than direct CR reconciliation.
4. Membership resolution pipeline
Group membership is not limited to static users. The README and file layout show three member sources: direct users, nested groups, and LDAP-query-based membership. That means the controller must expand a group graph and also consult LDAP to resolve dynamic members before syncing.
5. Backend synchronization
The pkg/clients tree is the integration boundary to external SaaS platforms:
• ldap for directory lookups
• fivetran, gitlab, snowflake, and redhat_rover for target systems
Each backend has its own client package plus resource-specific operations like users, teams, and team membership. This is the main outbound data flow from the operator.
6. State and caching
Usernaut has a separate cache abstraction in pkg/cache with both in-memory and Redis implementations. Redis manifests live under config/redis, which implies cache-backed persistence is part of the deployed architecture, not just a library detail. The cache likely stores reconciliation state, lookup results, or derived membership data to reduce repeated API calls.
7. Store layer
The pkg/store package sits between controllers and cached/derived data. There are dedicated stores for groups, teams, users, and user-group relationships, indicating the operator normalizes CRD and backend data into internal domain models before acting on them. This helps keep reconciliation logic separate from raw client APIs.
8. Periodic offboarding
internal/controller/periodicjobs/job_usernaut_offboarding.go and related tests indicate a scheduled offboarding job. The README confirms this is a daily task that removes users no longer present in LDAP from the managed backends. This is a distinct flow from normal reconcile: it is time-driven and cross-cutting across all systems.
9. HTTP API surface
The internal/httpapi package provides a separate REST server for querying memberships programmatically. It has its own handlers, server wrapper, and middleware for basic auth and CORS. This API is an auxiliary read-facing interface, not the primary control mechanism.
10. Configuration and runtime wiring
pkg/config and appconfig provide environment/file-based configuration for backend credentials, feature flags, and deployment-specific settings. The presence of config/default, config/manifests, config/manual-rbac, and environment overlays (rhprod, rhplatformtest) shows the same binary is deployed into multiple Kubernetes environments with different RBAC and env patches.
11. RBAC and platform integration
The repo includes explicit RBAC manifests for the operator, leader election, metrics access, and service accounts. There are also separate manifests for manual RBAC and admin service accounts, suggesting some deployment modes require additional permissions outside the default operator role set.
12. Operational and packaging boundaries
The repo is built and validated with Go tooling, GitHub Actions, Docker, and Kubernetes manifests. Metrics are exposed via the manager/service manifests, and config/prometheus plus config/scorecard indicate standard operator observability and operator-framework validation support.
13. Testing boundaries
Unit tests cover clients, cache, stores, controller behavior, and the HTTP layer. End-to-end tests live under test/e2e, which suggests the project validates not just local logic but also the reconciliation path against Kubernetes resources and externalized behavior.
14. Diagram-friendly data flow
A useful architecture diagram should show: Kubernetes Group CRs in the center; the controller reading CRs and config; LDAP as a read dependency for user resolution; Redis/in-memory cache as an internal accelerator/state layer; outbound writes to Fivetran, GitLab, Snowflake, and Rover; a separate periodic offboarding path; and a read-only REST API alongside the operator for membership queries.
Main entry points: group_controller.go Group Controller · store.go Membership Store · job_usernaut_offboarding.go Offboarding Job · main.go Manager Binary
Components 21
Kubernetes Control Plane
CRDs, controller runtime, and deployment manifests that define the operator's main reconciliation path.
- Group CRD · Custom resource definition for managed groups.
api/v1alpha1/group_types.go - CRD Manifest · Cluster manifest that installs the Group custom resource.
config/crd/bases/operator.dataverse.redhat.com_groups.yaml - Group Controller · Main reconciliation loop for syncing Group resources to external systems.
internal/controller/group_controller.go - Periodic Controller · Controller that triggers scheduled maintenance work.
internal/controller/periodic_tasks_controller.go - Manager Binary · Single Go process that wires controllers, clients, cache, and API server.
cmd/main.go
External Integrations
Outbound systems the operator reads from or syncs into.
- LDAP Client · Reads directory data and dynamic membership queries.
pkg/clients/ldap/client.go - Fivetran Client · Syncs users, teams, and memberships to Fivetran.
pkg/clients/fivetran/client.go - GitLab Client · Syncs users, teams, and memberships to GitLab.
pkg/clients/gitlab/client.go - Snowflake Client · Syncs users, teams, and memberships to Snowflake.
pkg/clients/snowflake/client.go - Rover Client · Syncs users, teams, and memberships to Red Hat Rover.
pkg/clients/redhat_rover/client.go
Internal State
Caching, stores, and domain models used to normalize and accelerate reconciliation.
- Membership Store · Normalized store for groups, teams, users, and user-group relationships.
pkg/store/store.go - Group Store · Group-centric storage and lookup logic.
pkg/store/group_store.go - Team Store · Team-centric storage and lookup logic.
pkg/store/team_store.go - User Store · User-centric storage and lookup logic.
pkg/store/user_store.go - User-Group Store · Tracks membership relationships between users and groups.
pkg/store/user_groups_store.go - Cache Layer · Shared cache interface used to reduce repeated lookups and preserve derived state.
pkg/cache/cache.go - Redis Cache · Redis-backed cache implementation used in deployment.
pkg/cache/redis/cache.go - In-Memory Cache · Local in-process cache implementation.
pkg/cache/inmemory/cache.go
Auxiliary Interfaces
Read-facing API and scheduled jobs that complement the main reconcile loop.
- Offboarding Job · Scheduled flow that removes users no longer present in LDAP.
internal/controller/periodicjobs/job_usernaut_offboarding.go - HTTP API · Auxiliary REST surface for membership queries.
internal/httpapi/server/server.go
Packaging
Kustomize overlays and runtime configuration used to ship the same binary into different environments.
- Config Loader · Loads environment/file configuration for credentials, flags, and deployment settings.
pkg/config/config.go
Connections 26
- CRD Manifest → Group CRD: installs · Cluster manifest defines the Group resource.
- Manager Binary → Config Loader: loads · Entry point reads runtime configuration.
- Manager Binary → Group Controller: runs · Manager starts the primary reconciler.
- Manager Binary → Periodic Controller: runs · Manager starts scheduled maintenance controller.
- Manager Binary → HTTP API: serves · Manager also hosts the read-only API.
- Group Controller → Group CRD: watches · Controller reconciles Group custom resources.
- Group Controller → Membership Store: uses · Controller reads and writes normalized domain state.
- Membership Store → Group Store: contains · Group-specific store component.
- Membership Store → Team Store: contains · Team-specific store component.
- Membership Store → User Store: contains · User-specific store component.
- Membership Store → User-Group Store: contains · Relationship store for membership edges.
- Membership Store → Cache Layer: accelerates · Stores use cache for derived state and lookups.
- Cache Layer → In-Memory Cache: implements · In-memory backend.
- Cache Layer → Redis Cache: implements · Redis-backed backend.
- Group Controller → LDAP Client: resolves · Reads directory data for direct and query-based members.
- Group Controller → Fivetran Client: syncs · Writes desired membership state.
- Group Controller → GitLab Client: syncs · Writes desired membership state.
- Group Controller → Snowflake Client: syncs · Writes desired membership state.
- Group Controller → Rover Client: syncs · Writes desired membership state.
- Periodic Controller → Offboarding Job: triggers · Runs the daily offboarding workflow.
- Offboarding Job → LDAP Client: checks · Verifies current LDAP presence before removal.
- Offboarding Job → Fivetran Client: removes · Cleans up managed users where needed.
- Offboarding Job → GitLab Client: removes · Cleans up managed users where needed.
- Offboarding Job → Snowflake Client: removes · Cleans up managed users where needed.
- Offboarding Job → Rover Client: removes · Cleans up managed users where needed.
- HTTP API → Membership Store: queries · API reads normalized membership data.