You're viewing Apigee Edge documentation.
Go to the
Apigee X documentation. info
Apigee Edge provides many different types of resources and each of them serve a different purpose. There are certain resources that can be configured (i.e., created, updated, and/or deleted) only through the Edge UI, management APIs, or tools that use management APIs, and by users with the prerequisite roles and permissions. For example, only org admins belonging to a specific organization can configure these resources. That means, these resources cannot be configured by end users through developer portals, nor by any other means. These resources include:
- API proxies
- Shared flows
- API products
- Caches
- KVMs
- Keystores and truststores
- Virtual hosts
- Target servers
- Resource files
While these resources do have restricted access, if any modifications are made to them even by the authorized users, then the historic data simply gets overwritten with the new data. This is due to the fact that these resources are stored in Apigee Edge only as per their current state. The main exceptions to this rule are API proxies and shared flows.
API Proxies and Shared Flows under Revision Control
API proxies and shared flows are managed -- in other words, created, updated and deployed -- through revisions. Revisions are sequentially numbered, which enables you to add new changes and save it as a new revision or revert a change by deploying a previous revision of the API proxy/shared flow. At any point in time, there can be only one revision of an API proxy/shared flow deployed in an environment unless the revisions have a different base path.
Although the API proxies and shared flows are managed through revisions, if any modifications are made to an existing revision, there is no way to roll back since the old changes are simply overwritten.
Audits and History
Apigee Edge provides the Audits and API, Product, and organization history features that can be helpful in troubleshooting scenarios. These features enable you to view information like who performed specific operations (create, read, update, delete, deploy, and undeploy) and when the operations were performed on the Edge resources. However, if any update or delete operations are performed on any of the Edge resources, the audits cannot provide you the older data.
Antipattern
Managing the Edge resources (listed above) directly through Edge UI or management APIs without using source control system
There's a misconception that Apigee Edge will be able to restore resources to their previous state following modifications or deletes. However, Edge Cloud does not provide restoration of resources to their previous state. Therefore, it is the user's responsibility to ensure that all the data related to Edge resources is managed through source control management, so that old data can be restored back quickly in case of accidental deletion or situations where any change needs to be rolled back. This is particularly important for production environments where this data is required for runtime traffic.
Let's explain this with the help of a few examples and the kind of impact that can be caused if the data in not managed through a source control system and is modified/deleted knowingly or unknowingly:
Example 1: Deletion or modification of API proxy
When an API proxy is deleted, or a change is deployed on an existing revision, the previous code won't be recoverable. If the API proxy contains Java, JavaScript, Node.js, or Python code that is not managed in a source control management (SCM) system outside Apigee, a lot of development work and effort could be lost.
Example 2: Determination of API proxies using specific virtual hosts
A certificate on a virtual host is expiring and that virtual host needs updating. Identifying which API proxies use that virtual host for testing purposes may be difficult if there are many API proxies. If the API proxies are managed in an SCM system outside Apigee, then it would be easy to search the repository.
Example 3: Deletion of keystore/truststore
If a keystore/truststore that is used by a virtual host or target server configuration is deleted, it will not be possible to restore it back unless the configuration details of the keystore/truststore, including certificates and/or private keys, are stored in source control.
Impact
- If any of the Edge resources are deleted, then it's not possible to recover the resource and its contents from Apigee Edge.
- API requests may fail with unexpected errors leading to outage until the resource is restored back to its previous state.
- It is difficult to search for inter-dependencies between API proxies and other resources in Apigee Edge.
Best Practice
- Use any standard SCM coupled with a continuous integration and continuous deployment (CICD) pipeline for managing API proxies and shared flows.
- Use any standard SCM for managing the other Edge resources, including API products,
caches, KVMs, target servers, virtual hosts, and keystores.
- If there are any existing Edge resources, then use management APIs to get the configuration details for them as a JSON/XML payload and store them in source control management.
- Manage any new updates to these resources in source control management.
- If there's a need to create new Edge resources or update existing Edge resources, then use the appropriate JSON/XML payload stored in source control management and update the configuration in Edge using management APIs.
* Encrypted KVMs cannot be exported in plain text from the API. It is the user's responsibility to keep a record of what values are put into encrypted KVMs.