README.md

CCF Backstage Plugin

Understand how your cloud usage impacts our environment and what you can do about it.

This plugin brings the functionallity of the open source project Cloud Carbon Footprint into Backstage. See the CCF demo and the CCF docs for more details.

For more visibility into the work planned and happening, please visit the project board or create an issue. For feedback, questions, or if you’d like to collaborate on shaping the product direction, please reach out to [email protected].

Estimates	Forecast

Recommendations	Carbon Intensity Map

Getting started

If you haven't already, check out the Backstage docs and create a Backstage application with

npx @backstage/create-app

Then, you will need to install and configure the CCF plugins for the frontend and the backend.

Frontend plugin

Install:

cd packages/app
yarn add @cloud-carbon-footprint/backstage-plugin-frontend

Add the plugin to packages/app/src/App.tsx:

// import:
import { CloudCarbonFootprintPage } from '@cloud-carbon-footprint/backstage-plugin-frontend'

// add to routes:
const routes = (
  <FlatRoutes ...>
  ...
    <Route path="/cloud-carbon-footprint" element={<CloudCarbonFootprintPage />} />
  </FlatRoutes>
)

In the recent v4 release of @cloud-carbon-footprint/client package, we introduced React 18. Until official support for React 18 is added to Backstage, there is a low-lift solution to help solve this issue:

In the root package.json of your new Backstage application, you will need to add the following to the resolutions object and do a fresh yarn install:

  "resolutions": {
    "@types/react": "^17",
    "@types/react-dom": "^17",
+   "react": "^17",
    }

Optionally, add config to app-config.local.yaml. See the client config schema for more details. Note that long date ranges and/or granular groupings can result in long load times. The default values are:

cloudCarbonFootprint:
  client:
    dateRangeType: months
    dateRangeValue: 1
    groupBy: week

Then, run yarn dev and access the plugin at localhost:3000/cloud-carbon-footprint. To see data populated in the UI, you must set up the backend plugin.

Backend plugin

Install:

cd packages/backend
yarn add @cloud-carbon-footprint/backstage-plugin-backend

Create a file packages/backend/src/plugins/ccf.ts:

import { createRouter } from '@cloud-carbon-footprint/backstage-plugin-backend';
import { PluginEnvironment } from '../types';

export default async function createPlugin({
  logger,
  config,
}: PluginEnvironment) {
  return await createRouter({
    config,
    logger,
  });
}

Add the plugin to packages/backend/src/index.ts:

// import:
import ccf from './plugins/ccf';
...

async function main() {
  ...
  // add env
  const ccfEnv = useHotMemoize(module, () =>
    createEnv('cloud-carbon-footprint'),
  );

  ...
  // add to router
  apiRouter.use('/cloud-carbon-footprint', await ccf(ccfEnv));
  ...
}

Add configuration for your cloud providers to app-config.local.yaml. See the backend README for more details.

cloudCarbonFootprint:
  gcp:
    useBillingData: true
    billingProjectId: my-project
    billingProjectName: My Project
    bigQueryTable: billing_export_dataset.gcp_billing_export_v1_01B22A_05AA4C_87BDAC

Once the backend plugin is configured, usage data for the given cloud providers will be displayed in the UI.

Join Us!

To begin as a contributor, please see the contributing page. Please read through our code of conduct for our expectations around this community.

⭐️Give us a star if you like the project or find this work interesting!

Don’t be shy!

Reach out with any questions, support requests, and further discussions in our discussion google group.

License

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0

---

© 2022 Thoughtworks, Inc.