Deploying and managing archives in an Apigee environment

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Develop and test your programmable API proxies using Apigee in VS Code. Then, deploy an archive of your API proxy configuration environment to your Apigee integration test and production environment as described in the following sections.

Enabling archive deployment in an Apigee environment

Before you can deploy an archive, you must enable archive deployment in your Apigee environment.

Note: Review the following information about archive deployment before proceeding:

The name of the Apigee environment must match the name of the local development environment.
When you enable archive deployment in an environment, to prevent conflicts with local development you will be prevented from performing a subset of actions within the environment using the Apigee UI, API, or gcloud. For more information, see Summary of prevented actions with archive deployment.
After you create an environment, the deployment type cannot be changed.
If you create an environment using the provisioning wizard, as described in Create an environment and environment group, you will not have the option of selecting archive as the deployment type for the environment.
You must be an Org Admin to create an environment.

Enable archive deployment as described in the following sections.

Apigee UI

In the Google Cloud console, go to the Apigee > Environments page.

Go to Environments
Click + Create Environment.
Select Archive under Deployment type.
Click Create.

Apigee API

To enable archive deployment when creating an environment using the API, set deploymentType to ARCHIVE in the request body.

For example:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments" \
   -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-type: application/json" \
   -d
   '{
      "name": "integration-test",
      "description": "Integration test environment",
      "displayName" : "Integration test",
      "deploymentType" : "ARCHIVE"
   }'

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 environment variables you can use, see Setting environment variables for Apigee API requests.

The following provides an example of the response:

{
  "name": "organizations/$ORG/operations/11b1ad1c-2371-473d-bcd4-f621f8d98ef7",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "INSERT",
    "targetResourceName": "organizations/$ORG/environments/integration-test",
    "state": "IN_PROGRESS"
  }
}

You can check the status of the operation. For example:

curl https://apigee.googleapis.com/v1/organizations/$ORG/operations/11b1ad1c-2371-473d-bcd4-f621f8d98ef7 /
   -H "Authorization: Bearer $TOKEN"

The following provides an example of the response. Note that the state of the operation is FINISHED and the state of the environment is set to ACTIVE.

{
  "name": "organizations/$ORG/operations/11b1ad1c-2371-473d-bcd4-f621f8d98ef7",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "INSERT",
    "targetResourceName": "organizations/$ORG/environments/integration-test",
    "state": "FINISHED"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.Environment",
    "name": "integration-test",
    "description": "Integration test environment",
    "createdAt": "1615553880084",
    "lastModifiedAt": "1615553881911",
    "displayName": "Integration test",
    "state": "ACTIVE",
    "deploymentType": "ARCHIVE"
  }
}

For more information about the API, see Create environments API.

Deploying an archive to an Apigee environment

To deploy an archive to an Apigee environment use the following gcloud command:

gcloud beta apigee archives deploy \
    --environment=$ENV \
    [--organization=$ORG] \
    [--source=$SOURCE] \
    [--labels $KEY=$VALUE[,$KEY2=$VALUE2,$KEY3=$VALUE3,...]]

You must specify the Apigee environment in which you want to deploy the archive using the --environment flag. The Apigee environment must be enabled for archive deployments. For more information, see gcloud beta apigee archives deploy.

By default, the archive is deployed:

To the organization associated with the current active project configured for gcloud.
To view the current gcloud configuration, run gcloud config list. To specify the organization, use the --organization flag.
From the current working directory.
If the src/main/apigee root directory of the archive is in a location other than the current working directory, use the --source flag to specify the location of the root directory of the archive. See also Understanding the structure of an Apigee workspace.

Optionally, you can add up to 64 custom label key/value pairs to an archive deployment using the --labels flag. For example, you might want to label an archive with a build number. The labels will display when you list archive deployments. Key values must adhere to the following guidelines:

Maximum length of 63 characters
Maximum size of 128 bytes
UTF-8 encoded
Conform to the following Perl-compatible regular expression (PCRE): [\p{Ll}\p{Lo}][\p{Ll}\p{Lo}\p{N}_-]{0,62}

