redocly logoAPI docs by Redocly

F5 Distributed Cloud Services API for ves.io.schema.virtual_k8s

Download OpenAPI specification:Download

Virtual K8s object exposes a Kubernetes API endpoint in the namespace that operates on all the physical Kubernetes clusters in each of the sites that are selected by the virtual-site referred to in the object.

Virtual K8s supports only a subset of Kubernetes APIs related to application management.

Read and write operations are currently supported on the following Kubernetes API resources:

  1. Deployment v1 apps
  2. StatefulSet v1 apps
  3. DaemonSet v1 apps
  4. Job v1 batch
  5. CronJob v1beta1 batch
  6. Service v1 core with type ClusterIP
  7. Secret v1 core
  8. ConfigMap v1 core
  9. ServiceAccount v1 core
  10. PersistentVolumeClaim v1 core

Only delete is supported on Pod v1 core.

Read only operations are currently supported on the following Kubernetes API resources:

  1. Pod v1 core
  2. ReplicaSet v1 apps
  3. Endpoints v1 core
  4. Node v1 core
  5. Namespace v1 core
  6. PersistentVolume v1 core
  7. Event v1 core

The semantics of using Kubernetes APIs on a Virtual K8s object are different compared to those on a single Kubernetes cluster since the Kubernetes resource objects created using the Virtual K8s API will be instantiated in all the physical Kubernetes clusters in each of the sites selected by the virtual-site referred to in the object. In a single Kubernetes cluster, when a Deployment resource is created with Replicas set to 3, the expectation is that 3 Pods will be created on the Kubernetes cluster. On the Virtual K8S API, when a Deployment resource is created with Replicas set to 3, the total number of Pods created is equal to the number of Replicas times the number of physical clusters in each of the sites selected by the referred to virtual-site. For example, if the virtual-site associated with Virtual K8s object selects 3 sites each having 1 physical Kubernetes cluster, then the total number of Pods created will be 9.

Kubernetes API resource objects can also be created with the annotation ves.io/virtual-sites=/ and those objects will be instantiated in all physical Kubernetes clusters in each of the sites selected by the virtual-site specified in the annotation only and not using the virtual-site specified in the Virtual K8s object. This provides an override mechanism to select different virtual-sites for the Kubernetes API resource to be instantiated on. The virtual-site referred to in the Virtual K8s can hence be thought of as the default virtual-site for all the Kubernetes API resource objects created on the Virtual K8s API without the above annotation.

Create Virtual Kubernetes

Create virtual_k8s will create the object in the storage backend for namespace metadata.namespace

Examples of this operation
path Parameters
metadata.namespace
required
string

namespace

x-example: "staging" This defines the workspace within which each the configuration object is to be created. Must be a DNS_LABEL format. For a namespace object itself, namespace value will be ""

Request Body schema: application/json
required
object (ObjectCreateMetaType)

ObjectCreateMetaType is metadata that can be specified in Create request of an object.

object (Create Virtual K8s)

Create virtual_k8s will create the object in the storage backend for namespace metadata.namespace

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{
  • "metadata": {
    },
  • "spec": {
    },
  • "system_metadata": {
    }
}

Replace Virtual Kubernetes

Replacing an endpoint object will update the object by replacing the existing spec with the provided one. For read-then-write operations a resourceVersion mismatch will occur if the object was modified between the read and write.

Examples of this operation
path Parameters
metadata.namespace
required
string

namespace

x-example: "staging" This defines the workspace within which each the configuration object is to be created. Must be a DNS_LABEL format. For a namespace object itself, namespace value will be ""

metadata.name
required
string

name

x-example: "acmecorp-web" The configuration object to be replaced will be looked up by name

Request Body schema: application/json
required
object (ObjectReplaceMetaType)

ObjectReplaceMetaType is metadata that can be specified in Replace request of an object.

object (Replace Virtual K8s)

Replacing an endpoint object will update the object by replacing the existing spec with the provided one. For read-then-write operations a resourceVersion mismatch will occur if the object was modified between the read and write.

Responses

Request samples

Content type
application/json
{
  • "metadata": {
    },
  • "spec": {
    }
}

Response samples

Content type
application/json
{ }

PVC Metrics

API to get PVC capacity/usage.

Examples of this operation
path Parameters
namespace
required
string

Namespace

x-example: "ns1"

Request Body schema: application/json
required
end_time
string (End time)

end time of metric collection from which data will be considered to build graph. Format: unix_timestamp|rfc 3339

Optional: If not specified, then the end_time will be evaluated to start_time+10m If start_time is not specified, then the end_time will be evaluated to

Example: "1570197600"

Validation Rules: ves.io.schema.rules.string.query_time: true

field_selector
Array of strings (Field Selector) [ 1 .. 8 ] items
Items Enum: "PVC_USAGE" "PVC_CAPACITY"

Select fields to be returned in the response. One or more fields in {PVC_USAGE, PVC_CAPACITY} can be specified.

Required: YES

