Aft Documentation

The primary engine of AFT. Converts between Apigee proxy ZIP bundles, concise YAML proxies, and JSON formats. Applies and removes modular features, instantiates templates with parameter substitutions, converts between features and SharedFlow ZIP bundles, or creates new proxies and templates from scratch.

Command Options

Examples

Inspects and summarizes any local file, remote repository resource (template, proxy, feature, product, user, or deployment), or Apigee organization configuration (--project). Renders a high-contrast terminal card detailing the name, description, endpoints, target URLs, flows, policies, parameters, KVMs, products, or org runtime settings without modifying or creating files. If given a non-existent filename as a single argument, AFT safely creates an empty template proxy instead.

Command Options

Examples

Resets a template, feature, or proxy file to its default empty contents. For templates, removes all features, parameters, endpoints, and targets. For features, removes all policies, flows, and resources while leaving endpoints and targets with no flow steps. For proxies, removes all policies, flows, and resources while leaving endpoints and targets with no flow steps.

Command Options

Examples

Browses all pre-built templates and features available in the central GitHub repository (https://github.com/gcp-samples/apigee-template-repository ↗). Supports structured output in JSON or YAML formats for integration with CI/CD pipelines and developer tooling. Results are cached locally for 24 hours.

Command Options

Examples

Installs or displays dynamic shell tab-completion scripts. Provides context-aware auto-completion for commands, flags, formats, and repository feature names across Zsh, Bash, Fish, and Windows PowerShell.

Command Options

Examples

Manages the native Apigee Templater skill for AI coding assistants. Installs the SKILL.md specification and guides into ~/.agents/skills/apigee-templater, enabling tools like Google Antigravity, Gemini CLI, Claude Code, Cursor, and Codex to author and debug AFT proxies automatically.

Command Options

Examples

Manages the local cache of templates, features, and schemas downloaded from the repository. The cache is stored in ~/.aft/cache/ and automatically expires after 24 hours. Use this command to force an immediate refresh of the catalog.

Command Options

Examples

In production Apigee environments, an API proxy never lives in isolation. It relies on backend routing configurations, security policies, Key-Value Maps (KVMs) for runtime lookups, API Products to govern quotas and operations, Developer Users who own client applications, API Keys / Secrets for authentication, Data Collectors for runtime telemetry, and automated tests to verify contract validity.

Traditionally, deploying this ecosystem required running several sequential tools (e.g., creating KVMs first, then deploying proxy revisions, then provisioning products, then issuing credentials, then running test runners). If any step failed, the environment was left in a half-configured state.

With AFT Deployment YAML:

• Single Source of Truth: Every asset required to run, secure, and test the API is captured in one manifest.
• Coordinated Multi-Asset Deployment: One CLI command deploys Data Collectors → Proxies & Templates → API Products → Developer Users & Apps → Custom Reports in proper dependency order.
• Clean Teardown: One command deletes the entire ecosystem in reverse dependency order (Users → Products → Proxies → Reports → Data Collectors) without leaving orphaned assets.
• Offline Emulation: Directly exports proxy bundles and emulator JSON configuration files (products.json, developers.json, developerapps.json, maps.json) for instantaneous testing with Apigee Emulator Service ↗.

The simplest way to use Deployment YAML is to link existing external template, product, and user YAML files. AFT resolves relative file paths starting from the deployment file's directory. If a file is not found locally, AFT automatically searches the central Apigee Template Repository ↗.

# yaml-language-server: $schema=https://raw.githubusercontent.com/apigee/apigee-templater/main/schema/gateway.schema.1.0.json
gateway: apigee
schemaVersion: 1.0.0
name: starter-deployment
type: deployment
description: Minimal deployment linking modular templates, products, and users

environments:
  - dev

# Links to external YAML files (relative or repository names)
templates:
  - templates/REST-AI-Completions.yaml

products:
  - products/ai-starter-package.yaml

users:
  - users/partner-developer.yaml

A production-ready Deployment YAML can embed standalone proxies, environment-scoped and proxy-scoped KVMs, advanced API products (REST, LLM, and MCP tools), developer identities with pre-provisioned credentials, telemetry collectors, and automated test assertions:

# yaml-language-server: $schema=https://raw.githubusercontent.com/apigee/apigee-templater/main/schema/gateway.schema.1.0.json
gateway: apigee
schemaVersion: 1.0.0
name: enterprise-ai-suite
displayName: Enterprise AI Gateway Suite
type: deployment
description: Production-grade deployment with proxy templates, direct proxies, KVMs, products, users, telemetry, and automated tests.
environments:
  - dev
  - prod

# 1. Composed Proxy Templates (referencing modular features)
templates:
  - REST-AI-Completions.yaml

# 2. Standalone Direct Proxies (embedded inline or linked)
proxies:
  - name: MockServiceProxy-v1
    displayName: Mock Service Proxy
    type: proxy
    description: Mock edge service with JavaScript response manipulation
    endpoints:
      - name: default
        basePath: /v1/mock
        routes:
          - name: default
            target: default
        flows:
          - name: PostFlow
            mode: Response
            steps:
              - name: JS-AddTimestamp
    targets:
      - name: default
        url: https://mocktarget.apigee.net
    policies:
      - name: JS-AddTimestamp
        type: Javascript
        content:
          Javascript:
            metadata:
              name: JS-AddTimestamp
            Source: |
              var body = JSON.parse(response.content || "{}");
              body.edgeTimestamp = Date.now();
              response.content = JSON.stringify(body);

# 3. Key-Value Maps (Environment-Scoped & Proxy-Scoped)
kvms:
  - name: GlobalEnvConfig
    type: environment
    values:
      ROUTING_TIER: enterprise-tier
      UPSTREAM_TIMEOUT: "3500"
      ENABLE_DEBUG_HEADERS: "false"
  - name: MockRoutingKvm
    type: proxy
    proxy: MockServiceProxy-v1
    values:
      DEFAULT_REGION: us-central1
      MAX_PAYLOAD_SIZE_KB: "1024"

# 4. API Products (Governing REST, LLM Model Garden, and MCP Tool Calls)
products:
  - name: enterprise-ai-product
    displayName: Enterprise AI Product
    type: product
    description: Bundled access to Gemini completions, mock service, and MCP CRM tools
    access: public
    approvalType: auto
    environments:
      - dev
    proxies:
      - REST-AI-Completions
      - MockServiceProxy-v1
    quota: "100000"
    quotaInterval: "1"
    quotaTimeUnit: month
    operations:
      - apiSource: MockServiceProxy-v1
        operations:
          - name: /json
            methods: [GET]
    llmOperations:
      - apiSource: REST-AI-Completions
        operations:
          - name: /v1/chat/completions
            methods: [POST]
            model: gemini-2.5-flash
            llmTokenQuota:
              limit: "25000"
              interval: "1"
              timeUnit: minute
    payloadOperations:
      - apiSource: REST-AI-Completions
        protocol: MCP
        operations:
          - name: tools/list
          - name: tools/call/get_customer_profile
            quota:
              limit: "120"
              interval: "1"
              timeUnit: minute

# 5. Developer Users, Apps & Pre-Provisioned API Credentials
users:
  - name: partner-dev
    type: user
    email: partner-dev@example.com
    firstName: Partner
    lastName: Developer
    userName: partnerdev
    status: active
    apps:
      - name: Enterprise Analytics Client
        displayName: Enterprise Analytics Client
        status: approved
        products:
          - enterprise-ai-product
        credentials:
          - consumerKey: client-api-key-998877
            consumerSecret: client-secret-554433
            status: approved
            products:
              - enterprise-ai-product

# 6. Data Collectors (Runtime Telemetry Capture)
dataCollectors:
  - name: dc_ai_model
    type: datacollector
    collectorType: STRING
    description: Name of the AI model invoked
  - name: dc_ai_prompt_token_count
    type: datacollector
    collectorType: INTEGER
    description: Token count for the request prompt

# 7. Custom Analytics Reports
reports:
  - name: ai_token_usage_by_model
    displayName: "AI Token Usage by Model"
    type: report
    chartType: col
    timeUnit: hour
    metrics:
      - name: dc_ai_prompt_token_count
        function: sum
    dimensions:
      - apiproxy
      - dc_ai_model

# 8. Automated Runtime Test Assertions
tests:
  - name: test-chat-completions-auth
    description: Validates end-to-end authorization and 200 OK status
    proxy: REST-AI-Completions
    product: enterprise-ai-product
    path: /v1/chat/completions
    method: POST
    injectGoogleToken: true
    headers:
      Content-Type: application/json
      x-api-key: client-api-key-998877
    body: |
      {
        "model": "gemini-2.5-flash",
        "messages": [{"role": "user", "content": "Ping"}]
      }
    assertions:
      - response.status == 200

Every resource block within a Deployment YAML is strictly typed and validated against the JSON schema:

AFT orchestrates complete multi-resource deployments and safe teardowns directly against your Google Cloud project using standard Application Default Credentials. Use --project, --org, or --organization interchangeably:

Deploying to Apigee X / Hybrid

Tearing Down Resources (--delete)

When tearing down a temporary testing or preview environment, passing --delete cleans up all assets in strict reverse dependency order to prevent orphaned resources or foreign key constraints:

1. Developer Apps & Users: Deletes developer apps and credentials first, then deletes developer identities.
2. API Products: Deletes API products and detaches environment/proxy associations.
3. Proxies, Templates & Features: Undeploys all revisions from environments and deletes the proxy bundles.
4. Custom Reports: Removes analytics custom reports.
5. Data Collectors: Deletes data collector definitions last.

AFT can compile an entire Deployment YAML into the exact artifacts required by the Apigee Emulator. This enables local development, zero-cloud-cost debugging, and offline CI/CD pipelines without connecting to a live GCP organization:

This single command generates the full suite of Apigee Emulator configuration files:

• {ProxyName}.zip: Deployable proxy bundles containing policies, endpoints, and resources.
• products.json & apiproducts.json: Emulator-compliant API product catalog with quota limits and proxy associations.
• developers.json & users.json: Developer identities mapped to the emulator runtime.
• developerapps.json & apps.json: Developer apps populated with consumer API keys and secrets.
• maps.json: Environment and proxy-scoped Key-Value Maps (KVMs).
• datacollectors.json: Runtime data collector metadata.

Running with Apigee Emulator Service

The generated artifacts can be directly mounted into the Apigee Emulator Service ↗ container:

# 1. Export deployment to a local testdata directory
aft deployment.yaml -f zip -o ./emulator-dist/

# 2. Spin up the Apigee Emulator Service container with the exported artifacts mounted
docker run -d --name apigee-emulator   -p 8080:8080 -p 8443:8443 -p 8998:8998   -v $(pwd)/emulator-dist:/opt/apigee/testdata   ghcr.io/tyayers/apigee-emulator-service:latest

# 3. Test your endpoints locally using the pre-provisioned credentials
curl -H "x-api-key: client-api-key-998877" http://localhost:8080/v1/mock

Explore sample configurations, Docker Compose setups, and automated testing patterns in the Apigee Emulator Service repository ↗.

Export deployed proxies, SharedFlows, API products, and developer user credentials from an Apigee X organization directly into clean, version-controllable YAML or JSON files.

Examples

Deploy local proxies, API products, developer users, and complete multi-resource templates directly to your Apigee X / hybrid environments.

Examples

Tears down and deletes Apigee resources defined in local YAML files. Handles multi-resource templates and deployment YAMLs with automatic reverse dependency ordering (Users -> Products -> Proxies -> Reports -> Data Collectors).

Examples

Create an enterprise AI gateway proxy routing to Google Cloud Vertex AI Model Garden with automatic token extraction and authentication.

Export all proxies, products, and developer credentials from an existing Apigee organization into structured folders for GitOps version control.

Maintain security policies as clean YAML features locally, and compile them into Apigee SharedFlow ZIP bundles for deployment.

Author a unified deployment YAML combining an AI proxy, environment & proxy KVMs, an API product with LLM rate limiting, a test developer with credentials, and deploy or export to the Apigee Emulator.