Tokens cost money. That becomes abundantly clear when you scale your AI web app to millions of users and receive a hefty price tag associated with token consumption. Every call to a remote cloud-hosted AI model, while miniscule on its own, adds costs that can compound fast. However, as AI models become smaller and smarter, it’s becoming possible and practical to offload some of those workloads to the on-device models on the client before they ever reach your backend.

Here are three strategies to drastically slash cloud token consumption. Each of them can be implemented on web apps built with Firebase AI Logic with on-device AI in Chrome. Together, and over time and with lots of users, these strategies will help you save more than a billion tokens in the AI apps you build.

Selective routing: Avoid sending any tokens at all

In some cases, a small on-device model can yield comparable results to larger cloud-hosted models. Summarization tasks are especially well suited for an on-device model and could result in a significant reduction in cloud costs over time.

For example, I built an application that takes a synopsis of an untitled article and outputs suggestions for titles and subtitles in different styles. On the left is the response from my cloud-hosted model and on the right is the response from my on-device model:

For my purposes, the results from the on-device model are comparable to those from my cloud-hosted model. By using an on-device model, an operation that would normally consume 131 input and output tokens with my cloud-hosted model can be completely offloaded. This brings the token consumption costs down to zero for inference associated with this feature.

Prompt summarization: reduce verbose user input

Language isn’t always as concise as it could be. In those cases, an on-device model is a great way to summarize the important information in a prompt before sending it off to the cloud model to do deeper thinking. This way you’re not spending input tokens on redundant or unnecessary pieces of information.

To demonstrate the impact on token consumption with this strategy, I built another web application that takes a transcript from a customer support chat session to generate an issue report in two ways. The first way, on the left, sends the original text of the chat transcript to the cloud-hosted model and returns what it could look like as an issue. The second way, on the right, sends the original text to the on-device AI model first to produce a summary of the transcript before sending that to the cloud model:

In this case, I was able to reduce input tokens by 44% by summarizing the transcript locally before sending it to my cloud-hosted model. Effective use of this strategy depends on crafting the right summarization instructions for the on-device model to adequately summarize prompts for your particular use case. In my case, I was able to avoid consuming about 80 tokens associated with this app functionality.

Session compacting: shrink session history

Selective routing and prompt summarization tackle token consumption at the prompt level. For AI chat applications, session compacting is a strategy for reducing token consumption in another part of the context: the session history.

When session history contains each and every verbose message from the user and ai, the payload sent to the model steadily increases with every message and response, taking up more of the context window. Session compacting reduces the token cost of the payload by replacing entries in the session history with shorter and more concise summaries.

To demonstrate, I built a basic AI chat app with an option to manually compact the session using an on-device model and show the token reduction for each message the session payload:

In the example above, only the messages from the model were compacted while the user messages were left intact. As a result, token consumption of the session history is reduced by 71%.

Similar to prompt summarization, effective use of session compacting requires a thoughtful balance between token reduction and response accuracy. You may find that replacing all the messages with shorter versions reduces token consumption the most, but choose to retain the most recent messages verbatim to maintain a level of accuracy. Or you might craft system instructions for the summarizing model that instruct it to retain particularly important information that might appear in each message. Depending on your application’s needs, your session compacting strategy may vary.

Implementing these strategies with Firebase AI Logic

Firebase AI Logic supports switching between using cloud-hosted models (through the Gemini Developer API or Agent Platform Gemini API) and an on-device model using the Prompt API from Chrome.

Implementing any of the token-saving strategies above comes down to specifying the inference mode in the model parameters. The inference mode controls how your application will handle subsequent AI Logic requests. For example, to implement a selective routing strategy where your app tries to use the on-device model before trying the cloud-hosted model, you’ll set the inference mode to PREFER_ON_DEVICE in model parameters provided to the getGenerativeModel method:

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, AgentPlatformBackend, InferenceMode } from "firebase/ai";

export async function generateAnyResponse(prompt){
  const app = initializeApp();
  const ai = getAI(app, { backend: new AgentPlatformBackend() });
  
  const model = getGenerativeModel(ai, {
    mode: InferenceMode.PREFER_ON_DEVICE,
    inCloudParams: {
      model: "gemini-3.5-flash-lite",
      systemInstruction: "instructions for cloud model",
    },
    onDeviceParams: {
      createOptions: {
        initialPrompts: [
          {
            role: "system",
            content: [
              {
                type: "text",
                value: "instructions for on-device model",
              },
            ],
          },
        ],
      },
    },
  });

  const result = await model.generateContent(prompt);
  return result.response.text();
}

With the PREFER_ON_DEVICE inference mode all subsequent model calls will use the on-device model if it’s available and fall back to the cloud-hosted model if it isn’t.

To avoid using a cloud-hosted model at all, you could specify the ONLY_ON_DEVICE inference mode, which will throw an exception if the on-device model is not available. This is useful you want to incorporate prompt summarization but don’t want to use your cloud-hosted model for any summarization tasks when the on-device model is unavailable:

import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, AgentPlatformBackend, InferenceMode } from "firebase/ai";

export async function generateLocalResponse(prompt){
  const app = initializeApp();
  const ai = getAI(app, { backend: new AgentPlatformBackend() });
  
  const model = getGenerativeModel(ai, {
    mode: InferenceMode.ONLY_ON_DEVICE,
    onDeviceParams: {
      createOptions: {
        initialPrompts: [
          {
            role: "system",
            content: [
              {
                type: "text",
                value: "Summarization instructions for on-device AI.",
              },
            ],
          },
        ],
      },
    },
  });

  const result = await model.generateContent(prompt);
  return result.response.text();
}

As you might expect there are additional inference modes like ONLY_IN_CLOUD and PREFER_IN_CLOUD for routing requests primarily to the cloud-hosted model. However, when it comes to conserving token usage from your client, some combination of ONLY_ON_DEVICE and PREFER_ON_DEVICE will be key to implementing any of the 3 strategies discussed.

Reaching a billion tokens

Saving a billion tokens is a massive milestone, but it isn’t a goal you hit overnight. It’s a cumulative victory that compounds slowly as you scale your user base and offload more of your AI functionality to the client. However, on-device AI isn’t a one-size-fits-all solution. To build a robust architecture that reaches that level, you need to navigate current environment requirements while knowing exactly when to stay in the cloud.

Limitations to consider

The most significant limitation today is the execution environment. For these strategies to work, your users must be running Chrome (version 139 or later) on a device that supports the Gemini Nano model. Because the model is downloaded and executed locally, the first run often requires a brief wait while Chrome prepares the environment.

Additionally, on-device models are typically smaller and more specialized. They excel at pattern recognition and summarization but may struggle with deep logical reasoning or maintaining accuracy over extremely large context windows.

Choosing your inference mode

Deciding where to run your model depends on the specific requirements of the task:

Prefer on-device AI when:

• Privacy is paramount: Processing sensitive user data that should never leave the local machine.
• Connectivity is unreliable: Ensuring applications remain functional in offline or low-bandwidth environments.
• Handling high-frequency, low-complexity tasks: Such as real-time text formatting, basic summarization, or local search indexing.
• Prefer in-cloud AI when:
• Tasks require complex reasoning: If your prompt involves multi-step logic, advanced coding assistance, or nuanced creative writing.
• Working with massive context: For tasks that require analyzing large documents or entire codebases.

By using the PREFER_ON_DEVICE mode in Firebase AI Logic, you get the best of both worlds: high-performance local execution for the majority of your users, with a transparent fallback to the cloud when hardware or complexity demands it.

Recapping core strategies

Token optimization is essential for building resilient, scalable AI architectures that support long-term growth. By strategically moving client-ready AI workloads to the edge by using on-device AI models you’re setting yourself up for success by ensuring that your user base can scale up without token consumption costs spiraling out of control.

To recap the three core strategies:

