Developer Center

Workspace basics

Learn about a PowerTools workspace in just a few minutes.

A workspace is where a team ships applications using PowerTools. Each workspace is linked to a code repository with one or more services.

A workspace has at least one environment, an AWS or GCP cloud account + resources it can ship code too. Most teams will want to have more than one environment, such as test and prod.

A workspace has at least one group, which let you split services between teams, workloads or however your team would like.

How a workspace works

When you first sign up for PowerTools, you will be prompted to create a workspace schema. A workspace schema is simply a yaml file that lives at the .powertools/workspace.yml path in your code repository.

This yaml schema file is used to tell PowerTools what workspace you are using for authentication, as well as what environments, groups and other configurations you would like.

You only need to touch your workspace schema when making changes to your workspace. Not for adding new services.

If you would like to create a new workspace schema, please run:

$ pt new --kind=workspace

You will receive a prompt asking you which template you would like to choose. When you answer the prompt questions, you will have a new schema in your path at .powertools/workspace.yml.

Workspace schema

A basic workspace schema has the following configuration:

name: workspace-id
owners:
  - admin@your-company-email.com
users:
  - user@your-company-email.com

root_domains:
  - your-company.com

environments:
  - name: prod
    cloud: aws
    cloud_region: us-east-1
    cloud_account_id: abc123

groups:
  - name: main
    default: true

You most likely will never want to create this file manually, rather you should use pt new --kind=workspace.

You can run pt schema validate .powertools/workspace to check your workspace schema for errors at anytime.

Cloud accounts

Each environment in your workspace is connected to a cloud account on AWS or GCP in a region of your choosing.

While you can have multiple environments in the same cloud account and region, we generally recommend using at least multiple regions. Occasionally, when you have too many services in a single cloud account you will have to request additional quota from AWS or GCP.

Try using a different cloud account for test and stage environments.

Authentication

When you run a pt command, PowerTools will automatically detect what access is needed from which account(s) to execute.

pt will check for cached credentials in the ~/.powertools directory before asking you to authenticate. You can authenticate with your cloud accounts in several different ways, please reference the aws auth or gcp auth docs.

Your credentials never leave your machine.

Syncing

PowerTools manages your workspace for you. When you run pt workspace sync, PowerTools builds a graph of your expected resource configurations for each environment, group and domain and then checks each of your cloud accounts to ensure they are properly configured.

Behind the scenes, we send a hash of your workspace schema to our API so we can ensure that your schema is always in sync between your entire team.

Many users have asked if we use Terraform or other infrastructure management tools under the hood. We currently do not, instead using the cloud apis directly for maximum reliability.

Out of sync?

Whenever you run a command using pt, we create a hash of your workspace schema and verify it previously synced hashes. If your schema is out of sync, we will ask you to run pt workspace sync before proceeding in most cases.

This is done to protect your infrastructure and ensure that you are always working with the latest version of your schema.

We never have access to your code, and if our servers are down during this check, your commands will print a warning and let you proceed.