DOC-2181 - add docs for Billing Engine setup APIs. Supports AWS and A…

…zure configurations. (#697)

api/services/beci/setup/paths/cbiV1SetupAccount.yaml

@@ -2,9 +2,7 @@ post:
   tags:
     - Accounts
   summary: Setup Cost Intelligence
-  description: Sets up and enables Cost Intelligence functionality on a Spot account.
-    The Spot account must already have credentials and be linked to a valid cloud
-    provider account (e.g. AWS account, Azure subscription, etc).
+  description: Sets up and enables Cost Intelligence functionality on a Spot account. The Spot account must already have credentials and be linked to a valid cloud provider account (e.g. AWS account, Azure subscription, etc).
   operationId: setupAccountCbiV1SetupAccountPost
   requestBody:
     required: true

api/services/beci/setup/paths/cbiV1SetupAccountValidation.yaml

@@ -2,8 +2,7 @@ post:
   tags:
     - Accounts
   summary: Perform Cost Intelligence Setup Validations
-  description: Validate that Cost Intelligence can be setup on the specified Spot
-    Account.
+  description: Validate that Cost Intelligence can be setup on the specified Spot Account.
   operationId: validateSetupAccountCbiV1SetupAccountValidationPost
   requestBody:
     required: true

api/services/beci/setup/paths/cloudBillingV1SetupAccount.yaml

@@ -0,0 +1,75 @@
+get:
+  tags:
+    - Accounts
+  summary: Get Billing Engine Registered Accounts
+  description: Get list of Spot accounts where Billing Engine has been setup.
+  operationId: listAccountsCloudBillingV1SetupAccountGet
+  parameters:
+    - name: paginationSize
+      in: query
+      required: false
+      schema:
+        type: integer
+        description: Number of items to include in the response
+      description: Number of items to include in the response
+    - name: paginationKey
+      in: query
+      required: false
+      schema:
+        type: string
+        description: Key used to fetch a specific page of items
+      description: Key used to fetch a specific page of items
+  responses:
+    '200':
+      $ref: ../responses/get200cloudBillingV1SetupAccount.yaml
+    '400':
+      content:
+        application/json:
+          schema:
+            $ref: ../../../../commons/schemas/errorResponse.yaml
+      description: Invalid request error response. Adjust the request before retrying.
+    '404':
+      content:
+        application/json:
+          schema:
+            $ref: ../../../../commons/schemas/errorResponse.yaml
+      description: Not found error response. The requested resource does not exist.
+    '422':
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            $ref: ../../../../commons/schemas/errorResponse.yaml
+post:
+  tags:
+    - Accounts
+  summary: Setup Billing Engine
+  description: Sets up and enables Billing Engine functionality on a Spot account. The Spot account must already have credentials and be linked to a valid cloud provider account (e.g. AWS account, Azure billing account, etc).
+  operationId: setupAccountCloudBillingV1SetupAccountPost
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: ../schemas/BERegisteredSetupAccountUpdateRequest.yaml
+  responses:
+    '200':
+      $ref: ../responses/post200cloudBillingV1SetupAccount.yaml
+    '400':
+      content:
+        application/json:
+          schema:
+            $ref: ../../../../commons/schemas/errorResponse.yaml
+      description: Invalid request error response. Adjust the request before retrying.
+    '404':
+      content:
+        application/json:
+          schema:
+            $ref: ../../../../commons/schemas/errorResponse.yaml
+      description: Not found error response. The requested resource does not exist.
+    '422':
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            $ref: ../../../../commons/schemas/errorResponse.yaml

api/services/beci/setup/paths/cloudBillingV1SetupAccountValidation.yaml

@@ -0,0 +1,33 @@
+post:
+  tags:
+    - Accounts
+  summary: Perform Billing Engine Setup Validations
+  description: Validate that Billing Engine can be setup on the specified Spot Account.
+  operationId: validateSetupAccountCloudBillingV1SetupAccountValidationPost
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: ../schemas/BERegisteredSetupAccountUpdateRequest.yaml
+  responses:
+    '200':
+      $ref: ../responses/post200cloudBillingV1SetupAccountValidation.yaml
+    '400':
+      content:
+        application/json:
+          schema:
+            $ref: ../../../../commons/schemas/errorResponse.yaml
+      description: Invalid request error response. Adjust the request before retrying.
+    '404':
+      content:
+        application/json:
+          schema:
+            $ref: ../../../../commons/schemas/errorResponse.yaml
+      description: Not found error response. The requested resource does not exist.
+    '422':
+      description: Error response.
+      content:
+        application/json:
+          schema:
+            $ref: ../../../../commons/schemas/errorResponse.yaml

api/services/beci/setup/responses/get200cloudBillingV1SetupAccount.yaml

@@ -0,0 +1,24 @@
+description: Successful response
+content:
+  application/json:
+    schema:
+      allOf:
+        - $ref: ../../../../commons/schemas/paginatedResponseItemWrapper.yaml
+        - type: object
+          properties:
+            request:
+              type: object
+              properties:
+                url:
+                  example: /cloudBilling/v1/setup/account
+                method:
+                  example: GET
+            response:
+              type: object
+              properties:
+                items:
+                  type: array
+                  items:
+                    $ref: ../schemas/setupBERegisteredAccountWithStatusResponse.yaml
+                kind:
+                  example: spotinst:cloudBilling:beRegisteredAccount

api/services/beci/setup/responses/post200cloudBillingV1SetupAccount.yaml

@@ -0,0 +1,24 @@
+description: Successful response
+content:
+  application/json:
+    schema:
+      allOf:
+        - $ref: ../../../../commons/schemas/responseItemWrapper.yaml
+        - type: object
+          properties:
+            request:
+              type: object
+              properties:
+                url:
+                  example: /cloudBilling/v1/setup/account
+                method:
+                  example: POST
+            response:
+              type: object
+              properties:
+                items:
+                  type: array
+                  items:
+                    $ref: ../schemas/setupCreateBERegisteredAccountResponse.yaml
+                kind:
+                  example: spotinst:cloudBilling:beRegisteredAccount

api/services/beci/setup/responses/post200cloudBillingV1SetupAccountValidation.yaml

@@ -0,0 +1,24 @@
+description: Successful response
+content:
+  application/json:
+    schema:
+      allOf:
+        - $ref: ../../../../commons/schemas/responseItemWrapper.yaml
+        - type: object
+          properties:
+            request:
+              type: object
+              properties:
+                url:
+                  example: /cloudBilling/v1/setup/account/validation
+                method:
+                  example: POST
+            response:
+              type: object
+              properties:
+                items:
+                  type: array
+                  items:
+                    $ref: ../schemas/validationModelResponse.yaml
+                kind:
+                  example: spotinst:cbi:accountRegistrationValidation

api/services/beci/setup/schemas/BERegisteredSetupAccountAwsConfig.yaml

@@ -0,0 +1,9 @@
+properties:
+  billingSource:
+    $ref: BERegisteredSetupAccountAwsConfigBillingSource.yaml
+    description: Configuration settings used to collect AWS billing data.
+type: object
+required:
+  - billingSource
+title: BERegisteredSetupAccountAwsConfig
+description: Configuration settings used to collect AWS billing data. Requires that the target Spot account is linked to an AWS account with billing data (e.g. master payer account).

api/services/beci/setup/schemas/BERegisteredSetupAccountAwsConfigBillingSource.yaml

@@ -0,0 +1,16 @@
+properties:
+  bucket:
+    type: string
+    description: The name of the AWS S3 bucket where the AWS CUR is stored.
+  region:
+    type: string
+    description: The AWS buckets AWS region (e.g. us-east-1).
+  pathPrefix:
+    type: string
+    description: The prefix path and report name generated for the AWS CUR you configured.
+type: object
+required:
+  - bucket
+  - region
+  - pathPrefix
+title: BERegisteredSetupAccountAwsConfigBillingSource

api/services/beci/setup/schemas/BERegisteredSetupAccountAzureConfig.yaml

@@ -0,0 +1,4 @@
+properties: {}
+type: object
+title: BERegisteredSetupAccountAzureConfig
+description: Configuration settings used to collect Azure billing data. Requires that the target Spot account is linked to an Azure billing account.

api/services/beci/setup/schemas/BERegisteredSetupAccountUpdateRequest.yaml

@@ -0,0 +1,16 @@
+properties:
+  accountId:
+    type: string
+    description: Spot Account ID.
+    example: act-23432
+  config:
+    anyOf:
+      - type: object
+      - $ref: BERegisteredSetupAccountAwsConfig.yaml
+      - $ref: BERegisteredSetupAccountAzureConfig.yaml
+    description: Configuration for the Billing Engine (e.g. location of the billing data)
+    nullable: true
+type: object
+required:
+  - accountId
+title: BERegisteredSetupAccountUpdateRequest

api/services/beci/setup/schemas/CIRegisteredAccountResponse.yaml

@@ -22,8 +22,7 @@ properties:
   updatedDate:
     type: string
     format: date-time
-    description: Date/time when the Cost Intelligence registration was updated on
-      the Spot account.
+    description: Date/time when the Cost Intelligence registration was updated on the Spot account.
 type: object
 required:
   - organizationId
@@ -33,5 +32,4 @@ required:
   - enabledDate
   - updatedDate
 title: CIRegisteredAccountResponse
-description: Represents a Spot account on which Cost Intelligence has been registered
-  / enabled. [kind/spotinst:cbi:inventory:ciRegisteredAccount]
+description: Represents a Spot account on which Cost Intelligence has been registered / enabled. [kind/spotinst:cbi:inventory:ciRegisteredAccount]

api/services/beci/setup/schemas/CIRegisteredAccountWithStatusResponse.yaml

@@ -22,8 +22,7 @@ properties:
   updatedDate:
     type: string
     format: date-time
-    description: Date/time when the Cost Intelligence registration was updated on
-      the Spot account.
+    description: Date/time when the Cost Intelligence registration was updated on the Spot account.
   statusSummary:
     $ref: accountStatusSummary.yaml
     description: Account status summary.

api/services/beci/setup/schemas/setupBERegisteredAccountWithStatusResponse.yaml

@@ -0,0 +1,54 @@
+properties:
+  accountId:
+    type: string
+    description: Spot Account ID.
+    example: act-23432
+  organizationId:
+    description: Spot Organization ID.
+    example: '634563908342'
+    type: string
+    nullable: true
+  cloudProvider:
+    type: string
+    description: Cloud provider.
+    example: aws
+  externalProviderId:
+    type: string
+    description: Cloud provider account ID.
+    example: '435345634'
+  externalProviderName:
+    description: Cloud provider account name.
+    example: Provider account name 1
+    type: string
+    nullable: true
+  enabledDate:
+    type: string
+    format: date-time
+    description: Timestamp when the Spot account was onboarded to Billing Engine.
+    example: '2019-08-24T14:15:22Z'
+  updatedDate:
+    type: string
+    format: date-time
+    description: Timestamp when Billing Engine config was last modified.
+    example: '2019-08-24T14:15:22Z'
+  statusSummary:
+    $ref: accountStatusSummary.yaml
+    description: Billing Engine account connection status.
+  status:
+    description: Billing Engine account status info.
+    type: array
+    items:
+      $ref: accountStatusItem.yaml
+    nullable: true
+type: object
+required:
+  - accountId
+  - organizationId
+  - cloudProvider
+  - externalProviderId
+  - externalProviderName
+  - enabledDate
+  - updatedDate
+  - statusSummary
+title: SetupBERegisteredAccountWithStatusResponse
+description: Represents a Spot account on which Billing Engine has been registered / enabled. [kind/spotinst:cloudBilling:beRegisteredAccount]

api/services/beci/setup/schemas/setupCreateBERegisteredAccountResponse.yaml

@@ -0,0 +1,44 @@
+properties:
+  accountId:
+    type: string
+    description: Spot Account ID.
+    example: act-23432
+  organizationId:
+    description: Spot Organization ID
+    example: '634563908342'
+    type: string
+    nullable: true
+  cloudProvider:
+    type: string
+    description: Cloud provider
+    example: aws
+  externalProviderId:
+    type: string
+    description: Cloud provider account ID
+    example: '435345634'
+  isBillingAccount:
+    type: boolean
+    description: True if Spot account is a billing account.
+  enabledDate:
+    type: string
+    description: Timestamp when the Spot account was onboarded to Billing Engine.
+    example: '2019-08-24T14:15:22Z'
+  updatedDate:
+    type: string
+    description: Timestamp when Billing Engine config was last modified.
+    example: '2019-08-24T14:15:22Z'
+  config:
+    description: Provider-specific configuration.
+    type: object
+    nullable: true
+type: object
+required:
+  - accountId
+  - organizationId
+  - cloudProvider
+  - externalProviderId
+  - isBillingAccount
+  - enabledDate
+  - updatedDate
+title: SetupCreateBERegisteredAccountResponse
+description: Represents a Spot account on which Billing Engine has been registered / enabled. [kind/spotinst:cloudBilling:beRegisteredAccount]

api/spot.yaml

@@ -954,4 +954,8 @@ paths:
     $ref: services/beci/setup/paths/cbiV1SetupAccount.yaml
   /cbi/v1/setup/account/validation:
     $ref: services/beci/setup/paths/cbiV1SetupAccountValidation.yaml
+  /cloudBilling/v1/setup/account:
+    $ref: services/beci/setup/paths/cloudBillingV1SetupAccount.yaml
+  /cloudBilling/v1/setup/account/validation:
+    $ref: services/beci/setup/paths/cloudBillingV1SetupAccountValidation.yaml
   # </be/ci path section>