LIST API REST API RESOURCE API

ROLE API

K2HR3 REST APIのロール(ROLE)に関連するAPI群です。

POST(ロール設定)

Scoped User Tokenを指定して、ロール(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(ロール(ROLE)設定)

Scoped User Tokenを指定して、ロール(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(ホスト(HOST)登録)

ロール(ROLE)メンバーにhostnameもしくはIPアドレスを設定するAPIです。呼び出しのTokenの種類により動作が異なります。
Scoped User Tokenを指定して、ロール(ROLE)メンバーにホスト(HOST)を設定(新規作成、更新)します。
Role Tokenを指定して、ロール(ROLE)メンバーにリクエスト送信元IPアドレスを設定(新規作成、更新)します。

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

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

Request Body

Scoped User Token(1 hostのみ登録)

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

Scoped User Token(複数host登録)

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

Role Token

{
    host:    {
        port:            <port number>
        cuk:             <container unique key: reserved>
        extra:           <extra string data>
    }
}

変数説明

注意

すでに存在しているhostname/IPアドレスと同じホスト(HOST)を異なるポートで指定した場合には、以下の動作に注意してください。

Response status

201、40x

Response Body(JSON)

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

PUT(ホスト(HOST)登録)

ロール(ROLE)メンバーにhostnameもしくはIPアドレスを設定するAPIです。呼び出しのTokenの種類により動作が異なります。
Scoped User Tokenを指定して、ロール(ROLE)メンバーにホスト(HOST)を設定(新規作成、更新)します。
Role Tokenを指定して、ロール(ROLE)メンバーにリクエスト送信元IPアドレスを設定(新規作成、更新)します。

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

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

URL Arguments

Scoped User Token

Role Token

注意

すでに存在しているhostname/IPアドレスと同じホスト(HOST)を異なるポートで指定した場合には、以下の動作に注意してください。

Response status

201、40x

Response Body(JSON)

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

GET(ロール(ROLE)データ)

Scoped User Tokenを指定して、ロール(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>",
                ...
            ],
            ips: [
                "<ip address> <port> <cuk>",
                ...
            ]
        }
    }
}

GET(Role Token)

Role Tokenを取得するためのAPIです。取得には3つの手段が準備されています。
1つは、Scoped User Tokenを指定して、Role Tokenを取得します。
Role Tokenを指定して、Role Token(更新された新しいRole Token)を取得します。
最後は、Tokenを指定せず、ロール(ROLE)を指定し、そのロール(ROLE)メンバーのホスト(HOST)である確認をした上で、Role Tokenを取得します。

Endpoint(URL)

Scoped User Token指定

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

Role Token指定

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

Token未指定

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

Header

Scoped User Token指定

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

Role Token指定

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

Token未指定

Content-Type: application/json

URL Arguments(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>
}

注意

RoleTokenの有効期限について

Scoped User Tokenによる発行する場合は、有効期限を指定することが可能です。未指定の場合はデフォルト値が使われます。(デフォルト値はconfigで指定できます)
Role Tokenを指定する場合、その指定したRoleTokenに設定された有効期限と同じ有効期限で発行されます。
Tokenが未指定の場合には、常にデフォルト値が使われます。

RoleTokenの再発行について

Role Tokenを指定した場合、新たに発行されるRoleTokenは、再発行されたRoleTokenであり、指定されたRoleTokenは再発行後には利用できなく(無効)なります。

GET(Role Token List)

ロールに対して発行されているRole Tokenのリストを取得するためのAPIです。このAPIを利用するためには、Scoped User Tokenを指定する必要があります。

Endpoint(URL)

Scoped User Token指定

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

Header

Scoped User Token指定

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>
    tokens: [
                  <role token striong>,
                  ...
    ]
}

展開する場合

{
    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>
        },
        ...
    }
}

