npm package: @kuckit/infra-gcp
Description: Kuckit GCP infrastructure provider - deploys to Cloud Run with Cloud SQL, Redis, and Artifact Registry
Latest version: 5.0.0

# @kuckit/infra-gcp

GCP infrastructure provider for Kuckit applications. Deploys to Google Cloud Platform with:

- **Cloud Run** - Containerized application hosting
- **Cloud SQL (PostgreSQL)** - Managed database
- **Memorystore (Redis)** - Caching and sessions
- **Artifact Registry** - Container image storage
- **VPC with Direct VPC Egress** - Private networking

## Prerequisites

- [Pulumi CLI](https://www.pulumi.com/docs/install/)
- [Google Cloud SDK (gcloud)](https://cloud.google.com/sdk/docs/install)
- GCP project with billing enabled
- Authenticated via `gcloud auth login` and `gcloud auth application-default login`

## Installation

```bash
bun add -D @kuckit/infra-gcp
# or
npm install -D @kuckit/infra-gcp
```

## Usage

This package is used by the Kuckit CLI. After installation:

```bash
# One-command deploy (init + deploy)
bunx kuckit infra up --env dev

# Or step by step:
bunx kuckit infra init --provider gcp --project YOUR_GCP_PROJECT
bunx kuckit infra deploy --env dev

# View status
bunx kuckit infra status --env prod

# Destroy infrastructure
bunx kuckit infra destroy --env dev
```

## How It Works

1. **`kuckit infra init`** - Creates base infrastructure without deploying the app:
   - VPC with private subnets
   - Cloud SQL PostgreSQL instance
   - Memorystore Redis instance
   - Artifact Registry repository
   - Service accounts with minimal permissions

2. **`kuckit infra deploy`** - Builds and deploys your application:
   - Builds Docker image using Cloud Build
   - Pushes to Artifact Registry
   - Deploys Cloud Run service with VPC connector
   - Configures secrets and environment variables

## Configuration

Infrastructure configuration is stored per-environment in `.kuckit/`:

| File                      | Environment | Description                     |
| ------------------------- | ----------- | ------------------------------- |
| `.kuckit/infra.dev.json`  | Development | Dev environment settings        |
| `.kuckit/infra.prod.json` | Production  | Production environment settings |
| `.kuckit/infra.json`      | Fallback    | Legacy/default configuration    |

Example configuration:

```json
{
	"provider": "gcp",
	"providerPackage": "@kuckit/infra-gcp",
	"region": "us-central1",
	"env": "dev",
	"providerConfig": {
		"gcpProject": "your-gcp-project"
	}
}
```

### Pulumi Project

The infrastructure uses Pulumi project name `kuckit-infra`. Stack names follow the pattern `{gcpProject}-{env}`.

> **⚠️ Important:** Changing the Pulumi project name causes resource recreation. See [AGENTS.md](./AGENTS.md) for details.

## Managing Configuration

```bash
# Set custom domain
bunx kuckit infra config set appUrl https://app.example.com --env prod

# Set Polar environment
bunx kuckit infra config set polarEnvironment production --env prod

# List all config
bunx kuckit infra config list --env prod
```

## Ejecting for Customization

If you need to customize the infrastructure beyond what the provider offers:

```bash
bunx kuckit infra eject
```

This copies the Pulumi code to your project's `infra/` directory for full customization.

## Environment Defaults

| Setting          | Dev         | Prod        |
| ---------------- | ----------- | ----------- |
| Cloud Run CPU    | 1           | 2           |
| Cloud Run Memory | 512Mi       | 1Gi         |
| Min Instances    | 0           | 1           |
| Max Instances    | 2           | 10          |
| Cloud SQL Tier   | db-f1-micro | db-g1-small |

## API Reference

This package exports:

```typescript
import { provider, gcpProvider } from '@kuckit/infra-gcp'
import type { GcpInfraConfig, GcpOutputs } from '@kuckit/infra-gcp'
```

The provider implements the `KuckitInfraProvider` interface from `@kuckit/cli`.

## Documentation

- [Deployment Guide](../../docs/DEPLOYMENT.md)
- [AGENTS.md](./AGENTS.md) - Provider internals and advanced configuration

## License

MIT