aws_savings_plan_recommendations.pt

name "AWS Savings Plan Recommendations"
rs_pt_ver 20180301
type "policy"
short_description "A policy that sends email notifications when AWS Savings Plan Recommendations are identified. NOTE: These Purchase Recommendations are generated by AWS. See the [README](https://github.com/flexera-public/policy_templates/tree/master/cost/aws/savings_plan/recommendations) and [docs.flexera.com/flexera/EN/Automation](https://docs.flexera.com/flexera/EN/Automation/AutomationGS.htm) to learn more."
long_description ""
severity "medium"
category "Cost"
default_frequency "weekly"
info(
  version: "3.3.2",
  provider: "AWS",
  service: "Compute",
  policy_set: "Savings Plans",
  recommendation_type: "Rate Reduction",
  hide_skip_approvals: "true"
)

###############################################################################
# Parameters
###############################################################################

parameter "param_email" do
  type "list"
  category "Policy Settings"
  label "Email Addresses"
  description "Email addresses of the recipients you wish to notify when new incidents are created."
  default []
end

parameter "param_aws_account_number" do
  type "string"
  category "Policy Settings"
  label "Account Number"
  description "Leave blank; this is for automated use with Meta Policies. See README for more details."
  default ""
end

parameter "param_min_savings" do
  type "number"
  category "Policy Settings"
  label "Minimum Savings Threshold"
  description "Specify the minimum estimated monthly savings that should result in a recommendation"
  min_value 0
  default 0
end

parameter "param_days" do
  type "string"
  category "Savings Plan Settings"
  label "Look Back Period"
  description "Number of days of prior usage to analyze."
  allowed_values "Last 7 Days", "Last 30 Days", "Last 60 Days"
  default "Last 30 Days"
end

parameter "param_scope" do
  type "string"
  category "Savings Plan Settings"
  label "Account Scope"
  description "The account scope that you want your recommendations for. Select Payer to produce results only for a Master Payer account, or Linked to produce results for all linked accounts as well."
  allowed_values "Payer", "Linked"
  default "Payer"
end

parameter "param_term" do
  type "string"
  category "Savings Plan Settings"
  label "Savings Plan Term"
  description "Length of savings plan term to provide recommendations for."
  allowed_values "1 Year", "3 Year"
  default "1 Year"
end

parameter "param_savings_plan_type" do
  type "string"
  category "Savings Plan Settings"
  label "Savings Plan Type"
  description "Type of Savings Plan to provide recommendations for."
  allowed_values "Compute Savings Plan", "EC2 Instance Savings Plan", "SageMaker Savings Plans"
  default "Compute Savings Plan"
end

parameter "param_payment_option" do
  type "string"
  category "Savings Plan Settings"
  label "Payment Option"
  description "Savings Plan purchase option to provide recommendations for."
  allowed_values "No Upfront", "Partial Upfront", "All Upfront"
  default "No Upfront"
end

###############################################################################
# Authentication
###############################################################################

credentials "auth_aws" do
  schemes "aws", "aws_sts"
  label "AWS"
  description "Select the AWS Credential from the list"
  tags "provider=aws"
  aws_account_number $param_aws_account_number
end

credentials "auth_flexera" do
  schemes "oauth2"
  label "Flexera"
  description "Select FlexeraOne OAuth2 credentials"
  tags "provider=flexera"
end

###############################################################################
# Pagination
###############################################################################

pagination "pagination_aws" do
  get_page_marker do
    body_path "NextPageToken"
  end
  set_page_marker do
    body_field "NextPageToken"
  end
end

###############################################################################
# Datasources & Scripts
###############################################################################

# Get applied policy metadata for use later
datasource "ds_applied_policy" do
  request do
    auth $auth_flexera
    host rs_governance_host
    path join(["/api/governance/projects/", rs_project_id, "/applied_policies/", policy_id])
    header "Api-Version", "1.0"
  end
end

# Gather local currency info
datasource "ds_currency_reference" do
  request do
    host "raw.githubusercontent.com"
    path "/flexera-public/policy_templates/master/data/currency/currency_reference.json"
    header "User-Agent", "RS Policies"
  end
