为 VNF 包添加制品支持¶

https://blueprints.launchpad.net/tacker/+spec/add-artifacts-vnf-packages

本文档描述了 Tacker 中 VNF 包管理的增强。

问题描述¶

在 Train 和 Ussuri 版本中，我们添加了 ETSI NFV-SOL 005 etsi_sol005 中定义的 VNF 包管理的支持，如 spec1 和 spec2 中所述。现在，我们希望扩展该支持，并实现从 CSAR 包内的 TOSCA.meta 和 manifest 文件中读取制品信息，如 ETSI NFV-SOL 004 etsi_sol004 中所述，在上传 VNF 包时。

提议的变更¶

为了在 VNF 包中添加制品支持，我们需要对以下组件进行更改

Tacker API 和 Conductor 服务
- 在上传 vnf 包时，读取 TOSCA.meta 和 Manifest 文件中的制品信息，并将其存储在新的数据库表中，如数据模型影响中所述。
- 修改 GET /vnf_packages/{vnfPkgId} REST API，以在响应中包含 additionalArtifacts 参数。
- 添加新的 REST API GET /vnf_packages/{vnfPkgId}/artifacts/{artifactPath}，以获取已上载 VNF 包中的单个制品。
- 读取并验证 TOSCA.meta 和 manifest 文件中的制品信息。
python-tackerclient
- 修改 vnf package show 命令，以显示 additionalArtifacts 信息。
- 添加新的 OSC 命令 vnf package artifact，以获取已上载 VNF 包中的单个制品。

从 TOSCA.meta 和 Manifest 文件读取制品信息¶

制品信息可以在 CSAR 包中的以下类型的文件中找到：-

TOSCA.meta

如果 CSAR 包包含 TOSCA.meta 文件，则可以根据 TOSCA v1.0 规范指定制品信息，如下所示

TOSCA-Meta-File-Version: 1.0
Created-by: Author_name
CSAR-Version: 1.1
Entry-Definitions: Definitions/root.yaml

Name: MRF.yaml
Content-Type: text/plain
Algorithm: SHA-256
Hash: 09e5a788acb180162c51679ae4c998039fa6644505db2415e35107d1ee213943

Name: scripts/install.sh
Content-Type: application/x-sh
Algorithm: SHA-256
Hash: d0e7828293355a07c2dccaaa765c80b507e60e6167067c950dc2e6b0da0dbd8b

Name: https://www.vendor_org.com/MRF/v4.1/scripts/scale/scale.sh
Content-Type: application/x-sh
Algorithm: SHA-256
Hash: 36f945953929812aca2701b114b068c71bd8c95ceb3609711428c26325649165

Name: Files/images/cirros.img
Content-Type: application/x-iso9066-image
Algorithm: SHA-256
Hash: 9569dfc57e26436315180cb61f2d0d45c0de7c0ddb47d5759271ae825dc3acab

注意

如果源在任何 VNFDs 的 artifacts 属性下引用，类型为 tosca.nodes.nfv.Vdu.VirtualBlockStorage 和 tosca.nodes.nfv.Vdu.Compute，并且制品类型为 tosca.artifacts.nfv.SwImage 或从类型 tosca.artifacts.Deployment.Image 派生，则应忽略这些制品，因为软件镜像不应包含在 additionalArtifacts 中，如表 10.5.2.2 etsi_sol003 中所述。

Manifest 文件

CSAR VNF 包应具有 manifest 文件。该 manifest 文件应具有 .mf 扩展名，并且与主 TOSCA 定义 YAML 文件具有相同的名称，并位于存档的根目录（不含 TOSCA-Metadata 目录）或 TOSCA.meta 文件指定的位置（包含 TOSCA-Metadata 目录）。在后一种情况下，相应的条目应命名为“ETSI-Entry-Manifest”。

manifest 文件应以 VNF 包元数据形式的名称-值对开头，但在 ‘Victoria’ 版本中，我们将完全忽略元数据部分，并仅处理制品信息，如下所示

