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 you can obtain 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.
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 Service Bindings
After you create and provision a virtual service, 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 a service binding, 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 an individual service binding. |
|
|
Create a service binding. |
|
|
Delete an individual service binding. |
|
|
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, allowing you to create multiple service bindings with a single POST request.
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
Delete an Individual Service Binding
To delete both the service bindings and virtual services, delete the service bindings first, then delete the virtual services.
Get an Individual or a 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]