• Selective routing: Eliminate cloud calls entirely for straightforward summarization tasks.
• Prompt summarization: Compress verbose inputs locally before dispatching them to large cloud models.
• Session compacting: Keep multi-turn chat context windows lean without losing crucial conversation state.

Whether you adopt one pattern or combine all three together, these techniques can scale significantly, potentially saving a billion tokens over time as your user base grows.

Ready to optimize your own app? Check out the Prompt API documentation for an interactive demo of session compacting or dive into the Firebase AI Logic documentation to start building hybrid, token-efficient web apps today.

Three ways to save a billion tokens with Firebase AI Logic and on-device AI for Chrome was originally published in Google Cloud - Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

You can keep an AI harness secure in a number of ways, like creating isolated sandbox environments with resource caps or making sure there’s write protection on production data. But these strategies go out the window if you can’t get a handle on who can access your harness and from where. Without these controls, your backend agent endpoints are left vulnerable to automated bots, credential stuffing, spam account creation, and imposter clients looking to exploit your agent’s tools.

That’s why securing the human-to-agent boundary is an important first line of defense against external threats and abuse. And this is where Firebase Authentication and Firebase App Check work in tandem to help protect your harness from abuse.

Identify users with Firebase Authentication

If you’ve deployed a custom harness using the Antigravity SDK (or really any other framework or library) to Google Cloud and it has a client facing endpoint, like a chat interface, you can use Firebase Authentication to help you verify the user’s identity using popular and trusted federated identity providers like Sign in with Google, Facebook, and GitHub. As a managed service, you’re able to drop in authentication into your client application with no additional infrastructure to set up or manage.

Attest approved devices with Firebase App Check

While Firebase Authentication verifies who the user is, Firebase App Check provides device and application attestation to help prove where the request is coming from. This helps ensure that the request originates from your authentic, untampered app on a real device. App Check issues a unique App Check token that a client can use to attest that it’s a legitimate source. This token is passed along via the Firebase client SDK to protected Firebase services, like Cloud Firestore and SQL Connect, as well as custom backends, like a proxy service set up in front of an agent. If a token is present, and the risk score is below the threshold, the connection is allowed. Otherwise, access is blocked.

App Check is able to achieve device verification by offloading this heavy lift to trusted platform-native attestation providers like DeviceCheck and App Attest for iOS, Play Integrity for Android, and reCAPTCHA Enterprise for web apps. These providers are constantly evolving behind the scenes to keep pace with new emerging attack patterns. That means that the entry to your agent continues to stay protected against device impersonation techniques that may not have existed when you first deployed your agentic workflows. If those providers don’t meet your needs, you can even add a custom attestation provider to mint your own App Check tokens.

Replay Protection for extra-sensitive endpoints

App Check tokens are the way App Check communicates whether a client device is approved and genuine. Session-based App Check tokens are valid according to a configured time-to-live (TTL) value that can be set to last from 30 minutes to 7 days. Session-based tokens allow a developer to balance latency with security, since acquiring a token has an encryption latency cost. After expiration, the client will silently acquire a new App Check token by calling the attestation provider (encryption cost). For additional protection for especially sensitive endpoints, tokens can be changed from session-based (which are reused) to one-time-use by setting up replay protection.

Replay protection works in two parts. First, on the client, an App Check token is requested using the getLimitedUseToken() method from the Firebase Client SDK, instead of getToken(). Next, on the backend where the Firebase Admin SDK checks that the token is valid, it is also marked as consumed. With that designation, the backend is able to reject any request that attempts to reuse that token.

Ultimately, your AI agent’s harness is only as safe as the gateway that governs the access to it. The combination of Firebase Authentication and Firebase App Check go a long way in helping to establish a secure boundary between the human and your AI agent. They work hand in hand to help ensure that your agents are protected from external exploits and threats while you can focus on building your agent harness.

How to protect your agent harness from abuse with Firebase was originally published in Google Cloud - Community on Medium, where people are continuing the conversation by highlighting and responding to this story.

Conveniently, it provides a shell script that will set you up with application default credentials. The problem is that it only works on Mac and Linux. If you’re on Windows, or if for whatever reason this script fails on your machine, you might be tempted to just hit that “Create API Key” button and avoid application default credentials altogether.

But don’t.

Instead, follow these 5 quick steps to get your application default credentials set up fast. (If you want more details on application default credentials, here’s a video I put out on the topic that you should check out.)

Step 1: Verify you’ve got gcloud installed

You’re gonna need the Google Cloud CLI (gcloud) installed on your machine. Verify it’s installed by running:

gcloud version

If you already have it, move on to step 2. If not, you can find install instructions right here.

Step 2: Log-in and set application default credentials

The Google Cloud CLI manages 2 types of authentication. gcloud auth login authorizes gcloud commands to access Google Cloud with your credentials. gcloud auth application default login sets your user credentials as application default credentials.

Set them both in one swoop with the following:

gcloud auth login --update-adc

Step 3: Set your project id

We’ll reference your project ID a few times so set that to an environment variable:

export PROJECT_ID=<YOUR_PROJECT_ID>

The Google Cloud CLI references a project ID in 2 different ways. First, it’s defined in your current workspace config. Set that with:

gcloud config set project $PROJECT_ID

Now your project will be used in step 4, and any other gcloud commands you run.

Application default credentials don’t look at this value for a Google Cloud project. Instead it needs a quota project. Set a quota project with the following command:

gcloud auth application-default set-quota-project $PROJECT_ID

This project will be used when accessing Google Cloud APIs via Cloud Client Libraries used in your application code locally.

Step 4: Enable the API

Before you can use Agent Platform, your project needs to have the Agent Platform API enabled in it. Enable it with this command:

gcloud services enable aiplatform.googleapis.com

This makes it so that the service is accessible on your project. Without it, you’ll get a 403 error.

Step 5: Verify your access

To verify everything is set up correctly, we’ll hit the Agent Platform API with a web request that includes a temporary access token generated via your application default credentials.

First, retrieve the token and set it to an environment variable:

export TOKEN=`gcloud auth application-default print-access-token`

Next, set another environment variable to the contents of the request:

export REQUEST=$(cat \<\<EOF  
{  
  "contents": \[{  
    "role": "user",  
    "parts": \[{ "text": "Wave hello to the world" }\]  
  }\]  
}  
EOF  
)

And finally, put it all together in a single curl command:

curl \-s \-X POST \\  
\-H "Authorization: Bearer $TOKEN" \\  
\-H "Content-Type: application/json" \\  
"https://aiplatform.googleapis.com/v1/projects/$PROJECT\_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" \\  
\-d “$REQUEST”

The output should include a line that reads something like: ”text”: “Hello, world! 🌍👋”

Now you’re ready to ditch the API key and use application default credentials.
Happy trails!

Vector database platforms like Pinecone and Qdrant offer a great streamlined experience for spinning up and querying a vector database. AlloyDB on Google Cloud is a different category of product entirely: it’s enterprise-grade PostgreSQL built for high availability, extreme scale, and production workloads. That depth means getting started with vector search on AlloyDB takes a few more steps than a vector-only platform, but if that’s the infrastructure you’re building on, it’s well worth it.

Here’s the fast path to spinning up your first vector database on AlloyDB.

Before we can start

We’ll need a few things before we get started:

A Google Cloud project with billing enabled. A valid billing account is required to use a lot of Google Cloud services. We’ll be using an AlloyDB free trial cluster to keep costs as low as possible.

Owner permissions on the project. The Owner role is generally not recommended, but for learning purposes we’ll use it to complete the steps. I’ll make a separate post about the IAM roles we’d use if we want to apply the principle of least privilege.

Enabled APIs and services. To complete the steps below, enable the following APIs on the Google Cloud project:

• AlloyDB API
• Vertex AI API
• Compute Engine API
• Service Networking API

Sample data. Here is a CSV file of 2,000 products of a mock online store. We’ll be using the product descriptions to generate vector embeddings and perform a semantic search.

