Burla
GitHubDiscordBook a Demo
  • Welcome
  • Overview
  • API-Reference
  • CLI-Reference
  • Installation: Self-Hosted
  • Installation: Fully-Managed
  • Examples
  • About
  • Brick
Powered by GitBook
On this page
  • CLI-Reference
  • burla install
  • burla login
  • burla dashboard
PreviousAPI-ReferenceNextInstallation: Self-Hosted

Last updated 6 days ago

CLI-Reference

Burla's CLI contains the following commands:

  • Install a self-hosted Burla instance in your Google Cloud project.

  • Authenticate your machine.

  • Open / login to the Burla dashboard in your default browser.

The global arg --help can be placed after any command or command group to see CLI documentation.


burla install

Install a self-hosted Burla instance in your Google Cloud project. Running burla install multiple times will update the existing installation with the latest version.

Description

Installs Burla inside the Google Cloud project that your is currently pointing to. For a more user-friendly installation guide see:

To view your current gcloud project run: gcloud config get project To change your current gcloud project run: gcloud config set project <desired-project-id>

Prerequisites:

  • Have the installed ().

  • Be logged in to the () (gcloud auth login & gcloud auth application-default login)

  • Have a Google Cloud user account with at least the minimum required permissions to install Burla. Or: Just run burla install, if you're missing any permissions it will tell you which ones!

Here are three sets of permissions, each of which would authorize somebody to run burla install:

Exact minimum required permissions
  1. Service Usage API (serviceusage.googleapis.com):

    • serviceusage.services.enable for enabling:

      • compute.googleapis.com

      • run.googleapis.com

      • firestore.googleapis.com

      • cloudresourcemanager.googleapis.com

      • secretmanager.googleapis.com

  2. Compute Engine API (compute.googleapis.com):

    • compute.firewalls.create

    • compute.firewalls.get (to check if firewall rule exists)

    • compute.networks.updatePolicy

  3. Secret Manager API (secretmanager.googleapis.com):

    • secretmanager.secrets.create

    • secretmanager.secrets.get

    • secretmanager.versions.add

  4. Firestore API (firestore.googleapis.com):

    • datastore.databases.create

    • datastore.databases.get

    • datastore.documents.create

    • datastore.documents.write

  5. Cloud Run API (run.googleapis.com):

    • run.services.create

    • run.services.update

    • run.services.get

    • run.services.setIamPolicy (for --allow-unauthenticated flag)

Here is an IAM role definition for this permission set:

title: "Burla Installation Role"
description: "Minimum permissions needed to install Burla"
stage: "GA"
includedPermissions:
- serviceusage.services.enable
- compute.firewalls.create
- compute.firewalls.get
- compute.networks.updatePolicy
- secretmanager.secrets.create
- secretmanager.secrets.get
- secretmanager.versions.add
- datastore.databases.create
- datastore.databases.get
- datastore.documents.create
- datastore.documents.write
- run.services.create
- run.services.update
- run.services.get
- run.services.setIamPolicy
Generic role based permissions (less complicated)

Burla can be installed by users having the following generic roles:

  1. Service Usage Admin (roles/serviceusage.serviceUsageAdmin)

  2. Cloud Run Admin (roles/run.admin)

  3. Compute Network Admin (roles/compute.networkAdmin)

  4. Secret Manager Admin (roles/secretmanager.admin)

  5. Firestore Database Admin (roles/datastore.owner)

Simplest possible permissions

Burla can be installed with either of the following roles:

  • Project Owner (roles/owner)

  • Project Editor (roles/editor)

Here is exactly what happens when burla install is run:

On install, your Google account (the one you are currently logged in to gcloud with) is set as the only account authorized to access this new Burla deployment.

To access the deployment you will need prove your identity by signing in to this same Google account through a Google sign-in page. Burla follows the standard Google OAuth 2.0 authorization flow.

Exact installation operations
  1. Required services are enabled (if they are not already enabled):

    • gcloud services enable is called on:

      • compute.googleapis.com

      • run.googleapis.com

      • firestore.googleapis.com

      • cloudresourcemanager.googleapis.com

      • secretmanager.googleapis.com

  2. Port 8080 is opened on any GCE VM having the tag burla-cluster-node:

    • gcloud compute firewall-rules create burla-cluster-node-firewall \ --action=ALLOW --rules=tcp:8080 --target-tags=burla-cluster-node ...

  3. A secret is created that's used to encrypt auth cookies in the dashboard:

    • gcloud secrets describe burla-cluster-id-token

    • gcloud secrets create burla-cluster-id-token ...

  4. A Google Cloud Firestore database is created: (manages information displayed in the dashboard)

    • gcloud firestore databases create --database=burla ...

  5. Your Google account (that you are currently logged in to gcloud with) is set as the only account authorized to access this new Burla deployment.

    • This account is discovered using the following command: gcloud auth list --filter=status:ACTIVE --format="value(account)"

    • Once set, this cannot be changed by other users running burla install again.

  6. The main-service (dashboard) is deployed on Google Cloud Run:

    • gcloud run deploy burla-main-service \ --image=burlacloud/main-service:latest ...

    • gcloud run services update-traffic burla-main-service --to-latest ...

  7. Thats it!

After Installing:

burla install prints the following:

Success! To view your new dashboard run `burla dashboard`
Quickstart:
  1. Start your cluster by hitting "⏻ Start" in the dashboard.
  2. Import and call `remote_parallel_map`!

burla login

Authenticates the current machine through a Google OAuth consent screen. Allows you to call remote_parallel_map on Burla deployments where you're authorized to do so.

Description

This is used to ensure that only people you have explicitly authorized have access to your Burla instance.

This token is refreshed each time the burla login or burla dashboard authorization flow is completed.

burla dashboard

Launch and login to the Burla dashboard associated with your current Google Cloud project. Allows you to call remote_parallel_map and access the Burla dashboard in Burla deployments where you're authorized to do so.

Description

The current project's Burla dashboard URL is discovered using the following command: gcloud run services describe burla-main-service ...

When redirecting to this dashboard the client attaches an authentication cookie identifying the user to the dashboard. Only explicitly authorized users are allowed to view a Burla dashboard.


We encourage you to check out in the client for even more specific installation details.

Launches the "sign in with google" page in your default web browser. This gives our backend access to only your email and name according to your google account. See our to learn how we protect this information.

Once signed-in successfully, an auth-token is saved in the text file burla_credentials.json. This file is stored in your operating system's recommended user data directory which is determined using the python library.

Runs the same OAuth authorization flow used in the burla login command, but redirects the user to their current project's Burla dashboard, instead of the page.

Like the burla login command, this command also updates local authorization credentials stored in burla_credentials.json, see the documentation for more info on these credentials.

Questions? , or email jake@burla.dev. We're always happy to talk.

_install.py
privacy-policy
appdirs
login success
Schedule a call with us
gcloud CLI
Installation: Self-Hosted
gcloud CLI
how do I install the gcloud CLI?
gcloud CLI
how do I log in?
burla install
burla login
burla dashboard
login command