Skip to main content

REST API Developer Guide 22.2

Virtual Services and Service Bindings

This Public Stable API gives you the ability to write rules on a per-service basis instead of having to write rules that apply to all the services running on a workload. By binding a workload to individual services, you can isolate one or more services running on a workload and create policies specific to those services. By binding services, you have the flexibility to create a finely-grained, highly-segmented security policy.

Once you have created, provisioned, and bound a virtual service to a specific workload, you can use the virtual service in rules.

Virtual Services

Virtual services can consist of either a single service or a collection of explicitly enumerated port/port range and protocol tuples. They can be used directly in a rule as a single entity, or labels that represent multiple virtual services can be used to write rules.

Virtual services are dynamically bound to workloads using service bindings. Create a virtual service, and then use a service binding to bind the specific virtual service to a workload. Rules written using a virtual service only apply to the workload to which the service is bound.

Use virtual services in the following scenarios:

  • Apply Rules to a Single Service

    This scenario represents a service or process on a workload using a name or label. You can write a policy that allows other entities to communicate only with that single service. The policy does not need to change if the service is moved to a different workload or a new set of workloads. Only the workload bindings on the virtual service need to be changed. The PCE dynamically calculates the required rules on the updated workloads to allow this virtual service.

  • Applying Rules to one of the many Virtual Services Running on a Workload

    In this case, multiple virtual services are running on the workload, with different labels, and the rule targets a subset of those services. You can write a rule to allow other entities to communicate only with that specific service. The policy does not need to change if this service is moved to a different workload or a new set of workloads. Only the workload bindings on the virtual service need to be changed. The PCE dynamically calculates the required rules on the updated workloads to allow the virtual service.

Virtual Services API Methods

Functionality

HTTP

URI

Get a collection of virtual services

GET

[api_version][org_href]/sec_policy/draft/virtual_services

Get an individual virtual service

GET

[api_version][org_href]/sec_policy/draft/virtual_services/virtual_service_id

Create a new virtual service

POST

[api_version][org_href]/sec_policy/ draft/virtual_services

Create a collection of virtual services

PUT

[api_version][org_href]/sec_policy/ draft/virtual_services/bulk_create

Update a virtual service

PUT

[api_version][org_href]/sec_policy/ draft/virtual_services/virtual_service_id

Update a collection of virtual services

PUT

[api_version][org_href]/sec_policy/ draft/virtual_services/bulk_update

Delete a virtual service

DELETE

[api_version][org_href]/sec_policy/ draft/virtual_services/virtual_service_id

Active vs. Draft Policy Items

Because virtual services are policy items, changes made to them must be provisioned before they can take effect on your policy. Policy items always exist in either a draft (not provisioned) or active (provisioned) state.

Security policy items that must be provisioned to take effect include IP lists, rulesets, rules, services, virtual services, label groups, user groups, virtual servers, and PCE security settings.

For these items, the URL of the API call must include the URI element called :pversion, which can be set to either draft or active when you make the API call.

Depending on the method, the API follows these rules:

  • For GET operations — :pversion can be draft or active

  • For POST, PUT, DELETE — :pversion can only be draft (you cannot operate on provisioned items)

Virtual Services Parameters

Parameter

Description

Type

Required

org_id

(GET, POST, PUT, DELETE) Organization

Integer

Yes

virtual_service_id

Virtual Service ID

(POST, PUT, DELETE)

(GET only for [api_version][org_href]/sec_policy/draft/virtual_services/virtual_service_id)

String

Yes

pversion

(GET, POST, PUT, DELETE) Security policy version

String

Yes

description

(GET, POST, PUT) Filtering description. Supports partial matches.

String

No

external_data_reference

(GET, POST, PUT) 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

no

external_data_set

(GET, POST, PUT) 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

No

labels

(GET, POST, PUT) List of lists of label URIs encoded as a JSON

string data type.

String

no

max_results

(GET) Maximum number of results to return.

Maximum limit for returned virtual services is 500.

If not specified, or a value greater than 500 is

specified, the API returns a maximum of 500 results.

Integer

no

name

(GET, POST) Name on which to filter. This parameter supports

partial matches.

String

Yes

service

(GET, POST) Service URI

String

No

service_address.fqdn

(GET) FQDN configured under service_address property, supports partial matches

String

No

service_address.ip

(GET) IP address configured under service_address property, supports partial matches

String

No

service_ports_port

(GET) Specify a port or a port range to filter results.

The range is from -1 to 65535.

String

No

service_ports.proto

(GET) Protocol to filter on.

Integer

No

usage

