LIST API REST API RESOURCE API

ROLE API

This page describes the K2HR3 ROLE API. The purpose of the ROLE API is to create and update and get and delete a K2HR3 ROLE. See the Basic Usage about the K2HR3 ROLE in the K2HR3.

POST(Create ROLE)

Creates a K2HR3 ROLE.

Endpoint(URL)

http(s)://API SERVER:PORT/v1/role

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

Request Body

{
    role:    {
        name:        <role name or yrn full path>
        policies:    [
                         <policy yrn full path>,
                         ...
                     ]
        alias:       [
                         <role yrn full path>,
                         ...
                     ]
    }
}

Response status

201、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
}

PUT(Create ROLE)

Creates a K2HR3 ROLE.

Endpoint(URL)

http(s)://API SERVER:PORT/v1/role?urlarg

Header

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

URL Arguments

Response status

201、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
}

POST(Add HOST to ROLE)

Adds a member(aka a hostname or an IP address) to a K2HR3 ROLE.

Endpoint(URL)

Scoped User Token

http(s)://API SERVER:PORT/v1/role/role path

Role Token

http(s)://API SERVER:PORT/v1/role/yrn full path to role

Header

Scoped User Token

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

Role Token

API server will add a source IP address to a role if it finds a role token in request parameters.

Content-Type: application/json
x-auth-token: R=<Role Token>

Request Body

Scoped User Token

One request body includes only one host.

{
    host:    {
        host:            <hostname / ip address>
        port:            <port number>
        cuk:             <container unique key: reserved>
        extra:           <extra string data>
        tag:             <tag string data>
        inboundip:       <ip address>
        outboundip:      <ip address>
    }
    clear_hostname:      <true/false>
    clear_ips:           <true/false>
}

One request body includes multiple hosts.

{
    host:    [
        {
            host:        <hostname / ip address>
            port:        <port number>
            cuk:         <container unique key: reserved>
            extra:       <extra string data>
            tag:         <tag string data>
            inboundip:   <ip address>
            outboundip:  <ip address>
        },
        ...
    ]
    clear_hostname:      <true/false>
    clear_ips:           <true/false>
}

Role Token

{
    host:    {
        port:            <port number>
        cuk:             <container unique key: reserved>
        extra:           <extra string data>
        tag:             <tag string data>
        inboundip:       <ip address>
        outboundip:      <ip address>
    }
}

Parameters

Note: Port assignment

You need to pay special attention in case you add a hostname or IP address that already exists with a different port.

Response status

201、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
}

PUT(Add HOST to ROLE)

Adds a member(aka a hostname or an IP address) to a K2HR3 ROLE.

Endpoint(URL)

Scoped User Token

http(s)://API SERVER:PORT/v1/role/role path?urlarg

Role Token

http(s)://API SERVER:PORT/v1/role/yrn full path to role?urlarg

Header

Scoped User Token

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

Role Token

API server will add a source IP address to a role if it finds a role token in request parameters.

Content-Type: application/json
x-auth-token: R=<Role Token>

URL Arguments

Scoped User Token

Role Token

Note

If you add a hostname or IP address that already exists with a different port, you should know the followings:

Response status

201、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
}

GET(Show ROLE details)

Shows details for a role.

Endpoint(URL)

http(s)://API SERVER:PORT/v1/role/role path or yrn full role path?urlarg

Header

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

URL Arguments

Response status

200、40x

Response Body(JSON)

{
    result:     <true/false>
    message:    <null or error message string>
    role:       {
        policies:   array,
        aliases:    array
        hosts: {
            hostnames: [
                "<hostname> <port> <cuk> <extra> <tag> <inboundip> <outboundip>",
                ...
            ],
            ips: [
                "<ip address> <port> <cuk> <extra> <tag> <inboundip> <outboundip>",
                ...
            ]
        }
    }
}

GET(Create ROLE Token)

Create a role token. Role API creates a role token in the following three cases.

Endpoint(URL)

A Scoped User Token

http(s)://API SERVER:PORT/v1/role/token/role path or yrn full role path

A Role Token

http(s)://API SERVER:PORT/v1/role/token/role path or yrn full role path

No Tokens

http(s)://API SERVER:PORT/v1/role/token/yrn full role path

Header

A Scoped User Token

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

A Role Token

Content-Type: application/json
x-auth-token: R=<Role Token>

No Tokens

Content-Type: application/json

URL Arguments(only for Scoped User Token)

Response status

200、40x

Response Body(JSON)

{
    result:       <true/false>
    message:      <null or error message string>
    token:        <role token string>
    registerpath: <URI path for userdata API>
}

Note

RoleToken expiration

When issuing with Scoped User Token, it is possible to specify the expiration date. If not specified, the default value is used. (The default value can be specified in config)
When Role Token is specified, it is issued with the same expiration date as that set for the specified RoleToken. If Token is not specified, the default value is always used.

Reissuing RoleToken

When Role Token is specified, the newly issued RoleToken is the reissued RoleToken, and the specified RoleToken cannot be used (invalid) after the reissue.

GET (Role Token List)

API to obtain a list of Role Tokens issued for the role. In order to use this API, it is necessary to specify Scoped User Token.

Endpoint (URL)

Scoped User Token specified

http(s)://APISERVER:PORT/v1/role/token/list/role path or yrn full role path

Header

Scoped User Token specified

Content-Type: application/json
x-auth-token: U = <Scoped User Token>

URL Arguments

Response status

200, 40x

Response Body (JSON)

Not expanding

