結構描述檔

身為系統管理員，當您使用「開放 API 資料模型 (結構描述)」區段定義範本服務包的參數結構描述 YAML 檔案時， AWS Proton 可以根據您在結構描述中定義的需求驗證參數值輸入。

如需有關格式和可用關鍵字的詳細資訊，請參閱 OpenAPI 的結構描述物件一節。

環境範本組合的結構描述需求

您的結構描述必須遵循 OpenAPI 的資料模型 (架構) 區段，採用 YAML 格式。它也必須是環境範本包的一部分。

對於您的環境結構描述，您必須包含格式化的標頭，以確定您正在使用 Open API 的資料模型 (結構描述) 區段。在下列環境結構描述範例中，這些標頭會出現在前三行中。

必environment_input_type須使用您提供的名稱包含和定義。在下列範例中，這是在第 5 行定義的。透過定義此參數，您可以將其與 AWS Proton 環境資源產生關聯。

若要遵循 Open API 結構描述模型，您必須包含types. 在下面的例子中，這是第 6 行。

接下來types，您必須定義一個environment_input_type類型。您可以將環境的輸入參數定義為的性質environment_input_type。您必須包含至少一個屬性，其名稱與環境基礎結構中列出的至少一個參數相符，作為與結構描述相關聯的程式碼 (IaC) 檔案。

當您建立環境並提供自訂參數值時， AWS Proton 會使用結構描述檔案來比對、驗證，並將其插入至關聯 CloudFormation IaC 檔案中的大括弧參數。對於每個性質 (參數)，提供name和type。您也可以選擇性地提供descriptiondefault、和pattern。

下列範例標準環境範本結構描述所定義的參數包括vpc_cidrsubnet_one_cidr、subnet_two_cidr與default關鍵字和預設值。當您使用此環境範本套件結構描述建立環境時，您可以接受預設值或提供您自己的預設值。如果參數沒有預設值且列為required屬性 (參數)，您必須在建立環境時提供該參數的值。

第二個範例標準環境範本結構描述會列出required參數my_other_sample_input。

您可以為兩種類型的環境樣板建立結構描述。如需詳細資訊，請參閱註冊和發佈範本。

標準環境範本

在下列範例中，使用描述和輸入性質定義環境輸入類型。此結構描述範例可與範例 3 中所示的 AWS Proton CloudFormation IaC 檔案搭配使用。

標準環境範本的範例結構描述：


schema:                            # required
  format:                          # required
    openapi: "3.0.0"               # required
  # required              defined by administrator
  environment_input_type: "PublicEnvironmentInput"
  types:                           # required
    # defined by administrator
    PublicEnvironmentInput:
      type: object
      description: "Input properties for my environment"
      properties:
        vpc_cidr:                   # parameter
          type: string
          description: "This CIDR range for your VPC"
          default: 10.0.0.0/16
          pattern: ([0-9]{1,3}\.){3}[0-9]{1,3}($|/(16|24))
        subnet_one_cidr:            # parameter
          type: string
          description: "The CIDR range for subnet one"
          default: 10.0.0.0/24
          pattern: ([0-9]{1,3}\.){3}[0-9]{1,3}($|/(16|24))
        subnet_two_cidr:            # parameter
          type: string
          description: "The CIDR range for subnet one"
          default: 10.0.1.0/24
          pattern: ([0-9]{1,3}\.){3}[0-9]{1,3}($|/(16|24))

包含required參數的標準環境範本的範例結構描述：


schema:                            # required
  format:                          # required
    openapi: "3.0.0"               # required
  # required              defined by administrator
  environment_input_type: "MyEnvironmentInputType"
  types:                           # required
    # defined by administrator
    MyEnvironmentInputType:
      type: object
      description: "Input properties for my environment"
      properties:
        my_sample_input:           # parameter
          type: string
          description: "This is a sample input"
          default: "hello world"
        my_other_sample_input:     # parameter
          type: string
          description: "Another sample input"
        another_optional_input:    # parameter
          type: string
          description: "Another optional input"
          default: "!"
      required:
        - my_other_sample_input

客戶管理的環境範本

在下列範例中，結構描述只包含複寫您用來佈建客戶管理基礎結構之 IaC 輸出的輸出清單。您需要將輸出值類型定義為僅字符串（而不是列表，數組或其他類型）。例如，下一個程式碼片段會顯示外部 AWS CloudFormation 範本的輸出區段。這是從示例 1 中顯示的模板。它可用於為範例 4 所建立的 AWS Proton Fargate 服務建立外部客戶管理的基礎架構。

重要

身為系統管理員，您必須確定已佈建和受管理的基礎結構，以及所有輸出參數都與相關聯的客戶受管理環境範本相容。 AWS Proton 無法代表您考慮變更，因為這些變更不會顯示給您 AWS Proton。不一致會導致失敗。

客戶管理環境範本的範例 CloudFormation IaC 檔案輸出：


// Cloudformation Template Outputs
[...]
Outputs:
  ClusterName:
    Description: The name of the ECS cluster
    Value: !Ref 'ECSCluster'
  ECSTaskExecutionRole:
    Description: The ARN of the ECS role
    Value: !GetAtt 'ECSTaskExecutionRole.Arn'
  VpcId:
    Description: The ID of the VPC that this stack is deployed in
    Value: !Ref 'VPC'
[...]

下列範例顯示對應 AWS Proton 客戶管理環境範本套裝軟體的結構描述。每個輸出值被定義為一個字符串。

客戶受管理環境範本的範例結構描述：


