Managing the Apigee Emulator

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

Note: Use local development with Apigee X and Apigee hybrid 1.5 and higher.

Manage the Apigee Emulator as described in the following sections. See also Exploring the Apigee Emulator.

Installing the Apigee Emulator

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

To install the Apigee Emulator:

1. Expand the Apigee Emulators section in the left pane.

   

2. Position your cursor over the Apigee Emulator that you want to install.

3. Click .

   

   You are prompted to configure the Apigee Emulator container.

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

5. Enter a unique numeric value to use as the control port for the Apigee Emulator container and press Enter. The control port defaults to 8080.
   

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

6. Enter a unique numeric value to use as the traffic port for the Apigee Emulator container and press Enter.
   The traffic port defaults to 8998.
   

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

The latest image of the Apigee Emulator is installed. After the installation completes, the following message displays, Emulator installed successfully, 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 Apigee Emulators section in the left pane.

   

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

3. Click +. You are prompted to configure the container.

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

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

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

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 Apigee Emulators section.

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 of the response:

CONTAINER ID   IMAGE                                COMMAND       CREATED        STATUS        PORTS                                      NAMES
33756b8c5c5b   ...apigee-emulator:1.6.1   "/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 Apigee Emulator container that you want to start and click .

Using the Docker CLI

To start the Apigee Emulator, run docker start apigee-emulator in the Terminal tab.

The status 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 Apigee Emulators section and click .

Using the Docker CLI

To reset the Apigee Emulator, run docker reset apigee-emulator in the Terminal tab.

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

The following provides an example of the response: 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 Apigee Emulators section and click .

Using the Docker CLI

To update the Apigee Emulator, run the following Docker commands in the Terminal tab:

• Run docker ps to obtain the image name.
  For example: gcr.io/apigee-release/hybrid/apigee-emulator:1.6.1

• Run docker pull imagename to update the Apigee Emulator installation image.
  For example: docker pull gcr.io/apigee-release/hybrid/apigee-emulator:1.6.1

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 Apigee Emulators section and click .

Using the Docker CLI

To stop the Apigee Emulator, run docker stop apigee-emulatorin 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 Apigee 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 to stop the Apigee Emulator installation image (if it's not already stopped).
  For example: docker stop MyContainer

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

The container is deleted.

See also Customizing the Apigee runtime Docker container.

Refreshing the Apigee Emulator view

Refresh the Apigee Emulator view to synchronize any recent changes.

To refresh the Apigee Emulator view, position your cursor over the Apigee Emulators title bar and click .

Using a different version of the Apigee Emulator

Prerequisite: This feature is available as part of the Insiders build (as of v1.21.0). You must install the Insiders build, as described in Installing Insiders builds.

To use a different version of the Apigee Emulator, perform the following steps:

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. View a list of Apigee Emulator versions using one of the following methods and note the Tag value:

   • Use the Google Container Registry at: https://gcr.io/apigee-release/hybrid/apigee-emulator

     

   • Use Docker Hub at: https://registry.hub.docker.com/r/google/apigee-emulator/tags

     

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

4. Click Add item.

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

6. Click OK.

7. Install the new version of the Apigee Emulator which adds a container for deploying to the Apigee Emulator.

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, as required, and save the file.