(GET) Include virtual service usage flags.

Boolean

No

service_ports

(POST, PUT) Service ports are:

  • port: Port Number (integer 0-65535 or -1 for any port).

    Also, the starting port when specifying a range.

  • to_port: High end of the port range inclusive if

    specifying a range. Do not send this parameter if you are

    not specifying a range.

Object

Integer

Integer

No

No

No

service_addresses

(POST, PUT) Configured under the property service_address.

  • ip: IP address to assign to the virtual service

  • network: Network URI for this IP address

  • port: Port associated with the IP address for the service

    (1-65535)

  • fqdn: FQDN to assign to the virtual service

Either ip or port can be specified, but not both.

If ip is specified, either network or port must be specified;

port cannot be used with network.

Object

String

String

Integer

String

No

No

No

No

No

apply_to

(POST, PUT) Allows you to choose if you want the rules associated with

the virtual service to be enforced over a host or bridge network.

  • internal_bridge_network: Virtual service rules are applied

    to a bridge network, interpreted in the FORWARD chain on Linux iptables

    (Windows platform is not supported in this release.)

  • host_only: Virtual service rules are enforced on the host,

    interpreted by the INPUT/OUTPUT chains in Linux iptables.

String

No

ip_overrides

(POST, PUT) Allows you to specify IP addresses or ranges (CIDR blocks)

to use for programming the rules associated with the virtual service,

instead of the IP address of the bound workload.

This parameter is similar to service_addresses but the ips

do not have associated ports or networks.

String

No

Get Collection of Virtual Services

Use this method to get a collection of Virtual Services.

URI to Get a Collection of Virtual Services

GET [api_version][org_href]/sec_policy/draft/virtual_services

Curl Command

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/
	dc82e7e8-7304-4a25-9f49-97e11d7de5d0",
    "created_at": "2015-10-27T14:34:42.941Z",
    "updated_at": "2015-10-27T14:34:42.941Z",
    "deleted_at": null,
    "created_by": { "href": "/users/14" },
    "updated_by": { "href": "/users/14" },
    "deleted_by": null,
    "update_type": null,
    "name": "Tomcat",
    "description": null,
    "service": { "href": "/orgs/7/sec_policy/draft/services/101" },
    "labels": [{ "href": "/orgs/7/labels/82" }],
    "ip_overrides": [],
    "apply_to": "host_only"
  },
  {
    "href": "/orgs/7/sec_policy/draft/virtual_services/256525b6
	-e7c5-4ad7-b7af-e70586aa1078",
    "created_at": "2016-06-23T00:33:58.995Z",
    "updated_at": "2016-06-23T00:33:58.995Z",
    "deleted_at": null,
    "created_by": { "href": "/users/54" },
    "updated_by": { "href": "/users/54" },
    "deleted_by": null,
    "update_type": null,
    "name": "Example",
    "description": null,
    "service": { "href": "/orgs/7/sec_policy/draft/services/107" },
    "labels": [],
    "ip_overrides": [],
    "apply_to": "internal_bridge_network"
  },
  {
    "href": "/orgs/7/sec_policy/draft/virtual_services/7b46fce0
	-4933-4e29-b86c-7a2a71e686ed",
    "created_at": "2016-05-31T18:19:43.467Z",
    "updated_at": "2016-05-31T18:19:43.467Z",
    "deleted_at": null,
    "created_by": { "href": "/users/54" },
    "updated_by": { "href": "/users/54" },
    "deleted_by": null,
    "update_type": null,
    "name": "test",
    "description": null,
    "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" }
    ],
    "ip_overrides": [
      "192.0.1.3",
      "192.168.100.0/24"
    ],
    "apply_to": "host_only"
  },
  {
    "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"
  }
]
Get an Individual Virtual Service

Use this method to get an individual virtual service. In the call, you identify the virtual service by its HREF, which can be obtained when you get a collection of virtual services.

Use the following query parameters to restrict the results of the query:

URI to Get an Individual Virtual Service

GET [api_version][virtual_service_href]

Note

For this method, you can get 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"
  }
Create an Individual Virtual Service

Use this method to create an individual virtual service. Because a virtual service is a policy item, you must create it in the draft state, and then provision the change using the Security Policy API.

Once the virtual service is provisioned, you can use the service binding method to bind the virtual service to a workload.

URI to Create an Individual Virtual Service

POST [api_version][org_href]/sec_policy/draft/virtual_services

Request Body

To create a virtual service, you need the HREF of the service you want to “bind” to a workload. You can obtain a service HREF by calling a GET collection with the service binding API.

