VMExpiration API

This is a reference for the OpenStack VM expiration API which is provided by the os-vm-expire project.

Vmexpires

Lists, extend, and deletes VM expirations.

All API calls described throughout the rest of this document require authentication with the OpenStack Identity service. After authentication, a base service url can be extracted from the Identity token of type vmexpire. This service url will be the root url that every API call uses to build a full path.

For instance, if the service url is http://myservice.pvt/v1/%(tenant_id)s then the full API call for /vmexpire is http://myservice.pvt/v1/%(tenant_id)s/vmexpire.

Depending on the deployment, the vmexpire service url might be http or https, a custom port, a custom path, and include your tenant id. The only way to know the urls for your deployment is by using the service catalog. The os-vm-expire URL should never be hard coded in applications, even if they are only expected to work at a single site. It should always be discovered from the Identity token.

GET
/vmexpires/

List expirations

Lists expiration info for all vmexpires in selected project.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Name In Type Description
all_tenants (Optional) path int get results for all tenants/projects, restricted to admin users

Response

Name In Type Description
vmexpires body array A list of vmexpire objects.
id body string id of the expiration.
instance_id (Optional) body string ID of the instance.
intance_name (Optional) body string Given name for the instance.
project_id body string id fo the project.
user_id (Optional) body string ID of the user owning the VM.

Example List VmExpires

{"vmexpires": [{"instance_name": "55", "updated": "2017-12-06T13:33:18", "project_id": "33", "user_id": "44", "links": {"self": "http://localhost:9311/v1/vmexpire/11"}, "created": "2017-12-06T13:33:18", "notified": false, "instance_id": "22", "expire": 1111111, "notified_last": false, "deleted_at": "2017-12-06T13:33:18", "id": "11"}], "total": 1, "links": {"self": "http://localhost:9311/v1/33/vmexpires/"}}
GET
/vmexpires/{id}

Get expiration

Get selected expiration details.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Response

Name In Type Description
vmexpire body object expiration data for an instance.
id body string id of the expiration.
instance_id (Optional) body string ID of the instance.
intance_name (Optional) body string Given name for the instance.
project_id body string id fo the project.
user_id (Optional) body string ID of the user owning the VM.

Example Get VmExpire

{"vmexpires": [{"instance_name": "55", "updated": "2017-12-06T13:33:18", "project_id": "33", "user_id": "44", "links": {"self": "http://localhost:9311/v1/vmexpire/11"}, "created": "2017-12-06T13:33:18", "notified": false, "instance_id": "22", "expire": 1111111, "notified_last": false, "deleted_at": "2017-12-06T13:33:18", "id": "11"}], "total": 1, "links": {"self": "http://localhost:9311/v1/33/vmexpires/"}}
PUT
/vmexpires/{id}

Extend expiration

Extend expiration delay for selected expiration.

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Response

Name In Type Description
vmexpire body object expiration data for an instance.
id body string id of the expiration.
instance_id (Optional) body string ID of the instance.
intance_name (Optional) body string Given name for the instance.
project_id body string id fo the project.
user_id (Optional) body string ID of the user owning the VM.
DELETE
/vmexpires/{id}

Delete expiration

Remove expiration (usually admin only according to policy.json).

Normal response codes: 204

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Response

Vmexcludes

Lists, creates, and deletes VM excludes.

All API calls described throughout the rest of this document require authentication with the OpenStack Identity service. After authentication, a base service url can be extracted from the Identity token of type vmexpire. This service url will be the root url that every API call uses to build a full path.

For instance, if the service url is http://myservice.pvt/v1/%(tenant_id)s then the full API call for /vmexpire is http://myservice.pvt/v1/%(tenant_id)s/vmexpire.

Depending on the deployment, the vmexpire service url might be http or https, a custom port, a custom path, and include your tenant id. The only way to know the urls for your deployment is by using the service catalog. The os-vm-expire URL should never be hard coded in applications, even if they are only expected to work at a single site. It should always be discovered from the Identity token.

This API is intended for administrators only. Access is restricted by policy.json.

When a VM is created, if its domain/project/user id matches an exclusion exclude_id, then no expiration is set for this VM.

GET
/vmexcludes/

List excludes

Lists excluded objects

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Response

Name In Type Description
vmexcludes body array A list of vmexclude objects.
id body string id of the exclude
exclude_id body string id of the domain/project/user to exclude
exclude_type body string type of exclusion, one of [domain, project, user]
GET
/vmexcludes/{id}

Get exclude

Get selected exclude details.

Normal response codes: 200

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Response

Name In Type Description
vmexclude body object exclusion object.
id body string id of the exclude
exclude_id body string id of the domain/project/user to exclude
exclude_type body string type of exclusion, one of [domain, project, user]
POST
/vmexpires/

Create exclude

Create an exclusion for an object id and type

Valid types: domain, project, user

Normal response codes: 202

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Example Create VmExcludes
{
    "id": "AA-BB-CC",
    "type": "domain"
}

Response

Name In Type Description
vmexclude body object exclusion object.
id body string id of the exclude
exclude_id body string id of the domain/project/user to exclude
exclude_type body string type of exclusion, one of [domain, project, user]
DELETE
/vmexcludes/{id}

Delete exclude

Remove exclusion

Normal response codes: 204

Error response codes: badRequest(400), unauthorized(401), forbidden(403)

Request

Response