end

datasource "ds_currency_code" do
  request do
    auth $auth_flexera
    host rs_optima_host
    path join(["/bill-analysis/orgs/", rs_org_id, "/settings/currency_code"])
    header "Api-Version", "0.1"
    header "User-Agent", "RS Policies"
    ignore_status [403]
  end
  result do
    encoding "json"
    field "id", jmes_path(response, "id")
    field "value", jmes_path(response, "value")
  end
end

datasource "ds_currency_target" do
  run_script $js_currency_target, $ds_currency_reference, $ds_currency_code
end

script "js_currency_target", type:"javascript" do
  parameters "ds_currency_reference", "ds_currency_code"
  result "result"
  code <<-EOS
  // Default to USD if currency is not found
  result = ds_currency_reference['USD']

  if (ds_currency_code['value'] != undefined && ds_currency_reference[ds_currency_code['value']] != undefined) {
    result = ds_currency_reference[ds_currency_code['value']]
  }
EOS
end

# Get region-specific Flexera API endpoints
datasource "ds_flexera_api_hosts" do
  run_script $js_flexera_api_hosts, rs_optima_host
end

script "js_flexera_api_hosts", type: "javascript" do
  parameters "rs_optima_host"
  result "result"
  code <<-EOS
  host_table = {
    "api.optima.flexeraeng.com": {
      flexera: "api.flexera.com",
      fsm: "api.fsm.flexeraeng.com"
    },
    "api.optima-eu.flexeraeng.com": {
      flexera: "api.flexera.eu",
      fsm: "api.fsm-eu.flexeraeng.com"
    },
    "api.optima-apac.flexeraeng.com": {
      flexera: "api.flexera.au",
      fsm: "api.fsm-apac.flexeraeng.com"
    }
  }

  result = host_table[rs_optima_host]
EOS
end

# Get AWS account info
datasource "ds_cloud_vendor_accounts" do
  request do
    auth $auth_flexera
    host val($ds_flexera_api_hosts, 'flexera')
    path join(["/finops-analytics/v1/orgs/", rs_org_id, "/cloud-vendor-accounts"])
    header "Api-Version", "1.0"
  end
  result do
    encoding "json"
    collect jmes_path(response, "values[*]") do
      field "id", jmes_path(col_item, "aws.accountId")
      field "name", jmes_path(col_item, "name")
      field "tags", jmes_path(col_item, "tags")
    end
  end
end

datasource "ds_vendor_account_table" do
  run_script $js_vendor_account_table, $ds_cloud_vendor_accounts
end

script "js_vendor_account_table", type:"javascript" do
  parameters "ds_cloud_vendor_accounts"
  result "result"
  code <<-EOS
  result = {}

  _.each(ds_cloud_vendor_accounts, function(account) {
    result[account['id']] = account['name']
  })
EOS
end

datasource "ds_sp_recommendations" do
  request do
    run_script $js_sp_recommendations, $param_days, $param_payment_option, $param_term, $param_savings_plan_type, $param_scope
  end
  result do
    encoding "json"
    collect jmes_path(response, "SavingsPlansPurchaseRecommendation.SavingsPlansPurchaseRecommendationDetails[*]") do
      field "accountID", jmes_path(col_item, "AccountId")
      field "currency", jmes_path(col_item, "CurrencyCode")
      field "currentAverageHourlyOnDemandSpend", jmes_path(col_item, "CurrentAverageHourlyOnDemandSpend")
      field "currentMaximumHourlyOnDemandSpend", jmes_path(col_item, "CurrentMaximumHourlyOnDemandSpend")
      field "currentMinimumHourlyOnDemandSpend", jmes_path(col_item, "CurrentMinimumHourlyOnDemandSpend")
      field "estimatedAverageUtilization", jmes_path(col_item, "EstimatedAverageUtilization")
      field "estimatedMonthlySavingsAmount", jmes_path(col_item, "EstimatedMonthlySavingsAmount")
      field "estimatedOnDemandCost", jmes_path(col_item, "EstimatedOnDemandCost")
      field "estimatedROI", jmes_path(col_item, "EstimatedROI")
      field "estimatedSavingsAmount", jmes_path(col_item, "EstimatedSavingsAmount")
      field "estimatedSavingsPercentage", jmes_path(col_item, "EstimatedSavingsPercentage")
      field "estimatedSavingsPlanCost", jmes_path(col_item, "EstimatedSPCost")
      field "hourlyCommitmentToPurchase", jmes_path(col_item, "HourlyCommitmentToPurchase")
      field "instanceFamily", jmes_path(col_item, "SavingsPlansDetails.InstanceFamily")
      field "offeringId", jmes_path(col_item, "SavingsPlansDetails.OfferingId")
      field "region", jmes_path(col_item, "SavingsPlansDetails.Region")
      field "upfrontCost", jmes_path(col_item, "UpfrontCost")
    end
  end
