## 1. Project Overview & Quickstart (vantage-sh/ec2instances.info) ## File: README.md # EC2Instances.info [](https://cloudflare.com) > I was sick of comparing EC2 instance metrics and pricing on Amazon's site so I > made [EC2Instances.info](https://ec2instances.info). EC2Instances.info was originally created by [Garret Heaton](https://github.com/powdahound), is now hosted by [Vantage](https://vantage.sh/) and developed by the community of contributors. ## Project status Vantage employees are actively maintaining and hosting the site with the help of contributors here. Improvements in the form of pull requests or ideas via issues are welcome! People have suggested many neat ideas and feature requests by opening issues on this repository. We also have a [Slack Community](https://vantage.sh/slack) for anyone to join with a devoted channel named #instances-vantage.sh. ## Requirements To do a full build, you just need Docker installed. To develop this, however, you will need Docker and it is suggested you also have [nvm](https://nvm.sh) installed. You can technically just use a Node version that matches or is higher than `next/.nvmrc`, though, if you so wish. ## Developing locally The first thing you should do is run `npm ci` in the root. This is to ensure you have prettier installed as expected. You then need to either: - [Scrape the data locally](#scraping-the-data-locally) - If you aren't touching the scraper, run `curl -L https://instances.vantagestaging.sh/www_pre_build.tar.gz | tar -xzf -` in the root of the repository to grab the latest CI artifact. To start the development server, cd into the `next` directory and run `nvm use` (run `nvm install` before this if the Node version changed or this is first usage). From here, run `npm ci`, for your first ever time run `npm run init`, and then `npm run dev`. This will start the Next development server. Before you make a pull request, it is suggested you run `npm run check-types` to find any type issues. This will be done before build by the CI, but it does tighten development cycles to do it here. When you make changes, it is suggested to use the recommended VS Code extensions if that is your editor. If not, tell your editor to auto-format based on the Prettier configuration in the root. Before you make a PR, you should run `make format` in the root to make sure the formatting is correct for the version of gofmt/Prettier we use. Make sure your pull requests target `develop` since this is our staging. When it is merged into `main`, that is production. ### Scraping the data locally The scraper is written in Go and fetches data from AWS, Azure, and GCP APIs. You'll need credentials for each provider. **AWS:** Ensure your IAM user has at least the following permissions: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ec2:DescribeInstanceTypes", "ec2:DescribeSpotPriceHistory", "ec2:DescribeInstanceTypeOfferings", "elasticache:DescribeEngineDefaultParameters", "rds:DescribeDBEngineVersions", "rds:DescribeOrderableDBInstanceOptions" ], "Resource": "*" } ] } ``` Set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` (`.env` is gitignored). **Azure:** Set `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_SUBSCRIPTION_ID`. [See the Azure setup guide.](./docs/setting-up-azure.md) **GCP:** Set `GCP_PROJECT_ID`, `GCP_CLIENT_EMAIL`, and `GCP_PRIVATE_KEY`. [See the GCP setup guide.](./docs/setting-up-gcp.md) Once credentials are in place, run `./fetch_data.sh` from the repository root. You only need to run this when the scraper is changed in a way that alters the data or there is new API data available you want to test against. EC2 instance launch dates (`date_introduced`) are enriched during each scrape from the public [instancetyp.es timeline](https://instancetyp.es/timeline.json). ## Building a full release **NOTE:** This is NOT needed for development in most cases and can on some setups mess with the file permsisions in the next folder leading to needing to clean the build output/temp folders in there. In most development cases, building the next part is sufficient for testing. However, this is needed for production/staging. To build a full release, you will likely want to clone a clean slate version of the repository. From here, go ahead and run `make all` with the following environment variables: - `AWS_ACCESS_KEY_ID`: Follow the start of [Developing locally](#developing-locally) to get a AWS key with the correct permissions. This is the key ID for that. - `AWS_SECRET_ACCESS_KEY`: Follow the start of [Developing locally](#developing-locally) to get a AWS key with the correct permissions. This is the secret access key for that. - `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID`: Azure credentials for the scraper. See [the Azure setup guide](./docs/setting-up-azure.md). - `GCP_PROJECT_ID`, `GCP_CLIENT_EMAIL`, `GCP_PRIVATE_KEY`: GCP credentials for the scraper. See [the GCP setup guide](./docs/setting-up-gcp.md). - `NEXT_PUBLIC_URL`: The public base URL for where the application lives. Probably `https:///`. - `NEXT_PUBLIC_SENTRY_DSN`: **(Optional)** The DSN for Sentry. If you add this, the other items are required: - `SENTRY_ORG`: The Sentry organisation. - `SENTRY_PROJECT`: The Sentry project. - `SENTRY_AUTH_TOKEN`: The Sentry auth token. - `NEXT_PUBLIC_GOOGLE_TAG_MANAGER_ID`: **(Optional)** The ID used for Google Tag Manager. - `NEXT_PUBLIC_ENABLE_VANTAGE_SCRIPT_TAG`: **(Optional)** If set to 1, enables the Vantage script tag. Intended for use internally. - `NEXT_PUBLIC_INSTANCESKV_URL`: **(Optional)** The base URL you wish to use for [instanceskv](https://github.com/vantage-sh/instanceskv). If this is unset, it will use the version hosted by Vantage. - `SLACK_WEBHOOK_URL`: **(Optional)** A Slack webhook to send scraping warnings to. **Important:** If you don't want your build to be indexed by search engines, you should also set `DENY_ROBOTS_TXT=1`. To remove adverts, you can also add `NEXT_PUBLIC_REMOVE_ADVERTS=1`. You should also set `OPENGRAPH_URL=` to a URL which serves a 1911x1156 JPEG background image for OG image generation; if you aren't Vantage and deploying to production, this is required as the default background is not MIT licensed. This will take ~30 minutes, and when it is done you will have a `www` folder with the content you can deploy to your web server. Your web server should do the following: - `/index.html` or `/index` should redirect to `/` - Trailing slashes should redirect without them. - Anything path ending `.html` should either 404 or redirect to the site without that. - 404's should show a 404 and display the content in `/404.html`. The logic we use to do this (a mix of a scripted push to R2 and a small Cloudflare Worker) can be found in `deployment/index.ts` and `worker.js`. ## Keep up-to-date Feel free to watch/star this repo as we're looking to update the site regularly. Vantage also works on the following relevant projects: - [vantage.sh/models](https://vantage.sh/models) - An open-source site for comparing LLM prices, specifications, benchmarks, and hosting information. - [cur.vantage.sh](https://cur.vantage.sh/) - Definitions of all AWS Cost and Usage Report (CUR) billing codes by service. - [The Cloud Cost Handbook](https://github.com/vantage-sh/handbook) - An open-source set of guides for best practices of managing cloud costs. - [The AWS Cost Leaderboard](https://leaderboard.vantage.sh/) - A hosted site of the top AWS cost centers. - [Vantage](https://vantage.sh/) - A cloud cost transparency platform. --- ## File: docs/setting-up-azure.md # Setting up Azure **Last Edited:** Astrid Gealer, 17th July 2025 Setting up Azure to work with this is quite difficult, but hopefully this guide will help you set it up! The first thing you want to do is sign up for a new Azure subscription. You can use the free tier from their site. This part varies from region to region. > **NOTE:** Not all subscriptions can see all VMs! You need to be able to see all of the virtual machines you want extra specifications about. Not being free tier likely helps here. ec2instances is deployed using an American non-free tier Azure user. ## Creating the application When you have an account, you now want to make an application. Search for "App registrations" in the search and click it: From here, click "New registration" make a new name for your application that you can remember. Leave everything else as it is, and don't set a redirect URI. When you get to the created application, note down the Directory ID (this is your `AZURE_TENANT_ID`) and Application ID (this is your `AZURE_CLIENT_ID`). Now in Manage in the sidebar, click on "API permissions". From here, we will want to add the `user_impersonation` role. To do this, click "Add a permission", "Azure Service Management", and then tick "user_impersonation". You can then click add permissions. **IMPORTANT:** After you do this, you MUST click "Grant admin consent for default directory" and then click Yes. ## Creating the API key To create the API key, go over to "Certificates & secrets" in the manage sidebar. From here, click "Client secrets", "New client secret", and make a new client secret. Copy the value that it specifies (this is your `AZURE_CLIENT_SECRET`). You can ignore the ID. ## Attaching the application to a subscription Now we have the application, we need to tie it to a subscription so we can get instance information from it. To do this, search for "Subscriptions" in Azure and find your subscription. Click it and then click "Access control (IAM)". From here, click "Add" and then subsequently "Add role assignment". In role, assign "Reader". Then in the top where it says "Members" click that. Make sure assign access to is set to "User, group, or service principal" and then click "Select members". In the search page, type the name of your application. It should show up and be selectable. From here, click "Review + assign", make sure everything looks good, and then click it again. This is now tied to your subscription! Go back to overview on this subscription and copy your subscription ID (this is your `AZURE_SUBSCRIPTION_ID`). Congrats! You now have the `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_SUBSCRIPTION_ID` enviornment variables you need! --- ## File: docs/setting-up-gcp.md # Setting up GCP **Last Edited:** Astrid Gealer, 24th March 2026 1. Go to [Cloud Billing API](https://console.cloud.google.com/marketplace/product/google/cloudbilling.googleapis.com) and enable the API. 2. Click Manage, in the new page that opens up, click Credentials in the side bar. 3. Click "Manage Service Accounts", in the new page that opens up, click "Create Service Account". 4. Give it any ID you want. Click create, then click the email of the ID you just made. 5. In the top, click Permissions > Manage access > Add another role. Then under "Basic" click "Viewer" in the popup. After this, click Apply. 6. In the top, click Keys > Add Key. Then create a JSON key. The following attributes from the JSON file should be your environment variables: - `GCP_PROJECT_ID` > the value of `project_id` in the JSON - `GCP_CLIENT_EMAIL` > the value of `client_email` in the JSON - `GCP_PRIVATE_KEY` > the value of `private_key` in the JSON ## 2. Official Technical Reference & Guides (vantage-sh/handbook) ## File: README.md # Cloud Cost Handbook This is the repository backing the site hosted at [handbook.vantage.sh](http://handbook.vantage.sh/). The Cloud Cost Handbook is a free open-source community-supported set of guides meant to help explain the complex pricing of public cloud infrastructure and service providers in "plain English." This guide is open for anyone to contribute their knowledge to the community. [Vantage](http://vantage.sh/) employees will maintain hosting the guide for everyone and ensure that content is relevant and adheres to style guides. The Cloud Cost Handbook is organized into two sections: general concepts and per-service pages. - **General concepts** are meant to cover topics that apply across multiple different infrastructure services. - **Per-service pages** are meant to give a brief summary of the service, the pricing dimensions of the service, and optionally, a list of cost concepts as it relates to that service. ## Contributing Guidelines Issues and pull requests (PRs) are welcome for requesting or contributing content. Vantage employees will review all issues and PRs to ensure we're keeping content relevant and up to standard. You're welcome to get in contact with us on our [Slack Community](https://join.slack.com/t/vantagecommunity/shared_invite/zt-1szz6puz7-zRuJ8J4OJIiBFlcTobYZXA) as well where we have a devoted #cloud-cost-handbook channel for discussion as it relates to the handbook. ### Installing Dependencies This site uses [mkdocs](https://www.mkdocs.org/). Install the following requirements: ```bash pip install --user mkdocs pip install --user mkdocs-material ``` ### Making and Reviewing Changes Prior to opening a pull request, please review your changes locally: 1. Create a separate feature branch, based on the `master` branch, and add your changes. 1. From your feature branch, run `mkdocs serve`. 1. Access and review your changes locally at `http://localhost:8000/`. 1. Open a PR and we will review your request as well as suggest any other changes. ### Deploying Once a PR is merged to the `master` branch, this will trigger a GitHub Actions workflow, which will deploy the site to GitHub Pages. To deploy the site locally, run: ```bash mkdocs gh-deploy --ignore-version ``` ## Keep Up To Date Feel free to watch/star this repo as we're looking to update the site regularly with additional services and concepts. Vantage also works on the following relevant projects: - [EC2Instances.info](https://github.com/vantage-sh/ec2instances.info): An open-source tool for comparing EC2 instance prices and configurations. - [cur.vantage.sh](https://cur.vantage.sh/): A dictionary for AWS billing codes present in the AWS cost and usage report. - [The AWS Cost Leaderboard](https://leaderboard.vantage.sh/): A hosted site of the top AWS cost centers. - [Vantage](https://vantage.sh/): A cloud cost transparency platform. --- ## File: docs/index.md # Cloud Cost Handbook The Cloud Cost Handbook is a free, open-source, community-supported set of guides meant to help explain the complex pricing of public cloud infrastructure and service providers in easy-to-understand terms. This guide is [hosted on GitHub](https://github.com/vantage-sh/handbook) and is open to anyone to contribute their knowledge to the community. [Vantage](https://www.vantage.sh/) employees will maintain hosting the guide for everyone and ensure that content is relevant and adheres to style guides. ## Structure This handbook is separated into two different sections as explained below: ### General Concepts These are general concepts that don't necessarily map directly to a particular service. ### Provider Services Provider services are meant to be the source of truth for explaining not only the pricing mechanics of the service but also to explain potentially nuanced concepts related to costs for that service. The focus of these pages is meant to be on the _pricing_ of these services and not related to the actual management or orchestration of the service itself. !!! contribute "A Note About Currency" Any listed prices are provided in US Dollars (USD). This is also the [default currency](https://repost.aws/knowledge-center/supported-aws-currencies) AWS uses for billing. ## Contributing Anyone is welcome to contribute to the Cloud Cost Handbook by issuing a pull request on the GitHub repo. [:material-github: Contribute](https://github.com/vantage-sh/handbook){ .md-button } ## Slack Community Generally interested in cloud concepts and associated costs? Join us in our public Slack community. We have a channel devoted to the handbook named `#cloud-costs-handbook` where you're welcome to hang out, ask questions, or spark conversation. [:material-slack: Slack Community](https://vantage.sh/slack){ .md-button }