Create Your First Policy

This guide walks you through creating your first access policy from scratch. You’ll learn the policy syntax, test your policy, and deploy it to control data access.

Transition In Progress

Policy administration is being migrated from YAML configuration-as-code workflows to the Web Admin Portal. This page remains as reference for the current declarative model and advanced workflows, but the exact configuration flow and policy surface are subject to change as responsibility moves into the portal.

What is a Policy?

A policy is a declarative rule that defines who can access what data, when, where, and why. Think of it as an access control list (ACL) written in a human-readable format that’s version-controlled alongside your code.

Instead of manually granting database access each time someone needs data, you write the rules once, and Alien Giraffe enforces them automatically.

Policy Structure

Every policy follows a formal access control model with five key components:

• Subjects - Which users or teams need access (e.g., team: customer-support)
• Resources - Which data sources and datasets they can access (e.g., source: production-db, datasets: [customers])
• Constraints - Time windows and duration limits (e.g., timeframe: business-hours, duration: 4h)
• Channels - Access methods and operations allowed (e.g., name: sql, operation: rw)
• Context - Purpose or justification (e.g., customer-support, incident-response)

Your First Policy

Let’s create a simple policy that grants customer support team access to customer data.

Step 1: Create Policy File

Create a file policies/customer-support-access.yaml:

apiVersion: v1
kind: Policy
metadata:
  name: customer-support-access
  namespace: production
  description: Allow customer support to view customer data during business hours
  owner: customer-support-lead

spec:
  # Subjects (who can access)
  subjects:
    - team: customer-support

  # Resources (what data they can access)
  resources:
    - source: production-postgres
      datasets:
        - customers
        - orders
        - support_tickets

  # Constraints (when they can access)
  constraints:
    - timeframe: business-hours  # 9 AM - 5 PM local time
    - duration: 4h               # Sessions last 4 hours max

  # Channels (where they can access from)
  channels:
    - name: sql
      operation: rw
    - name: web
      operation: r

  # Context (why they need access)
  context:
    - customer-support
    - order-inquiries

Step 2: Validate the Policy

Before deploying, validate your policy:

# Validate syntax and structure
a10e policy validate policies/customer-support-access.yaml

# Expected output:
# ✓ Syntax valid
# ✓ All referenced sources exist
# ✓ All referenced teams exist
# ✓ Policy ready to apply

Compile All Policies and Configurations

When working with multiple policies, you can validate all policies and configurations at once to ensure they can be properly executed and applied:

# Compile and validate all policies in a directory
a10e policy compile policies/

# Expected output:
# Compiling policies...
# ✓ policies/customer-support-access.yaml
# ✓ policies/engineering-access.yaml
# ✓ policies/analytics-access.yaml
#
# Validating cross-policy dependencies...
# ✓ No conflicting policies detected
# ✓ All source references valid
# ✓ All team references valid
# ✓ All time schedules valid
#
# Summary: 3 policies compiled successfully

# Compile with verbose output for detailed validation
a10e policy compile policies/ --verbose

# Compile specific namespace
a10e policy compile policies/production/ --namespace production

# Compile and check for conflicts
a10e policy compile policies/ --check-conflicts

# Compile with JSON output for CI/CD integration
a10e policy compile policies/ --output json

Example compile output with issues:

a10e policy compile policies/

# Expected output with errors:
# Compiling policies...
# ✓ policies/customer-support-access.yaml
# ✗ policies/engineering-access.yaml
#   Error: Referenced source 'staging-db' does not exist
#   Line 48: source: staging-db
# ✗ policies/analytics-access.yaml
#   Warning: Team 'legacy-team' has no members
#   Line 44: team: legacy-team
#
# Validating cross-policy dependencies...
# ✗ Policy conflict detected:
#   - customer-support-access (line 50)
#   - engineering-access (line 62)
#   Both grant access to 'customers' dataset with different permissions
#
# Summary: 1 policy compiled, 2 failed
# Exit code: 1

Step 3: Test the Policy (Dry Run)

Test how the policy would behave without actually deploying it:

# Simulate an access request
a10e policy test customer-support-access \
  --user alice@company.com \
  --source production-postgres \
  --dataset customers \
  --dry-run

# Expected output:
# ✓ Access would be GRANTED
# Reason: User alice@company.com is member of team customer-support
# Duration: 4 hours
# Channels: sql, web-ui

Step 4: Apply the Policy

Deploy the policy to production:

# Apply the policy
a10e policy apply -f policies/customer-support-access.yaml

# Verify it was created
a10e policy list

# View policy details
a10e policy get customer-support-access

Step 5: Test Real Access

Now test that a user can actually access data:

# Request access as a customer support team member
a10e access request \
  --source production-postgres \
  --datasets customers \
  --purpose "customer-support" \
  --duration 2h

# Expected output:
# ✓ Access granted
# Session ID: sess-abc123
# Expires: 2025-11-18 16:30:00 UTC
# Credentials saved to ~/.a10e/credentials

