Skip to main content

REST APIs for 24.2.20 and 24.2.10

Virtual Services and Bindings Reference

This topic covers properties and examples of virtual services and bindings.

Virtual Services Query Parameters

Property

Description

Type

Required

org_id

Organization ID

Integer

Yes

pversion

Security Policy Version

String

Yes

external_data_reference

A unique identifier within the external data source.

For example, if this virtual service information is stored in an external database.

String,

NULL for PUT only

external_data_set

The data source from which the resource originates.

For example, if this virtual service information is stored in an external database.

String

name

Name on which to filter. Supports partial matches

String

No

labels

List of lists of label URIs, encoded as a JSON string

String

No

virtual_service_id

Virtual Service ID

String

Yes

service

Service URI

String

No

service_ports.port

Specify port or port range to filter results. The range is from -1 to 65535.

String

No

service_ports.proto

Protocol to filter on.

Integer

No

service_address.fqdn

FQDN configured under service_address property supports partial matches

String

No

service_address.ip

The IP address configured under the service_address property supports partial matches

String

No

usage

Include Virtual Service usage flags.

Boolean

No

Virtual Services Properties

Property

Description

Type

href

URI of the virtual service

String

created_at

Timestamp when this virtual service was first created

String

date/time

updated_at

Timestamp when this virtual service was last updated

String

date/time

deleted_at

Timestamp when this virtual service was deleted

String/NULL

date/time

name

Name (does not need to be unique)

String

labels

Virtual service labels

References common/label_optional_key_value.schema.json

update_type

Update type for the virtual service

Reference to common/sec_policy_update_type.schema.json

external_data_set

The data source from which the resource originates.

For example, if this virtual service information is stored in an external database.

String,

NULL for PUT only

external_data_reference

A unique identifier within the external data source.

For example, if this virtual service information is stored in an external database.

String,

NULL for PUT only

service_addresses

Reference to virtual_service_service_addresses.schema.json

ip_overrides

Array of IPs or CIDRs as IP overrides

Curl command to get a collection of virtual services

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/7/sec_policy/active/virtual_services -H "Accept: application/json" -u $KEY:$TOKEN

Response

Each individual virtual service returned is identified by the virtual service HREF. To GET, PUT, or DELETE an individual virtual service, identify the service by its HREF in the API call.

[
  {
    "href": "/orgs/7/sec_policy/draft/virtual_services/1828d8ff-aeb7-4735-9975-db692813d193",
    "created_at": "2017-10-29T19:41:15.648Z",
    "updated_at": "2017-10-29T19:41:15.648Z",
    "deleted_at": null,
    "created_by": {"href": "/users/14"},
    "updated_by": {"href": "/users/14"},
    "deleted_by": null,
    "update_type": null,
    "name": "Jawoo",
    "description": null,
    "service": { "href": "/orgs/7/sec_policy/draft/services/99" },
    "labels": [
      { "href": "/orgs/7/labels/88" },
      { "href": "/orgs/7/labels/82" },
      { "href": "/orgs/7/labels/92" },
      { "href": "/orgs/7/labels/101" }
    ],
    "ip_overrides": [
      "192.0.1.0",
      "192.168.100.0/24"
    ],
    "apply_to": "host_only"
  }
]

URI to Get an Individual Virtual Service

GET [api_version][virtual_service_href]

Note

For this method, you can specify either draft or active for :pversion.

Curl Command

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/virtual_services/89 -H "Accept: application/json" -u $KEY:$TOKEN

Response

{
    "href": "/orgs/2/sec_policy/draft/virtual_services/6005a35a-1598-4c7b-a827-be4390f46773",
    "created_at": "2017-12-11T20:56:28.629Z",
    "updated_at": "2017-12-11T21:07:10.407Z",
    "deleted_at": null,
    "created_by": { "href": "/users/9" },
    "updated_by": { "href": "/users/9" },
    "deleted_by": null,
    "update_type": "create",
    "name": "Docker1",
    "description": null,
    "service": { "href": "/orgs/2/sec_policy/draft/services/5" },
    "labels": [
      { "href": "/orgs/2/labels/18" },
      { "href": "/orgs/2/labels/26" },
      { "href": "/orgs/2/labels/126" }
    ],
    "ip_overrides": [
      "192.0.1.0",
      "192.168.100.0/24"
    ],
    "apply_to": "internal_bridge_network"
  }

