Skip to content

Getting Started

Jump to bottom
Tim Krebs edited this page Apr 3, 2026 · 1 revision

Getting Started

This guide walks through the complete setup of the Netlix Platform from scratch, including prerequisites, bootstrap, HCP Terraform configuration, and first deployment.

Prerequisites

Tool Version Purpose
Terraform CLI >= 1.14.8 Infrastructure provisioning and Stacks CLI
HCP Terraform - Stack orchestration, state management, Sentinel
HCP Account - Vault Dedicated cluster, HVN networking
AWS CLI v2 Bootstrap IAM, EKS kubeconfig
kubectl v1.31+ Kubernetes cluster access
Kustomize v5+ Manifest rendering (bundled with kubectl)
GitHub CLI v2+ PR workflows, CD triggers
Sentinel CLI v0.26.3 Local policy testing
Helm v3+ Chart inspection (optional, Terraform manages Helm releases)

Account Setup

  1. AWS Account with IAM admin access (for bootstrap only)
  2. HCP Organization with:
    • Vault Dedicated cluster (netlix-vault) in an HVN
    • Service principal with Contributor role
  3. HCP Terraform Organization (tim-krebs-org) with:
    • Stacks feature enabled
    • GitHub App installed and connected to the repository
  4. GitHub Repository (timkrebs/netlix-platform) with Actions enabled
  5. Domain registered and delegated to Route53 (e.g., netlix.dev)

Phase 0 - Bootstrap AWS OIDC Trust

The bootstrap creates the IAM OIDC provider and per-environment roles that allow HCP Terraform Stacks to authenticate to AWS without static credentials.

cd bootstrap
terraform init
terraform apply

What it creates:

Resource Name Purpose
IAM OIDC Provider app.terraform.io Trust anchor for TFC workload identity
IAM Role tfc-netlix-dev Scoped role for dev Stack deployments
IAM Role tfc-netlix-staging Scoped role for staging Stack deployments
IAM Policy tfc-netlix-dev-scoped EC2, EKS, RDS, Route53, ACM, IAM, KMS, CloudWatch, SNS, STS
IAM Policy tfc-netlix-staging-scoped Same as dev (identical policy)

Role trust policy restricts assumption to specific TFC organization, project, and stack:

organization:tim-krebs-org:project:netlix-platform:stack:netlix-platform-{env}:*

Outputs needed for next phase:

terraform output dev_role_arn
# arn:aws:iam::173003892479:role/tfc-netlix-dev

terraform output staging_role_arn
# arn:aws:iam::173003892479:role/tfc-netlix-staging

Note: Bootstrap is run once manually with local AWS credentials. After this, all Terraform runs use OIDC workload identity through HCP Terraform.

Phase 1 - HCP Terraform Setup

1.1 Create Variable Sets

Variable sets provide sensitive credentials to Stack deployments without storing them in code.

Variable Set ID Variables Type
netlix-hcp varset-N9WxeF7Jw3G6LhdD hcp_client_id, hcp_client_secret Terraform (sensitive)

Important: Variable set values are always ephemeral in Stacks. They cannot flow into component inputs that persist to state. This is by design for security.

1.2 Create the Stack

  1. Navigate to HCP Terraform > Projects > netlix-platform
  2. Create a new Stack named netlix
  3. Connect to the GitHub repository timkrebs/netlix-platform
  4. HCP Terraform auto-discovers .tfcomponent.hcl and .tfdeploy.hcl files

1.3 Create Sentinel Policy Set

  1. Navigate to Settings > Policy Sets
  2. Create policy set netlix-sentinel
  3. Point to sentinel/ path in the repository
  4. Scope to the netlix Stack

1.4 Configure Route53 Hosted Zone

The DNS component uses a pre-existing Route53 hosted zone (data source, not managed resource). This prevents nameserver changes on Stack redeployment.

  1. Create the hosted zone manually in AWS Console (or via CLI)
  2. Note the Zone ID (e.g., Z03825243OZJVWRUDJ5T)
  3. Update domain registrar NS records to match Route53 nameservers
  4. Wait for DNS propagation (up to 48h for registrar changes)