Behind the scenes, the gcloud command performs the following steps when deploying to Apigee on Google Cloud:

Creates a zip file of your src/main/apigee Apigee workspace directory. For more information, see Understanding the structure of an Apigee workspace.
Note: When creating the zip file, only file types within the src/main/apigee directory and with the following extensions are included: .jar, .java, .js, .jsc, .json, .properties, .py, .wsdl, .xml, .xsd
Files without the extensions above will be excluded from the zip file.
Deploys the archive to Apigee on Google Cloud, as follows:
1. Generates a signed URL for the Google Cloud Storage bucket in the project associated with the current Apigee organization using the generateUploadUrl API.
2. Uploads the archive zip file to the Cloud Storage bucket using the signed URL.
3. Deploys the archive currently staged in the Cloud Storage bucket to Apigee on Google Cloud. using the Archive Deployments API.

Example requests

The following example creates a zip archive of src/main/apigee in the current directory and deploys it to the specified Apigee environment:

gcloud beta apigee archives deploy --environment=$ENV

The following example shows how you can specify an organization that is not associated with the current active project configured for gcloud:

gcloud beta apigee archives deploy --environment=$ENV --organization=$ORG

The following example creates a zip archive of the src/main/apigee directory under myarchive and deploys it to the specified Apigee environment:

gcloud beta apigee archives deploy --environment=$ENV --source=/myarchive

The following example adds the status and build_id labels to the archive deployment:

gcloud beta apigee archives deploy --environment=$ENV --labels=status=released,build=210315

Example response

The following provides an example of the response:

Using Apigee organization 'myorg'
Waiting for operation [b64c2665-b5ac-43cc-9e2d-232e8895c2ed] to complete...done.

Checking the archive deployment status

To check the archive deployment status, use the gcloud alpha apigee operations command.

The following example shows the archive deployment status for the operation with revision ID 439fa3f7-6aa4-42ad-8b12-3ca912c75d5c is IN_PROGRESS.

gcloud alpha apigee operations describe b64c2665-b5ac-43cc-9e2d-232e8895c2ed

The following provides an example of the response. Note that state is set to IN_PROGRESS.

Using Apigee organization 'myorg'
done: true
metadata:
  '@type': type.googleapis.com/google.cloud.apigee.v1.OperationMetadata
  operationType: INSERT
  state: IN_PROGRESS
  targetResourceName: uri
name: organizations/myorg/operations/b64c2665-b5ac-43cc-9e2d-232e8895c2ed
organization: myorg
response:
  '@type': type.googleapis.com/google.cloud.apigee.v1.CanaryEvaluation
  control: 1-5-0-20210319-071117-ghq74
  endTime: '2021-03-20T06:15:44.329363950Z'
  metricLabels:
    env: test
    location: us-central1
  name: uri
  startTime: '2021-03-20T06:14:44.306534584Z'
  treatment: 1-5-0-20210319-190954-if0wk
  verdict: NONE
uuid: b64c2665-b5ac-43cc-9e2d-232e8895c2ed

After the operation completes, the state is set to FINISHED.

Listing all archive deployments in an environment

List all archive deployments in an environment as described in the following sections.

gcloud

To list all archive deployments in Apigee on Google Cloud, use the following gcloud command:

gcloud beta apigee archives list --environment=$ENV

You must specify the Apigee environment in which you want to view archive deployments using the --environment flag. The Apigee environment must be Viewing details for an archive deployment. For more information, see gcloud beta apigee archives list.

The following provides an example of the response:

Using Apigee organization 'myorg'
ARCHIVE ID                        ENVIRONMENT   DEPLOYED AT           LABELS                         OPERATION STATUS
pzfbs8uidbdv224joz                myorg         2021-03-10 11:21:29   status=released,build=210315   Deployed
fb4r8log2gm63r3gtu                myorg         2021-03-05 13:40:30
vrytwbhso558oil53m                myorg         2021-03-03 21:20:53

Apigee API

To list the archive deployments in an environment, issue a GET request to the following API: https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments.

