BIG-IP Declarative API Overview and Quick Start

Overview

The BIG-IP Declarative API provides a declarative interface for managing services and configurations on BIG-IP systems. With a declarative model, you define the desired end state of your application in a single JSON document. BIG-IP automatically creates and manages the required configuration. Unlike F5 Application Services 3 Extension (AS3), this API uses a resource-oriented declarative model where BIG-IP LTM objects are defined explicitly.

This approach is designed to:

• Simplify deployment workflows
• Improve configuration consistency
• Enable automation and CI/CD integration
• Provide declarative control over LTM resources

Note: This API is separate from AS3 and provides a declarative interface that aligns closely with BIG-IP tmsh and iControl REST resource models.

Prerequisites

Before you begin, ensure you have:

• BIG-IP system running version 21.1.0 or later
• Access to the BIG-IP management interface (HTTPS)
• Administrator credentials
• A REST client such as:
  • curl
  • Postman

Note: This feature is an Early Access (EA) release and is not meant for production deployments.

About the Declarative Model

The Declarative Deployment API uses a JSON document to define BIG-IP LTM resources.

Instead of using high-level application constructs, this model defines individual BIG-IP resources explicitly. BIG-IP processes the declaration and ensures that all specified resources are created and configured accordingly.

A declaration typically includes:

• Nodes – Backend server definitions
• Pools – Groups of backend servers with load balancing configuration
• Virtual Servers – Traffic listeners that route requests to pools
• Profiles – Traffic processing behaviour (for example, HTTP, TCP)

Each resource in the declaration is defined using:

• A kind field that specifies the BIG-IP resource type
• A properties object that contains the configuration details for the resource

The Declarative Deployment API uses a resource-oriented model that closely aligns with BIG-IP LTM and iControl REST objects.

Key Declaration Elements

A declaration consists of a set of resources, where each resource contains:

• a kind field that identifies the BIG-IP resource type
• a properties object that defines the configuration values for the resource

Each entry in the resources array represents a specific BIG-IP LTM object, such as a node, pool, profile, or virtual server.

resources Defines the BIG-IP objects included in the declaration.

kind Specifies the BIG-IP resource type being declared.

The kind value corresponds to the primary portion of the iControl REST resource kind for the object.

Example: "kind": "tm:ltm:pool"

properties Contains configuration values for the specified resource.

The properties object is based on the corresponding iControl REST resource properties, excluding system-generated or metadata fields such as:

• kind
• fullPath
• generation
• selfLink
• *Reference

Example pool resource:

{
  "kind": "tm:ltm:pool",
  "properties": {
    "name": "pool_01",
    "loadBalancingMode": "round-robin",
    "members": [
      {
        "name": "10.0.0.10:80"
      }
    ]
  }
}

API Schema and OpenAPI Specification

The Declarative Deployment API uses schema-based validation for declaration processing.

Schema definitions are derived from BIG-IP LTM resource metadata and are used to validate incoming declarations before deployment.

The API schema:

• is internally represented using YAML/OpenAPI-based definitions
• is used for declaration validation and processing
• aligns closely with BIG-IP LTM and iControl REST resource models

The schema is based on corresponding iControl REST resource properties used for declarative validation and deployment processing.

Relationship to iControl REST Resources

The Declarative Deployment API aligns closely with BIG-IP LTM and iControl REST resource models.

Many declarative resource kinds correspond to existing iControl REST resource endpoints.

Examples:

This alignment may help users familiar with iControl REST understand declarative resource structures and properties.

Declarative resource properties are based on the corresponding iControl REST request body properties and are passed to iControl REST during deployment processing.

API Access

Supported API Endpoint

The BIG-IP Declarative Deployment API is exposed through the BIG-IP REST interface.

Base endpoint:

https://<BIG-IP>/mgmt/tm/sys/app-service

This endpoint is supported for BIG-IP 21.1.x releases.

Important:

• The endpoint and URI structure are version-specific and may change in future BIG-IP releases.
• Future releases may introduce updated endpoint structures or API organization changes.
• Customers should use release-specific documentation and validated examples for supported API paths and request formats.
• OpenAPI specification files are not currently planned for customer publication for BIG-IP 21.1.x releases.
• Example declarations and supported request examples will be provided through published documentation and validated examples.
• Users may also refer to the available BIG-IP iControl REST documentation for related resource behaviour and property definitions.

HTTP Methods

The Declarative Deployment API supports the following HTTP methods for BIG-IP 21.1.x releases.

The DELETE operation removes the application and associated deployed BIG-IP objects created through the declaration.

Cleanup processing attempts to remove all deployed resources. However, some automatically created BIG-IP objects, such as nodes generated by MCP for pool members, may remain if they were not explicitly defined in the original declaration.

Future BIG-IP releases may provide improved cleanup handling for automatically generated resources.

Versioning and Compatibility

The Declarative Deployment API behaviour, endpoints, schema definitions, and supported resource properties may vary between BIG-IP 21.1.x and the next major release as the API evolves from its Early Access (EA) implementation. Future releases are expected to provide greater API stability and broader resource coverage.

The initial release of this API is available as an Early Access (EA) feature in BIG-IP 21.1.x.

Customers should use release-specific documentation and validated example declarations when developing automation workflows.

The Declarative Deployment API aligns closely with BIG-IP iControl REST and tmsh resource models. As BIG-IP resource properties evolve between releases, corresponding declarative resource properties may also change.

F5 will make reasonable efforts to maintain backward compatibility in future supported releases where possible.

Future releases may include support for:

• additional BIG-IP object types
• onboarding-related resources
• service discovery integrations
• external resource retrieval from URLs
• alternate content formats such as Base64-encoded payloads

The API is not currently expected to use formal schema or API version identifiers.

Relationship to AS3

The Declarative Deployment API is separate from F5 Application Services 3 Extension (AS3).

AS3 declarations use a custom application-centric syntax where object names and properties do not directly match standard BIG-IP tmsh or iControl REST resource definitions. The Declarative Deployment API uses a syntax that aligns more closely with BIG-IP iControl REST and tmsh resource models.

The Declarative Deployment API is intended for users who require:

• closer alignment with BIG-IP LTM resource definitions
• the ability to modify declared objects directly using tmsh or iControl REST
• logical grouping of BIG-IP resources into applications
• declarative deployment workflows using BIG-IP-native resource properties

AS3 declarations and Declarative Deployment API declarations use different formats and are not interchangeable.

AS3 applications and resources cannot be referenced or managed through the Declarative Deployment API.

Authentication

Use standard BIG-IP REST authentication. Token-based authentication is recommended for improved security and session management.

Token-Based Authentication

Obtain an authentication token by sending a request to the BIG-IP authentication endpoint:

curl -sk -X POST https://<BIG-IP>/mgmt/shared/authn/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "<username>",
    "password": "<password>",
    "loginProviderName": "tmos"
  }'

Use the returned token in subsequent API requests:

curl -sk -X POST https://<BIG-IP>/mgmt/<declarative-api-endpoint> \
  -H "Content-Type: application/json" \
  -H "X-F5-Auth-Token: <token>" \
  -d @declaration.json

Basic Authentication (Alternative)

Basic authentication can be used for simple testing:

curl -sku <username>:<password> https://<BIG-IP>/mgmt/...

Note: Token-based authentication is preferred for production and automation use cases.

Quick Start: Deploy a Basic HTTP Service

This example demonstrates deploying a simple HTTP application using the resource-based declarative model.

Deployment Summary

This declaration creates:

• Two nodes (10.0.8.10, 10.0.8.11)
• A pool (html_pool) with round-robin load balancing
• An HTML profile (html_profile)
• A virtual server (html_virtual) listening on 10.1.2.27:80
• HTTP and TCP profiles applied to the virtual server

Example Declaration

{
  "name": "html_app",
  "partition": "Common",
  "resources": [
    {
      "kind": "tm:ltm:node",
      "properties": {
        "name": "10.0.8.10",
        "address": "10.0.8.10",
        "monitor": "default"
      }
    },
    {
      "kind": "tm:ltm:node",
      "properties": {
        "name": "10.0.8.11",
        "address": "10.0.8.11",
        "monitor": "default"
      }
    },
    {
      "kind": "tm:ltm:pool",
      "properties": {
        "name": "html_pool",
        "loadBalancingMode": "round-robin",
        "members": [
          { "name": "10.0.8.10:80", "ratio": 1, "state": "user-up" },
          { "name": "10.0.8.11:80", "ratio": 1, "state": "user-up" }
        ]
      }
    },
    {
      "kind": "tm:ltm:profile:html",
      "properties": {
        "name": "html_profile",
        "defaultsFrom": "html",
        "contentDetection": "enabled"
      }
    },
    {
      "kind": "tm:ltm:virtual",
      "properties": {
        "name": "html_virtual",
        "destination": "10.1.2.27:80",
        "ipProtocol": "tcp",
        "mask": "255.255.255.255",
        "pool": "html_pool",
        "profiles": [
          { "name": "html_profile" },
          { "name": "/Common/http", "context": "all" }
        ],
        "source": "0.0.0.0/0"
      }
    }
  ]
}

Submit the Declaration

curl -sku <username>:<password> \
  -X POST https://<BIG-IP>/mgmt/<declarative-api-endpoint> \
  -H "Content-Type: application/json" \
  -d @declaration.json

API Responses and Error Handling

The Declarative Deployment API returns standard HTTP status codes and response payloads for deployment requests.

Successful Responses

Successful responses may include:

• HTTP status code
• deployment status information
• generated resource details
• validation or processing messages

Response formats and payload structures may vary by operation and BIG-IP release.

In BIG-IP 21.1.x, declaration deployments are processed synchronously. Asynchronous task handling is not supported for application service deployments in this release.

Example declaration submission:

POST https://<BIG-IP>/mgmt/tm/sys/app-service

