> For the complete documentation index, see [llms.txt](https://docs.platform9.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.platform9.com/private-cloud-director/identity-and-multi-tenancy/tenant-lifecycle.md).

# Tenant Lifecycle: Rename and Delete

## Overview

<code class="expression">space.vars.product\_name</code> 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.

This guide walks through both operations safely.

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 <code class="expression">space.vars.product\_acronym</code> 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 <code class="expression">space.vars.product\_acronym</code> 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

```bash
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 <code class="expression">space.vars.product\_acronym</code>, 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.

#### Virtual Machines

List all VMs in the tenant:

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

Delete or migrate each VM before proceeding. VMs cannot be preserved across a tenant deletion.

#### Volumes

List all volumes in the tenant:

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

{% hint style="warning" %}
**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](/private-cloud-director/storage/troubleshooting-and-log-files/tenant-teardown-storage-cleanup.md).
{% endhint %}

Delete each volume:

```bash
pcdctl volume delete <volume-id>
```

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

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

#### Networks and Routers

List all networks in the tenant:

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

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

```bash
# 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:

```bash
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:

```bash
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:

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

Remove each assignment:

```bash
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** and confirm.

#### Using the CLI

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

### Step 4: Verify Cleanup

After deletion, verify that no orphaned resources remain:

```bash
# 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.

{% hint style="info" %}
**Storage backend cleanup**

The steps above remove the volume records from the <code class="expression">space.vars.product\_acronym</code> 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.
{% endhint %}

***

## 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:

```bash
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](#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](/private-cloud-director/identity-and-multi-tenancy/tenant-quotas-user-quotas-and-vm-leases.md).
* For role assignment details, see [RBAC Roles and Permissions](/private-cloud-director/identity-and-multi-tenancy/rbac-roles-and-permissions.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.platform9.com/private-cloud-director/identity-and-multi-tenancy/tenant-lifecycle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.