1. Create an AlloyDB cluster

We’ll start on the AlloyDB Get Started page where there are a few options for clusters we could create. If the option is available, you’ll see a banner to create a free trial cluster (sandbox cluster) that you can use at no charge for 30 days. Fill in a password and click Create free trial to create a new cluster.

If you’re able to create a free trial cluster, jump down to step 2 to continue. Otherwise, if you don’t see this option, the next lowest cost option will be a prototyping cluster. Click Create 1vCPU cluster.

This will load up a template that will deploy the smallest machine available for the C4A machine series in a single availability zone. Fill out the fields for cluster ID and password.

Click Generate to autofill in a secure password string. We’ll need it later, so keep this value safe somewhere. Keep the rest of the configuration set to their default values.

Lower on the page, where we choose a private connection method, keep Private Services Access selected and click Confirm network setup.

This will enable a private services access connection on our default VPC. That will take between 1 and 2 minutes. Once it completes, click Create cluster to create an AlloyDB cluster. When it finishes, the Overview page for the cluster will load.

Copy the value for Service Account to your clipboard. We’ll use that in the next step.

2. Grant the AlloyDB service account access to Vertex AI

AlloyDB’s AI functionality is powered by Vertex AI. It’s not automatic, so we have to manually grant the appropriate permissions to the AlloyDB service account that we copied in the last step. To do this, we head over to the IAM Admin page and click Grant Access. Specify the AlloyDB service account and choose the Vertex AI User role:

Hit save and head back to the AlloyDB cluster Overview page.

3. Create a new database

Our new cluster includes a default database called postgres but let’s create our own. There’s no way to do that in the console, so we have to use the in-console AlloyDB Studio. A link to AlloyDB Studio can be found in the left side navigation pane of the Overview page, next to the magnifying glass icon.

First it will ask us to log in to our database.

For Database, we’ll select the default postgres and choose Built-in database authentication as the authentication method. We’ll use the default user postgres and the cluster password we set when we created the cluster.

Once we’re in AlloyDB Studio, we can run the following statement to create a new database in our cluster:

CREATE DATABASE myvectordb;

At the top left of the AlloyDB Studio Explorer panel, click the person/gear icon to switch over to the new database.

We can use the same default built-in database authentication that we did to log into the postgres database.

4. Install required extensions

By default, our database does not have any AI functionality to support a vector database. For that, we have to install the vector and alloydb_scann extensions:

CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS alloydb_scann;

The vector extension is an AlloyDB-customized version of the open source pgvector PostgreSQL extension. The alloydb_scann extension lets us implement highly efficient indexing using the ScaNN algorithm. Together, they enhance our ordinary PostgreSQL database so that it can store and query vector embeddings.

5. Create a table with a vector embedding column

We’ve got a database, but we still need a table to store our data. Since we’re going to import data from a CSV file in the next step, we have to make sure that the order of the columns and their types match those in the sample csv file:

CREATE TABLE "public"."products" (
 "id" BIGINT NOT NULL,
 "category" TEXT,
 "name" TEXT,
 "brand" TEXT,
 "retail_price" NUMERIC,
 "department" TEXT,
 "sku" TEXT,
 "product_description" TEXT,
 "product_description_embedding" vector(3072) 
 GENERATED ALWAYS AS (embedding('gemini-embedding-001', product_description))
 STORED
);

The product_description_embedding column will be a vector with 3072 dimensions generated with the gemini-embedding-001 text embedding model applied to the product_description column.

6. Import data

Back on the Overview page, click the Import button at the top of the page.

Select CSV as file format, and then choose Upload files from your computer. Click Browse to select the local test data file.

Click the second Browse link to select Cloud Storage location to upload the sample CSV file to. If one doesn’t exist we can create a new bucket by clicking the new bucket icon at the top of the bucket selection pane.

Give it a universally unique name and click Create then Select.

Next, hit Upload to upload the file.

Finally, choose the database myvectordb and the table products, and click Import.

This will take a few minutes. When it’s done, our products table will have 2,000 rows, each with a text embedding in the last column generated using the gemini-embedding-001 model as specified when the table was created in the previous step. And any updates to content of the product_description column of any row will update the embedding column as well.

7. Create an index

At this point, we could perform a semantic search on our data. However, generating an index will pre-organize our vector embeddings in an index and allow similarity searches on millions of rows. We’ll head back to AlloyDB studio and run the following:

-- Generating the index requires more maintenance work memory than the default setting allows.
SET maintenance_work_mem = '400MB';

CREATE INDEX IF NOT EXISTS idx_product_description_embedding ON products
USING ScaNN (product_description_embedding cosine)
-- The optimal number of leaves is roughly the square root of the number of rows in the table.
WITH (num_leaves=173);

8. Do a semantic search

With text embeddings and ScaNN index in place we can now do a semantic search on our data. This example query combines a keyword filter on the category column with a semantic search query.

SELECT * FROM products
WHERE category = 'Outerwear & Coats'
ORDER BY
  product_description_embedding <=> CAST(embedding('gemini-embedding-001', 'lightweight puffer jackets for hiking') AS vector)
LIMIT 5;

The result we get back should be 5 rows, each one semantically matching the search term provided in the query.

What next?

These steps are dependent on the sample data that I provided at the top of the tutorial, but they have everything you need to apply it to your own data. Everything here was done from the Google Cloud Console. If you have a preferred client, like pgadmin, or if you want to connect your application to the database, check out the documentation for setting up a connection to AlloyDB. If you want to walk through the steps as an interactive code lab, check out Getting started with Vector Embeddings with AlloyDB AI.

Update: Since publishing this post, Vercel has added a provider for Google Vertex.

The Vercel AI SDK documentation includes code samples for hooking up the SDK to different providers like Anthropic, OpenAI, and others. This list includes Google, but only shows you how to use the Google AI JavaScript SDK. Here’s some sample code of how to hook it up to the Vertex AI SDK:

// app/api/chat/route.ts
import { VertexAI } from "@google-cloud/vertexai";
import { GoogleGenerativeAIStream, Message, StreamingTextResponse } from "ai";

const project = process.env.GOOGLE_CLOUD_PROJECT || "";
const location = "us-central1";

const vertexAI = new VertexAI({ project: project, location: location });

// Google GenAI API can use the edge runtime. This will not work with Vertex AI
// export const runtime = 'edge';

// Instantiate Gemini models
const generativeModel = vertexAI.getGenerativeModel({
  model: "gemini-pro",
});

const buildGoogleGenAIPrompt = (messages: Message[]) => ({
  contents: messages
    .filter(
      (message) => message.role === "user" || message.role === "assistant"
    )
    .map((message) => ({
      role: message.role === "user" ? "user" : "model",
      parts: [{ text: message.content }],
    })),
});

export async function POST(req: Request) {
  // Extract the `prompt` from the body of the request
  const { messages } = await req.json();

  const geminiStream = await generativeModel.generateContentStream(
    buildGoogleGenAIPrompt(messages)
  );

  // Convert the response into a friendly text-stream
  // GoogleGenerativeAIStream class decodes/extracts the text tokens in the
  // response and then re-encodes them properly for simple consumption.
  const stream = GoogleGenerativeAIStream(geminiStream);

  // Respond with the stream
  return new StreamingTextResponse(stream);
}

To run the above code, follow the instructions for the Getting Started tutorial and use it for the app/api/chat/route.ts file. (Skip the API key step).

Notes

Some differences between this Vertex AI SDK example and the one for the Google AI JavaScript SDK:

• We don’t indicate the runtime as 'edge' because it is not compatible with the Vertex AI SDK. Click here for more information on the Edge Runtime and Node.js modules.
• Instead of API keys, Vertex uses a project ID indicated via the GOOGLE_CLOUD_PROJECT environment variable and application default credentials indicated via the GOOGLE_APPLICATION_CREDENTIALS environment variable.

