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 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 run 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 for the updated workloads to allow virtual service.
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 bedraftoractiveFor 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 the resources, such as a configuration management database (CMDB) that holds 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