metadata:
  vnf_product_name: vMRF
  vnf_provider_id: Acme
  vnf_package_version: 1.0
  vnf_release_date_time: 2017-01-01T10:00:00+03:00

Source: MRF.yaml
Algorithm: SHA-256
Hash: 09e5a788acb180162c51679ae4c998039fa6644505db2415e35107d1ee213943

Source: scripts/install.sh
Algorithm: SHA-256
Hash: d0e7828293355a07c2dccaaa765c80b507e60e6167067c950dc2e6b0da0dbd8b

Source: https://www.vendor_org.com/MRF/v4.1/scripts/scale/scale.sh
Algorithm: SHA-256
Hash: 36f945953929812aca2701b114b068c71bd8c95ceb3609711428c26325649165

Source: Files/images/cirros.img
Algorithm: SHA-256
Hash: 9569dfc57e26436315180cb61f2d0d45c0de7c0ddb47d5759271ae825dc3acab

注意

如果源在任何 VNFDs 的 artifacts 下引用，并且制品类型为 tosca.artifacts.nfv.SwImage 或从类型 tosca.artifacts.Deployment.Image 派生，则应忽略这些制品。manifest 文件中没有提供指定 metadata 的方法，因此在 additionalArtifacts 参数中的类型 VnfPackageArtifactInfo 的 metadata 返回值始终为空字典。

注意

当在 TOSCA.meta 或 manifest 文件中提供具有 Name 的 URI 的外部资源时，应将其存储在 vnf_artifacts 数据库表中，但由于用户可以直接从 URI 获取它，因此无法使用新的 API GET /vnf_packages/{vnfPkgId}/artifacts/{artifactPath} 获取它。

Tosca 定义 VNFD 文件

您还可以将制品添加到 VNFD 中，用于软件镜像和/或从类型 tosca.artifacts.Deployment 或直接从 tosca.artifacts.Root 派生的其他制品，但它不强制您指定 ETSI GS NFV-SOL 003 第 10.5.3.3 节 etsi_sol003 所必需的 checksum，因此，包含在 VNFDs 中的所有此类制品将被忽略，并且不会在 GET /vnf_packages/{vnfPkgId} API 响应的 additionalArtifacts 参数中返回。

示例

VDU2:
  type: tosca.nodes.nfv.Vdu.Compute
    properties:
      name: VDU2
      sw_image_data:
        name: VrtualStorage
        version: '0.4.0'
        checksum:
          algorithm: sha-256
          hash: b9c3036539fd7a5f87a1bf38eb05fdde8b556a1a7e664dbeda90ed3cd74b4f9d
        container_format: bare
        disk_format: qcow2
        min_disk: 2 GB
        min_ram: 8192 MB
        size: 2 GB
      .....
  artifacts:
    sw_image:
      type: tosca.artifacts.nfv.SwImage
      file: Files/images/cirros.img
    python_script:
      type: tosca.artifacts.Deployment
      file: Files/scripts/my_python.py

在 PUT /vnf_packages/{id}/package_content API 中上传 CSAR 包时，它将从 TOSCA.meta 和 Manifest 文件读取制品信息，并将这些制品存储在新的数据库表 vnf_artifacts 中。然后，这些制品信息将在 GET /vnf_packages/{vnfPkgId} API 中返回，如下所示

{
  'additionalArtifacts': [{
      'artifactPath': 'MRF.yaml',
      'checksum': {
        'algorithm': 'sha-256',
        'hash': '09e5a788acb180162c51679ae4c998039fa6644505db2415e35107d1ee213943'
      }
      'metadata': {}
  },
  {
      'artifactPath': 'https://www.vendor_org.com/MRF/v4.1/scripts/scale/scale.sh',
      'checksum': {
        'algorithm': 'sha-256',
        'hash': '36f945953929812aca2701b114b068c71bd8c95ceb3609711428c26325649165'
      }
      'metadata': {}
  },
  {
      'artifactPath': 'scripts/install.sh',
      'checksum': {
        'algorithm': 'sha-256',
        'hash': 'd0e7828293355a07c2dccaaa765c80b507e60e6167067c950dc2e6b0da0dbd8b'
      }
      'metadata': {}
  }]
}