If you’ve got some application code sitting in GitHub and need to push it to a Docker registry, there are a lot of options. This article is going to cover just one: pushing to Google Cloud Artifact Registry using GitHub Actions. And we’re going to make it happen without using service account keys by leveraging Google Cloud Workload Identity Federation.

Where to begin

Some things we need first

To follow along with what I’m going to demonstrate, you’ll need a couple of things:

☑️ A Google Cloud project: this will be the project where we’ll be creating our resources, which includes an Artifact Registry repository and some IAM resources. Enable the IAM Service Account Credentials and Artifact Registry APIs on this project.

☑️ Google Cloud CLI: we’ll be using the gcloud CLI to interact with Google Cloud. If you don’t want to install it on your local machine, you can use the Cloud Shell in the Google Cloud console which has gcloud built-in.

☑️ A GitHub repository: you’ll need a GitHub repository with a Dockerfile so that you can build and push your container image to the Artifact Registry.

GitHub Actions workflow file

GitHub Action workflows are typically stored as yaml files in the .github/workflows/ directory of your repo. Here’s the GitHub Action workflow file we’re working with:

name: Push to Artifact Registry

on:
    push:
      branches: [ "main" ]

env:
  IMAGE_NAME: ''
  PROJECT_ID: ''
  AR_REPO_LOCATION: ''
  AR_URL: ''
  SERVICE_ACCOUNT: '' 
  WORKLOAD_IDENTITY_PROVIDER: ''

jobs:
  push_to_ar:
    permissions:
      contents: 'read'
      id-token: 'write'

    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Google Auth
        id: auth
        uses: 'google-github-actions/auth@v2'
        with:
          token_format: 'access_token'
          project_id: ${{ env.PROJECT_ID }}
          service_account: ${{ env.SERVICE_ACCOUNT }}
          workload_identity_provider: ${{ env.WORKLOAD_IDENTITY_PROVIDER }}

      - name: Docker Auth
        id: docker-auth
        uses: 'docker/login-action@v1'
        with:
          username: 'oauth2accesstoken'
          password: '${{ steps.auth.outputs.access_token }}'
          registry: '${{ env.AR_REPO_LOCATION }}-docker.pkg.dev'

      - name: Build and Push Container
        run: |-
          docker build -t "${{ env.AR_URL }}/${{ env.IMAGE_NAME }}:${{ github.sha }}" ./
          docker push "${{ env.AR_URL }}/${{ env.IMAGE_NAME }}:${{ github.sha }}"

This workflow will authenticate with Google Cloud using the Google Cloud auth GitHub Action and use Docker to authenticate and push to the registry. To make this workflow work (or flow?) we need to set up some Google Cloud resources and add in those values for our environment variables. Make sure to add in the value for PROJECT_ID where you have permission to create resources. The value for IMAGE_NAME can be anything — it’ll be created the first time this workflow runs:

...
env:
  IMAGE_NAME: 'my-app-image'
  PROJECT_ID: 'my-project-id'
  AR_REPO_LOCATION: ''
  AR_URL: ''
  SERVICE_ACCOUNT: '' 
  WORKLOAD_IDENTITY_PROVIDER: ''
...

Good start! Next we’ll need an Artifact Registry repository.

Artifact Registry repository

Artifact Registry is Google Cloud’s build artifact management solution. It supports several types of repositories like apt, Maven, and Python. For our purposes, we want a Docker repository. You can use an existing one, or create a new one with this gcloud command:

gcloud artifacts repositories create my-ar-repo \
  --repository-format=docker \
  --location=us-central1 \
  --description="Example Docker repository"

This will create a Docker repository called my-ar-repo in the us-central1 region. You can see it in the console on the Artifact Registry repositories page. For our workflow YAML file, we need the Artifact Registry URL. Let’s retrieve that with the following command:

gcloud artifacts repositories describe my-ar-repo --location=us-central1

The output will look like this:

Encryption: Google-managed key
Registry URL: us-central1-docker.pkg.dev/my-project-id/my-ar-repo
Repository Size: 5026.459MB
createTime: '2024-03-13T23:19:57.701232Z'
description: Example Docker repository
format: DOCKER
mode: STANDARD_REPOSITORY
name: projects/my-project-id/locations/us-central1/repositories/my-ar-repo
updateTime: '2024-03-18T17:08:49.658081Z'

Let’s take that value for the Registry URL and throw it into our GitHub Actions workflow file, along with the repo location:

...
env:
  IMAGE_NAME: 'my-app-image'
  PROJECT_ID: 'my-project-id'
  AR_REPO_LOCATION: 'us-central1'
  AR_URL: 'us-central1-docker.pkg.dev/my-project-id/my-ar-repo'
  SERVICE_ACCOUNT: '' 
  WORKLOAD_IDENTITY_PROVIDER: ''
...

Service account

Next, we need a service account to serve as the identity that’s going to be doing the pushing to the Artifact Registry repository. Create a service account with gcloud:

gcloud iam service-accounts create github-actions-service-account \
 --description="A service account for use in a GitHub Actions workflow" \
 --display-name="GitHub Actions service account."

Now that we have a service account (see it in the console under IAM), let’s add the service account email to our YAML file. The format is SERVICE_ACCT_NAME@PROJECT_ID.iam.gserviceaccount.com:

...
env:
  IMAGE_NAME: 'my-app-image'
  PROJECT_ID: 'my-project-id'
  AR_REPO_LOCATION: 'us-central1'
  AR_URL: 'us-central1-docker.pkg.dev/my-project-id/my-ar-repo'
  SERVICE_ACCOUNT: 'github-actions-service-account@my-project-id.iam.gserviceaccount.com' 
  WORKLOAD_IDENTITY_PROVIDER: ''
...

By default, the service account has no permissions on any resources on the project. We only need it to be able to push builds to our Artifact Registry repo. Let’s make it so:

gcloud artifacts repositories add-iam-policy-binding my-ar-repo \
  --location=us-central1 \
  --role=roles/artifactregistry.createOnPushWriter \
  --member=serviceAccount:github-actions-service-account@my-project-id.iam.gserviceaccount.com

The command above grants the Artifact Registry Create-on-Push Writer IAM role to our service account, but only for our particular Artifact Registry repository. We could grant it on the entire project by adding the IAM binding to the project IAM policy, but since Artifact Registry repos have their own IAM policies, we can practice some least privilege and narrow the scope to just the one we’re working with.

With that, our service account is able to push builds to our Artifact Registry. Well not really — now we need a way to tell it to do that.

Note: If the application image already existed in our repository, then roles/artifactregistry.writer would suffice. We’re using roles/artifactregistry.createOnPushWriter instead because on the first push, it needs to be able to create the initial image for our application.

Workload Identity Federation

Historically, one way to programmatically access resources with a service account has been to use JSON keys to authenticate with their credentials. That’s still possible, but it is highly discouraged due to the security risk associated with managing them. You’ll see caution signs about that throughout Google Cloud console and documentation:

Workload Identity Federation offers an alternative. It lets us grant external identities the ability to impersonate a service account without the burden of service account keys. Our goal is to create a workload identity pool provider for our GitHub repository so that we can impersonate our service account from a GitHub Actions workflow.

Create a workload identity pool

Before we can create a provider, we need to create a workload identity pool. A workload identity pool is a Google Cloud resource that is used to manage external identities. Google Cloud suggests creating a new pool for each non-Google Cloud environment that needs to access resources in our project. For our case, let’s create a workload identity pool for our app’s development environment:

gcloud iam workload-identity-pools create "my-app-dev-pool" \
  --project=PROJECT_ID \
  --location=global \
  --display-name="Identity pool for my test app"

This creates a workload identity pool on your project. See it in the console under IAM.

Create a workload identity pool provider

A workload identity pool provider describes the relationship between Google Cloud and an identity provider (IdP) that supports OpenID Connect (OIDC). It must be created within a workload identity pool:

gcloud iam workload-identity-pools providers create-oidc "github-actions-provider" \
 --location="global" \
 --workload-identity-pool="my-app-dev-pool" \
 --display-name="Provider for GitHub Actions" \
 --issuer-uri="https://token.actions.githubusercontent.com" \
 --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner"

The create-oidc sub-command indicates that we want to create an OpenID Connect (OIDC) provider in our pool. GitHub uses OIDC to authenticate with different cloud providers (see GitHub documentation on it here). The issuer-uri parameter specifies the provider URL, as indicated by GitHub’s OIDC documentation.

The --attribute-mapping parameter lists our attribute mapping. Attribute mapping defines how values are derived from an external token and mapped to the Google Security Token Service (STS) token attributes. The value for this parameter is a comma-separated list of mappings in the form of TARGET_ATTRIBUTE=SOURCE_EXPRESSION. These attributes will be referenced later when we set up permissions.

Learn more about attribute mapping from Google Cloud’s documentation on workload identity federation.

With a workload identity pool provider in place we can add the value to our workflow YAML file. First, retrieve the full name of the provider:

gcloud iam workload-identity-pools providers describe github-actions-provider \
  --location=global \
  --workload-identity-pool="my-app-dev-pool"

The output will include the name which will be in the format projects/PROJECT_NUMBER/locations/POOL_LOCATION/workloadIdentityPools/POOL_NAME/providers/PROVIDER_NAME. That’s what we need for the WORKLOAD_IDENTITY_PROVIDER environment variable:

...
env:
  IMAGE_NAME: 'my-app-image'
  PROJECT_ID: 'my-project-id'
  AR_REPO_LOCATION: 'us-central1'
  AR_URL: 'us-central1-docker.pkg.dev/my-project-id/my-ar-repo'
  SERVICE_ACCOUNT: 'github-actions-service-account@my-project-id.iam.gserviceaccount.com' 
  WORKLOAD_IDENTITY_PROVIDER: 'projects/123456789/locations/global/workloadIdentityPools/my-app-dev-pool/providers/github-actions-provider'
...

Setting permissions

The only permissions we’ve granted so far have been to our service account to push to the Artifact Registry repository. Now that we have a workload identity provider, we need to grant it permission to act as the service account.

If we wanted to grant service account impersonation permissions to a user account or service account principal, we would grant the Service Account Token Creator role on the service account’s IAM policy:

gcloud iam service-accounts add-iam-policy-binding \
  github-actions-service-account@my-project-id.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator \
  --member=user:roger@myemail.com

This command would allow my user account to act as the service account and access whatever the service account can access. With Workload Identity Federation, it’s the same concept with 2 differences: the IAM role and the principal (or the member parameter in the command above).

Instead of granting the Service Account Token Creator role (roles/iam.serviceAccountTokenCreator) to our workload identity pool principal, we need to grant the Workload Identity User role (roles/iam.workloadIdentityUser) instead. This role allows the principal to impersonate service accounts from federated workloads.

As for the principal, the prefixes user and serviceAccount are used for user accounts and service accounts, respectively, followed by an email address:

user:roger@myemail.com

serviceAccount:my-service-account@my-project-id.iam.gserviceaccount.com

Workload Identity Federation however uses principalSet as a prefix, followed by a member identifier that includes the identity pool and an attribute from the provider’s attribute mapping:

principalSet://iam.googleapis.com/WORKLOAD_IDENTITY_POOL_NAME/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

For example, the following principal can be used to grant access to external identities coming from any GitHub repository that your organization owns:

principalSet://iam.googleapis.com/WORKLOAD_IDENTITY_POOL_NAME/attribute.owner/your-github-organization

We can use any of the attributes that we mapped on our workload identity federation OIDC provider earlier. The principal that we’ll be using, however, will narrow access down to external identities corresponding with one particular GitHub repository using attribute.repository:

principalSet://iam.googleapis.com/WORKLOAD_IDENTITY_POOL_NAME/attribute.repository/github-repo-owner/github-repo-name

Note: Besides attributes, you can grant permissions to external identities by subject and by group. Learn more about that here.

So we’ve got a IAM role and a principal to grant it to. Let’s add an IAM binding to our service account’s IAM policy. First, retrieve the workload identity pool name:

gcloud iam workload-identity-pools describe "my-app-dev-pool" \
  --location=global

The value will be in the format projects/PROJECT_NUMBER/locations/POOL_LOCATION/workloadIdentityPools/POOL_NAME

It’s a long string, so let’s throw this into an environment variable:

export WIP_POOL=projects/123456789/locations/global/workloadIdentityPools/my-app-dev-pool

And finally, let’s add the binding to the service account’s IAM policy. Be sure to update the values for GITHUB_REPO_OWNER and GITHUB_REPO_NAME with values for the GitHub repo that you plan on the running the workflow from:

gcloud iam service-accounts add-iam-policy-binding \
  github-actions-service-account@my-project-id.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member=principalSet://iam.googleapis.com/${WIP_POOL}/attribute.repository/GITHUB_REPO_OWNER/GITHUB_REPO_NAME

With this binding in place, GitHub Actions is able to use Workload Identity Federation to authenticate as your service account and push builds to your Artifact Registry. There’s one more thing we can do to further narrow the scope of access: specify an attribute condition on the identity pool provider.

An attribute condition is an expression that checks an attribute and must evaluate to true for a given credential in order for it to be accepted. For example, we can define an attribute condition that checks whether the attribute repository_owner matches a GitHub organization or GitHub user that owns a repository:

gcloud iam workload-identity-pools providers update-oidc \
  github-actions-provider \
  --project=PROJECT_ID \
  --location=global \
  --workload-identity-pool=my-app-dev-pool \
  --attribute-condition="assertion.repository_owner == 'GITHUB_REPO_OWNER'"

In this example, the restriction added by this attribute condition is redundant, since the IAM policy binding is already limited to a particular repo owner. However, if for whatever reason the IAM policy ever changes to be more broad, this will still restrict access to the specified GitHub repo owner.

Let’s test drive

Before we can test this out, you’ll need a repository with a valid Dockerfile.

Here’s the final yaml file for our workflow:

name: Push to Artifact Registry

on:
    push:
      branches: [ "main" ]

env:
  IMAGE_NAME: 'my-app-image'
  PROJECT_ID: 'my-project-id'
  AR_REPO_LOCATION: 'us-central1'
  AR_URL: 'us-central1-docker.pkg.dev/my-project-id/my-ar-repo'
  SERVICE_ACCOUNT: 'github-actions-service-account@my-project-id.iam.gserviceaccount.com' 
  WORKLOAD_IDENTITY_PROVIDER: 'projects/123456789/locations/global/workloadIdentityPools/my-app-dev-pool/providers/github-actions-provider'

jobs:
  push_to_ar:
    permissions:
      contents: 'read'
      id-token: 'write'

    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Google Auth
        id: auth
        uses: 'google-github-actions/auth@v2'
        with:
          token_format: 'access_token'
          project_id: ${{ env.PROJECT_ID }}
          service_account: ${{ env.SERVICE_ACCOUNT }}
          workload_identity_provider: ${{ env.WORKLOAD_IDENTITY_PROVIDER }}

      - name: Docker Auth
        id: docker-auth
        uses: 'docker/login-action@v1'
        with:
          username: 'oauth2accesstoken'
          password: '${{ steps.auth.outputs.access_token }}'
          registry: '${{ env.AR_REPO_LOCATION }}-docker.pkg.dev'

      - name: Build and Push Container
        run: |-
          docker build -t "${{ env.AR_URL }}/${{ env.IMAGE_NAME }}:${{ github.sha }}" ./
          docker push "${{ env.AR_URL }}/${{ env.IMAGE_NAME }}:${{ github.sha }}"

We’ll place this configuration in our GitHub repository in .github/workflows/push-to-ar.yml. As soon as you merge this file into your main branch, it’ll kick off the workflow and if all permissions and resources are in place, you’ll have a build of your application sitting in your Artifact Registry. Verify by visiting the Artifact Registry page in the Google Cloud Console.

