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>
        inboundip:       <ip address>
        outboundip:      <ip address>
    }
    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>
            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>
    }
}

変数説明

注意

すでに存在している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> <extra> <tag> <inboundip> <outboundip>",
                ...
            ],
            ips: [
                "<ip address> <port> <cuk> <extra> <tag> <inboundip> <outboundip>",
                ...
            ]
        }
    }
}

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