How To: Managing Policy and Service Revisions

This guide explains how to manage policy and service revisions in Layer7 API Gateway using Graphman. Policy and service revisions allow you to maintain version history, rollback changes, and track modifications over time.

What are Revisions?

Revisions are versioned snapshots of policies and services. Each time you modify a policy or service, the Gateway can create a new revision while preserving the previous versions.

Key Concepts

• Ordinal: Sequential revision number (1, 2, 3, ...)
• Active Revision: The currently deployed version
• Revision Comment: Description of changes made in this revision
• Revision Author: User who created the revision
• Revision Time: Timestamp when revision was created

Revision Workflow

┌─────────────────┐
│  Policy v1      │ ──> Initial Creation (Ordinal 1, Active)
└─────────────────┘
         │
         ▼
┌─────────────────┐
│  Policy v2      │ ──> Modification (Ordinal 2, Active)
└─────────────────┘     (v1 becomes inactive)
         │
         ▼
┌─────────────────┐
│  Policy v3      │ ──> Another Change (Ordinal 3, Active)
└─────────────────┘     (v1, v2 inactive)
         │
         ▼
┌─────────────────┐
│  Rollback to v2 │ ──> Activate Previous (Ordinal 2, Active)
└─────────────────┘     (v1, v3 inactive)

Prerequisites

Gateway Requirements

• Layer7 API Gateway 11.1.1 or higher
• Graphman enabled on the Gateway
• User with appropriate permissions

Common Scenarios

Scenario 1: Migrate Revisions Between Gateways

Step 1: Export with Revisions

graphman export \
  --gateway source \
  --using all \
  --variables.includePolicyRevisions true \
  --output bundle-with-revisions.json

Note: By default, exports don't include revisions. Use the variables above to include them.

Step 2: Import with Revision Migration

graphman import \
  --gateway target \
  --input bundle-with-revisions.json \
  --options.migratePolicyRevisions true

What Happens:

• All policy and service revisions are imported
• Revision history is preserved
• Ordinal numbers are maintained
• Active revision status is preserved
• Comments and timestamps are retained

Note: Revisions will be imported for the newly created services and policies.

Scenario 2: Activate Latest Revision

Step 1: Import Services and Policies without immediate activation

graphman import \
  --gateway target \
  --input bundle-with-services-and-policies.json \
  --options.comment "Staging v1.23 changes"
  --options.activate false

Step 2: Activate them on demand

graphman import \
  --gateway target \
  --using set-policy-revisions \
  --input bundle-with-services-and-policies.json \
  --options.comment "Activating v1.23 changes"
  --options.activate true

What Happens:

• Gateway checks the latest revision ordinal
• If latest revision is not active, it activates it
• If latest revision is already active, no change occurs
• Returns status for each policy/service

Note: This scenario is applicable to Layer7 Gateway 11.1.3 and later releases.