Managing instances

This page applies to Apigee, but not to Apigee hybrid.

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:

Create a new instance

To create a new instance, you can use the Instances 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, see About the Apigee encryption keys.
  • its own non-overlapping /22 and /28 CIDR ranges for network peering. The ranges cannot be shared between instances.

Apigee in Cloud console

To create a new instance in Apigee in Cloud console:

  1. Open the Apigee UI in Cloud console in your browser.

  2. Select Management > Instances. The Instances pane displays a list of existing instances.

  3. Click + Create. 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.

  4. 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, see Using 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:

    • 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

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

    Select the environments you want attached to this instance. To do this, click the Environments 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 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 projectsOptionalClick 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.
    Enable loggingOptionalClick the Enable 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, see Logging Apigee access logs

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

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

    To create a custom filter, select Custom 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, 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.

Apigee API

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

If Apigee was provisioned with VPC-peering, see Create 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, see Environments and instances.

To attach or remove an environment from an instance using Apigee in Cloud console:

  1. Open the Apigee UI in Cloud console in your browser.
  2. Select Management > Instances.

  3. Click the instance that you want to edit.

  4. In the Instance details page, click Edit.
  5. In the Edit Instance page, click the Environments (optional) field and select the environment you want to attach to the instance, or deselect the environment you want to remove.
  6. Click OK.
  7. Click Save to save your changes.

In addition to 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 Cloud console in your browser.
  2. Select Management > Instances.

  3. Click the instance that you want to edit.

  4. In the Instance details page, click Edit.
  5. In the Accepted projects section of the Edit Instance page, 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.

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. Open the Apigee UI in Cloud console in your browser.
  2. Select Management > Instances.

  3. Click the instance that you want to edit.

  4. In the Instance details page, click Edit.
  5. the Edit Instance page, click the Enable logging toggle to disable the feature.
  6. Click Save to save your changes.

Delete an instance

You can use the Apigee UI in Cloud console 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 in a given 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 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 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.
QuotaQuota definitions, buckets, and counters.
Environment cacheAll cached data.

To delete an Apigee instance using the Apigee UI in Cloud console:

  1. Open the Apigee UI in Cloud console in your browser.

  2. Select Management > Instances.

  3. Click the instance that you want to delete.
  4. In the Instance Details page, click Delete.