Developing a Cloud Run service locally

Before you deploy a service to Cloud Run, you can develop it locally using a Cloud Run emulator.

Configuring your service for development

If you don't have a .vscode/launch.json file defined, the Run/Debug on Cloud Run Emulator dialog lets you configure your launch and then saves your settings to .vscode/launch.json. If you have a .vscode/launch.json file configured, you can edit the file directly.

To run your service locally, specify your configuration:

  1. Open the Command Palette (press Ctrl/Cmd+Shift+P) and then run the Run on Cloud Run Emulator command.
  2. In the Run/Debug on Cloud Run Emulator dialog, set the specifications for your configuration:

    • Only locally-installed build tools are available for Cloud Run Emulator
    • Choose Docker or Buildpacks as your builder and then specify the source
    • (Optional) To specify any environment variables to pass to the running containers, expand Advanced Build Settings and then click to specify key-value pairs.
      Name Description Example
      PORT The port for the HTTP server to listen on. 8080
      K_SERVICE The name of the Cloud Run service being run. hello-world
      K_REVISION The name of the Cloud Run revision being run. hello-world.1
      K_CONFIGURATION The name of the Cloud Run configuration that created the revision. hello-world
    • (Optional) To specify Cloud SQL connections, expand Advanced Service Settings, click Connections, and then specify one Cloud SQL connection per line.
    • (Optional) Check the Make the service accessible from other devices on the local network option.
    • (Optional) If you only want to rebuild and run your service manually, instead of automatically when you make a change, uncheck the Automatically re-build and re-run on changes option.

Running your service locally

  1. After you define your preferred settings, run your service by clicking Run.
  2. Monitor the status of your deployment in the output window.

    After deployment is complete, you can view your running service by opening the URL displayed in the output window.

  3. To view verbose logs, switch to the detailed Cloud Run view in the output window.

    Output pane with "hello-world-5 - Detailed" selected from output channel dropdown

  4. After your session completes, you can use the following contextual menu commands:

    • Open Deployment Logs: Open the application logs of a specific deployment with the Cloud Code Logs Explorer
    • Open Service URL: Open the application service URL of a specific service in a web browser
  5. If you've turned off watch mode in your launch configuration and you want to make changes to your application and rebuild and redeploy the application, in the Development sessions pane, pause on the run action and then click Rebuild and redeploy icon Rebuild and redeploy the application.

  6. To stop your deployment, you can click the Stop button in the action bar for your current deployment.

    Action bar for Cloud Run deployment

Storing secrets

If your code includes potentially sensitive data like API keys, passwords, and certificates, storing them as secrets can help secure them. The Cloud Code Secret Manager integration lets you securely store these secrets and fetch them programmatically. For a detailed look at how you can create and manage secrets with Cloud Code, see the Secret Manager guide.

Customizing an existing launch.json configuration

The Cloud Code plugin updates the launch.json configuration file automatically when you choose a run action. To further customize how your service is run, you can specify the following fields in your .vscode/launch.json file:

  • watch: Watches for changes in the workspace and reruns the service. True by default.

    The following sample shows watch set to true:

    "watch": true,
    
  • build: Specify the builder (Docker, jibMaven, jibGradle, or buildpacks) to build your images with.

    The following sample shows a Docker builder:

    "build": {
      "docker": {
        "path": "Dockerfile"
      }
    },
    

    The following sample shows a buildpack builder:

    "build": {
      "buildpacks": {
        "path": "src/requirements.txt",
        "builder": "gcr.io/buildpacks/builder:v1"
      }
    },
    
  • image: Specify the name of the image to use.

    The following sample shows how to specify an image name:

      "image": "hello-world",
    
  • service: Specify the Cloud Run service to use.

    The following sample shows how to specify a service name, port, and resource limits:

    "service": {
      "name": "hello-world",
      "containerPort": 8080,
      "resources": {
        "limits": {
          "memory": "256Mi"
        }
      }
    },
    
  • debug: Specify debug settings such as remote path mapping to map a local path to a path on the remote container.

    The following sample shows a debug section that indicates the source files' location:

    "debug": {
      "sourceFileMap": {
        "${workspaceFolder}": "/app"
      }
    }