What is Apigee Emulator

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Important: Open a workspace before setting up the emulator(s). See Manage the Apigee workspace.

Apigee Emulator lets you simulate an Apigee installation in your local development environment, for testing purposes. Apigee Emulator does not replace an Apigee installation for testing and does not have identical functionality, but simplifies testing from within the local development environment.

Apigee Emulator is available as a customized Docker image provided publicly to developers to deploy and test API proxies in a local development environment. Docker images are published regularly in gcr.

When you are ready to deploy and test your first API proxy, you will need to use the emulators section to view and manage your emulator versions and the lifecycle of the emulators that are set up.

Note: The images and examples in this guide are for reference purposes and might not show the latest Apigee Emulator version. Always use the latest stable Apigee Emulator version that meets your needs. See Choosing the emulator version for information.

This section lets you:

• View the different versions of the emulators that are installed, and the containers created for each emulator version, including its Docker and runtime information, and control and traffic ports.

• Add, delete, start, stop, reset, update, and refresh the view of the Apigee Emulator containers, as described in Managing the Apigee Emulator.

• View deployed applications (see Deploying environments).

• View active test resources (see Exporting test resources to the Apigee Emulator).

Managing the Apigee Emulator

Manage the Apigee Emulator as described in the following sections.

Note: Docker must be installed and running on your system in order for the Apigee Emulator to install and run.

Choosing the emulator version

By default, the emulator folder shows a version which is stable. However, you can choose a different version based on your requirements.

1. View a list of Apigee Emulator versions using one of the following methods and note the Tag value:

   • Use the Google Artifact Registry. (See the Documentation and User interface).

     

   • Use Docker Hub.

     

2. To add an Apigee Emulator version to the Cloud Code extension, click Manage > Settings and then search for apigee emulators.

3. Click Add item.

4. Enter the Tag value obtained in step 1. For example: 1.10.0 or google/apigee-emulator:1.10.0

5. Click OK.

6. The newly added emulator shows in the emulator folder.

Installing the Apigee Emulator

To install the Apigee Emulator:

1. Expand the emulators folder in your workspace.

2. Position your cursor over the Apigee Emulator version to install.

3. Click .

   

4. Add a container following the instructions in Adding a container for the Apigee

   Emulator.

The latest image of the selected Apigee Emulator version is installed. After the installation completes, the message Emulator installed successfully displays, and the Apigee Emulator container status changes to Ready.

Adding a container for the Apigee Emulator

To add a container for the Apigee Emulator using the UI:

1. Expand the emulators folder.

   

2. Position your cursor over the Apigee Emulator for which you want to add a container.

3. Click +.

4. Enter a unique name for the Apigee Emulator container and press Enter. Enter alphanumeric characters, dashes (-), or underscores (_).

5. Enter the numeric value to use as the control port for the Apigee Emulator container and press Enter. The control port must be unique across containers. It defaults to 8080.

   Important! The control port must be unique and not in use by any other component.

6. Enter the numeric value to use as the traffic port for the Apigee Emulator container and press Enter. The traffic port must be unique across containers. It defaults to 8998.

   Important! The traffic port must be unique and not in use by any other component.

The container is added.

Viewing status information for the Apigee Emulator

View status information for the Apigee Emulator as described in the following sections.

Using the UI

To view status information for the Apigee Emulator, including its Docker and Runtime information, expand the container in the emulators section. The information you see matches the Apigee Emulator version in use.

Using the Docker CLI

To view container status information for the Apigee Emulator and its configured ports, run docker ps in the Terminal tab. The following provides an example response. The actual response you see depends on the Apigee Emulator version in use:

CONTAINER ID   IMAGE                                COMMAND       CREATED        STATUS        PORTS                                      NAMES
33756b8c5c5b   ...apigee-emulator:1.11.0   "/usr/bin…"   10 hours ago   Up 10 hours   7000-7001/tcp, 0.0.0.0:8080->8080/tcp...   apigee-emulator

See also Customizing the Apigee runtime Docker container.

Starting the Apigee Emulator

Start the Apigee Emulator as described in the following sections.

Using the UI

To start the Apigee Emulator, position your cursor over the container that you want to start and click .

Using the Docker CLI

To start the Apigee Emulator, run docker start CONTAINER_NAME

in the Terminal tab.

The status is set to Ready:

See also Customizing the Apigee runtime Docker container.

Resetting the Apigee Emulator

Reset the Apigee Emulator to remove all deployments and exported test resources as described in the following sections.

Using the UI

To reset the Apigee Emulator, position your cursor over the Apigee Emulator container in the emulators section and click .

The Apigee Emulator is reset and the status is set to Ready:

The following information is displayed in the Output tab:

Resetting the Apigee Emulator
Reset completed

See also Customizing the Apigee runtime Docker container.

Restarting the Apigee Emulator

To restart the Apigee Emulator, run docker restart CONTAINER_NAME in the Terminal tab. For example: docker restart MyContainer

Updating the Apigee Emulator

If the Apigee Emulator is out of sync with the latest version, you can update your installed version using the UI or Docker CLI, as described in the following sections.

Using the UI

To update the Apigee Emulator, position your cursor over the Apigee Emulator in the emulators section and click .

Using the Docker CLI

To update the Apigee Emulator, run the following Docker commands in the Terminal tab, using the latest appropriate version:

• Run docker ps to obtain the image name. Example: gcr.io/apigee-release/hybrid/apigee-emulator:EMULATOR_VERSION

• Run docker pull IMAGE_NAME to update the Apigee Emulator installation image. Example: docker pull gcr.io/apigee-release/hybrid/apigee-emulator:EMULATOR_VERSION

The Apigee Emulator is updated and the following message is displayed: Emulator version is up to date

See also Customizing the Apigee runtime Docker container.

Stopping the Apigee Emulator

Stop the Apigee Emulator using the UI or Docker CLI as described in the following sections.

Using the UI

To stop the Apigee Emulator, position your cursor over the Apigee Emulator container in the emulators section and click .

Using the Docker CLI

To stop the Apigee Emulator, run docker stop CONTAINER_NAME in the Terminal tab.

The Apigee Emulator is stopped and the status is changed to Not running:

See also Customizing the Apigee runtime Docker container.

Deleting a container for the Apigee Emulator

Delete a container for the Apigee Emulator using the UI or Docker CL as described in the following sections.

Using the UI

To delete the Apigee Emulator, position your cursor over the Apigee Emulator container in the emulators section and click .

Using the Docker CLI

To delete a container for the Apigee Emulator, run the following Docker commands in the Terminal tab:

• Run docker stop CONTAINER_NAME to stop the Apigee Emulator installation image (if it's not already stopped). For example: docker stop MyContainer

• Run docker rm CONTAINER_NAME to stop the Apigee Emulator installation image. For example: docker rm MyContainer

The container is deleted.

See also Customizing the Apigee runtime Docker container.

Customizing the Apigee runtime Docker container

You can customize the Docker command line that is used to control the Apigee Emulator instances by using the following options.

Note: Customizing the Apigee runtime Docker container is not required; if not specified, the default option values are used. Any changes to the options are applicable only to the containers that are created after the options have been modified. If you want the options to be applied to existing containers, you need to recreate them.

Option	Description
additionalArguments	Add one or more arguments. The arguments are added to the docker run command exactly as provided. Defaults to "" (none).
detached	Controls whether the --detached option is used while running the container. Defaults to true.
dns	Controls the DNS service -dns flag, as described in DNS services. Defaults to 8.8.8.8.
environmentVariables	Add environment variables to the docker run command, as described in Options. The values, if provided, are added to the docker run command using -e name=value. Default list includes "XTERM": "xterm-256color".
labels	Add one or more labels to be attached with the container. The labels are added to the docker run command using -l label:value. Defaults to none.
privileged	Controls whether --privileged option is used while running the container. Defaults to true.
volumes	Add one or more volumes to be mounted on the container. The volumes are added to the docker run command using -v label:value. Defaults to none.

To customize the Apigee runtime Docker container:

1. This feature is available as part of the Insiders build (v1.21.0 and higher). Install the Insiders build, as described in Installing Insiders builds.

2. Click Manage > Settings and then search for apigee docker.

3. Under Cloudcode > Apigee: Docker Options, click Edit in settings.json. The customizable options are displayed in the settings.json file, as shown:

   "cloudcode.apigee.dockerOptions": {
     "environmentVariables": {
         "XTERM": "xterm-256-color"
     },
     "dns": "8.8.8.8",
     "detached": true
     "privileged": true,
     "labels": {},
     "volumes": {},
     "additionalArguments":""
   }

4. Edit the options and save the file.

Customizing the Apigee Emulator to support service account-based authentication

When testing the proxies that depend on Google Cloud service account-based authentication, Apigee Emulator needs access to the Google service account key. Follow the steps to configure your Apigee Emulator to support service account-based authentication.

Creating and downloading the service account key

Create a Google Cloud service account with the Service Account Token Creator role, which is a requirement for the Apigee Emulator to support service accounts. Create a key for the service account, as described in Create a service account key.

Download the key to the local file system, so that it can be provided to the Apigee emulator.

Note: Service account keys are a security risk if not managed correctly. You are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

If you acquired the service account key from an external source, you must validate it before use. For more information, see Security requirements for externally sourced credentials".

Configuring the Apigee Emulator

The settings defined in this section only apply to the Docker container instances that are created after the settings are saved.

To configure the Apigee Emulator settings:

1. Open the Docker options, as described in Customizing the Apigee runtime Docker

   container.

2. In the volumes section of the Docker options, add a new volume so that the downloaded service account key path is available in the container. Assuming the key was downloaded in the path /opt/apigee/keys/apigee-sa-key.json, the following setting mounts the contents of /opt/apigee/keys in the path /emulator/keys within the container:

   "volumes": {
     "/opt/apigee/keys":"/emulator/keys"
   }

3. In the environmentVariables section of the Docker options, add the GOOGLE_APPLICATION_CREDENTIALS variable that points to the file in the mounted path:

   "environmentVariables": {
     "GOOGLE_APPLICATION_CREDENTIALS":"/emulator/keys/apigee-sa-key.json"
   }

4. Save the settings and create a new container instance which can be used for testing.

The following example shows how to associate a Google service account key with the Apigee Emulator.

"cloudcode.apigee.dockerOptions": {
      "environmentVariables": {
          "XTERM": "xterm-256-color",
          "GOOGLE_APPLICATION_CREDENTIALS":"/emulator/keys/apigee-sa-key.json"
      },
      "dns": "8.8.8.8",
      "detached": true
      "privileged": true,
      "labels": {},
      "volumes": {
         "/opt/apigee/keys":"/emulator/keys"
      },
      "additionalArguments":""
    }

Configuring the Apigee Emulator to support HTTP forward proxy

The settings defined in this section only apply to emulator versions 1.11.0 and later.

Many times the backend targets associated with a proxy can only be reached using an HTTP forward proxy. The Apigee emulator can be configured to use the forward proxy while connecting to targets using an environment variable named FORWARD_PROXY.

The settings defined in this section only apply to the Docker container instances that are created after the settings are saved.

To configure the Apigee Emulator settings:

1. Open the Docker options, as described in Customizing the Apigee runtime Docker container.

2. In the environmentVariables section of the Docker options, add the FORWARD_PROXY variable that points to the forward proxy address as an HTTP URL

   "environmentVariables": {
     "FORWARD_PROXY":"http://proxy_host:proxy_port"
   }

3. Save the settings and create a new container instance for testing.