schema:                            # required
  format:                          # required
    openapi: "3.0.0"               # required
  # required              defined by administrator
  environment_input_type: "EnvironmentOutput"
  types:                           # required
    # defined by administrator
    EnvironmentOutput:
      type: object
      description: "Outputs of the environment"
      properties:
        ClusterName:               # parameter
          type: string
          description: "The name of the ECS cluster"
        ECSTaskExecutionRole:      # parameter
          type: string
          description: "The ARN of the ECS role"
        VpcId:                     # parameter
          type: string
          description: "The ID of the VPC that this stack is deployed in"
[...]

服務範本組合的結構描述需求

您的結構描述必須遵循 OpenAPI 的 YAML 格式的資料模型 (結構描述) 區段，如下列範例所示。您必須在服務範本包中提供結構描述檔案。

在下列服務結構描述範例中，您必須包含格式化的標頭。在下面的例子中，這是在前三行。這是為了確定您正在使用 Open API 的數據模型（模式）部分。

service_input_type必須使用您提供的名稱包含並定義 A。在下面的例子中，這是在第 5 行。這會將參數與 AWS Proton 服務資源產生關聯。

當您使用主控台或 CLI 建立 AWS Proton 服務時，依預設會包含服務管線。當您為服務包含服務管道時，必須包pipeline_input_type含您提供的名稱。在下面的例子中，這是在第 7 行。如果您不包含 AWS Proton 服務管線，請勿包含此參數。如需詳細資訊，請參閱註冊和發佈範本。

若要遵循 Open API 結構描述模型，您必須types在下列範例中包含在第 9 行中。

接下來types，您必須定義一個service_input_type類型。您可以將服務的輸入參數定義為的屬性service_input_type。您必須包含至少一個具有名稱的屬性，該屬性與服務基礎結構中列出的至少一個參數相符，作為與結構描述相關聯的程式碼 (IaC) 檔案。

若要定義服務管線，您必須在定service_input_type義之下定義一個pipeline_input_type. 如上所述，您必須包含至少一個屬性，其名稱與結構描述相關聯的管線 IaC 檔案中列出的至少一個參數相符。如果您不包含 AWS Proton 服務管線，請勿包含此定義。

當您身為系統管理員或開發人員，建立服務並提供自訂參數值時， AWS Proton 會使用結構描述檔來比對、驗證，並將其插入關聯的 CloudFormation IaC 檔案的大括弧參數中。對於每個性質 (參數)，提供name和type。您也可以選擇性地提供descriptiondefault、和pattern。

範例結構描述的定義參數包括portdesired_count、task_sizeimage和default關鍵字和預設值。當您使用此服務範本套件結構描述建立服務時，您可以接受預設值或提供您自己的預設值。此參數unique_name也包含在範例中，且沒有預設值。它會列示為required性質 (參數)。您身為管理員或開發人員，必須在建立服務時提供required參數值。

如果您要使用服務管線建立服務範本，請在結構描述pipeline_input_type中加入。

包含服務管線之服務的範例服務結構描述檔案。 AWS Proton

此結構描述範例可與範例 4 和範例 5 中所示的 AWS Proton IaC 檔案搭配使用。包括一個服務管道。


schema:                            # required
  format:                          # required
    openapi: "3.0.0"               # required
  # required           defined by administrator
  service_input_type: "LoadBalancedServiceInput"
  # only include if including AWS Proton service pipeline, defined by administrator
  pipeline_input_type: "PipelineInputs"

  types:                           # required
    # defined by administrator
    LoadBalancedServiceInput:
      type: object
      description: "Input properties for a loadbalanced Fargate service"
      properties:
        port:                      # parameter
          type: number
          description: "The port to route traffic to"
          default: 80
          minimum: 0
          maximum: 65535
        desired_count:             # parameter
          type: number
          description: "The default number of Fargate tasks you want running"
          default: 1
          minimum: 1
        task_size:                 # parameter
          type: string
          description: "The size of the task you want to run"
          enum: ["x-small", "small", "medium", "large", "x-large"]
          default: "x-small"
        image:                     # parameter
          type: string
          description: "The name/url of the container image"
          default: "public.ecr.aws/z9d2n7e1/nginx:1.19.5"
          minLength: 1
          maxLength: 200
        unique_name:               # parameter
          type: string
          description: "The unique name of your service identifier. This will be used to name your log group, task definition and ECS service"
          minLength: 1
          maxLength: 100
      required:
        - unique_name
    # defined by administrator
    PipelineInputs:
      type: object
      description: "Pipeline input properties"
      properties:
        dockerfile:                # parameter
          type: string
          description: "The location of the Dockerfile to build"
          default: "Dockerfile"
          minLength: 1
          maxLength: 100
        unit_test_command:         # parameter
          type: string
          description: "The command to run to unit test the application code"
          default: "echo 'add your unit test command here'"
          minLength: 1
          maxLength: 200

如果您想要建立不含服務管線的服務範本，請勿pipeline_input_type在結構描述中包含，如下列範例所示。

不包含服務管線之服務的範例服 AWS Proton 務結構描述檔案


schema:                            # required
  format:                          # required
    openapi: "3.0.0"               # required
  # required            defined by administrator  
  service_input_type: "MyServiceInstanceInputType"

  types:                           # required
    # defined by administrator
    MyServiceInstanceInputType:
      type: object
      description: "Service instance input properties"
      required:
        - my_sample_service_instance_required_input
      properties:
        my_sample_service_instance_optional_input:   # parameter
          type: string
          description: "This is a sample input"
          default: "hello world"
        my_sample_service_instance_required_input:   # parameter
          type: string
          description: "Another sample input"

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

地形 IAC 文件

清單和包裝