Validation Rules: ves.io.schema.rules.message.required: true ves.io.schema.rules.repeated.max_items: 8 ves.io.schema.rules.repeated.min_items: 1 ves.io.schema.rules.repeated.unique: true

filter
string (Label Filter)

filter is used to specify the list of matchers syntax for filter := {[]} :=

Optional: If not specified, metric will be aggregated based on the group_by labels.

Example: "{PVC=\"pvc-1\"}"

group_by
Array of strings (Group by)
Items Enum: "NAMESPACE" "PVC" "SITE"

Aggregate data by zero or more labels {NAMESPACE, PVC, SITE}

namespace
string (Namespace)

Example: "ns1"

range
string (Range)

range decides how far to go back in time to fetch values for each step. For example, if the range is 5m, then for step t1, query will be evaluated for t1-5m and for t2, query will be evaluated for t2-5m and so on. Format: [0-9][smhd], where s - seconds, m - minutes, h - hours, d - days

Note: For non-timeseries query, i.e., for step=end_time-start_time, range should be set to end_time-start_time

Optional: If not specified, range is set to 5m

Example: "10m"

Validation Rules: ves.io.schema.rules.string.time_interval: true

start_time
string (Start time)

start time of metric collection from which data will be considered to build graph. Format: unix_timestamp|rfc 3339

Optional: If not specified, then the start_time will be evaluated to end_time-10m If end_time is not specified, then the start_time will be evaluated to -10m

Example: "1570194000"

Validation Rules: ves.io.schema.rules.string.query_time: true

step
string (Step)

step is the resolution width, which determines the number of the data points [x-axis (time)] to be returned in the response. The timestamps in the response will be t1=start_time, t2=t1+step, ... tn=tn-1+step, where tn <= end_time. Format: [0-9][smhd], where s - seconds, m - minutes, h - hours, d - days

Optional: If not specified, then step size is evaluated to <end_time - start_time>

Example: "5m"

Validation Rules: ves.io.schema.rules.string.query_step: true

Responses

Request samples

Content type
application/json
{
  • "end_time": "string",
  • "field_selector": [
    ],
  • "filter": "string",
  • "group_by": [
    ],
  • "namespace": "string",
  • "range": "string",
  • "start_time": "string",
  • "step": "string"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "step": "string"
}

List Virtual Kubernetes

List the set of virtual_k8s in a namespace

Examples of this operation
path Parameters
namespace
required
string

namespace

x-example: "ns1" Namespace to scope the listing of virtual_k8s

query Parameters
label_filter
string

x-example: "env in (staging, testing), tier in (web, db)" A LabelSelectorType expression that every item in list response will satisfy

report_fields
Array of strings

x-example: "" Extra fields to return along with summary fields

report_status_fields
Array of strings

x-example: "" Extra status fields to return along with summary fields

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "items": [
    ]
}

Get Virtual Kubernetes

Get virtual_k8s will get the object from the storage backend for namesapce metadata.namespace

Examples of this operation
path Parameters
namespace
required
string

namespace

x-example: "ns1" The namespace in which the configuration object is present

name
required
string

name

x-example: "name" The name of the configuration object to be fetched

query Parameters
response_format
string
Default: "GET_RSP_FORMAT_DEFAULT"
Enum: "GET_RSP_FORMAT_DEFAULT" "GET_RSP_FORMAT_FOR_CREATE" "GET_RSP_FORMAT_FOR_REPLACE" "GET_RSP_FORMAT_STATUS" "GET_RSP_FORMAT_READ" "GET_RSP_FORMAT_REFERRING_OBJECTS" "GET_RSP_FORMAT_BROKEN_REFERENCES"

The format in which the configuration object is to be fetched. This could be for example - in GetSpec form for the contents of object - in CreateRequest form to create a new similar object - to ReplaceRequest form to replace changeable values

Default format of returned resource Response should be in CreateRequest format Response should be in ReplaceRequest format Response should be in StatusObject(s) format Response should be in format of GetSpecType Response should have other objects referring to this object Response should have deleted and disabled objects referrred by this object

Responses

Response samples

Content type
application/json
{
  • "create_form": {
    },
  • "deleted_referred_objects": [
    ],
  • "disabled_referred_objects": [
    ],
  • "metadata": {
    },
  • "referring_objects": [
    ],
  • "replace_form": {
    },
  • "spec": {
    },
  • "status": [
    ],
  • "system_metadata": {
    }
}

Delete Virtual Kubernetes

Delete the specified virtual_k8s

Examples of this operation
path Parameters
namespace
required
string

namespace

x-example: "ns1" Namespace in which the configuration object is present

name
required
string

name

x-example: "name" Name of the configuration object

Request Body schema: application/json
required
fail_if_referred
boolean <boolean> (fail_if_referred)

Fail the delete operation if this object is being referred by other objects

name
string (name)

Name of the configuration object

Example: "name"

namespace
string (namespace)

Namespace in which the configuration object is present

Example: "ns1"

Responses

Request samples

Content type
application/json
{
  • "fail_if_referred": true,
  • "name": "string",
  • "namespace": "string"
}

Response samples

Content type
application/json
null