{"id":50886053,"url":"https://github.com/hops-ops/tenant","last_synced_at":"2026-06-15T17:02:22.258Z","repository":{"id":359711939,"uuid":"1243874606","full_name":"hops-ops/tenant","owner":"hops-ops","description":"Tenant XRD: platform business-object kind composing Zitadel Org + default Project + default Roles + optional OpenPanel Org + Capsule Tenant in a per-Tenant namespace.","archived":false,"fork":false,"pushed_at":"2026-05-23T05:16:15.000Z","size":38,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T05:23:31.920Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go Template","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hops-ops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T18:47:13.000Z","updated_at":"2026-05-23T05:15:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hops-ops/tenant","commit_stats":null,"previous_names":["hops-ops/tenant"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/hops-ops/tenant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hops-ops%2Ftenant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hops-ops%2Ftenant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hops-ops%2Ftenant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hops-ops%2Ftenant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hops-ops","download_url":"https://codeload.github.com/hops-ops/tenant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hops-ops%2Ftenant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34372130,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-15T17:02:21.638Z","updated_at":"2026-06-15T17:02:22.252Z","avatar_url":"https://github.com/hops-ops.png","language":"Go Template","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tenant\n\n`Tenant` is the platform's business-object XRD. One `Tenant` per customer agreement / business relationship. Scaffolds the per-Tenant identity slice (Zitadel `Org` + default `Project` + default `Role`s), the analytics slice (OpenPanel `Organization` + default `Project`), and optional K8s isolation (Capsule `Tenant` CR) in a per-Tenant namespace.\n\nSits one layer above the stacks. [tenant-stack](https://github.com/hops-ops/tenant-stack) installs Capsule cluster-wide; [auth-stack](https://github.com/hops-ops/auth-stack) installs Zitadel; [analytics-stack](https://github.com/hops-ops/analytics-stack) installs OpenPanel. This `Tenant` XRD consumes those primitives (plus the Zitadel + OpenPanel provider MRs) to scaffold a real tenant in one apply.\n\nSee [[specs/tenant-xrd]] and [[specs/identity-architecture]] for the design.\n\n## Quick Start\n\nFull Tenant with identity + analytics + K8s isolation:\n\n```yaml\napiVersion: hops.ops.com.ai/v1alpha1\nkind: Tenant\nmetadata:\n  name: ops-com-ai\n  namespace: tenants\nspec:\n  clusterName: pat-local\n  type: business\n  display:\n    name: \"ops.com.ai\"\n    primaryDomain: ops.com.ai\n  identity:\n    zitadel: {}                        # defaults: orgName = metadata.name; tenant-admin + tenant-member roles\n  analytics:\n    openpanel:\n      enabled: true                    # composes OpenPanel Org + default Project\n  capsule:\n    enabled: true\n    userGroups: [tenant-admin]\n```\n\n## What gets composed\n\n| Resource | Provider | When |\n|---|---|---|\n| `Namespace` (per-Tenant) | provider-kubernetes Object | always |\n| Zitadel `Org` | provider-upjet-zitadel | always |\n| Zitadel default `Project` | provider-upjet-zitadel | unless `identity.zitadel.defaultProject.skip: true` |\n| Zitadel default `Role`s | provider-upjet-zitadel | one per `identity.zitadel.defaultProject.roles[]`; defaults to `tenant-admin` + `tenant-member` |\n| OpenPanel `Organization` | provider-openpanel | when `analytics.openpanel.enabled: true` |\n| OpenPanel default `Project` | provider-openpanel | when `analytics.openpanel.enabled: true` and `analytics.openpanel.defaultProject.skip: false` |\n| Capsule `Tenant` CR | provider-kubernetes Object | when `capsule.enabled: true` |\n\nMulti-iteration convergence (per [[feedback_crossplane_composition_gates]]):\n1. **Iter 1**: Namespace + Zitadel Org + OpenPanel Org + (optional) Capsule Tenant\n2. **Iter 2**: once Zitadel Org observed → Zitadel default Project + Roles emit; once OpenPanel Org observed → OpenPanel default Project emits\n\nZitadel `Role` MRs use `projectIdRef` to cross-resource reference the composed Project — Crossplane resolves the Zitadel projectId at reconcile time. OpenPanel Project's `organizationId` is a plain string with no `*Ref` field on the provider's MR, so we gate emission on observed Org id.\n\n## Adoption (existing external resources)\n\nTo take over an existing Zitadel or OpenPanel Org, set its id in the spec — the composition propagates it as the composed MR's `crossplane.io/external-name` annotation. Pair with `managementPolicies` excluding `Create`:\n\n```yaml\nspec:\n  identity:\n    zitadel:\n      orgId: \"373268222482392664\"      # existing Zitadel Org UUID\n      defaultProject:\n        skip: true                      # existing Org has its own Projects; manage via raw MRs\n  analytics:\n    openpanel:\n      enabled: true\n      orgId: \"\u003cexisting-openpanel-org-uuid\u003e\"\n  managementPolicies: [\"Observe\", \"Update\", \"LateInitialize\"]\n```\n\n**Alternative**: apply the XR without `orgId`, then `kubectl annotate org \u003cname\u003e-org crossplane.io/external-name=\u003cid\u003e` afterward. Same end state. The spec-field path is more declarative; the kubectl-annotate path matches the \"create then adopt\" flow some operators prefer.\n\n**OpenPanel adoption notes**: per [[reference_openpanel_organization_upsert_semantics]], OpenPanel's TF provider Create is find-or-create — adoption via `crossplane.io/external-name` is the safe path. Always set `analytics.openpanel.orgId` when adopting (or `kubectl annotate` immediately after apply).\n\n## What's NOT composed\n\n- **Additional Zitadel Projects/Roles beyond the default Project**: operators apply raw `Project` / `Role` MRs (`project.zitadel.m.crossplane.io`) in the per-Tenant namespace.\n- **Additional OpenPanel Projects/Clients**: operators apply raw OpenPanel MRs.\n- **HumanUsers, MachineUsers, Grants, IDPs, OrganizationSsoConfig**: separate XRDs in the auth-stack repo (still TO WRITE). When they land, they're applied as standalone XRs in the per-Tenant namespace.\n- **Foundation refs**: `accounts.*.foundationRef` is echoed in status but NOT composed. Foundation XR lifecycle is owned by `aws-foundation` (and equivalents).\n\n## ProviderConfig conventions\n\nDefaults derive from `spec.clusterName`:\n\n- `providerConfigRefs.kubernetes` → `\u003cclusterName\u003e` (e.g., `pat-local`)\n- `providerConfigRefs.zitadel` → `\u003cclusterName\u003e-zitadel` (e.g., `pat-local-zitadel`)\n- `providerConfigRefs.openpanel` → `\u003cclusterName\u003e-openpanel` (e.g., `pat-local-openpanel`)\n\nOverride explicitly when the convention doesn't fit (e.g., bring-your-own Zitadel/OpenPanel pointing at a tenant-owned instance).\n\n**Namespace constraint**: per [[reference_v2_providerconfig_same_namespace_lookup]], Crossplane v2 namespaced MRs only resolve ProviderConfigs in their own namespace. The composed MRs land in the XR's namespace, so the relevant PCs need to be there (or via a cluster-scoped variant). Resolution path is an operational choice.\n\n## Examples\n\n- `examples/tenants/standard.yaml` — full Tenant with identity + analytics + capsule + Foundation echo\n- `examples/tenants/adopt.yaml` — adopts the existing pat-local `tenant-platform` Zitadel Org\n- `examples/tenants/minimal.yaml` — Zitadel-only personal-brand Tenant (`pat-brand`); no analytics, no capsule\n\n## References\n\n- Spec: `[[specs/tenant-xrd]]`\n- Umbrella: `[[specs/identity-architecture]]`\n- Sibling stacks: `[[specs/tenant-stack]]`, `[[specs/auth-stack-zitadel]]`, `[[specs/analytics-stack-openpanel]]`\n- Memories: `feedback_crossplane_composition_gates`, `reference_openpanel_organization_upsert_semantics`, `reference_v2_providerconfig_same_namespace_lookup`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhops-ops%2Ftenant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhops-ops%2Ftenant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhops-ops%2Ftenant/lists"}