Additionally, if you want to add labels to the virtual service, you need the HREF of each label you want to add. Label HREFs can be obtained by calling a GET collection with the labels API. Labels are represented in the JSON request body as an array, opened and closed by square brackets ([ ]).

{ 
  "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" }]}'
Create or Update Virtual Services Collection

This method enables you to create a collection of virtual services in your organization using a single API call instead of creating individual services one at a time.

This capability is useful if you want to keep a set of PCE resources in sync with your internal representation of the resources, such as a configuration management database (CMDB) that holds the “source of truth” for your PCE resources.

After virtual services are created and the identifiers added to the service properties, you can get a collection of virtual services using query parameters that include the external data reference. You can also run an asynchronous query to get all virtual services through an offline job, which includes the external data references in the response.

The two properties you can use when creating virtual services, external_data_set and external_data_reference are UTF-8 strings with a maximum length of 255 characters each. The contents must form a unique composite key, meaning that both values of these properties are treated as a unique key. These two properties together are recognized as a unique key, even if one of them is left blank or set to zero.

URI to Create a Collection of Virtual Services

PUT [api_version][org_href]/sec_policy/draft/virtual_services/bulk_create

URI to Update a Collection of Virtual Services

PUT [api_version][org_href]/sec_policy/draft/virtual_services/bulk_update

Request Body

To create a collection of virtual services, pass a JSON object that describes the virtual service details. The request body and curl command for this method follow the same structure used to create an individual virtual service, only you add multiple virtual service JSON objects instead of just one.

Additionally, the href field must be present in the body for each virtual service that you are updating in the bulk_update.

Note

Bulk operations are rate-limited to 1,000 items per operation.

Update a Individual Virtual Service

To update (PUT) an individual virtual service, you need to know the HREF of the virtual service you want to update. Virtual service HREFs are returned when you get a collection of virtual services.

URI to Update an Individual Virtual Service

PUT [api_version][org_href]/sec_policy/draft/virtual_services/virtual_service_id

Request Properties

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

After you create a virtual service and provision it, use the service binding API to bind the virtual service to a workload. When you apply your policy to a virtual service, the virtual service must be bound to a workload where that service is running. You can only specify one workload and one virtual service per service binding.

When you bind a virtual service to a workload with a service binding, you must specify the workload to which you want to bind the service. You can also optionally specify any port overrides if you want the virtual service to communicate over a different port than the default.

Unlike virtual services, the service binding API does not require provisioning to take effect.

Note

Updating service bindings doesn't use a PUT method. To update it, delete it, and then POST a new service binding to replace it.

Service Binding API Methods

Functionality

HTTP

URI

Get a collection of service bindings

GET

[api_version][org_href]/service_bindings

Get an individual service binding

GET

[api_version][service_binding_href]

Create a service binding

POST

[api_version][org_href]/service_bindings

Delete an individual service binding

DELETE

[api_version][service_binding_href]

Service Bindings Parameters

Parameter

Description

Type

Required

org_id

(GET, POST, DELETE) Organization

Integer

Yes

service_binding_id

Service Binding ID

( DELETE)

(GET only for [api)_version][service_binding_href])

String

Yes

external_data_reference

(GET) 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

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

String

No

max_results

The maximum number of results you want to return when using the GET method. The maximum limit for returned service bindings is 500.

If this parameter is not specified, or a value greater than 500 is specified, a maximum of 500 results are returned. To get more than 500 results, use an Asynchronous GET Collection.

Integer

No

virtual_service

(GET) Virtual service URI

String

Noi

workload

(GET) The complete HREF of the workload referenced in the service binding.

String

No

Create a Service Binding

This method creates one or more service bindings, which associate (or “bind”) a virtual service to a workload. When you call this method, you specify the virtual service and workload you want to bind, plus you can optionally specify port overrides to use a different port for the service.

The JSON request body for creating a service binding is an array, which allows you to create multiple service bindings with a single POST.

Before you create a service binding, make sure that the virtual service you want to bind to a workload has been published and is in the active policy state.

URI to Create a Service Binding

POST [api_version][org_href]/service_bindings

Request Parameters

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

Make sure that the virtual service you are binding 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}" } ]
Get Individual or Collection of Service Bindings

You can use these methods to get one or more service bindings.

URI to Get a Collection of Service Bindings

GET [api_version][org_href]/service_bindings

URI to Get an Individual Service Binding

GET [api_version][service_binding_href]

Response Body

[ 
   {
     "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
Delete an Individual Service Binding

To delete both the service bindings and virtual services, delete the service bindings first, then delete the virtual services.

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: