Configuring and deploying environments

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

An environment is a runtime execution context for the API proxies and shared flows that you want to deploy. You must deploy your API proxies and shared flows to one or more environments before they can be accessed for testing. For more information about environments, see About environments and environment groups.

Configure and deploy environments as described in the following sections. See also Managing folders and files in an Apigee workspace.

Configuring an environment

Before you deploy an environment, you must configure it to identify the API proxies and shared flows you want to deploy, and configure shared flow hooks or target servers, as required.

To configure an environment, create the environment and edit the configuration defined in the following table.

Configuration Description
Debug masks (debugmasks.json) Define mask configurations to mask specific data in trace and debug sessions.
Deployments (deployments.json) Define the API proxies and shared flows in your deployment.
Flow hooks (flowhooks.json) Attach shared flows to flow hooks so that they execute at the same place for all API proxies deployed to the environment.
Target servers (targetservers.json) Decouple your concrete endpoints from your target endpoints to support load balancing and failover across multiple backend server instances.

In addition, if you use any policies that require resources, you can manage resources at the environment level, as required.

Creating an environment

To create an environment:

  1. Perform one of the following actions:

    • Position your cursor over the environments folder in the Apigee Explore and click Create icon.

      + displays when you position the cursor over environments folder

    • Select View > Command Palette to open the Command palette and select Apigee: Create environment.

    The Create environment wizard opens.

  2. Enter a name for the environment and press Enter.

The environment is added to the environments folder in the Apigee Explorer, as shown in the following figure.

Environments folder with deployments.json, flowhooks.json, and targetservers.json files

Configure the environment, as described in the following sections.

Configuring debug masks (debugmask.json)

Apigee enables you to define mask configurations to mask specific data in trace and debug sessions. When data is masked, it is replaced with asterisks in the trace output. For example:

<description>**********</description>

For more information, see Masking sensitive data.

To configure debug masks, update the debugmask.json file by editing the file directly.

The following provides an example of the basic structure of a mask configuration in JSON format. For more information about the mask configuration fields shown in the example, see DebugMask.

{
  "namespaces": {
    "myco": "https://example.com"
  },
  "requestXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "responseXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "faultXPaths": [
    "/myco:Greeting/myco:User"
  ],
  "requestJSONPaths": [
    "$.store.book[].author"
  ],
  "responseJSONPaths": [
    "$.store.book[].author"
  ],
  "faultJSONPaths": [
    "$.store.book[*].author"
  ],
  "variables": [
    "request.header.user-agent",
    "request.formparam.password"
  ]
}

Configuring the deployments (deployments.json)

Configure the API proxies and shared flows that you want to include in the deployment.

To configure the deployments, update the deployments.json file using the configuration wizard (described below) or by editing the file directly.

To configure the deployments using the configuration wizard:

  1. Position your cursor over the deployments.json file for the environment and click Wizard icon.

    settings icon displays when you position the cursor over deployments.json folder

  2. Step through the configuration wizard to select the deployments and auto-populate fields in the deployments.json file.
    The deployments.json file is opened in the editor.

  3. Edit the configuration, as required.

  4. Select File > Save or ⌘S to save your edits.

The following example configures the deployment to include the helloworld API proxy and mysharedflow and hw-sharedflow shared flows:

{
  "proxies" : [
     "helloworld"
  ],
  "sharedflows" : [
     "mysharedflow",
     "hw-sharedflow"
  ]
}

Attaching shared flows using flow hooks (flowhooks.json)

With a flow hook, you attach a shared flow so that it executes at the same place for all API proxies deployed to a specific environment. This gives you a separately implemented and deployed sequence of logic that is not part of an API proxy's implementation code. Specifically, you can attach a shared flow at the following locations in the API proxy flow:

  • Before an API proxy endpoint executes (PreProxyFlowHook)
  • After the API proxy endpoint executes and right before the response is sent out to the client (PostProxyFlowHook)
  • Before a target endpoint executes (PreTargetFlowHook)
  • After the target response executes (PostTargetFlowHook)

For more information about flow hooks, see Attaching shared flows using flow hooks.

To attach shared flows using flow hooks, update the flowhooks.json file using the configuration wizard (described below) or by editing the file directly.

To configure the deployments using the configuration wizard:

  1. Position your cursor over the flowhooks.json file for the environment and click Wizard icon.
  2. Step through the configuration wizard to select the shared flows to attach at specific locations in the API proxy flow and auto-populate fields in the flowhooks.json file.
    The flowhooks.json file is opened in the editor.
  3. Edit the configuration, as required.
  4. Select File > Save or ⌘S to save your edits.

The following example attaches the mysharedflow to the PreProxyFlowHook so that it executes before an API proxy endpoint executes:

{
  "PreProxyFlowHook": {
    "continueOnError": true,
    "sharedFlow": "mysharedflow",
    "description": "Shared enforced before a proxy endpoint executes."
  }  
}

Configuring the target servers (targetservers.json)

Target servers (TargetServers) decouple concrete endpoint URLs from target endpoint (TargetEndpoint) configurations. Instead of defining a concrete URL in the configuration, you can configure one or more named TargetServers. Then, reference each TargetServer by name in a TargetEndpoint HTTPConnection.

For more information about target servers, refer to the following topics:

To configure target servers, update the targetservers.json file using the configuration wizard (described below) or by editing the file directly. For a description of the fields in the targetservers.json file, see Resource: TargetServer.

To configure the deployments using the configuration wizard:

  1. Position your cursor over the targetservers.json file for the environment and click Wizard icon.
  2. Step through the configuration wizard to configure the target server and auto-populate fields in the targetservers.json file. The targetservers.json file is opened in the editor.
  3. Edit the configuration, as required.
  4. Select File > Save or ⌘S to save your edits.

The following example attaches the mysharedflow to the PreProxyFlowHook so that it executes before an API proxy endpoint executes:

[
  {
    "isEnabled": true,
    "description": "My first target server",
    "name": "mytargetserver",
    "host": "localhost",
    "port": 80
  }
]

Deploying an environment

Deploy your API proxies and shared flows configured for an environment so they can be accessed for testing.

To deploy an environment:

  1. In the Apigee Explorer, position your cursor over the folder of the environment that you want to deploy.
  2. Click Deploy icon.

    Deploy icon displays when you position the cursor over dev environment folder

The environment is deployed and the following information is displayed in the Output tab:

Environment dev deployed successfully with revision 7

The deployed applications are displayed in the Apigee Emulator, as shown below.

Apigee Emulator showing deployed helloworld application and active test resources