end

script "js_sp_recommendations", type: "javascript" do
  parameters "param_days", "param_payment_option", "param_term", "param_savings_plan_type", "param_scope"
  result "request"
  code <<-EOS
  // Tables to convert human-readable parameter values to their API equivalents
  period_table = {
    "Last 7 Days": "SEVEN_DAYS",
    "Last 30 Days": "THIRTY_DAYS",
    "Last 60 Days": "SIXTY_DAYS"
  }

  term_table = {
    "1 Year": "ONE_YEAR",
    "3 Year": "THREE_YEARS"
  }

  plan_table = {
    "Compute Savings Plan": "COMPUTE_SP",
    "EC2 Instance Savings Plan": "EC2_INSTANCE_SP",
    "SageMaker Savings Plans": "SAGEMAKER_SP"
  }

  // Build out the body of the request based on parameters
  body_fields = {
    AccountScope: param_scope.toUpperCase(),
    LookbackPeriodInDays: period_table[param_days],
    PaymentOption: param_payment_option.replace(' ', '_').toUpperCase()
    SavingsPlansType: plan_table[param_savings_plan_type],
    TermInYears: term_table[param_term]
  }

  var request = {
    auth: "auth_aws",
    pagination: "pagination_aws",
    host: "ce.us-east-1.amazonaws.com",
    path: "/",
    verb: "POST",
    body_fields: body_fields,
    headers: {
      "User-Agent": "RS Policies",
      "X-Amz-Target": "AWSInsightsIndexService.GetSavingsPlansPurchaseRecommendation",
      "Content-Type": "application/x-amz-json-1.1",
    }
  }
EOS
end

# Branching logic:
# This datasource returns an empty array if the target currency is USD.
# This prevents ds_currency_conversion from running if it's not needed.
datasource "ds_conditional_currency_conversion" do
  run_script $js_conditional_currency_conversion, $ds_currency_target, $ds_sp_recommendations
end

script "js_conditional_currency_conversion", type: "javascript" do
  parameters "ds_currency_target", "ds_sp_recommendations"
  result "result"
  code <<-EOS
  result = []
  from_currency = "USD"

  if (ds_sp_recommendations.length > 0) {
    if (typeof(ds_sp_recommendations[0]['currency']) == 'string') {
      from_currency = ds_sp_recommendations[0]['currency']
    }
  }

  // Make the request only if the target currency is not USD
  if (ds_currency_target['code'] != from_currency) {
    result = [{ from: from_currency }]
  }
EOS
end

datasource "ds_currency_conversion" do
  # Only make a request if the target currency is not USD
  iterate $ds_conditional_currency_conversion
  request do
    host "api.xe-auth.flexeraeng.com"
    path "/prod/{proxy+}"
    query "from", val(iter_item, 'from')
    query "to", val($ds_currency_target, 'code')
    query "amount", "1"
    # Ignore currency conversion if API has issues
    ignore_status [400, 404, 502]
  end
  result do
    encoding "json"
    field "from", jmes_path(response, "from")
    field "to", jmes_path(response, "to")
    field "amount", jmes_path(response, "amount")
    field "year", jmes_path(response, "year")
  end
end