Congratulations! You’ve created and deployed your first policy.

Common Policy Patterns

Pattern 1: Individual User Access

Grant access to specific users:

spec:
  subjects:
    - user: alice@company.com
    - user: bob@company.com

  resources:
    - source: analytics-db
      datasets: [reports, dashboards]

  constraints:
    - duration: 8h

  channels:
    - name: sql
      operation: rw

Pattern 2: Read-Only Analytics Access

Grant read-only access for analytics work:

metadata:
  name: analytics-read-access

spec:
  subjects:
    - team: data-analysts
    - team: data-scientists

  resources:
    - source: analytics-replica     # Read replica, not production
      datasets: ["*"]                # All datasets
      permissions: [SELECT]          # Read-only

  constraints:
    - timeframe: business-hours
    - duration: 8h

  channels:
    - name: sql
      operation: r
    - name: api
      operation: r

  context:
    - analytics
    - reporting

Pattern 3: Time-Restricted Access

Limit access to specific time windows:

metadata:
  name: weekend-maintenance

spec:
  subjects:
    - team: sre

  resources:
    - source: production-db
      datasets: [schema_migrations, system_config]

  constraints:
    - timeframe:
        days: [saturday, sunday]
        hours: [2-6]                 # 2 AM - 6 AM
    - duration: 4h

  channels:
    - name: sql
      operation: rw

  context:
    - maintenance
    - database-upgrades

Pattern 4: Approval-Required Access

Require manager approval for sensitive data:

metadata:
  name: pii-access-with-approval

spec:
  subjects:
    - team: engineering

  resources:
    - source: production-db
      datasets: [users_pii, payment_info]

  constraints:
    - duration: 2h

  channels:
    - name: sql
      operation: rw

  context:
    - debugging
    - incident-response

  approval:
    required: true
    approvers:
      - role: manager
      - role: data-privacy-officer
    timeout: 1h                      # Approval expires after 1 hour

Pattern 5: Emergency Break-Glass

Fast access for critical incidents:

metadata:
  name: emergency-production-access

spec:
  subjects:
    - team: on-call-engineers

  resources:
    - source: production-db
      datasets: ["*"]

  constraints:
    - timeframe: "*"                 # 24/7 access
    - duration: 1h                   # Short emergency sessions

  channels:
    - name: sql
      operation: rw

  context:
    - incident-response
    - outage

  mfa:
    required: true                   # Require multi-factor auth

  audit:
    level: verbose                   # Enhanced logging
    notify:
      immediate:
        - slack: "#security-alerts"
        - email: security@company.com

Advanced Policy Features

Multiple Sources

Grant access to multiple data sources in one policy:

spec:
  resources:
    - source: production-postgres
      datasets: [customers, orders]

    - source: finance-oracle
      datasets: [invoices, payments]

    - source: data-lake-s3
      paths: [/analytics/*, /reports/*]

Conditional Access

Apply conditions based on context:

spec:
  conditions:
    # Require VPN connection
    vpnRequired: true

    # Restrict to specific IP ranges
    ipAllowlist:
      - 203.0.113.0/24
      - 198.51.100.42

    # Require device compliance
    deviceCompliance: true

    # Time-based conditions
    timeConditions:
      - condition: weekend
        requireApproval: true
      - condition: after-hours
        requireMFA: true

Data Masking

Automatically mask sensitive fields:

spec:
  resources:
    - source: production-db
      datasets: [customers]
      masking:
        email: partial              # j***@example.com
        phone: last4                # ***-***-1234
        ssn: blocked                # Completely blocked

Session Extensions

Allow users to extend sessions:

spec:
  constraints:
    - duration: 4h
      maxExtensions: 2              # Can extend twice
      extensionDuration: 2h         # 2 hours each time

Policy Management

List Policies

# List all policies
a10e policy list

# Filter by namespace
a10e policy list --namespace production

# Show detailed information
a10e policy list --detailed

Update a Policy

# Edit the YAML file
vim policies/customer-support-access.yaml

# Apply changes
a10e policy apply -f policies/customer-support-access.yaml

# Or edit interactively
a10e policy edit customer-support-access

View Policy Usage

# See who's using this policy
a10e policy usage customer-support-access

# View access history
a10e policy audit customer-support-access --since 7d

Delete a Policy

# Delete a policy (requires confirmation)
a10e policy delete customer-support-access

# Force delete without confirmation
a10e policy delete customer-support-access --force

# Note: Active sessions are not affected by deletion

Next Steps

Now that you have a policy in place:

1. Set Up Identity Integration - Connect your identity provider for team management
2. Configure Monitoring - Set up audit logging and alerts
3. Policies Component Reference - Learn advanced policy features
4. Constraints (Just-In-Time Access) - Understand temporary access workflows

For more examples:

• Policy Cookbook - Collection of common policy patterns
• Security Best Practices - Secure your policies
• Compliance Guide - Meet regulatory requirements