For example:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments" \
  -H "Authorization: Bearer $TOKEN"

The following provides an example of the response:

{
  "archiveDeployments": [
    {
      "name": "organizations/myorg/environments/integration-test/archiveDeployments/pzfbs8uidbdv224joz",
      "labels": {
        "status": "released",
        "build": "210315"
      },
      "createdAt": "1615821232451727",
      "updatedAt": "1615821232451727",
      "operation": "organizations/apigee-docs-c/operations/b64c2665-b5ac-43cc-9e2d-232e8895c2ed"
    },
    {
      "name": "organizations/myorg/environments/integration-test/archiveDeployments/fb4r8log2gm63r3gtu",
      "createdAt": "1615819281858447",
      "updatedAt": "1615819281858447",
      "operation": "organizations/apigee-docs-c/operations/71549b9c-4493-41b6-9838-c0ad5b1b3181"
    },
    {
      "name": "organizations/myorg/environments/integration-test/archiveDeployments/vrytwbhso558oil53m",
      "createdAt": "1615578337832207",
      "updatedAt": "1615578337832207",
      "operation": "organizations/apigee-docs-c/operations/a2eb50b5-f276-4de4-96a3-72fac3d4c05e"
    }
  ]
}

Viewing details for an archive deployment

View details for an archive deployment as described in the following sections.

gcloud

To view details for an archive deployment in Apigee on Google Cloud, use the following gcloud command:

gcloud beta apigee archives describe $ID --environment=$ENV

You must specify the following:

ID of the archive deployment revision.
Apigee environment in which you want to view archive deployments using the --environment flag. The Apigee environment must be enabled for archive deployments.

For more information, see gcloud beta apigee archives describe.

For example:

gcloud apigee archives describe pzfbs8uidbdv224joz --environment=$ENV

The following provides an example of the response:

Using Apigee organization 'myorg'
createdAt: '1615578337832207'
labels:
  status: 'released'
  build: '210315'
name: organizations/myorg/environments/$ENV/archiveDeployments/pzfbs8uidbdv224joz
operation: organizations/myorg/operations/b64c2665-b5ac-43cc-9e2d-232e8895c2ed
operationStatus: Deployed
updatedAt: '1615821232451727'

Apigee API

To view details for an archive deployment, issue a GET request to the following API: https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/$ID.

You must pass the ID of the archive deployment revision. To view the list of archive deployment revision IDs for an Apigee environment, see Listing all archive deployments in an environment.

For example:

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

The following provides an example of the response:

{
  "name": "organizations/myorg/environments/integration-test/archiveDeployments/pzfbs8uidbdv224joz",
  "labels": {
     "status": "released",
     "build": "210315"
  },
  "createdAt": "1615578337832207",
  "updatedAt": "1615821232451727",
  "operation": "organizations/apigee-docs-c/operations/b64c2665-b5ac-43cc-9e2d-232e8895c2ed"
}

Updating labels for an archive deployment

Update labels for an archive deployment as described in the following sections.

gcloud

To update labels for an archive deployment in Apigee on Google Cloud, use the following gcloud command:

gcloud beta apigee archives update [$ID] --environment=$ENV
  [--update-labels=$KEY=$VALUE[,$KEY2=$VALUE2...$KEYn=$VALUEn]],
  [--clear-labels | --remove-labels=$KEY[,$KEY2...$KEYn]]

You must specify the following:

ID of the archive deployment revision
Apigee environment in which you want to view archive deployments using the --environment flag. The Apigee environment must be enabled for archive deployments.

One or more of the following flags:

Flag	Description
`--clear-labels`	Removes all labels. If `--update-labels` is also specified, `--clear-labels` is applied first. Cannot be specified if `--remove-labels` is specified.
`--remove-labels`	Removes the specified labels. If `--update-labels` is also specified, it is applied first. Cannot be specified if `--clear-labels` is specified.
`--update-labels`	Update the labels. If a label exists, its value is modified; otherwise, a new label is created. Combine with `--remove-labels` or `--clear-labels` flags to remove a subset or all labels, respectively, before updating labels.