{
    result:       <true/false>
    message:      <null or error message string>
    tokens: [
                  <role token striong>,
                  ...
    ]
}

Expanding

{
    result:       <true/false>
    message:      <null or error message string>
    tokens:	{
        <role token string>: {
            date:		  <create date(UTC ISO 8601)>
            expire:		  <expire date(UTC ISO 8601)>
            user:		  <user name if user created this token>
            hostname:	  <hostname if this token was created by host(name)>
            ip:			  <ip address if this token was created by ip>
            port:		  <port number, if specified port when created token>
            cuk:		  <cuk, if specified cuk when created token>
            registerpath: <register path in user data script>
        },
        ...
    }
}

HEAD(Validate ROLE)

Validates the client’s source IP address, a scoped user token or a role token.

Endpoint(URL)

A Scoped User Token

http(s)://API SERVER:PORT/v1/role/role path or yrn full role path

A Role Token

http(s)://API SERVER:PORT/v1/role/role path or yrn full role path

A No Tokens

http(s)://API SERVER:PORT/v1/role/yrn full role path

Header

A Scoped User Token

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

A Role Token

Content-Type: application/json
x-auth-token: R=<Role Token>

No Tokens

Content-Type: application/json

Response status

204、40x

Response Body(JSON)

The server will not return a message-body in the response in the HEAD method.

DELETE(Delete ROLE)

Deletes a role.
Scoped User Token must be specified.

Endpoint(URL)

A Scoped User Token

http(s)://API SERVER:PORT/v1/role/role path or yrn full role path?urlarg

Header

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

URL Arguments

Specify nothing as URL Arguments.
Note that if URL Arguments such as host are accompanied, it will operate as deleting the role member host.

Response status

204、40x

Response Body(JSON)

Empty.

DELETE(Hostname/IP address deletion-role specification)

This API deletes Hostname or IP address.
Specify a Scoped User Token or call it from a host that is a member of the role.
(If you specify the Role Token and call the DELETE method, it will be a different process.)

Endpoint (URL)

Scoped User Token specified

http(s)://APISERVER:PORT/v1/role/role path or yrn full role path

Token not specified

http(s)://APISERVER:PORT/v1/role/yrn full role path

Header

Scoped User Token

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

No Token

Content-Type: application/json

URL Arguments

Scoped User Token

No Token

Response status

204, 40x

Response Body (JSON)

Empty.

DELETE(Hostname/IP address deletion - Role not specified)

This API specifies CUK (Custom Unique Key) that is specified when the IP address is automatically registered.
And remove the IP address below the ROLE key registered with the same CUK.

This API is used to delete an automatically registered IP address (or Hostname) from OpenStack and kubernetes.
K2HR3 supports automatic registration of IP addresses by USER DATA SCRIPT as OpenStack support.
For kubernetes pod registration, the K2HR3 system offers a dedicated Sidecar.
These automatic registrations are systems in which each IP address is registered by specifying CUK.
This API is provided to allow you to delete an IP address by specifying CUK.

This API is not intended to be used from K2HR3 Web Application or directly using the API.
This API is called from Neutron Notification Listner which is hooking to RabbitMQ of OpenStack and from deletion logic of Pods by kubernetes.

For calling this API from OpenStack Neutron Notification Listner is allowed only from the IP address registered in Tenant/Role for which the following settings have been configured as the K2HR3 Web Application config.
You can set in default.json or local.json

{
  'k2hr3admin': {
     'tenant':      'admintenant',
     'delhostrole': 'delhostrole'
  }
}

Endpoint(URL)

http(s)://API SERVER:PORT/v1/role?urlarg

Header

Content-Type: application/json

URL Arguments

-cuk = custom unique key
When registering an OpenStack VirtualMachine, specify its Instance ID.
When registering from a pod of kubernetes, specify the CUK string calculated for registration (automatically calculated by Sidecar provided by the K2HR3 system).
The IP address associated with this value will be deleted. -host
This parameter specifies the IP address to be deleted.
Of the IP addresses associated with CUK, only the IP address specified by this parameter is subject to deletion.
When specifying multiple IP addresses, specify them as a string array in the JSON object.
For a single IP address, specify a character string.
If this parameter is not specified and only CUK is specified, all IP addresses linked to ** CUK ** will be deleted.
When registering with OpenStack or kubernets, it is assumed that there is only one IP address linked to CUK, and it is not usually necessary to specify the host parameter.

Response status

204, 40x

Response Body (JSON)

Empty.

DELETE (RoleToken deletion - Role specified)

API to delete (invalidate) Role Token.
This API confirms Role Token and the role(specified by the full YRN path), and that the request source IP address is a member of that role.
And the Role Token Disable.

Endpoint (URL)

Role Token specified

http(s)://API SERVER:PORT/v1/role/role path or yrn full role path

Header

Role Token

Content-Type: application/json
x-auth-token: R=<Role Token>

URL Arguments

-port = port number
Specify the port number required to delete the host (IP address) that sent this request from the role.
If no identification is required, it is unspecified or 0.

Response status

204, 40x

Response Body (JSON)

Empty.

DELETE(Delete RoleToken - Role not specified)

API to delete(invalidate) Role Token by specifying Scoped User Token.
This API is required to manage Role Token and is mainly used from K2HR3 Web Application.

Endpoint (URL)

Role Token specified

http(s)://API SERVER:PORT/v1/role/token/role token string

Header

Scoped User Token specified

Content-Type: application/json
x-auth-token: U=<Scoped User Token>

URL Arguments

Empty.

Response status

204, 40x

Response Body (JSON)

Empty.

LIST API REST API RESOURCE API