数据模型影响¶

在 ‘tacker’ 数据库中添加以下新的数据库表。

vnf_artifacts:

id int(11) Pri, auto_increment

package_uuid varchar(36) NOT NULL

artifact_path text NOT NULL

algorithm varchar(64) NOT NULL

hash varchar(128) NOT NULL

metadata json NULL

created_at datetime NOT NULL

updated_at datetime NOT NULL

deleted_at datetime NULL

deleted tinyint(1) NULL

此表将具有 id 作为主键。package_uuid 将是 vnf_packages.`package_uuid` 的外键。

REST API 影响¶

修改 GET /vnf_packages/{vnfPkgId}

在响应中返回 additionalArtifacts 参数，如下所示

{
  "vnfSoftwareVersion":"1.0",
  "usageState":"NOT_IN_USE",
  "vnfProductName":"Sample VNF",
  "softwareImages":[]
  "vnfProvider":"Test VNF Provider",
  "userDefinedData":{}
  "vnfdId":"b3ab49d6-389d-46f9-8650-d0bf778b5e92",
  "additionalArtifacts": [{
    "artifactPath" : "foobar/foo/foo.yaml"
    "checksum": {
      "algorithm": "sha-256",
      "hash": "b9c3036539fd7a5f87a1bf38eb05fdde8b556a1a7e664dbeda90ed3cd74b4f9d"
    },
    "metadata": {
      "Content-Type": "application/json",
      "size": "1024",
    }
  }],
  "_links":{
    "packageContent":{
      "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb/package_content"
    },
    "self":{
      "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb"
    },
    "vnfd":{
      "href":"/vnfpkgm/v1/vnf_packages/4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb/vnfd"
    }
  },
  "vnfdVersion":"1.0",
  "onboardingState":"ONBOARDED",
  "operationalState":"DISABLED",
  "id":"4e8b9d2c-ecb5-408b-a8ce-8ea0890bacbb"
}

注意

如果用户已经在之前的版本中上传了 vnf 包，那么在这种情况下，在 GET /vnf_packages/{vnfPkgId} API 中，响应的 additionalArtifacts 参数始终将返回一个空列表。在 VNF 包内容上载之前，此参数将不存在。

注意

additionalArtifacts 不应包含 VNFC 的镜像。

修改 GET /vnf_packages

允许用户根据请求中的 additionalArtifacts 查询参数过滤 vnf 包。

例如，以下 URL 查询参数将获取与 algorithm=sha-256 匹配的 vnf 包
```
GET /vnf_packages?filter=(eq,additionalArtifacts/checksum/algorithm,sha-256)
```
additionalArtifacts 属性是一个复杂的属性，因此默认情况下它不会在响应中返回。如果用户想要查看/隐藏此复杂属性，则需要使用以下方式显式查询：-
1. all_fields: 此 URI 查询参数请求在响应中包含所有复杂属性，例如，GET /vnf_packages?all_fields 将在响应中返回 additionalArtifacts。
2. fields: 此 URI 查询参数请求在响应中包含列出的复杂属性。例如，GET /vnf_packages?fields=additionalArtifacts/checksum 将仅返回 additionalArtifacts 的 checksum 以及其他简单属性。
  
  示例响应如下所示