What next?

Arguably, the star of the show is the Google Auth GitHub Action - that’s what’s using the Workload Identity Provider and service account to access your Google Cloud project. If you plan on doing other things with this authentication, just be sure to use a service account that has the right access those things. For example, if you’re using the Secret Manager GitHub Action to access secrets from Secret Manager, make sure the service account has the Secret Manager Secret Accessor IAM role on the project or secret. To take a look at all of the available actions, check out the repos available in the Google GitHub Actions GitHub organization.

How basic are we talking here?

We’re going to use Cloud Build to run Terraform for us in our Google Cloud Project. And when I say a very basic example, I mean a very basic example. This won’t be anything you’ll use in production, but this will be the start of a series of posts that build towards a more intricate solution, discussing some important concepts and considerations along the way.

My friend Terraform and my buddy Cloud Build

Those already familiar with Terraform already know the 3 magic commands we use to deploy resources to Google Cloud, or any other cloud provider out there: terraform init to initialize, followed by terraform plan to preview, and terraform apply to deploy. Manually running these commands is useful for learning Terraform or managing your own personal infrastructure in the Cloud, but in practice you’re going to need to learn how to automate Terraform. Let some robots do it for you. There plenty of ways to do that. Using Cloud Build is just one.

Cloud Build is Google Cloud’s serverless CI/CD platform. You give it a yaml configuration with some instructions and it can build, test and deploy your software. I won’t get into any more details than that — the documentation does a much better job than I can.

Where to begin?

First you’ll need a directory to work out of (a root Terraform module) with 2 files in it (for now): cloudbuild.yaml and main.tf. You can go and create these yourself, or just clone this branch in this repository that has the files already pre-written for you.

You’ll also need a Google Cloud Project with the Cloud Build API enabled. When you enable the Cloud Build API, your project will generate a default Cloud Build service account that looks like this:

98476438052@cloudbuild.gserviceaccount.com

This service account automatically has the Cloud Build Service Account IAM role assigned to it, allowing it to do all the Cloud Build things it needs to be able to do, like manage Google Cloud Storage buckets and access Artifact Registry. You can see a full list of permissions right here.

Tell Terraform what to do

Terraform gets its instructions from .tf files. For the sake of simplicity, let’s use this main.tf file I copied and pasted from one of Hashicorp’s documentation pages:

# main.tf 

resource "random_string" "random" {
  length           = 16
  special          = true
  override_special = "/@£$"
}

output "random_string" {
    value = random_string.random.id
}

There’s nothing fancy to see here. It just creates a random string resource and spits its value out as output.

Tell Cloud Build what to do

Cloud Build accepts yaml configuration files. Here is a simple one that will execute those 3 magic Terraform commands:

# cloudbuild.yaml

steps:
  - id: 'terraform init'
    name: 'hashicorp/terraform:1.0.0'
    script: terraform init
  - id: 'terraform plan'
    name: 'hashicorp/terraform:1.0.0'
    script: terraform plan
  - id: 'terraform apply'
    name: 'hashicorp/terraform:1.0.0'
    script: terraform apply --auto-approve

The id field is the name that will show up in the logs, and the name field is the public image that it will build and use to execute the provided command.

You can kick off a Cloud Build job by running gcloud builds submit . in your working directory. It will automatically look for a cloudbuild.yaml file and create a Cloud Build job that will execute the provided instructions. You can see the progress as output in your terminal or head over the Cloud Build History page where you’ll see your job’s status and output:

And there you have it! Cloud Build executing Terraform! That’s all there is to it!

Wait a second, there must be more to it

Okay, actually there’s a lot more to it. While we did indeed run Terraform with Cloud Build we didn’t actually deploy any infrastructure (or anything useful for that matter). There are some things that we need to consider.

Permissions

Cloud Build creates a default service account with those default Cloud Build service account permissions assigned to it. Any additional permissions that this service accounts needs will depend on the cloud resources that you want your Terraform to create. If you’re managing resources across lots of different Google Cloud services, then the Cloud Build service account will inevitably accumulate excessive permissions, resulting in a potential security risk. Yuck.

Terraform state file

You’ll notice that the Terraform state file is no where to be found. The state file that would have been generated to your local disk had you ran terraform apply locally only existed temporarily in the container that Cloud Build ran the command from. If this Terraform had created a cloud resource, you would have no way to update its parameters using a second terraform apply or destroy it using terraform destroy. Ugh.

That — auto-approve flag

If this were an automated pipeline, we probably wouldn’t be running running apply automatically after plan. Without approvals, reviews, or staging environments in place, we can’t really make sure our infrastructure doesn’t fall apart after each terraform job. Yikes.

Key takeaways

• Enabling the Cloud Build API will create a default Cloud Build service account in your project. Cloud Build jobs run using this service account by default.
• Cloud Build’s instructions are provided as steps listed in a yaml file, each one with it’s own output that show up in the build logs. If the Terraform creates any cloud resources, the service account will need the appropriate permissions to manage those resources.
• Without any remote state configured, the state file will only exist temporarily and then get lost in the abyss.

Well, what next?

While limited in its utility, this example can serve as a starting point for your own exploration around the considerations I mentioned above. Service account impersonation will definitely play a role in ironing out the permissions (here’s a blog about Terraform and service account impersonation I published here), while Terraform’s support for remote state files on Google Cloud Storage will give us the persistent state that we need to keep our infrastructure updated safely. As for the lack of approvals and reviews, there are unlimited ways to design your pipeline to accommodate such requirements with features like gating builds on approvals. I won’t leave you high and dry though. I will post a follow up soon with another bite of our elephant for us to explore.

Terraform using Google Cloud Build: a very basic example was originally published in DevOps.dev on Medium, where people are continuing the conversation by highlighting and responding to this story.

Service Accounts Deserve a Purpose

When you’re working out of a development project, it can be tempting to use a generic all-powerful dev service account with unfettered access to everything via the Editor role. Even some of the default service accounts are created with that access. But you’ve heard of the principle of least privilege right? It’s the thing system administrators have been yelling about for decades whenever someone asks for root access. It means that you should only have access to the minimum permissions you need to do your job. This goes for services accounts too.

Before you even assign roles and permissions, think through what you’re going to use that service account for and make it as specific as possible. Then make that purpose clear to you and anyone else who might manage it later on by adding a clear display name and description. This is a great way to quickly and informally document what a service account is meant to do. You’ll know if a display name and description are good enough if they an answer a few questions by just looking at them:

• What roles could this account probably have assigned?
• What services or APIs could this account probably accessing?
• What applications/users/systems could be using this account?
• What would probably break if I disable this account?

When it comes to assigning roles and permissions, if the service account is coming from a dummy dev project, then it’s not such a big deal if you misconfigure some permissions here and there. But what better place to figure it out than in development? Finding the right IAM roles and permissions for your service accounts can be pretty straightforward, but it can be tricky if your needs don’t fit perfectly into any of the predefined roles. You need to identify what your service account needs — and in some cases what it will not need — to assign the appropriate roles. So as easy as it is, resist the temptation to assign Editor to your service accounts. It’s worth the extra effort to narrow things down early on and give your service account a clear purpose.

Something to try:

If you’ve got some mysterious looking service accounts in your project, update the description and the display name in one shot:

gcloud iam service-accounts update SERVICE_ACCOUNT — display-name “A DECENT DISPLAY NAME” — description “A DESCRIPTIVE DESCRIPTION”

The display name should be short, sweet and to the point. The description has a character limit of 256 so feel free to go nuts.

Service Accounts are Resources Too

As it turns out, a service account is more than just an IAM account. They’re resources too. The same way you might want to limit which people have access to a server or a database, you want to make sure you do that for your service accounts, too.

