Virtual Services
This Public Stable API allows you to write rules per service 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.
You can use it in rules once you have created, provisioned, and bound a virtual service to a specific workload. See Create an Individual Virtual Service.
About Virtual Services
Virtual services can consist of 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 representing 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, identified by 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 run on the workload, each with a different label, and the rule targets a subset of these 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 for the updated workloads to allow virtual services.
Virtual Services API Methods
Functionality | HTTP | URI |
|---|---|---|
Get a collection of virtual services. |
|
|
Get an individual virtual service. |
|
|
Create a new virtual service. |
|
|
Create a collection of virtual services. |
|
|
Update a virtual service. |
|
|
Update a collection of virtual services. |
|
|
Delete a virtual service. |
|
|
Active vs. Draft Policy Items
Because virtual services are policy items, changes 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 —
:pversioncan bedraftoractive.For POST, PUT, DELETE —
:pversioncan only bedraft(you cannot operate on provisioned items)
Get a 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/:pversion/virtual_services
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.
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
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 ([ ]).
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 those resources, such as a configuration management database (CMDB) that serves as the “source of truth” for your PCE resources.
After creating virtual services and adding identifiers to the service properties, you can collect 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. Together, these two properties are recognized as unique keys, even if one 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 details of the virtual service. This method's request body and curl command follow the same structure used to create an individual virtual service; you only add multiple virtual service JSON objects instead of just one.
Additionally, the href field must be present in the body for each virtual service you update in the bulk_update.
Note
Bulk operations are rate-limited to 1,000 items per operation.
Update an 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
Virtual Services and Bindings Reference
This topic covers properties and examples of virtual services and bindings.
Virtual Services Query Parameters
Property | Description | Type | Required |
|---|---|---|---|
| Organization ID | Integer | Yes |
| Security Policy Version | String | Yes |
| 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 | |
| The data source from which the resource originates. For example, if this virtual service information is stored in an external database. | String | |
| Name on which to filter. Supports partial matches | String | No |
| List of lists of label URIs, encoded as a JSON string | String | No |
| Virtual Service ID | String | Yes |
| Service URI | String | No |
| Specify port or port range to filter results. The range is from -1 to 65535. | String | No |
| Protocol to filter on. | Integer | No |
| FQDN configured under service_address property supports partial matches | String | No |
| The IP address configured under the service_address property supports partial matches | String | No |
| Include Virtual Service usage flags. | Boolean | No |
Virtual Services Properties
Property | Description | Type |
|---|---|---|
| URI of the virtual service | String |
| Timestamp when this virtual service was first created | String date/time |
| Timestamp when this virtual service was last updated | String date/time |
| Timestamp when this virtual service was deleted | String/NULL date/time |
| Name (does not need to be unique) | String |
| Virtual service labels References | |
| Update type for the virtual service Reference to | |
| 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 |
| 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 |
| Reference to | |
| 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 |
|---|---|---|---|
| Organization ID | Integer | Yes |
| Virtual service href | String | No |
| Service Binding ID | String | Yes |
| The complete HREF of the workload referenced in the service binding. | String | No |
| A unique identifier within the external data source. For example, if this virtual service information is stored in an external database. | String | No |
| 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 href, required for POST | Object |
| Bound service href, required for GET | Object |
| The complete HREF of the workload referenced in the service binding. | String |
| Reference to | |
| A unique identifier within the external data source. For example, if this virtual service information is stored in an external database. | String, NULL |
| The data source from which the resource originates. For example, if this virtual service information is stored in an external database. | String, NULL |
| 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