{
  "name": "my_app",
  "partition": "Common",
  "resources": [
    {
      "kind": "tm:ltm:pool",
      "properties": {
        "name": "pool_01",
        "loadBalancingMode": "round-robin",
        "members": [
          {
            "name": "/Common/10.0.0.10:443",
            "ratio": 1,
            "state": "user-up"
          }
        ]
      }
    },
    {
      "kind": "tm:ltm:virtual",
      "properties": {
        "name": "virtual_01",
        "destination": "10.1.1.10:443",
        "mask": "255.255.255.255",
        "pool": "pool_01",
        "ipProtocol": "tcp"
      }
    }
  ]
}

Example successful response:

{
  "name": "my_app",
  "partition": "Common",
  "resources": [
    {
      "kind": "tm:ltm:pool",
      "properties": {
        "loadBalancingMode": "round-robin",
        "members": [
          {
            "name": "/Common/10.0.0.10:443",
            "ratio": 1,
            "state": "user-up"
          }
        ],
        "name": "pool_01"
      }
    },
    {
      "kind": "tm:ltm:virtual",
      "properties": {
        "destination": "10.1.1.10:443",
        "ipProtocol": "tcp",
        "mask": "255.255.255.255",
        "name": "virtual_01",
        "pool": "pool_01"
      }
    }
  ]
}

Example GET request to retrieve deployed applications:

GET https://<BIG-IP>/mgmt/tm/sys/app-service

Example response:

[
  {
    "name": "/Common/my_app",
    "partition": "Common"
  }
]

Error Responses

The Declarative Deployment API uses standard HTTP status codes to indicate request and deployment status.

Error responses may include validation details, deployment failure information, or resource-specific error messages.

Example error response for an existing application:

{
  "code": 422,
  "message": "Failed to create application service: application service my_app already exists, please use the update operation instead"
}

Example error response for deleting a non-existing application:

{
  "code": 404,
  "message": "Failed to delete application service: requested application instance (foo) was not found"
}

In BIG-IP 21.1.x, validation failures and deployment errors are returned synchronously through standard HTTP responses. Error handling and validation responses may be enhanced in future releases.

Verify Deployment

After submitting the declaration:

1. Log in to the BIG-IP Configuration utility
2. Navigate to Local Traffic → Virtual Servers
3. Confirm the service virtual server exists
4. Verify pool members are healthy

Tip: Use both the UI and API responses to validate deployment success.

Troubleshooting Failed Deployments

If a declaration deployment fails:

• Verify the JSON syntax is valid.
• Confirm authentication credentials and permissions.
• Ensure referenced resources and dependencies are correctly defined.
• Validate resource kinds and property names.
• Review deployment response payloads for validation or processing errors.
• Review BIG-IP REST framework and deployment service logs.

Common troubleshooting log locations include:

/var/log/restjavad.* /var/log/ltm /var/log/declared.log

The Declarative Deployment API does not currently provide customer-accessible OpenAPI specifications or pre-deployment schema validation for BIG-IP 21.1.x.

Use release-specific documentation and validated example declarations when developing and troubleshooting deployments.

Supported Declaration Examples

The Declarative Deployment API supports multiple deployment scenarios for BIG-IP LTM resources.

Validated declaration examples for the initial release include scenarios such as:

• HTTP and HTTPS virtual server deployments
• TCP and UDP application services
• FastL4 configurations
• DNS and LDAP virtual services
• RADIUS and SIP application examples
• SSL profile and cipher configurations
• Analytics profile integration
• Persistence profile configuration
• iRule attachment
• Classification profile configuration
• Multi-monitor and advanced TCP profile configurations
• Deployments in non-Common partitions

Available examples may include combinations of:

• virtual servers
• pools
• nodes
• monitors
• SSL profiles
• TCP, UDP, and FastL4 profiles
• analytics profiles
• persistence profiles
• iRules
• virtual address configurations

Validated declaration examples for supported BIG-IP releases are provided through release documentation and associated example content.

Examples for BIG-IP 21.1.x includes application service deployments and protocol-specific configurations such as HTTP, HTTPS, TCP, UDP, SIP, DNS, LDAP, RADIUS, analytics, persistence, SSL, cipher, and classification profile use cases.

Security Policy and WAF Guidance

BIG-IP 21.1.x does not support attaching WAF or security policies through Declarative Deployment API declarations.

Security-related configurations and policy deployment workflows are not supported in the initial Early Access (EA) release of the Declarative Deployment API.

Customers requiring WAF or security policy deployment should use the supported BIG-IP configuration workflows and release-specific product documentation.

Known Limitations

The Declarative Deployment API is an Early Access (EA) feature in BIG-IP 21.1.x and is intended for evaluation and development use cases.

Current limitations include:

• API endpoints and schema definitions may change between releases.
• Resource coverage is limited to the BIG-IP object types and deployment scenarios validated for the current release.
• Declaration formats and supported properties may evolve in future releases.
• Backward compatibility between releases is not guaranteed for the Early Access release.
• Some advanced BIG-IP features or integrations may not yet have validated declarative deployment support.
• Operational behaviour, validation responses, and supported workflows may vary by BIG-IP release.
• WAF and security policy deployment are not supported in BIG-IP 21.1.x Declarative Deployment API workflows.

Customers should use release-specific documentation and validated example declarations when developing declarative automation workflows.