Managing instances

This page applies toApigee, but not toApigee hybrid.

View Apigee Edge documentation.

Aninstance is a virtualmachine 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 expandsinto more regions. This section explains how to:

Note: Evaluation organizations can only have one instance (region).To expand beyond a single region and instance, you must have apaid organization. Your subscription entitlements limit the number of instances (regions) you can add. You can add more instances (regions) by purchasing an Org Pack. For more information, see Subscription entitlements.

Create a new instance

To create a new instance, you can use theInstances API or the Apigee UI. 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, seeAbout the Apigee encryption keys.
  • its own non-overlapping /22 and /28 CIDR ranges for network peering. The ranges cannot be shared between instances.
Note: You must have a paid organization to add an instance. Evaluation accounts are limited to one region or instance and cannot be expanded to a second. Your entitlements limit the number of regions you can add. For more information, seeApigee Pricing.

Apigee UI

Important: This topic only applies to organizations that were created with VPC peering enabled. See alsoApigee networking options.

To create a new instance in Apigee UI:

  1. In the Google Cloud console, go to theManagement> Instances page.

    Go to Instances

    TheInstances pane displays a list of existing instances.

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

    TheCreate new instance page displays.

  3. Enter details about your new instance in the fields:
    FieldRequiredDescription
    Runtime hosting locationRequiredSelect 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, seeUsing multiple regions.
    NameRequired

    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 allocationRequired

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

    Note:Once created, you cannot change the IP range later. If you ever need to change the range, you will have to create a new instance.
    • 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 keyRequired

    UnderDisk 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. ClickCreate key.
    2. Select a key ring, or if one doesn't exist, enableCreate 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. ClickContinue.
    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. ClickContinue and review your selections.
    6. ClickCreate.
    7. ClickGrant to grant the service account permission to encrypt/decrypt with the selected key.
    EnvironmentsOptional

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

    Note that all instances' environments count towards the total number of environments that you can have allocated. For more information, seeAbout 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 theInstances attachment create API or the UI to add and remove them later. SeeAttach or remove an environment.

    Accepted projectsOptionalClickAdd 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.
    Enable loggingOptionalClick theEnable logging toggle to enable Cloud Logging ingress access logs for the instance. This feature allows you to view the logs generated by ingress gateways in your Apigee infrastructure, such as an external Application Load Balancer or an Anthos gateway, to assist in troubleshooting Apigee API calls.

    For more information, seeLogging Apigee access logs

    FilterOptionalSelect an HTTP response code from theresponse code box to act as a filter for the ingress access logs.

    If you want to include all logs, regardless of HTTP response code, selectNone (all HTTP responses).

    To create a custom filter, selectCustom and enter the filter in the following format:

    status_code > XX && status code<= YY

    For example:

    status_code >= 500 && status_code< 504

    If your org cannot create a new instance, contactApigee Sales.

  4. ClickCreate.

    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 theInstances UI.

Apigee API

If Apigee was provisioned without VPC-peering, seeCreate a runtime instance in the non-VPC peering provisioning steps.

If Apigee was provisioned with VPC-peering, seeCreate a runtime instance in the VPC peering provisioning steps.

Attach or remove environments from an instance

When you create an environment using the Apigee UI in Google Cloud console, you have the option to assign the environment to an existing instance. For more information, see Creating a new environment in the UI.

If you did not attach your environment to an instance during environment creation, or you want to remove an environment from an instance, you can follow these steps. For more information on environments and instances, seeEnvironments and instances.

To attach or remove an environment from an instance using the Apigee UI:

  1. In the Google Cloud console, go to theManagement> Instances page.

    Go to Instances

  2. Click the instance that you want to edit.

  3. In theInstance details page, clickEdit.
  4. In theEdit Instance page, click theEnvironments (optional) field and select the environment you want to attach to the instance, or deselect the environment you want to remove.
  5. ClickOK.
  6. ClickSave to save your changes.

In addition to using the UI, you can also attach environments to an instance using theInstances attachment create API. For an example, seeCreatean environment in the command-line provisioning documentation.

Edit the accepted projects list

You can add or remove projects from theAccepted projects list:

  1. In the Google Cloud console, go to theManagement> Instances page.

    Go to Instances

  2. Click the instance that you want to edit.

  3. In theInstance details page, clickEdit.
  4. In theAccepted projects section of theEdit Instance page, clickDelete next to a project to remove it.To add a project clickAdd accepted project and enter the ID of the project to add.
  5. ClickSave to save your changes.

Enable or disable ingress access logs for an instance

After you create an instance, you can enable and disable Cloud Logging ingress access logs for the instance:

  1. In the Google Cloud console, go to theManagement> Instances page.

    Go to Instances

  2. Click the instance that you want to edit.

  3. In theInstance details page, clickEdit.
  4. theEdit Instance page, click theEnable logging toggle to disable the feature.
  5. ClickSave 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 theInstances API.

Only one Apigee instance can be in a given Google Cloud region. When you delete an instance, it is completely removed from its region. See alsomulti-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 havemultiple instances, such as in a multi-region installation, your data will be lost onlyif you delete all of the instances. Before deleting the last instance, be sure to extractand back up any data you do not wish to lose.Note: Deleting an instance removes the association for any attached environments. You may need to move any attached environments to new instances byAttaching and removing environments from an instance before deleting the instance. All environments must be attached to at least one instance for their proxies to function.

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

Type of dataDescription
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 theAccessEntity policy or the relatedApigee API to retrieve the data you wish to save.
Key value map (KVM)Any data that can be created or managed with KVM policies. SeeRetrieving KVMs.
QuotaQuota definitions, buckets, and counters.
Environment cacheAll cached data.

To delete an Apigee instance using the Apigee UI:

  1. In the Google Cloud console, go to theManagement> Instances page.

    Go to Instances

  2. Click the instance that you want to delete.
  3. In theInstance Details page, clickDelete.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.