Skip to content

Commit

Permalink
Add OpenAPI doucmentation to CNS (#1461)
Browse files Browse the repository at this point in the history
Add initial swagger documentation for CNS

This adds documentation for a few of the endpoints in CNS. It's not
exhaustive, but it's a place to start.
  • Loading branch information
timraymond committed Sep 28, 2023
1 parent 78a577c commit 9200af8
Showing 1 changed file with 353 additions and 0 deletions.
353 changes: 353 additions & 0 deletions cns/swagger.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,353 @@
---
openapi: "3.0.0"
info:
version: 0.1.0
title: Container Networking Service (CNS)
paths:
/network/nmagentsupportedapis:
post:
description: |
Returns the supported API names from NMAgent
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NMAgentSupportedAPIsRequest'
responses:
'200':
description: The list of supported API names
content:
application/json:
schema:
$ref: '#/components/schemas/NMAgentSupportedApisResponse'

/network/deletenetworkcontainer:
post:
summary: Removes the Network Container from CNS's purview
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/DeleteContainerRequest"
responses:
'200':
description: >-
The delete request was processed. This does not indicate the request
was successful.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteContainerResponse'

/network/setorchestratortype:
post:
description: >-
Sets the orchestrator type for a given node
requestBody:
required: true
content:
application/json:
schema:
$ref: "#components/schemas/SetOrchestratorTypeRequest"
responses:
'200':
description: The request was submitted. This does not indicate success.
content:
application/json:
schema:
$ref: '#/components/schemas/Response'

/network/createorupdatenetworkcontainer:
post:
requestBody:
required: true
content:
application/json:
schema:
$ref: "#components/schemas/CreateNetworkContainerRequest"
responses:
'200':
description: >-
The request was submitted. This does not indicate success. You
must check the value of the return code in the response body.
content:
application/json:
schema:
$ref: "#/components/schemas/Response"
/network/publishnetworkcontainer:
post:
summary: Publish NetworkContainer via NMAgent
description: >-
Publishes the provided network container via the NMAgent running on the
node CNS is running on. CNS acts as a proxy for this request.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/PublishNetworkContainerRequest"
responses:
'200':
description: >-
The request was submitted. Check the return code for success or
failure information.
content:
application/json:
schema:
$ref: "#/components/schemas/PublishNetworkContainerResponse"

/network/unpublishnetworkcontainer:
post:
summary: Unpublish Network Container via NMAgent
description: >-
Unpublishes the network container through the NMAgent running on the CNS
node. CNS acts as a proxy to NMAgent.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UnpublishNetworkContainerRequest"
responses:
'200':
description: >-
The request was submitted. Check the response code for more
information on success or failure.
content:
application/json:
schema:
$ref: "#/components/schemas/UnpublishNetworkContainerResponse"

components:
schemas:
UnpublishNetworkContainerResponse:
type: object
properties:
Response:
$ref: "#/components/schemas/Response"
UnpublishErrorStr:
type: string
UnpublishStatusCode:
type: string
UnpublishResponseBody:
type: string
description: >-
The base64 encoded response body from NMAgent
PublishNetworkContainerResponse:
type: object
properties:
Response:
$ref: "#/components/schemas/Response"
PublishErrStr:
type: string
PublishStatusCode:
type: string
PublishResponseBody:
type: string
description: >-
The base64 encoded response body from NMAgent
UnpublishNetworkContainerRequest:
type: object
properties:
NetworkID:
type: string
NetworkContainerID:
type: string
JoinNetworkURL:
type: string
DeleteNetworkContainerURL:
type: string

PublishNetworkContainerRequest:
type: object
properties:
NetworkID:
type: string
NetworkContainerID:
type: string
JoinNetworkURL:
type: string
CreateNetworkContainerURL:
type: string
CreateNetworkContainerRequestBody:
type: string
description: >-
The base64 encoded value of the create network container request
body
CreateNetworkContainerRequest:
type: object
properties:
Version:
type: string
NetworkContainerType:
type: string
NetworkContainerid:
type: string
PrimaryInterfaceIdentifier:
type: string
AuthorizationToken:
type: string
LocalIPConfiguration:
$ref: "#/components/schemas/IPConfiguration"
OrchestratorContext:
type: object
IPConfiguration:
$ref: "#/components/schemas/IPConfiguration"
SecondaryIPConfigs:
type: object
additionalProperties:
$ref: "#/components/schemas/SecondaryIPConfig"
MultiTenancyInfo:
type: object
properties:
EncapType:
type: string
description: >-
The encapsulation type for multitenancy.
ID:
type: integer
description: >-
The identifier associated with the encapsulation type specified.
For VLAN, this would be the VLAN ID. For VXLAN, the VXLAN id,
for GRE, the gre-key, etc.
CnetAddressSpace:
type: array
items:
$ref: "#/components/schemas/IPSubnet"
Routes:
type: array
items:
$ref: "#/components/schemas/Route"
AllowHostToNCCommunication:
type: boolean
AllowNCToHostCommunication:
type: boolean
EndpointPolicies:
type: array
items:
$ref: "#/components/schemas/NetworkContainerRequestPolicy"

NetworkContainerRequestPolicy:
type: object
description: >-
Specifies policies associated with a request to create a network
container.
properties:
Type:
type: string
EndpointType:
type: string
Settings:
type: object

Route:
type: object
properties:
IPAddress:
type: string
GatewayIPAddress:
type: string
InterfaceToUse:
type: string

SecondaryIPConfig:
type: object
properties:
IPAddress:
type: string
NCVersion:
type: integer

IPSubnet:
type: object
properties:
IPAddress:
type: string
PrefixLength:
type: integer
minimum: 0
maximum: 255
IPConfiguration:
type: object
properties:
IPSubnet:
$ref: "#/components/schemas/IPSubnet"
DNSServers:
type: array
items:
type: string
GatewayIPAddress:
type: string
SetOrchestratorTypeRequest:
type: object
required:
- OrchestratorType
- NodeID
properties:
OrchestratorType:
type: string
enum:
- "Kubernetes"
- "ServiceFabric"
- "Batch"
- "DBforPostgreSQL"
- "AzureFirstParty"
- "KubernetesCRD"
DncPartitionKey:
type: string
NodeID:
type: string

NMAgentSupportedAPIsRequest:
type: object
required:
- GetNmAgentSupportedApisURL
properties:
GetNmAgentSupportedApisURL:
type: string

DeleteContainerRequest:
type: object
required:
- NetworkContainerid
properties:
NetworkContainerid:
type: string

NMAgentSupportedApisResponse:
type: object
required:
- Response
- SupportedApis
properties:
Response:
$ref: "#/components/schemas/Response"
SupportedApis:
type: array
items:
type: string

DeleteContainerResponse:
type: object
required:
- Response
properties:
Response:
$ref: "#/components/schemas/Response"

Response:
type: object
required:
- ReturnCode
- Message
properties:
ReturnCode:
type: integer
description: The CNS Error Code
Message:
type: string
description: The error message

0 comments on commit 9200af8

Please sign in to comment.