Scoped User Tokenによるロール(ROLE)へのアクセス確認、またはRole Tokenの確認、リクエスト送信元IPアドレスのロール(ROLE)メンバーの確認の3つの機能を提供します。
Scoped User Token場合には、URLパスで指定するロール(ROLE)パスもしくはYRNフルパスで指定したロール(ROLE)パスに設定されているロール(ROLE)へのアクセス、ロール(ROLE)の存在を確認します。
Role Tokenの場合には、URLパスで指定するロール(ROLE)パスもしくはYRNフルパスで指定したロール(ROLE)パスに設定されているロール(ROLE)のTokenであるか確認します。
Token未指定の場合には、APIリクエスト元のIPアドレスがURLパスで指定したYRNフルパスのロール(ROLE)メンバーであるか確認します。

Endpoint(URL)

Scoped User Token指定

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

Role Token指定

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

Token未指定

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

Header

Scoped User Token指定

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

Role Token指定

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

Token未指定

Content-Type: application/json

Response status

204、40x

Response Body(JSON)

なし

DELETE(ロール(ROLE)削除)

ロールの削除を行うAPIです。
Scoped User Tokenを指定する必要があります。

Endpoint(URL)

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

URL Argumentsとして何も指定しません。
hostなどのURL Argumentsを伴う場合には、ロールメンバーのhostの削除として動作しますので、注意してください。

Response status

204、40x

Response Body(JSON)

なし

DELETE(Hostname/IPアドレス削除 - ロール指定)

HostnameもしくはIPアドレスを削除するAPIです。
Scoped User Tokenを指定するか、ロールのメンバーであるホストから呼び出すようにしてください。
(Role Tokenを指定してDELETEメソッドを呼び出すと別の処理となります。)

Endpoint(URL)

Scoped User Token指定

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

Token未指定

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

Header

Scoped User Token指定

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

Token未指定

Content-Type: application/json

URL Arguments

Scoped User Token指定

Token未指定

Response status

204、40x

Response Body(JSON)

なし

DELETE(Hostname/IPアドレス削除 - ロール未指定)

本APIは、IPアドレスが自動登録されたときに指定される CUK(Custom Unique Key)を指定し、同じCUKで登録されたIPアドレスを、ROLEキー以下のHOST情報から削除します。

このAPIは、OpenStackおよびkubernetesから自動登録されたIPアドレス(もしくはHostname)を削除するために使用するAPIです。
K2HR3では、OpenStack対応として、USER DATA SCRIPTによるIPアドレスの自動登録をサポートしています。
kubernetesのPodの登録のためにK2HR3システムは、専用のSidecarを提供しています。
これらの自動登録は、CUKを指定して各々のIPアドレスが登録される仕組みです。
そして、このAPIはCUKを指定してIPアドレスの削除ができるために提供されます。

本APIは、K2HR3 Web Applicationからの操作や、APIを直接利用することを想定したものではなく、OpenStackのRabbitMQにHookするNeutron Notification Listnerからの呼び出し、もしくはkubernetesによるPodsの削除に連動することを想定しています。

OpenStack Neutron Notification Listnerから本APIの呼び出しは、K2HR3 Web Applicationのconfigとして以下の設定がなされているTenant/Roleに登録されているIPアドレスからのみ許可されます。
default.jsonやlocal.jsonに設定してください

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

Endpoint(URL)

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

Header

Content-Type: application/json

URL Arguments

Response status

204、40x

Response Body(JSON)

なし

DELETE(RoleToken削除 - ロール指定)

Role Tokenを削除(無効化)するAPIです。
Role Tokenを指定し、URLパスで指定されるロール(YRNフルパスで指定されている)であることが確認され、またリクエストの送信元IPアドレスがロールのメンバーであることも確認し、そのRole Tokenを無効化します。

Endpoint(URL)

Role Token指定

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

Response status

204、40x

Response Body(JSON)

なし

DELETE(RoleToken削除 - ロール未指定)

Scoped User Tokenを指定して、Role Tokenを削除(無効化)するAPIです。
Role Tokenの管理をするために必要となるAPIであり、主にK2HR3 Web Applicationから利用されます。

Endpoint(URL)

Role Token指定

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

Header

Scoped User Token指定

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

URL Arguments

なし

Response status

204、40x

Response Body(JSON)

なし

LIST API REST API RESOURCE API