From 2fcc1d744a2191ebc81f9158568d2506b11f623c Mon Sep 17 00:00:00 2001 From: zulfiqar Date: Thu, 6 May 2021 03:20:24 +0200 Subject: [PATCH] added notes in common SOL002SOL003_def.yaml file --- src/definitions/SOL002SOL003_def.yaml | 244 +++++++++++--------------- 1 file changed, 101 insertions(+), 143 deletions(-) diff --git a/src/definitions/SOL002SOL003_def.yaml b/src/definitions/SOL002SOL003_def.yaml index d833759f..0ce395f4 100644 --- a/src/definitions/SOL002SOL003_def.yaml +++ b/src/definitions/SOL002SOL003_def.yaml @@ -92,6 +92,12 @@ definitions: description: > This type represents subscription filter criteria to match VNF instances. + * NOTE 1: The attributes "vnfdIds" and "vnfProductsFromProviders" are alternatives to reference to VNF instances + that are based on certain VNFDs in a filter. They should not be used both in the same filter instance, + but one alternative should be chosen. + NOTE 2: The attributes "vnfInstanceIds" and "vnfInstanceNames" are alternatives to reference to particular VNF + instances in a filter. They should not be used both in the same filter instance, but one alternative + should be chosen. type: object anyOf: - oneOf: @@ -108,22 +114,14 @@ definitions: vnfdIds: description: > If present, match VNF instances that were created based on a VNFD - identified by one of the vnfdId values listed in this attribute. - The attributes "vnfdIds" and "vnfProductsFromProviders" are - alternatives to reference to VNF instances that are based on certain - VNFDs in a filter. They should not be used both in the same filter - instance, but one alternative should be chosen. + identified by one of the vnfdId values listed in this attribute. See note 1. type: array items: $ref: "#/definitions/Identifier" vnfProductsFromProviders: description: > If present, match VNF instances that belong to VNF products from - certain providers. - The attributes "vnfdIds" and "vnfProductsFromProviders" are - alternatives to reference to VNF instances that are based on certain - VNFDs in a filter. They should not be used both in the same filter - instance, but one alternative should be chosen. + certain providers. See note 1. type: array items: type: object @@ -175,22 +173,14 @@ definitions: vnfInstanceIds: description: > If present, match VNF instances with an instance identifier listed - in this attribute. - The attributes "vnfInstanceIds" and "vnfInstanceNames" are - alternatives to reference to particular VNF Instances in a filter. - They should not be used both in the same filter instance, but one - alternative should be chosen. + in this attribute. See note 2. type: array items: $ref: "#/definitions/Identifier" vnfInstanceNames: description: > If present, match VNF instances with a VNF Instance Name listed in - this attribute. - The attributes "vnfInstanceIds" and "vnfInstanceNames" are - alternatives to reference to particular VNF Instances in a filter. - They should not be used both in the same filter instance, but one - alternative should be chosen. + this attribute. See note 2. type: array items: type: string @@ -199,10 +189,17 @@ definitions: description: > This type represents parameters to connect to a VIM for managing the resources of a VNF instance. - This structure is used to convey VIM-related parameters over the Or-Vnfm - interface. Additional parameters for a VIM may be configured into the - VNFM by means outside the scope of the present document, and bound to - the identifier of that VIM. + * NOTE 1: If applicable, this attribute also provides information about the resourceGroupIds + that are accessible using a particular set of credentials. See definition of + "resourceGroupId" in clause 9.5.3.3. + * NOTE 2: Once the connectivity between VNFM and VIM is provided through a secure connection over + HTTP Secure (HTTP over SSL/TLS), and the connection might also be established through a VPN + (for example TLS-based VPN tunnelling) for site-to-site connection, the "accessInfo" JSON data + structure, and the sensitive data related information ("username"/"password" as required properties + for authentication purpose), will be transmitted as plain text through a TLS tunnel without additional + encoding/encryption before transmitting it, making the sensitive data visible to the endpoint. + The base64 encoded certificates are only used by the VNFM to verify the authenticity of the + interface endpoint of the VIM. type: object required: - vimType @@ -239,7 +236,7 @@ definitions: description: > Authentication credentials for accessing the VIM, and other access-related information such as tenants or infrastructure - resource groups (see note). The applicable keys are dependent on the + resource groups (see note 1). The applicable keys are dependent on the content of vimType. If the VimConnectionInfo structure is part of an HTTP response payload body, sensitive attributes that are children of this attributes @@ -249,19 +246,7 @@ definitions: as passwords) shall be present if they have not been provisioned out of band. - If applicable, this attribute also provides information about the - resourceGroupIds that are accessible using a particular set of credentials. - See definition of "resourceGroupId" in clause 9.5.3.3. - - Once the connectivity between VNFM and VIM is provided through a secure - connection over HTTP Secure (HTTP over SSL/TLS), and the connection might - also be established through a VPN (for example TLS-based VPN tunnelling) - for site-to-site connection, the "accessInfo" JSON data structure, - and the sensitive data related information ("username"/"password" as required - properties for authentication purpose), will be transmitted as plain text through - a TLS tunnel without additional encoding/encryption before transmitting it, - making the sensitive data visible to the endpoint. The base64 encoded certificates - are only used by the VNFM to verify the authenticity of the interface endpoint of the VIM. + See note 2. $ref: "#/definitions/KeyValuePairs" extra: description: > @@ -310,19 +295,28 @@ definitions: VnfExtCpData: description: > - This type represents configuration information for external CPs created - from a CPD. + This type represents configuration information for external CPs created. + * NOTE 1: In case this identifier refers to a CPD with trunking enabled, the external CP instances created + from this CPD will represent ports in a trunk. + * NOTE 2: Within one VNF instance, all VNFC instances created from a particular VDU have the same external + connectivity. Thus, given a particular value of the "cpdId" attribute, there shall be one + "cpConfig" entry for each VNFC instance that has been or can be created from a VDU which includes + a CPD identified by the "cpdId" attribute. If the cpConfig represents a subport in a trunk, + all "cpConfig" entries in this list shall have the same segmentationId, which means they are + connected to the same set of external VLs via the trunk. + * NOTE 3: The map entry value shall be set to "null" in order to delete a "VnfExtCpConfig" entry identified + by a particular key value from the map, i.e. for the disconnection of an existing external + CP instance addressed by cpInstanceId in the deleted map entry from a particular external + virtual link, and deletion of that instance in case it represents a subport. Deleting the + last key from the map removes the affected instance of the "VnfExtCpData" structure from + its parent data structure. type: object required: - cpdId properties: cpdId: description: > - The identifier of the CPD in the VNFD. In case this identifier refers to a CPD with trunking enabled, - the external CP instances created from this CPD will represent ports in a trunk. - - NOTE: In case this identifier refers to a CPD with trunking enabled, the external CP instances created - from this CPD will represent ports in a trunk. + The identifier of the CPD in the VNFD. See note 1. $ref: "#/definitions/IdentifierInVnfd" cpConfig: description: > @@ -330,16 +324,7 @@ definitions: created from the respective CPD. The key of the map which identifies the individual VnfExtCpConfig entries is managed by the API consumer. The entries shall be applied by the VNFM according to the rules of JSON Merge Patch (see IETF RFC 7396). - Within one VNF instance, all VNFC instances created from a particular VDU have the same external connectivity. - Thus, given a particular value of the “cpdId” attribute, there shall be one “cpConfig” entry for each VNFC - instance that has been or can be created from a VDU which includes a CPD identified by the “cpdId” attribute. - If the cpConfig represents a subport in a trunk, all “cpConfig” entries in this list shall have the same - segmentationId, which means they are connected to the same set of external VLs via the trunk. - The map entry value shall be set to "null" in order to delete a "VnfExtCpConfig" entry identified by a - particular key value from the map, i.e. for the disconnection of an existing external CP instance addressed - by cpInstanceId in the deleted map entry from a particular external virtual link, and deletion of that instance - in case it represents a subport. Deleting the last key from the map removes the affected instance of the - "VnfExtCpData" structure from its parent data structure. + See note 2 and note 3. type: object additionalProperties: $ref: "#/definitions/VnfExtCpConfig" @@ -352,6 +337,20 @@ definitions: external CP to the external VL. In a link port is not provided, the VNFM shall create a link port on the external VL, and use that link port to connect the external CP to the external VL. + * NOTE: The following conditions apply to the attributes "linkPortId" and "cpProtocolData": + 1) Void. + 2) At least one of the "linkPortId" and "cpProtocolData" attributes shall be present for an external + CP instance representing a subport that is to be created, or an external CP instance that is to be + created by creating the corresponding VNFC or VNF instance during the current or a subsequent LCM + operation, or for an existing external CP instance that is to be re-configured or added to a + particular external virtual link. + 3) If the "linkPortId" attribute is absent, the VNFM shall create a link port. + 4) If the "cpProtocolData" attribute is absent, the "linkPortId" attribute shall be provided referencing + a pre created link port, and the VNFM can use means outside the scope of the present document to obtain + the pre-configured address information for the connection point from the resource representing + the link port. + 5) If both "cpProtocolData" and "linkportId" are provided, the API consumer shall ensure that the + cpProtocolData can be used with the pre-created link port referenced by "linkPortId". anyOf: - required: - linkPortId @@ -369,22 +368,7 @@ definitions: linkPortId: description: > Identifier of a pre-configured link port to which the external CP - will be associated. - The following conditions apply to the attributes "linkPortId" and - "cpProtocolData": - 1) At least one of the "linkPortId" and "cpProtocolData" attributes shall - be present for a to-be-created external CP instance or an existing external - CP instance. - 2) If the "linkPortId" attribute is absent, the VNFM shall create a - link port. - 3) If the "cpProtocolData" attribute is absent, the "linkPortId" - attribute shall be provided referencing a pre-created link port, - and the VNFM can use means outside the scope of the present - document to obtain the pre-configured address information for the - connection point from the resource representing the link port. - 4) If both "cpProtocolData" and "linkportId" are provided, the API - consumer shall ensure that the cpProtocolData can be used with the - pre-created link port referenced by "linkPortId". + will be associated. See note $ref: "#/definitions/Identifier" createExtLinkPort: @@ -399,26 +383,7 @@ definitions: cpProtocolData: description: > Parameters for configuring the network protocols on the link port - that connects the CP to a VL. - The following conditions apply to the attributes "linkPortId" and - "cpProtocolData": - 1) Void - 2) At least one of the "linkPortId" and "cpProtocolData" attributes - shall be present for an external CP instance representing a subport - that is to be created, or an external CP instance that is to be created - by creating the corresponding VNFC or VNF instance during the current or - a subsequent LCM operation, or for an existing external CP instance - that is to be re-configured or added to a particular external virtual link. - 3) If the "linkPortId" attribute is absent, the VNFM shall create a - link port. - 4) If the "cpProtocolData" attribute is absent, the "linkPortId" - attribute shall be provided referencing a pre-created link port, - and the VNFM can use means outside the scope of the present - document to obtain the pre-configured address information for the - connection point from the resource representing the link port. - 5) If both "cpProtocolData" and "linkportId" are provided, the API - consumer shall ensure that the cpProtocolData can be used with the - pre-created link port referenced by "linkPortId". + that connects the CP to a VL. See note. type: array items: $ref: "#/definitions/CpProtocolData" @@ -426,17 +391,16 @@ definitions: CpProtocolData: description: > This type represents network protocol data. + * NOTE: This attribute allows to signal the addition of further types of layer and protocol + in future versions of the present document in a backwards-compatible way. In the current + version of the present document, only IP over Ethernet is supported. type: object required: - layerProtocol properties: layerProtocol: description: > - Identifier of layer(s) and protocol(s). - This attribute allows to signal the addition of further types of - layer and protocol in future versions of the present document in a - backwards-compatible way. In the current version of the present - document, only IP over Ethernet is supported. + Identifier of layer(s) and protocol(s). See note. type: string enum: - IP_OVER_ETHERNET @@ -450,6 +414,16 @@ definitions: IpOverEthernetAddressData: description: > This type represents network address data for IP over Ethernet. + * NOTE 1: At least one of "macAddress" or "ipAddresses" shall be present. + * NOTE 2: Exactly one of "fixedAddresses", "numDynamicAddresses" or "ipAddressRange" shall be present. + * NOTE 3: If the CP instance represents a subport in a trunk, segmentationId shall be present. + Otherwise it shall not be present. + * NOTE 4: Depending on the NFVI networking infrastructure, the segmentationId may indicate the actual + network segment value (e.g. vlan Id, Vxlan segmentation id, etc.) used in the transport header + of the packets or it may be an identifier used between the application and the NFVI networking + infrastructure to identify the network sub-interface of the trunk port in question. In the latter + case the NFVI infrastructure will map this local segmentationId to whatever segmentationId is + actually used by the NFVI’s transport technology. type: object anyOf: - required: @@ -467,8 +441,7 @@ definitions: macAddress: description: > MAC address. If this attribute is not present, it shall be chosen by - the VIM. - At least one of "macAddress" or "ipAddresses" shall be present. + the VIM. See note 1. $ref: "#/definitions/MacAddress" segmentationType: description: > @@ -485,20 +458,14 @@ definitions: segmentationId: description: > - Identification of the network segment to which the CP instance connects to. If the CP instance represents a - subport in a trunk, segmentationId shall be present. Otherwise it shall not be present. - Depending on the NFVI networking infrastructure, the segmentationId may indicate the actual network segment - value (e.g. vlan Id, Vxlan segmentation id, etc.) used in the transport header of the packets or it may be an - identifier used between the application and the NFVI networking infrastructure to identify the network - sub-interface of the trunk port in question. In the latter case the NFVI infrastructure will map this local - segmentationId to whatever segmentationId is actually used by the NFVI’s transport technology. + Identification of the network segment to which the CP instance connects to. See note 3 and note 4. type: string ipAddresses: description: > List of IP addresses to assign to the CP instance. Each entry represents IP address data for fixed or dynamic IP address assignment per subnet. - If this attribute is not present, no IP address shall be assigned. + If this attribute is not present, no IP address shall be assigned. See note 1. type: array items: type: object @@ -516,25 +483,21 @@ definitions: fixedAddresses: description: > Fixed addresses to assign (from the subnet defined by - "subnetId" if provided). - Exactly one of "fixedAddresses", "numDynamicAddresses" or - "ipAddressRange" shall be present. + "subnetId" if provided). See note 2. type: array items: $ref: "#/definitions/IpAddress" numDynamicAddresses: description: > Number of dynamic addresses to assign (from the subnet defined - by "subnetId" if provided). - Exactly one of "fixedAddresses", "numDynamicAddresses" or - "ipAddressRange" shall be present. + by "subnetId" if provided). See note 2. type: integer addressRange: description: > An IP address range to be used, e.g. in case of egress connections. In case this attribute is present, IP addresses from the range - will be used. + will be used. See note 2. type: object required: - minAddress @@ -560,6 +523,16 @@ definitions: ExtVirtualLinkData: description: > This type represents an external VL. + * NOTE 1: The information about the VIM connection referenced by the VIM connection id is known to the VNFM. + Moreover, the identifier of the VIM connection provides scope to the resourceId. + * NOTE 2: A link port is not needed for an external CP instance that exposes a VIP CP in the following cases: + 1 For a VIP CP directly exposed as extCP: + 1.1 No dedicated IP address is allocated as VIP address, as indicated in the VNFD. + 1.2 A dedicated IP addresss is allocated as VIP address, but the NFVO indicates that no port + is needed (createExtLinkPort in VnfExtCpconfig set to false). + 2 For a VIP CP exposed as extCP via a floating IP address: + 2.1 No dedicated IP address is allocated as VIP address, as indicated in the VNFD, and the VNFC + CP associated to the VIP CP is also exposed via a floating IP addresss. type: object required: - id @@ -575,7 +548,7 @@ definitions: description: > Identifier of the VIM connection to manage this resource. This attribute shall only be supported and present if VNF-related - resource management in direct mode is applicable. + resource management in direct mode is applicable. See note 1. $ref: "#/definitions/Identifier" resourceProviderId: description: > @@ -602,15 +575,7 @@ definitions: connection points to this external VL. If this attribute is not present, the VNFM shall create the link ports on the external VL unless the extCp exposes a VIP CP and a link port is not needed - for it based on the conditions defined below. - A link port is not needed for an external CP instance that exposes a VIP CP in the following cases: - 1 For a VIP CP directly exposed as extCP: - 1.1 No dedicated IP address is allocated as VIP address, as indicated in the VNFD. - 1.2 A dedicated IP address is allocated as VIP address, but the NFVO indicates that no - port is needed (createExtLinkPort in VnfExtCpConfig set to false). - 2 For a VIP CP exposed as extCP via a floating IP address: - 2.1 No dedicated IP address is allocated as VIP address, as indicated in the VNFD, and - the VNFC CP associated to the VIP CP is also exposed via a floating IP address. + for it based on the conditions defined below. See note 2. type: array items: $ref: "#/definitions/ExtLinkPortData" @@ -727,6 +692,7 @@ definitions: description: > This type represents an externally provided link port to be used to connect an external connection point to an external VL. + * NOTE: The value of "trunkResourceId" is scoped by the value of "vimConnectionId" in the "resourceHandle" attribute. type: object required: - id @@ -746,9 +712,7 @@ definitions: description: > Identifier of the trunk resource in the VIM. Shall be present if the present link port corresponds to the parent - port that the trunk resource is associated with. - The value of \"trunkResourceId\" is scoped by the value of - \"vimConnectionId\" in the \"resourceHandle\" attribute. + port that the trunk resource is associated with. See note. $ref: "#/definitions/IdentifierInVim" GrantedLcmOperationType: @@ -823,17 +787,17 @@ definitions: #SOL003 location: 4.3.5.3 description: > The definition of the general "ProblemDetails" data structure from - IETF RFC 7807 [19] is reproduced inthis structure. Compared to the - general framework defined in IETF RFC 7807 [19], the "status" and + IETF RFC 7807 is reproduced inthis structure. Compared to the + general framework defined in IETF RFC 7807, the "status" and "detail" attributes are mandated to be included by the present document, to ensure that the response contains additional textual information about - an error. IETF RFC 7807 [19] foresees extensibility of the + an error. IETF RFC 7807 foresees extensibility of the "ProblemDetails" type. It is possible that particular APIs in the present document, or particular implementations, define extensions to define additional attributes that provide more information about the error. The description column only provides some explanation of the meaning to Facilitate understanding of the design. For a full description, see - IETF RFC 7807 [19]. + IETF RFC 7807. type: object required: - status @@ -841,7 +805,7 @@ definitions: properties: type: description: > - A URI reference according to IETF RFC 3986 [5] that identifies the + A URI reference according to IETF RFC 3986 that identifies the problem type. It is encouraged that the URI provides human-readable documentation for the problem (e.g. using HTML) when dereferenced. When this member is not present, its value is assumed to be @@ -879,6 +843,10 @@ definitions: #TODO: How to express "any additional attributes"? SubscriptionAuthentication: + description: > + * NOTE: The clientId and clientPassword passed in a subscription shall not be the same as the clientId and + clientPassword that are used to obtain authorization for API requests. Client credentials may differ between + subscriptions. The value of clientPassword should be generated by a random process type: object required: - authType @@ -935,23 +903,13 @@ definitions: description: > Client identifier to be used in the access token request of the OAuth 2.0 client credentials grant type. - Shall be present if it has not been provisioned out of band. - The clientId and clientPassword passed in a subscription shall - not be the same as the clientId and clientPassword that are used - to obtain authorization for API requests. Client credentials may - differ between subscriptions. The value of clientPassword should - be generated by a random process. + Shall be present if it has not been provisioned out of band. See note. type: string clientPassword: description: > Client password to be used in the access token request of the OAuth 2.0 client credentials grant type. - Shall be present if it has not been provisioned out of band. - The clientId and clientPassword passed in a subscription shall - not be the same as the clientId and clientPassword that are used - to obtain authorization for API requests. Client credentials may - differ between subscriptions. The value of clientPassword should - be generated by a random process. + Shall be present if it has not been provisioned out of band. See note. type: string tokenEndpoint: description: > -- GitLab