Request Body for an Individual Virtual Service

{ 
  "name": "MyVirtualService", 
  "description": "Test",
  "service": { "href": "/orgs/7/sec_policy/draft/services/218" }, 
  "labels": [ 
    { "href": "/orgs/7/labels/88" }, 
    { "href": "/orgs/7/labels/82" }, 
    { "href": "/orgs/7/labels/92" }, 
    { "href": "/orgs/7/labels/95" } 
  ] 
}

Curl Command to create a new virtual service:

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/virtual_services -H "Content-Type: application/json" -u $KEY:$TOKEN.-d '{ "name": "MyVirtualService", "description": "Test", "service": {"href": "/orgs/7/sec_policy/draft/services/218"}, "labels": [{"href": "/orgs/7/labels/88"}, {"href": "/orgs/7/labels/82"}, {"href": "/orgs/7/labels/92"}, {"href": "/orgs/7/labels/95" }]}'
Request Properties for updating a virtual service

The request properties for updating a virtual service are the same as those for creating a virtual service.

Request Body

This example request body can be passed to update a virtual service to include a workload binding:

{
  "service": { "href": "/orgs/2/sec_policy/draft/services/91" },
  "labels": [ 
    { "href": "/orgs/2/labels/316" },
    { "href": "/orgs/2/labels/101" },
    { "href": "/orgs/2/labels/102" },
    { "href": "/orgs/2/labels/103" }
  ]
}

Curl Command

curl -i -X PUT https://pce.my-company.com:8443/api/v2/orgs/2/sec_policy/draft/virtual_services/256525b6-e7c5-4ad7-b7af-e70586aa1078 -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"name":"test","description":null,"service":{"href":"/orgs/2/labels/316"},"labels": [{"href":"/orgs/2/labels/101"}, {"href":"/orgs/2/labels/102"}, {"href":"/orgs/2/labels/103"}]}'
Service Bindings Query Parameters

Parameter

Description

Type

Required

org_id

Organization ID

Integer

Yes

virtual_service

Virtual service href

String

No

service_binding_id

Service Binding ID

String

Yes

workload

The complete HREF of the workload referenced in the service binding.

String

No

external_data_reference

A unique identifier within the external data source. For example, if this virtual service information is stored in an external database.

String

No

external_data_set

The data source from which the resource originates. For example, if this virtual service information is stored in an external database.

String

No

Service Bindings Properties

Property

Description

Type

virtual_service

Virtual service href, required for POST

Object

bound_serviuce

Bound service href, required for GET

Object

workload

The complete HREF of the workload referenced in the service binding.

String

port_overrides

Reference to port_overrides.schema.json

external_data_reference

A unique identifier within the external data source. For example, if this virtual service information is stored in an external database.

String, NULL

external_data_set

The data source from which the resource originates. For example, if this virtual service information is stored in an external database.

String, NULL

workload

HREF of the workload

String

Request Parameters to create a service binding

The request body for creating a service binding is an array of service binding objects. Because this JSON request body is an array, you can create multiple service bindings in a single POST.

Note

Ensure that the virtual service you bind to a workload has been provisioned.

This is an example JSON representation of a single service binding:

[{"workload": {"href": "/orgs/1/workloads/45c69cf3-4cbb-4c96-81ee-70e94baea1b8"}, "virtual_service": {"href": "/orgs/1/sec_policy/draft/virtual_services/a735332e-5d31-4899-a3a5-fac7055e05c0"}, "port_overrides": [{"port": 14000, "protocol": 6, "new_port": 26000 }]}]

Curl Command

To create a single service binding:

curl -i -X POST https://pce.my-company.com:8443/api/v2/orgs/2/service_bindings -H "Content-Type:application/json" -u $KEY:$TOKEN -d '[{"workload":{"href":"/orgs/1/workloads/45c69cf3-4cbb-4c96-81ee-70e94baea1b8"}, "virtual_service":{"href":"/orgs/1/sec_policy/draft/virtual_services/a735332e-5d31-4899-a3a5-fac7055e05c0"}, "port_overrides":[{"port":14000,"protocol":6,"new_port":26000}]}]'

