Skip to content

GitLab

Commit ec514b15 authored by Samir Noir's avatar Samir Noir 🧀
Browse files

Add documentation for Vlan API

parent 8798f713
Hide whitespace changes
Inline Side-by-side
app/controllers/apidocs_controller.rb
View file @ ec514b15
......@@ -6,13 +6,14 @@ class ApidocsController < ActionController::Base
info do
key :version, '3.0'
key :title, "Grid'5000 API"
key :description, "Grid'5000 complete API"
key :description, "This is the user and developer documentation for the Grid'5000 "\
"API. The API allows to facilitate interractions and automation with Grid'5000."
contact do
key :name, 'support-staff@lists.grid5000.fr'
end
license do
key :name, 'Apache 2.0'
end
end
server do
key :url, 'https://api.grid5000.fr/'
end
tag do
......@@ -47,8 +48,13 @@ class ApidocsController < ActionController::Base
'environment image on the nodes you have reserved. It uses the Kadeploy tool.'
end
server do
key :url, 'https://api.grid5000.fr/3.0'
tag do
key :name, 'vlan'
key :description, "The vlan API allows to get informations about vlans and to "\
"manipulate them. For example, it is possible to put deployed nodes in "\
"reserved vlans, to fetch current vlans and nodes status or to start or "\
"stop dhcp servers.\nThe associated documentation about Kavlan can be found "\
"on [Grid'5000's wiki](https://www.grid5000.fr/w/KaVLAN)"
end
end
......@@ -249,8 +255,14 @@ class ApidocsController < ActionController::Base
VersionsController,
DeploymentsController,
JobsController,
VlansController,
VlansUsersController,
VlansUsersAllController,
VlansNodesController,
VlansNodesAllController,
Grid5000::Deployment,
Grid5000::Job,
Grid5000::Kavlan,
self
].freeze
......
app/controllers/vlans_controller.rb
View file @ ec514b15
......@@ -13,8 +13,31 @@
# limitations under the License.
class VlansController < ApplicationController
include Swagger::Blocks
include Vlans
swagger_path "/sites/{siteId}/vlans" do
operation :get do
key :summary, 'List vlans'
key :description, 'Fetch the list of all the vlans for site.'
key :tags, ['vlan']
parameter do
key :$ref, :siteId
end
response 200 do
content :'application/json' do
schema do
key :'$ref', :VlanCollection
end
end
key :description, 'Vlan collection for site.'
end
end
end
# List vlans
def index
allow :get
......@@ -40,6 +63,36 @@ class VlansController < ApplicationController
end
end
swagger_path "/sites/{siteId}/vlans/{vlanId}" do
operation :get do
key :summary, 'Get vlan'
key :description, 'Fetch the list of all the vlans for site.'
key :tags, ['vlan']
[:siteId, :vlanId].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
content :'application/json' do
schema do
key :'$ref', :Vlan
end
end
key :description, 'A specific vlan.'
end
response 404 do
content :'text/plain'
key :description, 'Vlan not found.'
end
end
end
# Display the details of a vlan
def show
allow :get
......@@ -56,6 +109,57 @@ class VlansController < ApplicationController
end
end
swagger_path "/sites/{siteId}/vlans/{vlanId}/dhcpd" do
operation :put do
key :summary, 'Start/stop dhcpd'
key :description, 'Start or stop dhcp server for vlan.'
key :tags, ['vlan']
[:siteId, :vlanId].each do |param|
parameter do
key :$ref, param
end
end
request_body do
key :description, 'dhcp action payload.'
key :required, true
content 'application/json' do
schema do
property :action do
key :type, :string
key :description, "Action to perform, 'start' or 'stop'"
key :example, 'start'
end
end
end
end
response 204 do
key :description, 'dhcp server successfully started or stopped.'
end
response 403 do
content :'text/plain'
key :description, 'Not enough privileges on kavlan resource to perform action.'
end
response 404 do
content :'text/plain'
key :description, 'Vlan not found.'
end
response 415 do
content :'text/plain'
key :description, 'Content-Type not supported.'
end
response 422 do
content :'text/plain'
key :description, 'Unprocessable data structure.'
end
end
end
# start/stop dhcpd server for a vlan
def dhcpd
......
app/controllers/vlans_nodes_all_controller.rb
View file @ ec514b15
......@@ -14,6 +14,73 @@
class VlansNodesAllController < ApplicationController
include Vlans
include Swagger::Blocks
swagger_path "/sites/{siteId}/vlans/nodes" do
operation :get do
key :summary, 'List nodes with current vlan.'
key :description, 'Fetch list of all nodes and their current vlan.'
key :tags, ['vlan']
parameter do
key :$ref, :siteId
end
response 200 do
key :description, 'Collection of nodes.'
content :'application/json' do
schema do
key :'$ref', :VlanAllNodeCollection
end
end
end
end
operation :post do
key :summary, 'Ask vlan for nodes.'
key :description, 'Fetch list of asked nodes and their current vlan.'
key :tags, ['vlan']
parameter do
key :$ref, :siteId
end
request_body do
key :description, 'Asked nodes.'
key :required, true
content 'application/json' do
schema do
key :type, :array
key :description, "Nodes list."
items do
key :type, :string
key :format, :hostname
end
key :example, ['dahu-3.grenoble.grid5000.fr']
end
end
end
response 200 do
key :description, 'Vlans added.'
content :'application/json' do
schema do
key :'$ref', :VlanAllNodeCollection
end
end
end
response 415 do
content :'text/plain'
key :description, 'Content-Type not supported.'
end
response 422 do
content :'text/plain'
key :description, 'Unprocessable data structure.'
end
end
end
# Display nodes for a vlan
def index
......
app/controllers/vlans_nodes_controller.rb
View file @ ec514b15
......@@ -14,6 +14,88 @@
class VlansNodesController < ApplicationController
include Vlans
include Swagger::Blocks
swagger_path "/sites/{siteId}/vlans/{vlanId}/nodes" do
operation :get do
key :summary, 'List nodes in vlan'
key :description, 'Fetch list of current nodes in vlan.'
key :tags, ['vlan']
[:siteId, :vlanId].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
key :description, 'Collection of nodes.'
content :'application/json' do
schema do
key :'$ref', :VlanNodeCollection
end
end
end
response 404 do
content :'text/plain'
key :description, 'Vlan not found.'
end
end
operation :post do
key :summary, 'Add nodes to vlan'
key :description, 'Add nodes to vlan.'
key :tags, ['vlan']
[:siteId, :vlanId].each do |param|
parameter do
key :'$ref', param
end
end
request_body do
key :description, 'Nodes to add payload.'
key :required, true
content 'application/json' do
schema do
key :type, :array
key :description, "Nodes list."
items do
key :type, :string
key :format, :hostname
end
key :example, ['dahu-3.grenoble.grid5000.fr',
'dahu-10.grenoble.grid5000.fr']
end
end
end
response 200 do
key :description, 'Vlans added.'
content :'application/json' do
schema do
key :'$ref', :VlanAddResponse
end
end
end
response 404 do
content :'text/plain'
key :description, 'Vlan not found.'
end
response 415 do
content :'text/plain'
key :description, 'Content-Type not supported.'
end
response 422 do
content :'text/plain'
key :description, 'Unprocessable data structure.'
end
end
end
# Display nodes for a vlan
def index
......
app/controllers/vlans_users_all_controller.rb
View file @ ec514b15
......@@ -14,6 +14,30 @@
class VlansUsersAllController < ApplicationController
include Vlans
include Swagger::Blocks
swagger_path "/sites/{siteId}/vlans/users" do
operation :get do
key :summary, 'List users using vlans'
key :description, 'Fetch list of all users currently using vlans.'
key :tags, ['vlan']
[:siteId, :vlanId].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
key :description, 'Collection of users, with their vlans.'
content :'application/json' do
schema do
key :'$ref', :VlanUserAllCollection
end
end
end
end
end
# List users
def index
......@@ -33,6 +57,30 @@ class VlansUsersAllController < ApplicationController
end
end
swagger_path "/sites/{siteId}/vlans/users/{userId}" do
operation :get do
key :summary, 'List vlans for user'
key :description, 'Fetch vlans for a user.'
key :tags, ['vlan']
[:siteId, :vlanId].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
key :description, 'List of vlan for user.'
content :'application/json' do
schema do
key :'$ref', :VlanUserAll
end
end
end
end
end
# Display the vlans allowed for a user
def show
allow :get
......
app/controllers/vlans_users_controller.rb
View file @ ec514b15
......@@ -14,6 +14,35 @@
class VlansUsersController < ApplicationController
include Vlans
include Swagger::Blocks
swagger_path "/sites/{siteId}/vlans/{vlanId}/users" do
operation :get do
key :summary, 'List user for vlan'
key :description, 'Fetch list of current users with rights on vlan.'
key :tags, ['vlan']
[:siteId, :vlanId].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
key :description, 'Collection of users.'
content :'application/json' do
schema do
key :'$ref', :VlanUserCollection
end
end
end
response 404 do
content :'text/plain'
key :description, 'Vlan not found.'
end
end
end
# List users
def index
......@@ -34,6 +63,34 @@ class VlansUsersController < ApplicationController
end
end
swagger_path "/sites/{siteId}/vlans/{vlanId}/users/{userId}" do
operation :get do
key :summary, 'Get user status for vlan'
key :description, 'Fetch user authorization for a vlan.'
key :tags, ['vlan']
[:siteId, :vlanId, :userId].each do |param|
parameter do
key :$ref, param
end
end
response 200 do
key :description, "Status of user for Vlan, can be authorized or unauthorized."
content :'application/json' do
schema do
key :'$ref', :VlanUser
end
end
end
response 404 do
content :'text/plain'
key :description, 'Vlan not found.'
end
end
end
# Display the rights on a vlan for a user
def show
allow :get
......@@ -48,7 +105,8 @@ class VlansUsersController < ApplicationController
end
end
# Remove rights for user on a vlan
# Remove rights for user on a vlan.
# Limited to some users, like OAR, so not documented
def destroy
ensure_authenticated!
allow :delete
......@@ -63,7 +121,8 @@ class VlansUsersController < ApplicationController
status: result.code
end
# Add rights for user on a vlan
# Add rights for user on a vlan.
# Limited to some users, like OAR, so not documented
def add
ensure_authenticated!
allow :put
......
lib/grid5000/kavlan.rb
View file @ ec514b15
......@@ -19,9 +19,391 @@ module Grid5000
# Class representing vlans
class Kavlan
include ApplicationHelper
include Swagger::Blocks
attr_accessor :base_uri, :user, :tls_options
# Swagger doc
swagger_component do
parameter :vlanId do
key :name, :vlanId
key :in, :path
key :description, 'ID of vlan to fetch.'
key :required, true
key :type, :integer
end
parameter :userId do
key :name, :userId
key :in, :path
key :description, "ID of Grid'5000 user."
key :required, true
key :type, :string
end
schema :Vlan do
key :required, [:uid, :type, :links]
property :uid do
key :type, :integer
key :description, 'The Vlan ID.'
key :example, 2
end
property :type do
key :type, :string
key :description, 'The Vlan type (kavlan, kavlan-global, kavlan-global, '\
'kavlan-global-remote).'
key :example, 'kavlan-local'
end
property :links do
key :type, :array
items do
key :'$ref', :Links
end
key :example, [{
'rel': 'dhcpd',
'type': 'application/vnd.grid5000.item+json',
'href': '/3.0/sites/grenoble/vlans/21/dhcpd'
},
{
'rel': 'nodes',
'type': 'application/vnd.grid5000.item+json',
'href': '/3.0/sites/grenoble/vlans/21/nodes'
},
{
'rel': 'users',
'type': 'application/vnd.grid5000.collection+json',
'href': '/3.0/sites/grenoble/vlans/21/users'
},
{
'rel': 'self',
'href': '/3.0/sites/grenoble/vlans/21',
'type': 'application/vnd.grid5000.item+json'
},
{
'rel': 'parent',
'href': '/3.0/sites/grenoble/vlans',
'type': 'application/vnd.grid5000.collection+json'
}]
end
end
schema :VlanItems do
key :required, [:items]
property :items do
key :type, :array
items do
key :'$ref', :Vlan
end
end
end
schema :VlanCollection do
allOf do
schema do
key :'$ref', :BaseApiCollection
end
schema do
key :'$ref', :VlanItems
end
schema do
property :links do
key :type, :array
items do
key :'$ref', :links
end
key :example, [{
'rel': 'nodes',
'href': '/sid/sites/grenoble/vlans/nodes',
'type': 'application/vnd.grid5000.collection+json'
},
{
'rel': 'users',
'href': '/sid/sites/grenoble/vlans/users',
'type': 'application/vnd.grid5000.collection+json'
},
{
'rel': 'self',
'href': '/sid/sites/grenoble/vlans',
'type': 'application/vnd.grid5000.collection+json'
},
{
'rel': 'parent',
'href': '/sid/sites/grenoble',
'type': 'application/vnd.grid5000.item+json'
}]
end
end
end
end
schema :VlanUserAllCollection do
allOf do
schema do
key :'$ref', :BaseApiCollection
end
schema do
key :required, [:items]
property :items do
key :type, :array
items do