# Add an environment

> Create an environment in Cloud Management Platform (CMP), or upload one exported from another instance

---

Site [llms.txt](/llms.txt)

---

An environment pairs a resource handler with the groups, parameters, OS builds, and networks available to anyone ordering into it. You need the **environment.manage** permission to create one.

## Create an environment

1. Go to **Admin** > **Environments**.
1. Select **Add**, then **Create New**.
1. Complete the dialog.
1. Select **Create**.

| Field | Description |
| --- | --- |
| **Name** | Required. Users see this name when they choose where to deploy, so name it based on what distinguishes it, such as its location, purpose, or the technology behind it. |
| **Description** | Optional. |
| **Resource Handler** | The handler CMP contacts for every server in this environment. The list shows only those you have access to. See [Resource handlers](/docs/cmp/configure/infrastructure/resource-handlers/). |
| **Tenant** | Appears only when you can choose a tenant. See [Multi-tenancy](/docs/cmp/configure/access-and-security/multi-tenancy/). |

CMP opens the new environment's detail page, where you can associate groups, parameters, OS builds, and networks.

<div class="alert alert-info" role="alert">


A new environment is placed in the **Unassigned** group and stays off the order form until you associate it with at least one other group. Do that on the environment's **Groups** tab. This behavior comes from **Restrict new Environments** in [Miscellaneous settings](/docs/cmp/configure/administration/system/miscellaneous-settings/), which is enabled by default; turn it off to make new environments available to every group.
</div>


## Upload an environment

Uploading recreates an environment exported from another CMP instance, along with its parameters, limits, OS builds, and rates. Only CMP administrators can upload an environment. See [Export and import environments](/docs/cmp/configure/infrastructure/environments/export-and-import/) for instructions on producing the file.

1. Go to **Admin** > **Environments**.
1. Select **Add**, then **Upload Environment**.
1. Select the zip file.
1. If secrets were encrypted during export, enter the password used at that time. Without it, those values do not survive the import.
1. To overwrite an environment of the same name rather than create a second one, select **Replace an existing environment if one is found with the same name**.
1. Select **Save**.

<div class="alert alert-danger" role="alert">


Replacing overwrites the existing environment, and the change cannot be undone.
</div>


Two things can interrupt the upload:

- If CMP cannot identify a resource handler from the file, it asks you to choose one.
- If the file lacks the expected metadata, usually because it was exported from an older release, CMP warns you and offers to upload it anyway.

If you reference environments by global ID via the API, select **Replace an existing environment if one is found with the same name**. If not selected and a matching name already exists, this results in two environments with different global IDs.

## Related

- [Export and import environments](/docs/cmp/configure/infrastructure/environments/export-and-import/): Produce the file this page uploads.
- [Groups, roles, and permissions](/docs/cmp/configure/access-and-security/groups-roles-permissions/): Associate an environment with groups.