Phase 2 - Deploy Infrastructure

Push to the repository (or trigger manually in HCP Terraform). The Stack will:

  1. Plan all 12 components in dependency order
  2. Cost estimation calculates monthly cost delta
  3. Sentinel evaluates 6 policies against the plan
  4. Apply provisions dev (and staging, if configured)

Deployment Pipeline

Push to repo
    │
    ▼
HCP Terraform detects changes
    │
    ▼
Plan (12 components, parallelized where possible)
    │
    ▼
Cost Estimation (Sentinel soft-mandatory: < $2,000/month)
    │
    ▼
Sentinel Policy Check (6 policies)
    │
    ├── Hard-mandatory: mandatory tags, encryption, no public S3
    ├── Soft-mandatory: instance types, cost limit (admin override)
    └── Advisory: VPC flow logs
    │
    ▼
Apply (components in dependency order)
    │
    ▼
Outputs available (VPC ID, cluster endpoint, Vault namespace, etc.)

Verify Deployment

# Get Stack outputs
terraform stacks deployment-run list

# Configure kubectl
aws eks update-kubeconfig --region eu-central-1 --name netlix-dev

# Verify cluster
kubectl get nodes
kubectl get namespaces

Phase 3 - Application Deployment

3.1 Create Datadog Secret

The Datadog Operator requires an API key stored as a Kubernetes secret (managed outside Terraform due to Stacks ephemeral value constraints):

kubectl create secret generic datadog-secret \
  --namespace datadog \
  --from-literal api-key=<YOUR_DATADOG_API_KEY>

3.2 Apply DatadogAgent CRD

kubectl apply -f kubernetes/monitoring/datadog-agent.yaml

3.3 Verify Application

ArgoCD automatically syncs the application from app/overlays/{env}/. Verify:

# Check ArgoCD sync status
kubectl get application netlix-app -n argocd

# Check pods
kubectl get pods -n consul

# Check ingress
kubectl get ingress -n consul

# Test endpoints
curl https://app.dev.netlix.dev/health
curl https://argocd.dev.netlix.dev

Phase 4 - Post-Deployment Verification

Infrastructure Checks

# EKS cluster health
aws eks describe-cluster --name netlix-dev --query 'cluster.status'

# RDS instance
aws rds describe-db-instances --db-instance-identifier netlix-dev --query 'DBInstances[0].DBInstanceStatus'

# VPC Flow Logs
aws logs describe-log-groups --log-group-name-prefix /aws/vpc/flow-log

# ACM Certificate
aws acm list-certificates --query 'CertificateSummaryList[?DomainName==`*.dev.netlix.dev`]'

Vault Verification

# Login to Vault (requires vault CLI + access)
export VAULT_ADDR="https://netlix-vault-public-vault-....hashicorp.cloud:8200"
export VAULT_NAMESPACE="admin"
vault login -method=userpass username=<admin>

# Check namespaces
vault namespace list

# Check PKI (in environment namespace)
export VAULT_NAMESPACE="admin/dev"
vault secrets list
vault read pki_int/roles/netlix-dev

DNS Verification

# Check Route53 records
aws route53 list-resource-record-sets --hosted-zone-id Z03825243OZJVWRUDJ5T

# Resolve application DNS
nslookup app.dev.netlix.dev
nslookup argocd.dev.netlix.dev

Quick Reference

# Bootstrap (one-time)
cd bootstrap && terraform init && terraform apply

# Local validation
terraform fmt -check -recursive terraform/components/
cd sentinel && sentinel test -verbose ./policies/
kubectl kustomize app/overlays/dev/

# Cluster access
aws eks update-kubeconfig --region eu-central-1 --name netlix-dev

# ArgoCD UI
kubectl port-forward svc/argocd-server -n argocd 8080:443
# Or visit: https://argocd.dev.netlix.dev

Clone this wiki locally