```
{
  'vnfSoftwareVersion': '1.0',
  'usageState': 'NOT_IN_USE',
  'vnfProductName': 'Sample VNF',
  ...
  'additionalArtifacts': [{
      'checksum': {
          'algorithm': 'sha-256',
          "hash": "b9c3036539fd7a5f87a1bf38eb05fdde8b556a1a7e664dbeda90ed3cd74b4f9d"
      }
  }]
}
```
3. exclude_fields: 此 URI 查询参数请求从响应中排除列出的复杂属性。
  
  例如，GET /vnf_packages?exclude_fields=additionalArtifacts/checksum 不会返回 checksum 的 additionalArtifacts。它将包含 additionalArtifacts 的其他属性，如 metadata 和 artifactPath。
4. exclude_default: 此 URI 查询参数请求从响应中排除默认一组复杂属性。
  
  例如，GET /vnf_packages?exclude_default 或 GET /vnf_packages 不会包含响应中的 additionalArtifacts 复杂属性。

添加新的 API - GET /vnf_packages/{vnfPkgId}/artifacts/{artifactPath}

获取 VNF 包中的制品内容。请求可以包含“Range”HTTP 标头，以获取制品文件中的单个字节范围。
方法类型：GET
正常的 http 响应代码：200 OK 或 206 Partial Content

预期的错误 http 响应代码

401 NotAuthorized: shall be returned when authentication fails.

403 Forbidden: Shall be returned when user is not authorized to call
this REST API.

404 NotFound: Shall be returned when the vnfPkgId or artifactPath specified in
the URL doesn't exists.

409 Conflict: Shall be returned when "onboardingState" of the VNF package has
value different from "ONBOARDED".

416 Range Not Satisfiable: Shall be returned when the byte range passed in the
"Range" header did not match any available byte range in the artifact file.
(e.g. "access after end of file").

响应 - 返回制品文件的整个内容。有效负载主体应包含来自 VNF 包的制品文件的副本，如 ETSI GS NFV-SOL 004 etsi_sol004 中定义的。 Content-Type HTTP 标头应根据制品文件的内容类型设置。如果无法确定内容类型，则应将标头设置为 application/octet-stream。

其他最终用户影响¶

添加新的 OSC 命令以获取已上载 VNF 包中的单个制品
```
openstack vnf package artifact <vnfPkgId> <artifactPath>
```
修改 OSC 命令 vnf package list 和 vnf package show，以在控制台输出中显示 additionalArtifacts 信息。

其他部署者影响¶

将为新添加的 restFul API 添加以下默认策略。如果您想自定义这些策略，则必须编辑 policy.json 文件。

# Fetch an individual artifact in an on-boarded VNF package.
# GET  /vnf_packages/{vnfPkgId}/artifacts/{artifactPath}
# "os_nfv_orchestration_api:vnf_packages:fetch_artifact": "rule:admin_or_owner"

实现¶

负责人¶

主要负责人

伊藤良人 <yoshito.itou.dr@hco.ntt.co.jp>

其他贡献者

Nitin Uikey <nitin.uikey@nttdata.com>

Tushar Patil <tushar.vitthal.patil@gmail.com>

Prashant Bhole <prashant.bhole@nttdata.com>

工作项¶

修改 GET /vnf_packages/{vnfPkgId} API 以在响应中返回 additionalArtifacts 参数。
修改 GET /vnf_packages API 以根据类型为 VnfPackageArtifactInfo 的属性选择查询参数过滤 VNF 包。
实现新的 Rest API GET /vnf_packages/{vnfPkgId}/artifacts/{artifactPath}，以获取已上载 VNF 包中的单个制品。
修改 tosca-parser 以读取并验证 TOSCA.meta 和 Manifest 文件中的制品信息。
在上传 VNF 包时，从 TOSCA.meta 和 Manifest 文件读取制品信息。
添加单元和功能测试。

依赖项¶

无

测试¶

将添加所需的单元和功能测试，以验证从已上载的 VNF 包中正确设置和检索制品信息。

文档影响¶

更新 REST API 影响中提到的所有 API 更改的 API 文档。

参考资料¶

无

为 vnf 包添加 artifacts 支持