datasource "ds_currency" do
  run_script $js_currency, $ds_currency_target, $ds_currency_conversion
end

script "js_currency", type:"javascript" do
  parameters "ds_currency_target", "ds_currency_conversion"
  result "result"
  code <<-EOS
  result = ds_currency_target
  result['exchange_rate'] = 1

  if (ds_currency_conversion.length > 0) {
    currency_code = ds_currency_target['code']
    current_month = parseInt(new Date().toISOString().split('-')[1])

    conversion_block = _.find(ds_currency_conversion[0]['to'][currency_code], function(item) {
      return item['month'] == current_month
    })

    if (conversion_block != undefined) {
      result['exchange_rate'] = conversion_block['monthlyAverage']
    }
  }
EOS
end

datasource "ds_sp_normalization" do
  run_script $js_sp_normalization, $ds_sp_recommendations, $ds_applied_policy, $ds_vendor_account_table, $ds_currency, $ds_currency_conversion, $ds_conditional_currency_conversion, $param_min_savings, $param_days, $param_scope, $param_term, $param_payment_option, $param_savings_plan_type
end

script "js_sp_normalization", type: "javascript" do
  parameters "ds_sp_recommendations", "ds_applied_policy", "ds_vendor_account_table", "ds_currency", "ds_currency_conversion", "ds_conditional_currency_conversion", "param_min_savings", "param_days", "param_scope", "param_term", "param_payment_option", "param_savings_plan_type"
  result "result"
  code <<-'EOS'
  // Used for formatting numbers to look pretty
  function formatNumber(number, separator) {
    formatted_number = "0"

    if (number) {
      formatted_number = (Math.round(number * 100) / 100).toString().split(".")[0]

      if (separator) {
        withSeparator = ""

        for (var i = 0; i < formatted_number.length; i++) {
          if (i > 0 && (formatted_number.length - i) % 3 == 0) { withSeparator += separator }
          withSeparator += formatted_number[i]
        }

        formatted_number = withSeparator
      }

      decimal = (Math.round(number * 100) / 100).toString().split(".")[1]
      if (decimal) { formatted_number += "." + decimal }
    }

    return formatted_number
  }

  service_table = {
    "Compute Savings Plan": "Compute",
    "EC2 Instance Savings Plan": "EC2",
    "SageMaker Savings Plans": "SageMaker"
  }

  result = []
  total_savings = 0.0

  exchange_rate = ds_currency['exchange_rate']

  _.each(ds_sp_recommendations, function(recommendation) {
    resourceType = recommendation["instanceFamily"]

    if (resourceType == "" || resourceType == null) {
      resourceType = param_savings_plan_type
    }

    currentAverageHourlyOnDemandSpend = recommendation["currentAverageHourlyOnDemandSpend"] * exchange_rate
    currentMaximumHourlyOnDemandSpend = recommendation["currentMaximumHourlyOnDemandSpend"] * exchange_rate
    currentMinimumHourlyOnDemandSpend = recommendation["currentMinimumHourlyOnDemandSpend"] * exchange_rate
    estimatedAverageUtilization = recommendation["estimatedAverageUtilization"] * 1
    estimatedMonthlySavingsAmount = recommendation["estimatedMonthlySavingsAmount"] * exchange_rate
    estimatedOnDemandCost = recommendation["estimatedOnDemandCost"] * exchange_rate
    estimatedSavingsAmount = recommendation["estimatedSavingsAmount"] * exchange_rate
    estimatedSavingsPercentage = recommendation["estimatedSavingsPercentage"] * 1
    estimatedSavingsPlanCost = recommendation["estimatedSavingsPlanCost"] * exchange_rate
    upfrontCost = recommendation["upfrontCost"] * exchange_rate

    if (estimatedMonthlySavingsAmount >= param_min_savings) {
      total_savings += recommendation["estimatedMonthlySavingsAmount"] * exchange_rate

      if (typeof(currentAverageHourlyOnDemandSpend) != 'number') { currentAverageHourlyOnDemandSpend = "" }
      if (typeof(currentAverageHourlyOnDemandSpend) == 'number') { currentAverageHourlyOnDemandSpend = Number(currentAverageHourlyOnDemandSpend.toFixed(3)) }

      if (typeof(currentMaximumHourlyOnDemandSpend) != 'number') { currentMaximumHourlyOnDemandSpend = "" }
      if (typeof(currentMaximumHourlyOnDemandSpend) == 'number') { currentMaximumHourlyOnDemandSpend = Number(currentMaximumHourlyOnDemandSpend.toFixed(3)) }

      if (typeof(currentMinimumHourlyOnDemandSpend) != 'number') { currentMinimumHourlyOnDemandSpend = "" }
      if (typeof(currentMinimumHourlyOnDemandSpend) == 'number') { currentMinimumHourlyOnDemandSpend = Number(currentMinimumHourlyOnDemandSpend.toFixed(3)) }

      if (typeof(estimatedAverageUtilization) != 'number') { estimatedAverageUtilization = "" }
      if (typeof(estimatedAverageUtilization) == 'number') { estimatedAverageUtilization = Number(estimatedAverageUtilization.toFixed(3)) }

      if (typeof(estimatedMonthlySavingsAmount) != 'number') { estimatedMonthlySavingsAmount = "" }
      if (typeof(estimatedMonthlySavingsAmount) == 'number') { estimatedMonthlySavingsAmount = Number(estimatedMonthlySavingsAmount.toFixed(3)) }

      if (typeof(estimatedOnDemandCost) != 'number') { estimatedOnDemandCost = "" }
      if (typeof(estimatedOnDemandCost) == 'number') { estimatedOnDemandCost = Number(estimatedOnDemandCost.toFixed(3)) }

      if (typeof(estimatedSavingsAmount) != 'number') { estimatedSavingsAmount = "" }
      if (typeof(estimatedSavingsAmount) == 'number') { estimatedSavingsAmount = Number(estimatedSavingsAmount.toFixed(3)) }

      if (typeof(estimatedSavingsPercentage) != 'number') { estimatedSavingsPercentage = "" }
      if (typeof(estimatedSavingsPercentage) == 'number') { estimatedSavingsPercentage = Number(estimatedSavingsPercentage.toFixed(2)) }

      if (typeof(estimatedSavingsPlanCost) != 'number') { estimatedSavingsPlanCost = "" }
      if (typeof(estimatedSavingsPlanCost) == 'number') { estimatedSavingsPlanCost = Number(estimatedSavingsPlanCost.toFixed(3)) }

      if (typeof(upfrontCost) != 'number') { upfrontCost = "" }
      if (typeof(upfrontCost) == 'number') { upfrontCost = Number(upfrontCost.toFixed(3)) }

      result.push({
        accountID: recommendation["accountID"],
        accountName: ds_vendor_account_table[recommendation["accountID"]],
        savingsCurrency: ds_currency['symbol'],
        currentAverageHourlyOnDemandSpend: currentAverageHourlyOnDemandSpend,
        currentMaximumHourlyOnDemandSpend: currentMaximumHourlyOnDemandSpend,
        currentMinimumHourlyOnDemandSpend: currentMinimumHourlyOnDemandSpend,
        estimatedAverageUtilization: estimatedAverageUtilization,
        savings: estimatedMonthlySavingsAmount,
        estimatedOnDemandCost: estimatedOnDemandCost,
        estimatedSavingsAmount: estimatedSavingsAmount,
        estimatedSavingsPercentage: estimatedSavingsPercentage,
        estimatedSavingsPlanCost: estimatedSavingsPlanCost,
        recommendedQuantity: recommendation["hourlyCommitmentToPurchase"],
        instanceFamily: recommendation["instanceFamily"],
        offeringId: recommendation["offeringId"],
        region: recommendation["region"],
        upfrontCost: upfrontCost,
        term: param_term,
        paymentOption: param_payment_option,
        resourceType: resourceType,
        lookbackPeriod: param_days,
        service: service_table[param_savings_plan_type],
        policy_name: ds_applied_policy['name'],
        total_savings: "",
        message: ""
      })
    }
  })

  // Messaging for currency conversion
  currency = ds_currency['code']

  if (ds_conditional_currency_conversion[0] != undefined) {
    currency = ds_conditional_currency_conversion[0]['from']
  }

  conversion_message = ""

  if (ds_currency['code'] != currency && ds_currency_conversion.length > 0 && exchange_rate != 1) {
    conversion_message = [
      "Savings values were converted from ", currency, " to ", ds_currency['code'],
      " using an exchange rate of ", exchange_rate, ".\n\n"
    ].join('')
  }

  if (ds_currency['code'] != currency && ds_currency_conversion.length == 0) {
    conversion_message = "Savings values are in ", currency, " due to a malfunction with Flexera's internal currency conversion API. Please contact Flexera support to report this issue."
  }

  message = [
    "The following settings were used when generating recommendations:\n",
    "- Savings Plan Type: ", param_savings_plan_type, "\n",
    "- Account Scope: ", param_scope, "\n",
    "- Term: ", param_term, "\n",
    "- Look Back Period: ", param_days, "\n",
    "- Payment Option: ", param_payment_option, "\n",
    "- Minimum Savings Threshold: ", param_min_savings, "\n\n",
  ].join('')

  disclaimer = "The above settings can be modified by editing the applied policy and changing the appropriate parameters.\n\n"
  empty_fields = "Empty fields indicate information that is not applicable to that particular recommendation."

  savings_message = [
    ds_currency['symbol'], ' ',
    formatNumber(parseFloat(total_savings).toFixed(2), ds_currency['t_separator'])
  ].join('')

  // Sort by highest savings first
  result = _.sortBy(result, function(item) { return item['savings'] * -1 })

  if (result.length > 0) {
    result[0]['total_savings'] = savings_message
    result[0]['message'] = conversion_message + message + disclaimer + empty_fields
  }