Request Body to Create Multiple Service Bindings

An example JSON request body for creating multiple service bindings with a different port number:

[{"workload": {"href": "/orgs/1/workloads/820efcdc-c906-46b9-9729-26bab7a53223"}, "virtual_service": {"href": "/orgs/1/sec_policy/draft/virtual_services/e38ce044-d2ac-4d7f-aeec-16ef8fbd0b15"}, "port_overrides": [ {"port": 10000, "protocol": 6, "new_port": 26000 } ]}, {"workload": {"href": "/orgs/1/workloads/820efcdc-c906-46b9-9729-26bab7a53223"}, "virtual_service": {"href": "/orgs/1/sec_policy/draft/virtual_services/e38ce044-d2ac-4d7f-aeec-16ef8fbd0b15"}, "port_overrides": [ {"port": 11000, "protocol": 6, "new_port": 25000} ]}]

Service Binding Request Body

If you create more than one service binding with a single POST, all of the service bindings must be constructed properly or the POST will fail and no service bindings will be created.

Note

The response of “failure” indicates the error, but it does not confirm that no service bindings have been created.

For example, if you use POST to create 10 service bindings and one of the workloads referenced in the JSON payload uses an incorrect URI (HREF), the POST fails with an error message similar to the following message:

[ { "token": "invalid_uri", "message": "Invalid URI: {/orgs/1/workloadzzz/820efcdc-c906-46b9-9729-26bab7a53223}" } ]

Response Body to get individual or collection of Service Bindings

[ 
   {
     "href": "/orgs/7/service_bindings/287568ad-4a1f-4000-a9fb-e67d1dabce15", 
     "virtual_service": {"href": "/orgs/7/sec_policy/active/virtual_services/256525b6-e7c5-4ad7-b7af-e70586aa1078"}, 
     "workload": {"href": "/orgs/7/workloads/baef2547-2036-4e00-b6f7-3f4be1f7669a", 
     "name": null, 
     "hostname": "AssetMgt-proc2", 
     "deleted": false }, 
     "port_overrides": [{"new_port": 8080,"protocol": 6,"port": 3306}]
     }, 
        {
           "href": "/orgs/7/service_bindings/faebe7bf-0bb7-49a5-868e-8297e038fa9e", 
           "virtual_service": {"href": "/orgs/7/sec_policy/active/virtual_services/7b46fce0-4933-4e29-b86c-7a2a71e686ed"}, 
           "workload": {"href": "/orgs/7/workloads/aee4381b-9836-45b6-b7ab-aee246bf482f", 
           "name": null, 
           "hostname": "onlinestore-web2", 
           "deleted": false }, 
           "port_overrides": [] 
         },
         {
           "href": "/orgs/7/service_bindings/924ad8c2-94bf-40f5-bc4c-13474982bd00", 
           "virtual_service": {"href": "/orgs/7/sec_policy/active/virtual_services/256525b6-e7c5-4ad7-b7af-e70586aa1078"}, 
           "workload": {"href": "/orgs/7/workloads/69fd736b-cd21-4a4c-bdb9-132207c760ce", 
           "name": null, 
           "hostname": "test-us", 
           ": false }, 
           "port_overrides": [] 
         }
]

Curl Command to Get an Individual Service Binding

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/service_bindings/xxxxxxxx-4a86-4dd4-b303-23f699d0ebbf -H "Accept: application/json" -u $KEY:$TOKEN

Curl Command to Get Service Binding Collection

curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/2/service_bindings -H "Accept: application/json" -u $KEY:$TOKEN

URI to Delete an Individual Service Binding

DELETE [api_version][service_binding_href]

Curl Command to Delete a Service Binding

Use this curl command to delete the service binding:

curl -i -X DELETE https://pce.my-company.com:8443/api/v2/orgs/2/service_bindings/xxxxxxxx-4a86-4dd4-b303-23f699d0ebbf -u $KEY:$TOKEN
See also: