Managing instances

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

An instance is a virtual machine where your API project and related services are stored. Instances correspond to regions. Typically, you start with a single instance and add new instances as your organization expands into more regions. This section explains how to use the Apigee UI to:

Create 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 Create a runtime instance.

Requirements for a new instance

Before you create a new instance, keep the following requirements in mind:

  • Each instance requires its own disk encryption key for the network. Apigee 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.

Edit an instance

To edit an instance:

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

  3. Select next to the instance that you want to delete and select Edit.

    This displays the Edit Instance pane.

    Select
  Edit.
  4. Delete an 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. Select 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:

      The
    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.

    Attach environments to an instance

    After you create a new environment, you must attach it to an instance for the environment to be accessible (in addition to adding the environment to an environment group). To attach an environment to an instance:

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

    3. Select next to the instance that you want to attach the environment to and select Edit. This displays the Edit Instance pane.

      Select
  Edit.
    4. Click in the Environments field and select the environment (or environments) you want to attach to the instance to.

      Select
  environments for the instance.
    5. Click OK.

    Besides using the UI, you can also attach environments to an instance using the Instances attachment create API. For an example, see Create an environment in the command-line provisioning documentation.