For more information, see gcloud beta apigee archives update.

For example:

gcloud apigee archives update pzfbs8uidbdv224joz --environment=$ENV \
  --clear-labels --update-labels=status=released,build=210315,tier=1

The following provides an example of the response:

Using Apigee organization `myorg`
createdAt: 2020-04-04T04:04:04.004Z
labels:
  status: released,
  build: 210315,
  tier: 1
name: organizations/apigee-docs-c/environments/dev/archiveDeployments/pzfbs8uidbdv224joz
operation: organizations/apigee-docs-c/operations/bf587121-8b5c-4897-9d8f-9b1ef0cb06ca
updatedAt: '1633450432067431'

Apigee API

To update labels for an archive deployment in Apigee on Google Cloud, issue a PATCH request to the following API: https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/$ID.

You must pass the ID of the archive deployment revision. To view the list of archive deployment revision IDs for an Apigee environment, see Listing all archive deployments in an environment.

Pass all of the labels you want to add to the archive in the request body. The labels that you pass overwrite the current set of labels, so you can remove labels by omitting them from the request body or remove all labels by passing an empty list.

For example:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/$ID" \
  -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "labels": {
      "status" : "released",
      "build" : "210315"
    }
  }'

The following provides an example of the response:

{
  "name": "organizations/myorg/environments/integration-test/archiveDeployments/pzfbs8uidbdv224joz",
  "labels": {
     "status": "released",
     "build": "210315"
  },
  "createdAt": "1615578337832207",
  "updatedAt": "1615821232451727",
  "operation": "organizations/apigee-docs-c/operations/b64c2665-b5ac-43cc-9e2d-232e8895c2ed"
}

Deleting an Apigee environment with archive deployments

To delete an Apigee environment with archive deployments:

In a temporary folder, create the following directory structure where $ENV matches the name of the environment you want to delete. For example:
```
mkdir -p /$TEMP/archive/src/main/apigee/environments/$ENV
```

Add the deployments.json file to the directory. For example:

touch /$TEMP/archive/src/main/apigee/environments/$ENV/deployments.json

Update the deployments.json to include an empty proxies array, as shown below.
```
{
"proxies" : []
}
```
Change directory (cd) to the $TEMP/archive folder.
```
cd $TEMP/archive
```
Deploy the archive to the Apigee environment that you want to delete.
```
gcloud beta apigee archives deploy --environment=$ENV
```
Delete the Apigee environment.

Deleting a revision of an archive deployment

Delete a revision of an archive deployment as described in the following section.

gcloud

To delete a revision of an archive deployment in Apigee on Google Cloud, use the following gcloud command:

gcloud beta apigee archives delete $ID --environment=$ENV

You must specify the following:

The ID of the revision that you want to delete.
Apigee environment in which you want to view archive deployments using the --environment flag. The Apigee environment must be enabled for archive deployments.

For example:

gcloud apigee archives delete fb4r8log2gm63r3gtu --environment=dev

The following provides an example of the response:

Archive deployment revision "fb4r8log2gm63r3gtu" deleted

Apigee API

To delete a revision of an archive deployment in Apigee on Google Cloud, issue a DELETE request to the following API: https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/$ID.

You must pass the ID of the archive deployment revision that you want to delete. To view the list of archive deployment revision IDs for an environment, see Listing all archive deployments in an environment.

For example:

curl "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/archiveDeployments/$ID" \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN" \

The following provides an example of the response:

{}

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-06-09 UTC.

Deploying and managing archives in an Apigee environment Stay organized with collections Save and categorize content based on your preferences.

Enabling archive deployment in an Apigee environment

Apigee UI

Apigee API

Deploying an archive to an Apigee environment

Example requests

Example response

Checking the archive deployment status

Listing all archive deployments in an environment

gcloud

Apigee API

Viewing details for an archive deployment

gcloud

Apigee API

Updating labels for an archive deployment

gcloud

Apigee API

Deleting an Apigee environment with archive deployments

Deleting a revision of an archive deployment

gcloud

Apigee API

Deploying and managing archives in an Apigee environment