Deploying an API proxy

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Note: To deploy API proxies in environments enabled for archive deployments, see Deploying and managing archives in an Apigee environment.

You cannot invoke an API proxy until it has been deployed. After you create a new API proxy or make a change to an existing one, you can deploy it to your cluster.

When you create a new revision of an API proxy without changing its base path, then deploy it to an environment in which it's already deployed, the previous revision is undeployed and the new revision is deployed in its place.

Note: You cannot make incremental changes to an API proxy revision and redeploy that same revision to Apigee. To deploy changes to an API proxy, you must save it as a new revision and deploy it.

Deploy an API proxy

Deploy an API proxy revision as described for one of the following methods.

Note: Apigee is introducing a new version of the Proxy Editor, which will make it easier to manage proxies.

The instructions in the first two tabs below explain how to use either the new Proxy Editor or the classic Proxy Editor.

Apigee UI in Cloud console

To deploy an API proxy:

1. Open the Apigee UI in Cloud console
2. Select Proxy development > API proxies.

3. Click the API proxy that you want to deploy. The UI displays the Overview page:

   

4. To deploy your changes, first click Deploy to display the Deploy dialog:

   

5. Enter the following:
   • Revision: The revision number of the proxy you want to deploy.
   • Environment: The environment where you want to deploy the proxy.
   • Service account (optional): A service account for the proxy.
6. Click Deploy.

The UI begins the process of deploying the selected revision.

Note: It may take a few minutes for Apigee to deploy the new proxy.

When the proxy is deployed, the Status column in the Deployments section displays a green icon to show that revision 1 of the proxy is deployed.

Classic Proxy Editor

To deploy an API proxy in the Apigee UI:

1. Sign in to the Apigee UI.
2. Select Develop > API Proxies.

   The UI displays a list of API proxies and their deployment status:

   

3. From the Environment drop-down list, select the environment to which you want to deploy the API proxy.

4. Click the API proxy that you want to deploy.

   The UI displays the API Proxies Overview tab. This view includes the Deployments, Proxy Endpoints, and Target Endpoints sections:

   

   If this is a new API proxy that you have not deployed before (or an API proxy that you have undeployed), the Revision column shows Not deployed.

5. In the Revision column, expand the drop-down selector.

   If this is a new API proxy that has never been deployed before, the drop-down list displays only 1 and Undeploy:

   

   For API proxies with multiple revisions, the drop-down list displays all revisions that you can choose from as well as Undeploy.

   

6. Select the revision that you want to deploy from the drop-down list.

   The UI prompts you to confirm the deployment:

   

7. Click Deploy.

   The UI begins the process of deploying the selected revision.

   Note: It may take a few minutes for Apigee to deploy the new proxy.

   Position the cursor over the Details link in the Status column to view the status of the deployment. If there are one or more revisions already deployed, you can monitor the status of their undeployment, as shown in the following figure. For more information, see Zero-downtime deployment.

   

   When deployment is complete, the Status details indicates that the revision is fully deployed:

   

   Note that deployment is not an instantaneous process. Apigee's eventually consistent deployment model means that a new deployment will be rolled out to the cluster over a short period of time and not immediately. For more information, see About deployment.

   For information on what the status indicators mean and how to check the status, see see Viewing deployment status.

   

Alternatively, you can deploy the current revision you are editing in the Develop tab. When you do this, Apigee creates a new revision for you.

1. Click the Deploy to: env_name drop-down list

   

   The UI displays a list of environments. In the Revision column, the UI lists the currently deployed revision (or "‑‑" if none).

2. Click Deploy revision to deploy the revision that you most recently edited.

   The UI prompts you to confirm the deployment.

3. Click Deploy.

   The UI begins the process of deploying the selected revision.

Apigee API

The following sections provide examples of using the Apigee API to deploy API proxy revisions and list the deployments for your organization.

• Create a deployment change report before deploying
• Deploying an API proxy revision using the API
• Listing deployments of an API proxy using the API

See also Viewing deployment status.

Note: Apigee restricts the number of deployment requests processed per second. If you attempt a large number of deployment requests simultaneously, you may see deployment failures due to timeout errors.

Create a deployment change report before deploying

Deploying a proxy in more than one environment in the same environment group may lead to undefined behavior. To determine whether this will occur, you can generate a report using the generateDeployChangeReport method as follows:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/apis/$API/revisions/$REV/deployments:generateDeployChangeReport" \
-X POST \
-H "Authorization: Bearer $TOKEN"

