Creating instances

You're viewing Apigee X documentation.
View Apigee Edge documentation.

You typically start with a single instance and add new instances as your org expands into more regions. For more information, see Using multiple regions. The information in this section applies to paid organizations only and not eval orgs. Eval orgs cannot expand beyond a single region and a single instance.

Creating a new instance

To create a new instance, you can use the Instances API or the Apigee UI. This section describes how to create a new instance using the UI. For an example of creating a new instance using the API, see Step 5: Create a runtime instance.


To create a new instance, you must meet the following criteria:

  • You must have a paid organization to add an instance. Eval accounts are limited to one region or instance and cannot be expanded to a second.
  • The number of regions you can add is limited by your entitlements, with a hard limit of 5 instances in your org. If you have fewer than that, you can add an instance (and region) if you purchase an org pack. For more information, see Apigee Pricing.

  • Each instance requires its own disk encryption key for the network. Google recommends that you also create a separate key ring for the new instance. For more information, see About the Apigee encryption keys.
  • Your peered network must have a CIDR block range available from /16 through /20. For more information, see Peering ranges.

Creating an instance in the Apigee UI

To create a new instance in the Apigee UI:

  1. Open the Apigee UI in your browser.
  2. Select Admin > Instances.

    The Instances pane displays:

    The Instances
    pane in the Apigee UI

  3. Click Create Instance. There might be a delay while the UI determines if your org has the proper entitlements to create a new instance.

    The New Instance dialog displays:

    The New
      Instance dialog box

  4. Enter details about your new instance in the fields:
    Field Required Description
    Runtime hosting region Required Select the region in which you want to create your new instance. You cannot create a new instance in a region that already has an instance. For more information about working with multiple regions, see Using multiple regions.
    Name Required

    Enter the ID of the new instance.

    The default value is the name of the runtime hosting region that you selected, but you can change it to any meaningful name that you want, as long as you follow the naming rules:

    • Minimum length of 2.
    • Maximum length of 32.
    • Only use lower case letters, numbers, and hyphens (following the pattern /^[a-z0-9\-]+$/).
    • Must start with a letter; doesn't have leading digits or hyphens.
    • Must end with a number or letter; doesn't have trailing hyphens.
    • Must be unique across your org.
    CIDR Block Range Required

    Select from the list of supported range sizes for your block of allocated IP addresses. Apigee supports blocks from /20 (minimum) to /16 (recommended for production and large enterprises).

    If your network does not have a range allocated, either allocate one using the VPC admin (if you are using Google Virtual Private Cloud network), or ask your network administrator to allocate one if you are using a shared network.

    You cannot create a new instance without a CIDR block being available.

    For more information about IP allocations, see Peering ranges.

    Disk encryption key ID Required Enter your disk encryption key's key path for the new instance. The key ring and key's region must match the region you selected for the Runtime hosting region. For more information, see About the Apigee encryption keys.
    Environments Optional

    Select environments you want attached to this instance. To do this, click the Environments drop-down list. The UI displays a list of environments in your org:

    A drop-down list of environments in the org

    To attach an environment, enable the checkbox next the environment. You can do this for as many environments as you want.

    Note that all instances' environments count towards the total number of environments that you can have allocated. For more information, see About environments and environment groups.

    Adding environments when you create a new instance is optional. If you do not add them now, you can insteads use the Instances attachment create API to add and remove them later.

    If your org cannot create a new instance, contact Apigee Sales.

  5. Click Create.

    Apigee begins a long-running operation that can take 20 minutes or more to complete. When it's done, the new instance will appear in the list of instances in the Instances UI.

Deleting an existing instance

You can use the Apigee UI to delete an existing instance, as described in this section. Alternatively, you can delete an instance using the Instances API.

Warning: When you delete an instance, all data associated with that instance is lost. This step cannot be undone.

To delete an existing instance in the Apigee UI:

  1. Open the Apigee UI in your browser.
  2. Select Admin > Instances.

  3. Hover over next to the instance that you want to delete and select Delete.

    Apigee prompts you to confirm that you really want to delete this instance:

    Delete instance dialog

  4. Click Delete.

    Apigee begins the process of deleting the instance. This process can take about 10 to 15 minutes to complete.

Attaching environments to instances

After you create a new environment, you must add it to an instance for it to be accessible (in addition to adding it to an environment group). You can do this when you create a new instance (if the environment already existed), or you can use the Instances attachment create API. For an example of using the API, see Create an environment in the command-line provisioning documentation.