An easy mistake to make when you want to give someone access to any service account is to grant the permissions on the project IAM policy. For example, by granting the Service Account Token Creator role to a user on a project policy, you are giving them the power to impersonate all service accounts on the project, and by extension, access all resources accessed by those service accounts. That’s a bit much.

Luckily, since service accounts are resources, each one has an IAM policy of its own attached to it. There you can grant service account IAM roles that are binded to users for that specific account instead of project wide. For example, if you add joe@yourorg.com as the Service Account Token Creator on dev-sql-service@yourproject.iam.gserviceaccount.com, then Joe will have that role’s privileges over that service account only. This way, Joe won’t be able to accidentally mess with any of the other important stuff that you don’t want Joe to access. Sorry Joe.

Something to try:

Check the IAM policy for a service account with this gcloud command:

gcloud iam service-accounts get-iam-policy SERVICE_ACCOUNT

By default these are blank. Add a user to the policy like this:

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT --member MEMBER — role=ROLE

The MEMBER will be the user account’s email address and the ROLE will be IAM role you want to grant that user (in the roles/ format). Here’s a list of the service account roles that currently exist.

You don’t always need private keys

When you’re accessing Google Cloud from your local machine, how do you access the service accounts you need? If your answer involves generating a json key every time you need one then you deserve to know that there’s an easier and more secure way.

Instead of using keys, with the right permissions, you can use short-lived credentials. It’s a way of doing basically the same thing with a little less hassle. The Service Account Token Creator role allows a user to generate short-lived credentials on a service account. If you’re accessing Cloud via REST API then you can generate access tokens for that service account. If you’re mostly just running gcloud commands, then you can stick the --impersonate-service-account flag instead of using a key file.

Something to try:

First, you’ll need to grant the Service Account Token Creator role to the user for the service account they want to use. You can do that with the command I mentioned above:

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT --member MEMBER --role=roles/iam.serviceAccountTokenCreator

With that in place, the user can run gcloud commands as a service account by tacking on the — impersonate-service-account flag along with the service account email address. The same functionality is extended to gsutil if you’re working with GCS buckets, except they’ll use the -i flag instead, followed by the service account. Easy.

If you want to access the Google Cloud REST API as a service account using an access token, first get an access token for your own account and stick it in an environment variable:

export MYTOKEN=$(gcloud auth print-access-token)

Next, you’ll have to include a request in the form of a json object. Throw that into a file that looks like this:

{
"delegates": [
],
"scope": [
"https://www.googleapis.com/auth/cloud-platform",
],
"lifetime": "3600s"
}

For this example, I named that file request.json. This is a pretty barebones version of a request. The “delegates” here are used if you’ve got a conga line (delegation chain) of service accounts that are used to access one another. If that’s not the case, don’t worry about it, you can leave this blank.

As for the scope, this refers to the Oauth 2.0 scope that you’ll need to access certain API’s. What you include here will depend on what you want to do with the service account you’re requesting a token for. A full list of APIs and their corresponding scopes is documented here.

And finally, the lifetime is simply how long you want the token to be good for, in seconds.

Once you’ve got all that, you can request a token with this curl command that will send a POST request to the Google Cloud API:

curl -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com:generateAccessToken -H “Authorization: Bearer $MYTOKEN” -H “Content-Type: application/json; charset=utf-8” -d @request.json

The output here will be the access token for the service account that you can subsequently use to hit up the API as that service account. Tah dah.

More Things About Service Accounts

That’s just 3 things about service accounts but there’s a lot more information on best practices when it comes to making them, managing them, and using them. Here’s a link to the official documentation if you’re into that sort of thing. If you want to learn more about short-lived service account credentials, you can find that right here. If you’re tired of reading, check out a video series on the Google Cloud Tech Youtube channel here.

“You become what you give your attention to…If you yourself don’t choose what thoughts and images you expose yourself to, someone else will.”

— Epictetus, O.G. Greek Philosopher

You’re familiar with this pattern: You’ve got something you need to work on, an important assignment for work or school. You sit down and decide to get started.

You’re ready.

You’re in the zone.

It’s time to focus.

Ten seconds in: BZZZZZZ! Without giving it a second thought, reflexively, you pick up your phone and see what the fuss is about. A half hour later you put your phone down and don’t even remember why you picked it up in the first place, but for some reason unexplained reason you now know that the guy you went to high school with had sushi for dinner last night.

Okay, now it’s time to focus.

For reals this time.

A few minutes later: BZZZZZ! Rinse and repeat. On a bad day, I’d go through this series of events in an endless loop, resulting in an embarrassingly minuscule amount of actual productivity. For the longest time I chalked it up to a self-diagnosed case of ADHD and I got by the best I could. It wasn’t until I read Atomic Habits by James Clear that I considered that this was actually a series of habits wired in my brain that I’d be able to reprogram with a little self awareness and a bit of effort. I do still have those bad days, but I’ll share 3 strategies that have helped those bad days be less bad.

“BZZZZZZ!” — algorithms, trying to control your behavior

First, a Quick Recap on Habits

One of the main takeaways from Atomic Habits is that habits, good or bad, are essentially neurological feedback loops. For any given habit, a cue triggers a craving that motivates a response to get a reward. For example, in the case of social media: a notification on my phone (cue) reminds me of whatever warm fuzzy feeling I get from a like or retweet (craving) and causes me to open an app (response) so that i can feel that warm fuzzy feeling (reward).

Our days are chock-full of these feedback loops and we don’t even realize it. Take the classic fridge example. Have you ever walked to the kitchen and opened up the fridge 100 times a day even though you already know what’s in there? Yep, that’s an automated feedback loop where the cue is your location in the kitchen, the craving is something yummy to put in your tummy, the action is opening up the fridge and the reward is supposed to be food, which may or may not be there.

So knowing this, let’s see if we can exploit this loop so that maybe you don’t pick up your phone in the first place.

Curb the Cue: Nix Your Notifications

John Oliver had a delightful segment about push notifications and he nails it. What started out as a really nifty feature has devolved into a way for thirsty corporations desperate for clicks to trick you into unlocking your phone and interacting with their product to sell you things you probably don’t need. It’s time to stand up to those apps and say “no, not today.”

Most apps have notification options, or you can simply block them on the operating system level on both Android and iOS. Once you get rid of the notifications, the buzz buzz that triggers you to check your phone is gone gone. We’ve eliminated the cue!

At this point you’re probably thinking to yourself, well duh. I know this isn’t a groundbreaking strategy. Well hold on. Sometimes this isn’t enough. I realized that after nuking my notifications, I was still mindlessly scrolling, swiping and tapping. And that’s because sometimes the cue isn’t as obvious as a notification. When I was already on my phone, just the mere presence of the app’s aesthetically pleasing icon on my home screen was a cue, reminding me to tap that app. So, what can we do about that?

Rein in Your Response: Anchor Your Apps

I’ve been off of Facebook for about 2 years now, but I’m not here to tell you to #DeleteFacebook (you totally should though) or any other social media service for that matter. There’s a nice middle ground to keep your digital addictions in check, and it targets your response to the craving.

Way back before we could fit it in our back pockets, the internet was anchored to a chunky box sitting in our homes. As a teenager, I had a home PC. If I wanted to check my MySpace and update my top 8 (younger readers can look this up) I couldn’t do that in the middle of the day while waiting in line at the grocery store as soon as the thought popped in my head. Nope, I had to wait until I got home to my beloved chunky box. And even then, before broadband was available in my neighborhood, I had to wait ages for my mom to get off the phone. Those days it was a little harder for social media to become a bad habit in the first place. In hindsight, it was nice.

We can recreate this mindset with a bit of effort. I won’t suggest that you uninstall every single smartphone app from your phone, that’s crazy talk. But how about this: choose 1 or 2 apps that frequently take your attention hostage and remove them from your phone. Once you’ve done that, create a new habit of only accessing those apps or websites from a device that you don’t carry around all day, like a tablet, laptop, or PC. Truthfully, some of them are better in a browser anyway. This works great for news apps, especially if you’re trying to detox from the American news cycle. It also works great for Twitter if you’re okay with not live tweeting your day to day. By doing this, now you’re really telling those apps who’s in charge of your attention. Fun fact: Chrissy Teigen tweets from a computer, so maybe she’s got the right idea.

