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

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.

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 a list of existing instances.

  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 Create new instance page displays:

    The New
      Instance dialog box

  4. Enter details about your new instance in the fields:
    Field Required Description
    Runtime hosting location 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.
    IP range allocation Required

    Specify how you want to allocate an IP range. Choose between these options:

    • Automatic (Recommended) - Apigee selects an available CIDR range with a prefix size of /22. No further action on your part is required.
    • Custom - In advanced use cases, you may need to specify exactly which IP range you want Apigee to use. For these cases, you specify a custom IP range, and it must have a prefix size of /22. The range must be available as part of a private connection between your project and Apigee.
    Disk encryption key Required

    Under Disk encryption key, choose a customer-managed encryption key. If a key already exists, you can pick it. The wizard lists all keys in the same location as the runtime hosting region across all key rings. If a key doesn't exist, or if you don't want to use an existing key, you can create a new key from within the wizard. To create a key:

    1. Click CREATE KEY.
    2. Select a key ring, or if one doesn't exist, enable Create key ring and enter a key ring name and pick a key ring location. Key ring names can contain letters, numbers, underscores (_), and hyphens (-). Key rings can't be renamed or deleted.
    3. Click CONTINUE.
    4. Create a key. Enter a name and protection level. Note that key names can contain letters, numbers, underscores (_), and hyphens (-). Keys can't be renamed or deleted. For protection level, Software is a good choice. This is the same default used by Cloud KMS; however, you can change it if you wish.
    5. Click CONTINUE and review your selections.
    6. Click CREATE.
    7. Click GRANT to grant the service account permission to encrypt/decrypt with the selected key.
    Environments Optional

    Select the environments you want attached to this instance. To do this, click the Environments drop-down list and select the checkboxes next the environments you want to attach. You can do this for as many environments as you want. Then click OK.

    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 instead use the Instances attachment create API or the UI to add and remove them later. See Attach or remove an environment.

    Accepted projects Optional Click ADD ACCEPTED PROJECT to select one or more Cloud projects. The selected projects can privately connect to the service attachment for your instance. By default, the project associated with your Apigee organization is included in this list.

    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.

Attach or remove an environment

To attach an environment to the instance or remove an environment from the instance:

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

  3. Click the instance that you want to edit.

  4. Click EDIT.
  5. In the Environments menu, select the environment that you want to attach to the instance. If you want to detach any environments that are already attached, deselect them from the list.

    Select
  Edit.

  6. Click SAVE to save your changes.

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.

Edit the Accepted projects list

You can add or remove projects from the Accepted Projects list.

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

  3. Click the instance that you want to edit.

  4. Click EDIT.
  5. In the Accepted projects section, click the delete icon next to a project to remove it. To add a project click ADD ACCEPTED PROJECT and enter the ID of the project to add.
  6. Click SAVE to save your changes.

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.

Only one Apigee instance can be located in a Google Cloud region. When you delete an instance, it is completely removed from its region. See also multi-region installation.

Warning: When you delete an instance, all data associated with that instance is lost. This step cannot be undone. Note, however, that if you have multiple instances, such as in a multi-region installation, your data will be lost only if you delete all of the instances. Before deleting the last instance, be sure to extract and back up any data you do not wish to lose.

The following data is stored in an Apigee instance and will be deleted if you delete the instance:

Type of data Description
Key management system (KMS) KMS data includes API products, developers, developer apps, OAuth tokens (including access tokens, refresh tokens, and authorization codes), and API keys. Use the AccessEntity policy or the related Apigee API to retrieve the data you wish to save.
Key value map (KVM) Any data that can be created or managed with KVM policies. See Retrieving KVMs.
Quota Quota definitions, buckets, and counters.
Environment cache All cached data.

To delete an instance:

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

  3. Click the instance that you want to delete.

  4. Click DELETE.
  5. Apigee prompts you to confirm that you really want to delete this instance.

  6. Type the name of the instance in the Instance Name field and click Delete.

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