EOS
end

###############################################################################
# Policy
###############################################################################

policy "pol_aws_sp_recommendations" do
  validate_each $ds_sp_normalization do
    summary_template "{{ with index data 0 }}{{ .policy_name }}{{ end }}: {{ len data }} AWS Savings Plan Purchase Recommendations"
    detail_template <<-'EOS'
    **Potential Monthly Savings:** {{ with index data 0 }}{{ .total_savings }}{{ end }}

    {{ with index data 0 }}{{ .message }}{{ end }}
    EOS
    check lt(val(item, "savings"), 0)
    escalate $esc_email
    export do
      resource_level false
      field "accountID" do
        label "Account ID"
      end
      field "accountName" do
        label "Account Name"
      end
      field "region" do
        label "Region"
      end
      field "service" do
        label "Service"
      end
      field "savingsCurrency" do
        label "Currency"
      end
      field "savings" do
        label "Estimated Monthly Savings"
      end
      field "estimatedSavingsPercentage" do
        label "Estimated Savings Percentage"
      end
      field "estimatedSavingsPlanCost" do
        label "Estimated Savings Plan Cost"
      end
      field "lookbackPeriod" do
        label "Look Back Period (Days)"
      end
      field "paymentOption" do
        label "Payment Option"
      end
      field "recommendedQuantity" do
        label "Recommendeded Quantity to Purchase"
      end
      field "upfrontCost" do
        label "Upfront Cost"
      end
      field "currentAverageHourlyOnDemandSpend" do
        label "Current Average Hourly On-Demand Spend"
      end
      field "currentMaximumHourlyOnDemandSpend" do
        label "Current Maximum Hourly On-Demand Spend"
      end
      field "currentMinimumHourlyOnDemandSpend" do
        label "Current Minimum Hourly On-Demand Spend"
      end
      field "offeringId" do
        label "Offering Id"
      end
      field "instanceFamily" do
        label "Instance Family"
      end
      field "resourceType" do
        label "Resource Type"
      end
      field "term" do
        label "Term"
      end
    end
  end
end

###############################################################################
# Escalations
###############################################################################

escalation "esc_email" do
  automatic true
  label "Send Email"
  description "Send incident email"
  email $param_email
end