From 66b3579ed0f18fad4732bcc1569f43b55704ac1a Mon Sep 17 00:00:00 2001 From: Alfonso Tierno Date: Wed, 4 Mar 2020 16:56:23 +0100 Subject: [PATCH] enhancing NBI API description Signed-off-by: Alfonso Tierno --- 12-osm-nbi.md | 237 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 153 insertions(+), 84 deletions(-) diff --git a/12-osm-nbi.md b/12-osm-nbi.md index f19c485..0c67e5d 100644 --- a/12-osm-nbi.md +++ b/12-osm-nbi.md @@ -144,7 +144,7 @@ URL: /osm GET POST /k8sclusters O O / O O O /k8srepos O O - / O O + / O /nst/v1 O O /netslice_templates_content O O @@ -233,103 +233,179 @@ Header field name Reference Example Descriptions - POST: Obtain a token. The 'username' and 'password' is mandatory only if http header does not contain Authorization. 'project' can be provided, if not, first project of available for this user is assigned. For changing project, a new token must be obtained. - Example of request content: `'{username: , password: , project_id: }'` -`/admin/v1/tokens/` +`/admin/v1/tokens/ID` - GET: show token details - DELETE: revoque token. Logout `/admin/v1/users`. (rbac: `users`). Users may operate in several projects -- GET: Get users +- GET: Get user list - POST: Add a new user. - Example of request content: `'{username: , password: , projects: [P1, P2, ...]}'` -`/admin/v1/users/`. (rbac: `users:id`). +`/admin/v1/users/ID`. (rbac: `users:id`). - GET: Get user details -- PUT/PATCH: Edit user. - - Example of user edition: - - Change password: `'{password: }'` - - Change the list of available projects to a new one: `'{projects: [P1, P2, ...]}'` - - Remove a project 'P' from user if exist: `{projects: {"$'P'": null}}'` - - Add a project 'P' to user if not already exist: `'{projects: {"$+'P'": "P"}}'` - - Set 'P' to be project by default, (adding it if not exist): `'{projects: {"$'P'": null, "$+[0]": "P"}}'` +- PUT/PATCH: Edit user. Example of user edition: + - Change password: `'{password: }'` + - Add role R1, projects P1: `'{add_project_role_mappings: [{project: role: R1}, ...]}'` + - Remove role R1, project P1 from user: `{remove_project_role_mappings: [{project: P1, role: R1}]}'` + - Remove a project 'P1' (all roles) from user: `{remove_project_role_mappings: [{project: P1}]}'` + - DELETE: Removes user. `/admin/v1/projects`. (rbac: `projects`). A project contains its own separate space -- GET: Get projects -- POST: Add a new project. - - Example of request content: `'{name: , admin: }'` +- GET: Get project list +- POST: Add a new project. Example of request content: `'{name: , admin: }'` -`/admin/v1/projects/`. (rbac: `projects:id`) +`/admin/v1/projects/ID`. (rbac: `projects:id`) - GET: Get project details -- PUT/PATCH: Edit project. - - Example of project edition to change admin status: `'{admin: }'` +- PUT/PATCH: Edit project.Example of project edition to change admin status: `'{admin: }'` - DELETE: Removes project. `/admin/v1/vim_accounts`. (rbac: `vims`). Vim account is the deployment target - GET: Get vim_accounts -- POST: Add a new vim_accounts. - - Example of request content: TODO +- POST: Add a new vim_accounts.Example of request content: + +```yaml + name: ost2 + vim_url: http://vim-server:vim-port/version + vim_type: openstack + vim_user: user + vim_password: password + vim_tenant_name: tenant +``` -`/admin/v1/vim_accounts/`. (rbac: `vims:id`) +`/admin/v1/vim_accounts/ID`. (rbac: `vims:id`) - GET: Get vim_account details -- PUT/PATCH: Edit vim_account. - - Example of vim_account edition: TODO +- PUT/PATCH: Edit vim_account. Example of vim_account edition: + +```yaml + vim_user: new-user + vim_password: new-password + vim_tenant_name: new-tenant +``` + - DELETE: Removes vim_account. `/admin/v1/wim_accounts`. (rbac: `wims`). WIM are WAN Infrastructure Managers, that is in charge of inter VIM connectivity management - GET: Get wim_accounts -- POST: Add a new wim_account. - - Example of request content: TODO +- POST: Add a new wim_account. Example of request content: + +```yaml + name: wim-name + wim_url: http://wim-server:wim-port/version + wim_type: onosof +``` -`/admin/v1/wim_accounts/`. (rbac: `wims:id`) +`/admin/v1/wim_accounts/ID`. (rbac: `wims:id`) - GET: Get wim_account details -- PUT/PATCH: Edit wim_account. - - Example of wim_account edition: TODO +- PUT/PATCH: Edit wim_account. Example of wim_account edition: + +```yaml + wim_url: http://new-server:new-port/new-version + wim_type: new-type +``` + - DELETE: Removes wim_account. `/admin/v1/sdns`. (rbac: `sdn_controllers`). SDN controllers in charge of VIM's underlay connectivity in SDN Assist -- GET: Gets sdns -- POST: Add a new sdn. - - Example of request content: TODO - -`/admin/v1/k8sclusters`. (rbac: `k8sclusters`). K8S Clusters to deploy juju bundles or helm packages +- GET: Gets sdn controller list +- POST: Add a new sdn. Example of request content: -- GET: Gets k8s clusters -- POST: Add a new k8s cluster. - - Example of request content: TODO +```yaml + name: sdn-name + type: onosof + url: "10.95.172.251:8181" + config: {dpid: "00:00:28:99:3a:43:38:a1"} + user: username + password: password +``` -`/admin/v1/k8srepos`. (rbac: `k8srepos`). K8S repository that contains the juju bundles or helm packages +`/admin/v1/sdns/ID`. (rbac: `sdn_controllers:id`) -- GET: Gets k8s repositories -- POST: Add a new k8s repository. - - Example of request content: TODO +- GET: Get sdn details +- PUT/PATCH: Edit sdn. Example of sdn edition: -`/admin/v1/sdns/`. (rbac: `sdn_controllers:id`) +```yaml + type: odlof + url: http://10.96.125.234:8080 + config: {dpid: "00:00:29:88:1b:55:27:c4"} +``` -- GET: Get sdn details -- PUT/PATCH: Edit sdn. - - Example of sdn edition: TODO - DELETE: Removes sdn. -`/admin/v1/k8sclusters/`. (rbac: `k8sclusters:id`) +`/admin/v1/k8sclusters`. (rbac: `k8sclusters`). K8S Clusters to deploy juju bundles or helm packages + +- GET: Gets k8s cluster list +- POST: Add a new k8s cluster. Example of request content: + +```yaml + name: "k8s-cluster-name" + credentials: + apiVersion: v1 + clusters: + - cluster: + certificate-authority-data: "LS0tLS1CRUdJTi...LS0tLQo=" + server: "https://127.0.0.1:16443" + name: "microk8s-cluster" + contexts: + - context: + cluster: "microk8s-cluster" + user: "admin" + name: microk8s + current-context: "microk8s" + kind: "Config" + preferences: {} + users: + - name: "admin" + user: + username: "admin" + password: "password" + vim_account: c13b32f0-270c-4589-8610-24caa4c0ddb4 + k8s_version: "1.16" + nets: # kdu: VIM + mgmt: "mgmt-net" + mgmt2: null +``` + +`/admin/v1/k8sclusters/ID`. (rbac: `k8sclusters:id`) - GET: Get k8sclusters details -- PUT/PATCH: Edit k8sclusters. +- PUT/PATCH: Edit k8sclusters. Example of k8scluster edition: + +```yaml +k8s_version: "1.17" +nets: + internal: int-net + external: ext-net +description: K8sCluster description text +``` + - DELETE: Removes k8sclusters. -`/admin/v1/k8srepos/`. (rbac: `k8srepos:id`) +`/admin/v1/k8srepos`. (rbac: `k8srepos`). K8S repository that contains the juju bundles or helm chart packages + +- GET: Gets k8s repositories +- POST: Add a new k8s repository. Example of request content: + +```yaml + name: k8s-repo-name + type: helm-chart|juju-bundle + url: https://repo-server/path +``` + +`/admin/v1/k8srepos/ID`. (rbac: `k8srepos:id`) - GET: Get k8srepos details -- PUT/PATCH: Edit k8srepos. - DELETE: Removes k8srepos. ## PDU Details @@ -339,8 +415,7 @@ Physical Data Unit. This is catalogue of physical elements present at some vim_a `/pdu/v1/pdu_descriptor`. (rbac: `pduds`) - GET: List PDUs. Use query string for filtering. -- POST: Create a new PDU. - - Example of request content: +- POST: Create a new PDU. Example of request content: ```yaml name: descriptive name # mandatory @@ -355,7 +430,7 @@ interfaces: # mandatory vim-network-name: xxx ``` -`/pdu/v1/pdu_descriptor/`. (rbac: `pduds:id`) +`/pdu/v1/pdu_descriptor/ID`. (rbac: `pduds:id`) - GET: show PDU details - PUT: overwrite this PDU @@ -366,13 +441,13 @@ interfaces: # mandatory Virtual Network Function Descriptor. This includes also Physical and Hybrid Network Funcitons Descriptors (PNFD/HNFD). (At VDU level, it is indicated if it is physical with the `'pdu-type'` information element). -TBC +See complete documentation on: [Open OSM NBI in Swagger-UI](https://forge.etsi.org/swagger/ui/?url=https%3A%2F%2Fosm.etsi.org%2Fgitweb%2F%3Fp%3Dosm%2FSOL005.git%3Ba%3Dblob_plain%3Bf%3Dosm-openapi.yaml%3Bhb%3DHEAD) ## NSD Details Network Services Descriptor -TBC +See complete documentation on: [Open OSM NBI in Swagger-UI](https://forge.etsi.org/swagger/ui/?url=https%3A%2F%2Fosm.etsi.org%2Fgitweb%2F%3Fp%3Dosm%2FSOL005.git%3Ba%3Dblob_plain%3Bf%3Dosm-openapi.yaml%3Bhb%3DHEAD) ## NSLCM Details @@ -395,7 +470,7 @@ vnf: [ {member-vnf-index: "1", vimAccountId: vim-uuid, internal-vld: [], vdu: [] vld: [ {name: vld-name, ip-profile: {}, vnfd-connection-point-ref: [{}] }] ``` -`/nslcm/v1/ns_instances_content/`. (rbac: `ns_instances:id`) +`/nslcm/v1/ns_instances_content/ID`. (rbac: `ns_instances:id`) - GET: Obtains details of a NS - DELETE: (Asynchronous) Terminates (or undeploy) and deletes (if termination is done successfully) a NS @@ -414,12 +489,12 @@ additionalParamsForNs: {param1: value1, param2: value2} additionalParamsForVnf: [member-vnf-index: "1", additionalParams: {param1: value1, param2: value2}] ``` -`/nslcm/v1/ns_instances/`. (rbac: `ns_instances:id`) +`/nslcm/v1/ns_instances/ID`. (rbac: `ns_instances:id`) - GET: Obtains details of a NS - DELETE: Deletes a NS. It fails if NS is in 'INSTANTIATED' state -`/nslcm/v1/ns_instances//instantiate`. (rbac: `ns_instances:id:instantiate:post`) +`/nslcm/v1/ns_instances/ID/instantiate`. (rbac: `ns_instances:id:instantiate:post`) - POST: (Asynchronous). Deploys a NS that it is in NOT_INSTANTIATED state. It returns the nsLcmOpOccId (Operations Occurrence Id) in the response header `'Location'`. Example of request content: @@ -431,14 +506,13 @@ vnf: [ {member-vnf-index: "1", vimAccountId: vim-uuid, internal-vld: [], vdu: [] vld: [ {name: vld-name, ip-profile: {}, vnfd-connection-point-ref: [{}] }] ``` -`/nslcm/v1/ns_instances//terminate`. (rbac: `ns_instances:id:terminate:post`) +`/nslcm/v1/ns_instances/ID/terminate`. (rbac: `ns_instances:id:terminate:post`) - POST: (Asynchronous). Undeploys a NS that it is in INSTANTIATED state. It returns the nsLcmOpOccId (Operations Occurrence Id) in the response header `'Location'` -`/nslcm/v1/ns_instances//action`. (rbac: `ns_instances:id:action:post`) +`/nslcm/v1/ns_instances/ID/action`. (rbac: `ns_instances:id:action:post`) -- POST: (Asynchronous). Performs a Day-2 operation over the NS. It returns the nsLcmOpOccId (Operationts Occurence Id) in the response header `'Location'` - - Example of content to executing a primitive: +- POST: (Asynchronous). Performs a Day-2 operation over the NS. It returns the nsLcmOpOccId (Operationts Occurence Id) in the response header `'Location'`. Example of content to executing a primitive: ```yaml member_vnf_index: str # Needed for VNFD mapping NSD.constituent-vnfd.member-vnf-index. If missing a NSD is targeting @@ -450,29 +524,24 @@ primitive_params: dict # Optional. Maps [NSD.ns-configuration or VNFD.vnf-conf ... ``` -`/nslcm/v1/ns_instances//scale`. (rbac: `ns_instances:id:scale:post`) +`/nslcm/v1/ns_instances/ID/scale`. (rbac: `ns_instances:id:scale:post`) -- POST: (Asynchronous). Performs a manual scale OUT/IN over one of the VNFs of the NS. It returns the nsLcmOpOccId (Operationts Occurence Id) in the response header `'Location'` - - Example of content: +- POST: (Asynchronous). Performs a manual scale OUT/IN over one of the VNFs of the NS. It returns the nsLcmOpOccId (Operationts Occurence Id) in the response header `'Location'`. Example of content: -```json -{ - scaleType: SCALE_VNF, - scaleVnfData: { - scaleVnfType: SCALE_OUT|SCALE_IN, - scaleByStepData: { - member-vnf-index: , +```yaml + scaleType: SCALE_VNF + scaleVnfData: + scaleVnfType: SCALE_OUT|SCALE_IN + scaleByStepData: + member-vnf-index: scaling-group-descriptor: - } - } -} ``` `/nslcm/v1/ns_instances/nsi_lcm_op_occs`. (rbac: `ns_instances:opps`) - GET: Obtains the list of Operations occurrences. It may be useful filtering by a concrete NS with `'?nsInstanceId='` -`/nslcm/v1/ns_instances/nsi_lcm_op_occs/`. (rbac: `ns_instances:opps:id`) +`/nslcm/v1/ns_instances/nsi_lcm_op_occs/ID`. (rbac: `ns_instances:opps:id`) - GET: Show details of an Operations occurrences. @@ -480,7 +549,7 @@ primitive_params: dict # Optional. Maps [NSD.ns-configuration or VNFD.vnf-conf - GET: Obtains the list of VNF. It may be useful filtering by a concrete NS with `'?nsr-id-ref='` -`/nslcm/v1//vnf_instances/`. (rbac: `vnf_instances:id`) +`/nslcm/v1/ID/vnf_instances/`. (rbac: `vnf_instances:id`) - GET: Show details of a concrete VNF @@ -493,7 +562,7 @@ NetSlice Template descriptor - GET: (rbac: `slice_templates:get`). Obtain list of Network Slice Templates - POST (rbac: `slice_templates:content:post`). Create a Network Slice Template and upload the content -`/nst/v1/netslice_templates_content/`. (rbac: `slice_templates:id`) +`/nst/v1/netslice_templates_content/ID`. (rbac: `slice_templates:id`) - GET: Show the detail of Network Slice Template - PUT: Update the whole Network Slice Template @@ -504,22 +573,22 @@ NetSlice Template descriptor - GET: Obtain list of Network Slice Templates - POST: Create an empty Network Slice Template. A PUT should be done afterwards to upload the package -`/nst/v1/netslice_templates/`. (rbac: `slice_templates:id`) +`/nst/v1/netslice_templates/ID`. (rbac: `slice_templates:id`) - GET: Show the detail of Network Slice Template descriptor used by OSM - DELETE: Remove a Network Slice Template. The Network Slice template is removed only if state is `NOT_IN_USE`. - PATCH: Update a Network Slice Template field -`/nst/v1/netslice_templates//nst_content`. (rbac: `slice_templates:content`) +`/nst/v1/netslice_templates/ID/nst_content`. (rbac: `slice_templates:content`) - GET: Show the detail of the source Network Slice Template package - PUT: Update a Network Slice Template -`/nst/v1/netslice_templates//nst`. (rbac: `slice_templates:id:nst`) +`/nst/v1/netslice_templates/ID/nst`. (rbac: `slice_templates:id:nst`) - GET: Show the detail of the source Network Slice Template descriptor -`/nst/v1/netslice_templates//artifacts[/]`. (rbac: `slice_templates:id:nst_artifact`) +`/nst/v1/netslice_templates/ID/artifacts[/]`. (rbac: `slice_templates:id:nst_artifact`) - GET: Obtain Network Slice Templates Artifacts. This is useful for download the Network Slice Templates @@ -547,7 +616,7 @@ netslice-vld: ip-profile: Profile of the vld ``` -`/nsilcm/v1/netslice_instances_content/`. (rbac: `slice_instances:id`) +`/nsilcm/v1/netslice_instances_content/ID`. (rbac: `slice_instances:id`) - GET: Show details of a concrete Network Slice Instance - DELETE: (Asynchronous) Terminates (or _`undeploy`_) and deletes (if termination is done successfully) a Network Slice Instance Record @@ -557,16 +626,16 @@ netslice-vld: - GET: Obtain the list of Network Slice Instances - POST: Create the Network Slice Instance but do not instantiate it. It returns the netsliceInstanceId in the response header `'Location'`. Example of request content: Same content as section [NSILCM Details /nsilcm/v1/netslice_instances_content](#nsilcm-details) -`/nsilcm/v1/netslice_instances/`. (rbac: `slice_instances:id`) +`/nsilcm/v1/netslice_instances/ID`. (rbac: `slice_instances:id`) - GET: Show details of a concrete Network Slice Instance - DELETE: Delete the Network Slice Instance Record, if it is not instantiated -`/nsilcm/v1/netslice_instances//instantiate`. (rbac: `slice_instances:id:instantiate:post`) +`/nsilcm/v1/netslice_instances/ID/instantiate`. (rbac: `slice_instances:id:instantiate:post`) - POST: (Asynchronous). Deploys a Network Slice Instance that it is in `NOT_INSTANTIATED` state. It returns the `nsiLcmOpOccId` (Operations Occurrence Id) in the response header 'Location'. Example of request content: Same content as section [NSILCM Details /nsilcm/v1/netslice_instances_content](#nsilcm-details) -`/nsilcm/v1/netslice_instances//terminate`. (rbac: `slice_instances:id:terminate:post`) +`/nsilcm/v1/netslice_instances/ID/terminate`. (rbac: `slice_instances:id:terminate:post`) - POST: (Asynchronous). Undeploys a Network Slice Instance that it is in `INSTANTIATED` state. It returns the `nsLcmOpOccId` (Operations Occurrence Id) in the response header `'Location'` @@ -574,6 +643,6 @@ netslice-vld: - GET: Obtain the list of Network Slice Instances operations. It may be useful filtering by a concrete NSI with `'?netsliceInstanceId='` -`/nsilcm/v1/netslice_instances/nsi_lcm_op_occ/`. (rbac: `slice_instances:opps:id`) +`/nsilcm/v1/netslice_instances/nsi_lcm_op_occ/ID`. (rbac: `slice_instances:opps:id`) - GET: Show details of a concrete Network Slice Instance operation -- GitLab