Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
193 lines (138 loc) · 5.39 KB

GETTING_STARTED.md

File metadata and controls

193 lines (138 loc) · 5.39 KB

Getting Started with PTD

This guide walks you through setting up PTD to deploy Posit Team products on AWS or Azure.

Prerequisites

Required Tools

Tool Version Description
Go 1.21+ For building the CLI
Python 3.12+ For Pulumi IaC
uv Latest Python package manager
Pulumi 3.x Infrastructure as Code
just Latest Command runner
goreleaser Latest For building releases

Cloud Provider Tools

For AWS:

  • AWS CLI v2
  • AWS Session Manager Plugin
  • AWS credentials configured (via aws configure or environment variables)
  • Route 53 hosted zone for your deployment domain (e.g., example.posit.team). PTD uses ExternalDNS to manage DNS records automatically, and it requires an existing hosted zone in the target AWS account. Create one in the Route 53 console before running ptd ensure.
  • admin.posit.team IAM role deployed to each AWS account PTD will manage. See ptd admin generate-role and IAM Permissions for details.

For Azure:

  • Azure CLI
  • Azure credentials configured (via az login)

Installation

1. Clone the Repository

git clone https://github.com/posit-dev/ptd.git
cd ptd

2. Install Dependencies

just deps

This installs:

  • Python dependencies via uv
  • Go dependencies
  • Required CLI tools symlinked to .local/bin/

3. Build the CLI

just cli

The CLI binary is created at .local/bin/ptd.

4. Configure AWS Accounts (Optional)

Copy and edit the account configuration:

cp accounts.env.example accounts.env
# Edit accounts.env with your AWS account IDs

This step is optional - PTD can auto-detect your AWS account via STS.

Setting Up Your First Deployment

1. Create a Targets Directory

PTD organizes deployments into "targets" - either control rooms or workloads.

mkdir -p my-infrastructure/__ctrl__/my-control-room
mkdir -p my-infrastructure/__work__/my-workload

2. Copy Example Configurations

# Copy control room example
cp examples/control-room/ptd.yaml my-infrastructure/__ctrl__/my-control-room/

# Copy workload example
cp -r examples/workload/* my-infrastructure/__work__/my-workload/

3. Edit Configurations

Edit the configuration files with your actual values:

Control Room (my-infrastructure/__ctrl__/my-control-room/ptd.yaml):

  • AWS account ID
  • Domain names
  • Trusted principals (users who can manage)

Workload (my-infrastructure/__work__/my-workload/ptd.yaml):

  • AWS account ID
  • Control room reference
  • Cluster configuration
  • Site domains

Site (my-infrastructure/__work__/my-workload/site_main/site.yaml):

  • Authentication (OIDC/SAML) configuration
  • Product versions
  • Replicas and scaling

4. Configure PTD

Tell PTD where your configurations are:

# Option 1: Environment variable
export PTD_TARGETS_CONFIG_DIR=/path/to/my-infrastructure

# Option 2: Config file (~/.config/ptd/ptdconfig.yaml)
echo "targets_config_dir: /path/to/my-infrastructure" > ~/.config/ptd/ptdconfig.yaml

# Option 3: CLI flag (per-command)
ptd --targets-config-dir /path/to/my-infrastructure <command>

5. Deploy

# Deploy the control room first
ptd ensure my-control-room

# Then deploy the workload
ptd ensure my-workload

Note: For workloads, the first step (bootstrap) creates the Pulumi state backend (S3 bucket and KMS key on AWS, storage account on Azure) and initializes secrets. If you use --start-at-step or --only-steps to skip bootstrap on a fresh deployment, subsequent steps will fail because the state backend does not exist. Use -v (verbose) to see the expected resource names if you encounter state backend errors. See Ensure Command Flow for details on each step.

Architecture Overview

PTD deployments consist of:

Organization
├── Control Room (1 per org)
│   ├── EKS cluster
│   ├── DNS management
│   └── Shared services
│
└── Workloads (1+ per org)
    ├── AWS Infrastructure
    │   ├── VPC
    │   ├── EKS cluster(s)
    │   ├── RDS PostgreSQL
    │   └── FSx for OpenZFS
    │
    └── Sites (1+ per workload)
        ├── Workbench
        ├── Connect
        └── Package Manager

Common Operations

Access a Cluster

# Start a proxy to the cluster
ptd proxy my-workload

# In another terminal, use kubectl
export KUBECONFIG=./kubeconfig
kubectl get pods -A

View Deployment Status

ptd workon my-workload

Update a Deployment

Edit the configuration files, then re-run:

ptd ensure my-workload

Next Steps