Establish a No Phone Zone

Remember the example I mentioned about the fridge in the kitchen? Well if you wanted to break that habit of mindlessly opening the refrigerator over and over again, one way of doing it is by straight up removing it from the kitchen. Boom, problem solved. That strategy isn’t very practical for refrigerators but works great for phones.

I used to charge my phone overnight right next to my bed. On some mornings after snoozing and then dismissing my alarm, I’d just lay there mindlessly scrolling through feeds and half-assedly reading the breaking news of the day (it’s never good). The fact that this would happen first thing in the morning meant that my mood at the start of my day was at the mercy of whatever content some algorithm decides I should care about.

Nowadays, I place my phone on the other side of the room and as soon as I wake up, I dismiss the alarm and start my day. I don’t even check my messages or apps for another few hours on a typical day. This empowered me to keep my mind clear and have a morning routine that isn’t dictated by apps. Even before bed or during the day, I’m committed to never using my phone near my bed. If you’re in a relationship, bonus points if you can convince your significant other to do the same (good luck).

Of course your no phone zones can be wherever you’d like: the desk where you do your work, the table where you eat your meals, the bathroom where you.. well you get the point. It doesn’t matter where your zones are, what matters is that you have them so that you can interrupt the attention-stealing habit loop and give you a moment to yourself to be present in the real world.

Revisit and Revise

So these are just three strategies you can try out to keep your digital diet in check. They’re not perfect and there are tons more. Some days you’ll look back and shake your head at the 2 hours you spent on Reddit between the 3 hours you scrolled on Facebook. Then maybe you’ll tweet about it. That’s fine.

If nothing else, the one thing you should definitely try to do on occasion is revisit the habit feedback loop and see where you can tighten up and take control. It’ll at least remind you to be mindful of the time you spend with your face inside a screen, and hopefully free yourself from its spell.

Okay, back to work!

It sounds frightening, but it doesn’t have to be. I’ll share a few important tips (small pieces of advice) and tricks (helpful hints)** for organizing your resources on Google Cloud. My hope is that what I’ll share will help you get started quicker, and with a better understanding of what you’re running in the cloud. Let’s make things a lot more simple and a lot less yikes.

Resource Hierarchy

I’ve heard that there’s more than one way to skin a cat. While I don’t know what that means, I do know that there’s more than one way to organize your Google Cloud resources. That’s the resource hierarchy.

The hierarchy can map to your organization’s structure, and allows you to manage access and permissions to all of your cloud resources. Here’s an example of a resource hierarchy, straight from Google Cloud’s official Resource Hierarchy documentation:

Your resource hierarchy could be as simple as a single project under an organization, but if you’ve got bigger plans, there are additional methods for organizing things so that you’ll get a better understanding of which teams are using which resources and are responsible for which costs.

Tip: Do some planning

Understanding the resource hierarchy will enable you to organize your resources in the way that best suits your organization. Do some diagramming similar to the one above to get an idea of what your resource hierarchy might look like. If your organization is grouped by departments, maybe it makes sense for those to map to folders. Take into account the primary attach points for access management — organization level, folder level, and project level — and remember that permissions are inherited from top to bottom.

Trick: Start Simple

The resource hierarchy is flexible. You can always move projects, folders, and change permissions after the initial setup, so don’t feel overwhelmed by your planning. Get familiar with organizing resources while diagramming so you can make smaller and quicker changes.

The Domain and Organization

Here’s the tippy-top of the resource hierarchy. When you sign up for Cloud Identity or G Suite, you’ll be asked to provide a domain. When that’s verified an organization is created. It is essentially the umbrella of all things created in Google Cloud. All projects created will belong to the organization rather than the user who created them. This is especially important in cases where a project owner leaves the organization. Permissions set at the organization level are inherited to folders and projects below.

Tip: One organization is all you need

You might have the need to manage multiple organizations. However, your G Suite or Cloud Identity account is limited to one single organization and one single domain. Consider organizing your sub-organizations as folders instead.

If that truly doesn’t work for your needs, you can manage multiple G Suite or Cloud Identity accounts and therefore multiple organizations. The downside here is that they will be isolated from each other, require separate domains, and lack centralized access and administration. There’s more information on the effects of using multiple organization nodes here.

Trick: Start with IAM

If you’re just getting started and have your organization set up, the initial account you start with will have limited permissions. In fact, you’ll only have the role Organization Admin. An organization admin will be able to access all projects that belong to the organization and assign IAM roles to other users. Before exploring folder and project creation beneath your organization, take a moment to check the Identity & Organization page. From here you’ll be able to migrate projects, create a billing account, expand permissions for yourself or other users, and even delegate the organization admin permissions to others.

Billing accounts and payments profile

A billing account is a cloud-level resource that’s used to manage billing-related functions. This is where you’ll define the payment methods you’ll use to pay for your Cloud usage, access reports and forecasts for your costs, generate a budgets to avoid surprises, and pretty much anything else having to do with bills.

While a billing account is managed in Cloud Console, the payments profile is a Google-level resource that connects to all of your Google services like Cloud, Ads or Chrome licenses. I’m mentioning it here because a billing account is required to be linked to an existing payments profile or one will be created. If you don’t already pay for other Google services you may not need to worry about connecting to an existing payments profile.

Tip: Use a single billing account

You are allowed to configure multiple billing accounts per organization, but I recommend sticking to a single billing account instead. Associating all of your organization’s projects to one billing account will give you a more complete and centralized view of your costs and will make them easier to track.

Trick: Understand billing account users, viewers, and admins

There are 3 types of billing account roles you can delegate: billing account users, billing account viewers, and billing account administrators. While admins can unlink projects, set budgets and initiate billing exports, billing account users can only associate projects and see spend. Billing account admins are also the only ones who can contact billing support. Billing account viewers have the same permissions as users, but with a bit more visibility. Pay special attention to the differences among users, viewers and admins and delegate each role to groups or people accordingly. As a reference, here are the permissions of each role side by side:

Resources

The bread and butter. The meat and potatoes. Resources are any Google Cloud service, like BigQuery, Compute Engine, Cloud Storage, etc. Resources are organized into projects.

Tip: Think about your folders

Projects can be organized into folders. Much like a basic filesystem, a project will inherit the permissions and access from the folders to which it belongs, as well as the organization above that. If you’re planning on having multiple projects on Google Cloud, or if you’ve got multiple teams that will be deploying to Google Cloud under your organization, definitely consider using folders. Like I mentioned earlier, folders are an additional attach point for access management and will make it easier to delegate roles and permissions. It’ll also give you another way to break down billing charges at the end of the month by allowing you to analyze costs by folder rather than individual projects if you export to Big Query.

Trick: Use labels for extra granularity

Labels provide a way to horizontally organize your projects’ resources and help you gain a more granular view of costs. For example, let’s say you’ve got a project with VMs and Kubernetes clusters corresponding with either a staging or production environment. By applying a label with a key ‘environment’ and a value of either ‘staging’ or ‘production’, you can see what spending is per environment instead of just resource type. The more granularity you have, the better you’ll be able to understand your costs and keep them under control. You can read more about labels here.

More Resources to Get Started

To help you get started on Cloud, Google offers a free trial with a $300 credit. Their pricing landing page is right here. To learn more about billing check out the Beyond Your Bill series on Youtube by Mark Mirchandani that goes over most of the content above and much more.

Good luck!

** No, there is no distinguishable difference between a tip and a trick.

Google Cloud Tips and Tricks: Understanding the Resource Hierarchy was originally published in Google Cloud - Community on Medium, where people are continuing the conversation by highlighting and responding to this story.