From 12d0f57e5a3bd93930bdd362f4bfc4f8639595a7 Mon Sep 17 00:00:00 2001 From: Paul van Wichen <126611130+paul-van-wichen@users.noreply.github.com> Date: Wed, 18 Dec 2024 08:29:01 -0500 Subject: [PATCH] DOC-2181 - add docs for Billing Engine setup APIs. Supports AWS and Azure configurations. (#697) --- .../beci/setup/paths/cbiV1SetupAccount.yaml | 4 +- .../paths/cbiV1SetupAccountValidation.yaml | 3 +- .../paths/cloudBillingV1SetupAccount.yaml | 75 +++++++++++++++++++ .../cloudBillingV1SetupAccountValidation.yaml | 33 ++++++++ .../get200cloudBillingV1SetupAccount.yaml | 24 ++++++ .../post200cloudBillingV1SetupAccount.yaml | 24 ++++++ ...0cloudBillingV1SetupAccountValidation.yaml | 24 ++++++ .../BERegisteredSetupAccountAwsConfig.yaml | 9 +++ ...redSetupAccountAwsConfigBillingSource.yaml | 16 ++++ .../BERegisteredSetupAccountAzureConfig.yaml | 4 + ...BERegisteredSetupAccountUpdateRequest.yaml | 16 ++++ .../schemas/CIRegisteredAccountResponse.yaml | 6 +- ...CIRegisteredAccountWithStatusResponse.yaml | 3 +- ...BERegisteredAccountWithStatusResponse.yaml | 54 +++++++++++++ ...etupCreateBERegisteredAccountResponse.yaml | 44 +++++++++++ api/spot.yaml | 4 + 16 files changed, 332 insertions(+), 11 deletions(-) create mode 100644 api/services/beci/setup/paths/cloudBillingV1SetupAccount.yaml create mode 100644 api/services/beci/setup/paths/cloudBillingV1SetupAccountValidation.yaml create mode 100644 api/services/beci/setup/responses/get200cloudBillingV1SetupAccount.yaml create mode 100644 api/services/beci/setup/responses/post200cloudBillingV1SetupAccount.yaml create mode 100644 api/services/beci/setup/responses/post200cloudBillingV1SetupAccountValidation.yaml create mode 100644 api/services/beci/setup/schemas/BERegisteredSetupAccountAwsConfig.yaml create mode 100644 api/services/beci/setup/schemas/BERegisteredSetupAccountAwsConfigBillingSource.yaml create mode 100644 api/services/beci/setup/schemas/BERegisteredSetupAccountAzureConfig.yaml create mode 100644 api/services/beci/setup/schemas/BERegisteredSetupAccountUpdateRequest.yaml create mode 100644 api/services/beci/setup/schemas/setupBERegisteredAccountWithStatusResponse.yaml create mode 100644 api/services/beci/setup/schemas/setupCreateBERegisteredAccountResponse.yaml diff --git a/api/services/beci/setup/paths/cbiV1SetupAccount.yaml b/api/services/beci/setup/paths/cbiV1SetupAccount.yaml index bb06a5fb..0db40592 100644 --- a/api/services/beci/setup/paths/cbiV1SetupAccount.yaml +++ b/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 diff --git a/api/services/beci/setup/paths/cbiV1SetupAccountValidation.yaml b/api/services/beci/setup/paths/cbiV1SetupAccountValidation.yaml index 66bc6bbe..7ebb51fa 100644 --- a/api/services/beci/setup/paths/cbiV1SetupAccountValidation.yaml +++ b/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 diff --git a/api/services/beci/setup/paths/cloudBillingV1SetupAccount.yaml b/api/services/beci/setup/paths/cloudBillingV1SetupAccount.yaml new file mode 100644 index 00000000..797d4727 --- /dev/null +++ b/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 diff --git a/api/services/beci/setup/paths/cloudBillingV1SetupAccountValidation.yaml b/api/services/beci/setup/paths/cloudBillingV1SetupAccountValidation.yaml new file mode 100644 index 00000000..1cffba7b --- /dev/null +++ b/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 diff --git a/api/services/beci/setup/responses/get200cloudBillingV1SetupAccount.yaml b/api/services/beci/setup/responses/get200cloudBillingV1SetupAccount.yaml new file mode 100644 index 00000000..1aa700b5 --- /dev/null +++ b/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 diff --git a/api/services/beci/setup/responses/post200cloudBillingV1SetupAccount.yaml b/api/services/beci/setup/responses/post200cloudBillingV1SetupAccount.yaml new file mode 100644 index 00000000..bfefda9d --- /dev/null +++ b/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 diff --git a/api/services/beci/setup/responses/post200cloudBillingV1SetupAccountValidation.yaml b/api/services/beci/setup/responses/post200cloudBillingV1SetupAccountValidation.yaml new file mode 100644 index 00000000..a6224f4f --- /dev/null +++ b/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 diff --git a/api/services/beci/setup/schemas/BERegisteredSetupAccountAwsConfig.yaml b/api/services/beci/setup/schemas/BERegisteredSetupAccountAwsConfig.yaml new file mode 100644 index 00000000..fe7b2c14 --- /dev/null +++ b/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). diff --git a/api/services/beci/setup/schemas/BERegisteredSetupAccountAwsConfigBillingSource.yaml b/api/services/beci/setup/schemas/BERegisteredSetupAccountAwsConfigBillingSource.yaml new file mode 100644 index 00000000..04905d5f --- /dev/null +++ b/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 diff --git a/api/services/beci/setup/schemas/BERegisteredSetupAccountAzureConfig.yaml b/api/services/beci/setup/schemas/BERegisteredSetupAccountAzureConfig.yaml new file mode 100644 index 00000000..01d854da --- /dev/null +++ b/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. diff --git a/api/services/beci/setup/schemas/BERegisteredSetupAccountUpdateRequest.yaml b/api/services/beci/setup/schemas/BERegisteredSetupAccountUpdateRequest.yaml new file mode 100644 index 00000000..37ef161e --- /dev/null +++ b/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 diff --git a/api/services/beci/setup/schemas/CIRegisteredAccountResponse.yaml b/api/services/beci/setup/schemas/CIRegisteredAccountResponse.yaml index 56ffe088..e48df5c9 100644 --- a/api/services/beci/setup/schemas/CIRegisteredAccountResponse.yaml +++ b/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] diff --git a/api/services/beci/setup/schemas/CIRegisteredAccountWithStatusResponse.yaml b/api/services/beci/setup/schemas/CIRegisteredAccountWithStatusResponse.yaml index 72f14a7e..03424b7f 100644 --- a/api/services/beci/setup/schemas/CIRegisteredAccountWithStatusResponse.yaml +++ b/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. diff --git a/api/services/beci/setup/schemas/setupBERegisteredAccountWithStatusResponse.yaml b/api/services/beci/setup/schemas/setupBERegisteredAccountWithStatusResponse.yaml new file mode 100644 index 00000000..f350a1bb --- /dev/null +++ b/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] diff --git a/api/services/beci/setup/schemas/setupCreateBERegisteredAccountResponse.yaml b/api/services/beci/setup/schemas/setupCreateBERegisteredAccountResponse.yaml new file mode 100644 index 00000000..34f37cf8 --- /dev/null +++ b/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] diff --git a/api/spot.yaml b/api/spot.yaml index 92e18766..5df10b75 100644 --- a/api/spot.yaml +++ b/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 #