run

A lightweight utility for Node.js developers that simplifies creating, deploying, and monitoring serverless Cloud Run apps on Google Cloud.

This is not an official Google project.

run is not a replacement for everything that you can do with the gcloud CLI. In fact, the current version requires that you also install gcloud because it wraps some of gcloud's functionality.

However, run provides a simple and streamlined experience using just a few commands and a configuration file (which it generates).

To create and deploy an application, you run the following commands:

run login
run new
run deploy

You will be prompted for options that will be saved to a configuration file and used for deploying subsequent app revisions.

To contrast this against the equivalent gcloud experience, see this blog post: Getting started with the Google Cloud CLI interactive shell for serverless JavaScript developers

Prerequisites

• Node.js 18+
• Google Cloud account (see steps #1 and #2 here)
• gcloud

For gcloud, you only need to install it. You can ignore all other instructions. Once installed, run the following command:

gcloud components install beta

Usage

You can use run from the command line by using npx or by installing it globally with npm.

npx @subfuzion/run

Or

npm i -g @subfuzion/run

If using npx, you might want to create a shell alias:

alias run="npx @subfuzion/run@latest"

Login / logout

run login
run logout

The current version of run wraps auth functionality from gcloud and implements other functionality using the Node.js Cloud Client Library. When you execute run login, you will be prompted for authorization in the browser twice: the first time for running wrapped interactive gcloud CLI commands and the second time for obtaining credentials for use with the client library.

Create a new app

run create

You will be prompted for a name and project template to use.

Deploy an app

run deploy

On first deployment, you will be prompted for a service name to use to identify the deployed app, a globally unique name to identify the Google Cloud project, and a region to deploy the service to.

These settings are saved to a configuration file (run.yaml) in the working directory.

Install run as a package dependency

After setting up your configuration and testing it, you should install run as a package devDependency to your package.json file with the following command:

npm install --save-dev @subfuzion/run

Then you can add package.json run scripts.

  "scripts": {
    "deploy": "run deploy",
  },

run configuration

run uses two configuration files:

• General user configuration stored in $HOME/.config/run/run.yaml
• Specific app configuration stored in ./run.yaml

General user configuration

General user configuration consists of a single field:

$HOME/.config/run/run.yaml

# Billing ID (https://console.cloud.google.com/billing)
billingId = '';

Specific app configuration

Specific app configuration consists of the following fields:

./run.yaml

# Google APIs to enable (defaults include APIs to build/deploy Cloud Run app)
googleapis = [
'artifactregistry',
'cloudbuild',
'run',
];

# The Project ID (not necessarily the same as the project name)
project = '';

# Cloud Run region (https://cloud.google.com/run/docs/locations)
region = '';

# The hosted service name to use with Cloud Run
service = '';

Multiple app projects might share the same cloud project ID and region, but the service name must be unique within the cloud project.

The project ID must be globally unique across all of Google Cloud. Read more here.

Contributing changes.

Entirely new samples and bug fixes are welcome, either as pull requests or as GitHub issues.

See CONTRIBUTING.md for details on how to contribute.

Licensing

Code in this repository is licensed under the Apache 2.0. See LICENSE.