This returns a deployment change report that warns you if a base path in the proxy you want to deploy will not receive traffic due to an existing deployment that is already using that base path.

Deploying an API proxy revision using the API

To deploy an API proxy revision, use the following API call:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/apis/$API/revisions/$REV/deployments" \
  -X POST \
  -H "Authorization: Bearer $TOKEN"

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

Key Point: If an existing API proxy revision is deployed, set the override query parameter to true. In this case, Apigee deploys the new revision fully before undeploying the existing revision, as described in Zero-downtime deployment.

The following shows an example of the response output. In this example, revision 1 of the helloworld API proxy was deployed successfully to the test environment:

{
  "environment": "test",
  "apiProxy": "helloworld",
  "revision": "1",
  "deployStartTime": "1559149080457"
}

For more information, see Deploy API proxy revision API.

Listing deployments using the API

To list all deployments of API proxies and shared flows for your organization, enter the following API call:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/deployments" \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

Where $TOKEN is set to your OAuth 2.0 access token, as described in Obtaining an OAuth 2.0 access token. For information about the curl options used in this example, see Using curl. For a description of the environment variables used, see Setting environment variables for Apigee API requests.

Key Point: When viewing a list of deployments, deployment status will not be provided. To view deployment status for an individual API proxy revision, see Viewing deployment status.

The following provides an example of the response. In this example, there are three API proxies deployed, including helloworld which was deployed in the previous section.

{
  "deployments": [
    {
      "environment": "test",
      "apiProxy": "helloworld",
      "revision": "1",
      "deployStartTime": "1559149080457"
    },
    {
      "environment": "test",
      "apiProxy": "weather",
      "revision": "1",
      "deployStartTime": "1558620435217"
    },
    {
      "environment": "test",
      "apiProxy": "testproxy",
      "revision": "2",
      "deployStartTime": "1558635113086"
    }
  ]
}

gcloud

The following sections provide examples of using gcloud apigee CLI commands to deploy API proxy revisions and list the deployments for your organization.

• Deploying an API proxy revision using the gcloud CLI
• Listing deployments of an API proxy using the gcloud CLI

See also Viewing deployment status.

For more information and a description of the environment variables used in the examples, see Getting started using gcloud with Apigee.

Deploying an API proxy revision using the gcloud CLI

To deploy an API proxy revision, use the following gcloud command:

gcloud apigee apis deploy $REV --api=$API --environment=$ENV

Key Point: If an existing API proxy revision is deployed, set the override flag to true. In this case, Apigee deploys the new revision fully before undeploying the existing revision, as described in Zero-downtime deployment.

The following shows an example of the response output. In this example, revision 1 of the helloworld API proxy was deployed successfully to the test environment:

Using Apigee organization 'my-org'
apiProxy: helloworld
deployStartTime: '1598032332802'
environment: test
revision: '1'

For more information, see Deploy API proxy revision CLI.

Listing deployments using the gcloud CLI

To list all deployments of API proxies and shared flows for your organization, use the following gcloud command:

gcloud apigee deployments list

Key Point: When viewing a list of deployments, deployment status will not be provided. To view deployment status for an individual API proxy, see Viewing deployment status.

The following provides an example of the response. In this example, there are three API proxies deployed, including helloworld which was deployed in the previous section.

Using Apigee organization `my-org`
 - apiProxy: helloworld
   deployStartTime: 1598032332802
   environment: test
   revision: 1
 - apiProxy: weather
   deployStartTime: 1558620435217
   environment: test
   revision: 1
 - apiProxy: testproxy
   deployStartTime: 1558635113086
   environment: test
   revision: 2

For more information, see List deployments CLI.

Troubleshooting

If you are unable to deploy your API proxy, check to see if one of the following common scenarios may apply.

Naming restrictions for environment groups

If the name of your environment group does not comply with naming restrictions your proxy will not deploy. In some cases, it is possible to create an environment group and add environments to it without having to meet these restrictions. However, this will prevent proxy deployment.

See Creating environment groups for a description of naming guidelines and restrictions.

Environment created with a previously used environment name

If you create an environment with the same name as an environment that was previously deleted, your proxy will not deploy. For example, if you created an environment named prod-1 after previously creating and deleting a prod-1 environment, you will need to remove it. You can use the following steps to resolve this issue:

1. Detach the prod-1 environment from your environment group using the API.
2. Delete the prod-1 environment using the API.
3. Create a new environment. For example, prod-2.
4. Attach the new prod-2 environment to your environment group using the API.

Note: To resolve deployment issues, see deployment errors. For policy related issues, see policy errors.