Tenant Lifecycle: Rename and Delete

Safely rename and delete tenants (projects) in PCD, including how to handle orphaned volumes, networks, and role assignments before deletion.

Overview

Private Cloud Director supports renaming and deleting tenants (projects) at any time. Both operations carry risks if done without preparation:

• Renaming can create confusion if two tenants end up with similar names, and any tooling or scripts that reference tenants by name (rather than by ID) will break.
• Deleting a tenant while it still contains resources (volumes, networks, role assignments) leaves those resources in an orphaned state that can be difficult to clean up later.

To help prevent accidental orphaning, the PCD UI shows a confirmation dialog before deleting a tenant that lists the resource types and counts still associated with it. This is a safeguard, not a substitute for the audit and cleanup steps in this guide — review it carefully before confirming deletion.

This guide walks through both operations safely.

If your deployment uses Granular RBAC, see Granular RBAC Permissions Reference (Beta) for which roles can rename and delete tenants.

In this guide, you will rename a tenant without disruption and delete a tenant after verifying that all its resources have been cleaned up.

Rename a Tenant

Before You Rename

Tenant names in PCD are unique within a domain, not globally. Two tenants in different domains can share the same name. Before renaming:

• Check that no other tenant in the same domain already uses the target name. Duplicate names within a domain are not allowed and the rename will fail with a conflict error.
• Identify all scripts, CI/CD pipelines, and configuration files that reference the tenant by name. Update them to use the tenant ID instead, or plan to update them after the rename.
• Notify users who access this tenant that the name is changing, since the login experience and OS_PROJECT_NAME environment variable values will need to be updated.

Rename a Tenant Using the UI

1. Log in to PCD as an Admin with a domain-level or tenant-level Admin role.
2. Navigate to Settings > Tenants & Users > Tenants.
3. Select the tenant you want to rename.
4. Select Edit and update the Name field.
5. Select Save.

Rename a Tenant Using the CLI

pcdctl project set --name "<new-name>" "<current-name-or-id>"

After You Rename

• Update the OS_PROJECT_NAME environment variable in any pcdctl or API configurations that reference the old name.
• Verify that SAML group mappings that reference this tenant by name still resolve correctly. In PCD, SAML group mappings reference tenants by ID internally, so a rename does not break SSO role assignments, but double-check if your IdP-side configuration uses the display name.

---

Delete a Tenant

Deleting a tenant is irreversible. All resources owned by the tenant that are not cleaned up beforehand may become orphaned and difficult to recover.

Step 1: Audit Resources in the Tenant

Before deleting, confirm that all resources in the tenant have been removed or transferred.

Quick check before you start

The tenant-deletion confirmation dialog in the UI (see Step 3: Delete the Tenant) lists the resource types and counts still owned by the tenant. Use it as a quick check, but complete the audit below to identify and clean up the specific resources rather than relying on the dialog alone.

Virtual Machines

List all VMs in the tenant:

pcdctl server list --os-project-name <tenant-name>

Delete or migrate each VM before proceeding. As an alternative to deletion, an Admin can transfer a VM to another tenant instead; see Transfer a VM to Another Tenant.

Volumes

List all volumes in the tenant:

pcdctl volume list --os-project-name <tenant-name>

Volumes require separate cleanup

Deleting a tenant does not automatically delete the underlying volume data on the storage backend. Volumes must be explicitly deleted or detached and transferred before removing the tenant. For storage-backend-specific cleanup steps, refer to Tenant Teardown: Storage Cleanup.

Delete each volume:

pcdctl volume delete <volume-id>

If a volume is attached to a VM, detach it first:

pcdctl server remove volume <server-id> <volume-id>

Networks and Routers

List all networks in the tenant:

pcdctl network list --os-project-name <tenant-name>

Delete routers first (they must be detached from subnets before deletion), then subnets, then networks:

# Remove the router gateway and interfaces, then delete the router
pcdctl router unset --external-gateway <router-id>
pcdctl router remove subnet <router-id> <subnet-id>
pcdctl router delete <router-id>

# Delete subnets, then the network
pcdctl subnet delete <subnet-id>
pcdctl network delete <network-id>

Floating IPs

Release all floating IPs associated with the tenant:

pcdctl floating ip list --os-project-name <tenant-name>
pcdctl floating ip delete <floatingip-id>

Security Groups

The default security group is deleted automatically when the tenant is deleted. Custom security groups should be reviewed and deleted:

pcdctl security group list --os-project-name <tenant-name>
pcdctl security group delete <security-group-id>

Step 2: Remove Role Assignments

Role assignments are stored independently of the resources. Remove all role assignments from the tenant before deleting it to avoid leaving orphaned entries in the Identity Service.

List all role assignments in the tenant:

pcdctl role assignment list --project <tenant-name-or-id>

Remove each assignment:

pcdctl role remove --user <user-id> --role <role-name> \
  --os-project-name <tenant-name>

For SSO group-based role assignments, remove the tenant from each SAML group mapping:

1. Navigate to Settings > Enterprise SSO > SAML Groups.
2. Open each SAML group that has a role assignment in the tenant.
3. Remove the tenant from Tenants & Roles.
4. Select Save.

Step 3: Delete the Tenant

Once all resources and role assignments have been removed:

Using the UI

1. Navigate to Settings > Tenants & Users > Tenants.
2. Select the tenant.
3. Select Delete. A confirmation dialog lists the resource types and counts still associated with the tenant (for example, VMs, volumes, and networks), so you can confirm whether any resources still need to be cleaned up before proceeding.
4. Review the listed resources, then select Confirm to proceed with deletion.

The dialog is a warning, not a cleanup step

Confirming deletion does not clean up the listed resources — it deletes the tenant while those resources remain, and they become orphaned. Complete Step 1: Audit Resources in the Tenant first so you know exactly what to do with each resource before you confirm.

Using the CLI

pcdctl project delete <tenant-name-or-id>

Step 4: Verify Cleanup

After deletion, verify that no orphaned resources remain:

# Confirm no volumes remain associated with the deleted tenant
pcdctl volume list --all-projects | grep <former-tenant-id>

# Confirm no networks remain
pcdctl network list --all-projects | grep <former-tenant-id>

If orphaned resources are found, contact Platform9 Support for assistance with Identity Service-level cleanup.

Storage backend cleanup

The steps above remove the volume records from the PCD management plane. Storage backends (Ceph, NetApp, etc.) may retain the underlying data until it is freed at the storage level. Coordinate with your storage administrator after tenant deletion to ensure that backend resources are released according to your organization's policies.

---

Common Issues

"Tenant name already exists" on rename

Two tenants in the same domain cannot share a name. Check existing tenant names in the domain using:

pcdctl project list --domain <domain-name>

Choose a unique name and retry.

Tenant deletion fails because the tenant still contains resources

The API rejects deletion if the tenant still contains resources. Complete Step 1: Audit Resources in the Tenant before retrying.

Volumes persist after tenant deletion

Volume records in the management plane may linger if the deletion order was incorrect. Contact Platform9 Support, who can remove the stale records from the Identity Service database.

Next Steps

• For quota management in a tenant, see Tenant Quotas, User Quotas and VM Leases.
• For role assignment details, see RBAC Roles and Permissions.