Skip to content

🔐 Enable API Access - IL Production

📋 Overview

This guide explains how to enable external API access for clients in the IL (Israel) production environment by adding their IP addresses to the security group whitelist.

Important Context

  • Environment: IL Production (il-prod)
  • Repository: unibeam-workload-sia-prod-terraform
  • Branch: il-prod-security-groups
  • Component: Security Groups
  • Deployment Method: GitHub Actions

🎯 Prerequisites

Before you begin, ensure you have:

  • [ ] GitHub repository access with write permissions
  • [ ] The client's public IP address(es) to whitelist
  • [ ] Knowledge of the client/service name for documentation
  • [ ] Understanding that changes affect production environment

Production Impact

Changes to the security group are deployed to production and take effect immediately after Terraform apply. Coordinate with the team for scheduled maintenance windows if needed.

📝 Step-by-Step Process

Step 1: 🔄 Switch to the Correct Branch

The security groups configuration for IL production is managed in a dedicated branch.

# Clone the repository (if not already cloned)
git clone https://github.com/your-org/unibeam-workload-sia-prod-terraform.git
cd unibeam-workload-sia-prod-terraform

# Checkout the IL production security groups branch
git checkout il-prod-security-groups

# Pull the latest changes
git pull origin il-prod-security-groups

Branch Naming Convention

The branch il-prod-security-groups is specifically used for managing security group configurations in the Israel production environment.

Step 2: 📍 Locate the IP List File

Navigate to the security groups component directory:

cd managed-services/components/security-groups

The IP whitelist is maintained in:

managed-services/components/security-groups/ip-list.txt

Step 3: ✏️ Add the IP Address

Open the ip-list.txt file in your preferred editor:

# Using vim
vim ip-list.txt

# Using nano
nano ip-list.txt

# Using VSCode
code ip-list.txt

Add the new IP address at the end of the file following this format:

<IP_ADDRESS>/32 <Client-Name-Description>

IP Address Format Examples

203.0.113.10/32 Acme-Corp-Office
198.51.100.0/24 Partner-XYZ-Network
192.0.2.50/32 External-Gateway-Service
147.237.70.0/24 GovIL-Production

Format Rules:

# For a single IP address, use /32
203.0.113.10/32 Client-Office-Main

# For a subnet range, specify the appropriate CIDR
198.51.100.0/24 Client-Corporate-Network

# Add each IP on a separate line
203.0.113.10/32 Client-Office-NY
203.0.113.20/32 Client-Office-LA
203.0.113.30/32 Client-Office-CHI

Naming Conventions

  • Use hyphens (-) instead of spaces in descriptions
  • Be descriptive but concise (e.g., Maccabi-POC, Pelephone-Proxy-IP)
  • No special characters except hyphens
  • Use CIDR notation (e.g., /32 for single IP, /24 for subnet)

Step 4: 💾 Commit and Push Changes

After adding the IP address, commit your changes:

# Add the modified file
git add ip-list.txt

# Commit with a descriptive message
git commit -m "Add IP whitelist for <Client-Name> (<IP-Address>/32)"

# Push to the branch
git push origin il-prod-security-groups

Good Commit Message Examples

git commit -m "Add IP whitelist for Clalit-Health-Prod (147.234.30.254/32)"
git commit -m "Add IP whitelist for External-Partner-API (203.0.113.0/24)"
git commit -m "Add temp access for Contractor-Demo (192.0.2.50/32)"

🚀 Deploy via GitHub Actions

Step 1: Navigate to GitHub Actions

  1. Go to the repository on GitHub: unibeam-workload-sia-prod-terraform
  2. Click on the Actions tab at the top
  3. Look for the workflow: "Deploy Managed Services Component" or "Terraform Deploy"

Step 2: Run the Workflow

Workflow Execution Steps

  1. Click the "Run workflow" button (top right)
  2. Select the branch: il-prod-security-groups
  3. Fill in the workflow inputs:
    • Environment: il-prod
    • Component: security-groups
    • Action: apply (or plan to preview first)
  4. Click "Run workflow" to start
# Expected workflow inputs
Branch: il-prod-security-groups
Environment: il-prod
Component: security-groups
Action: plan  # First run 'plan' to preview changes

Step 3: Review Terraform Plan

Always Review the Plan First

Before applying, always run with action: plan to preview the changes.

In the workflow logs, you'll see output similar to:

Terraform will perform the following actions:

  # module.api_external_sg.aws_security_group_rule.ingress["28"] will be created
  + resource "aws_security_group_rule" "ingress" {
      + cidr_blocks       = ["203.0.113.10/32"]
      + description       = "Client-XYZ-Office"
      + from_port         = 443
      + protocol          = "tcp"
      + security_group_id = "sg-0123456789abcdef0"
      + to_port           = 443
      + type              = "ingress"
    }

Plan: 1 to add, 0 to change, 0 to destroy.

Verify:

  • [ ] Only the expected IP address is being added
  • [ ] Port is 443 (HTTPS)
  • [ ] Protocol is TCP
  • [ ] Description matches your entry
  • [ ] No unexpected deletions or modifications

Step 4: Apply Changes

After confirming the plan looks correct:

  1. Re-run the workflow with action: apply
  2. Monitor the deployment in the Actions tab
  3. Wait for completion (typically 2-5 minutes)

Deployment Success

When complete, you'll see: 

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

🔍 Verification Steps

1. ✅ Verify in AWS Console

# List security group rules
aws ec2 describe-security-groups \
  --filters "Name=tag:Name,Values=api-ext-sg-il-prod" \
  --region eu-central-1 \
  --query 'SecurityGroups[0].IpPermissions[?ToPort==`443`]'

Expected output should include your newly added IP:

{
  "FromPort": 443,
  "IpProtocol": "tcp",
  "IpRanges": [
    {
      "CidrIp": "203.0.113.10/32",
      "Description": "Client-XYZ-Office"
    }
  ],
  "ToPort": 443
}

2. 🧪 Test Connectivity from Client IP

From the client's network (with the whitelisted IP), test API connectivity:

# Test HTTPS connectivity
curl -v https://api.il.unibeam.com/health

# Expected response
HTTP/2 200
{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z"
}

Testing Tips

  • Test from the exact IP address that was whitelisted
  • Ensure you're testing port 443 (HTTPS)
  • Check DNS resolution first: nslookup api.il-prod.unibeam.com

⚙️ How It Works

Infrastructure Overview

The security group configuration uses Terraform to dynamically generate ingress rules:

graph LR
    A[ip-list.txt] --> B[Terraform main.tf]
    B --> C[Parse & Generate Rules]
    C --> D[Security Group: api-ext-sg-il-prod]
    D --> E[AWS VPC]
    E --> F[API Gateway / Load Balancer]

Rule Generation Process

  1. File Reading: main.tf reads ip-list.txt
  2. Parsing: Each line is split into CIDR and description
  3. Rule Creation: Creates an ingress rule for each IP:
  4. Protocol: tcp
  5. Port: 443
  6. Source: CIDR from file
  7. Description: Text from file
  8. Application: Rules are applied to api-ext-sg-il-prod

📊 Common Scenarios

Scenario 1: Adding Multiple IPs for Same Client

# Client with multiple offices
203.0.113.10/32 Acme-Corp-Office-TLV
203.0.113.20/32 Acme-Corp-Office-Haifa
203.0.113.30/32 Acme-Corp-Office-Beer-Sheva

Scenario 2: Adding an Entire Subnet

# Corporate network range
198.51.100.0/24 Partner-Corp-Network-Israel

Scenario 3: Temporary Access

Add a comment with expiration date:

# TODO: Remove after 2024-12-31
192.0.2.50/32 Contractor-Temp-Access-Q4

Scenario 4: Replacing an IP Address

# Old IP (comment out)
# 203.0.113.10/32 Client-Old-Office

# New IP
203.0.113.20/32 Client-New-Office

🚨 Troubleshooting

Issue: IP Not Working After Deployment

Checklist

  1. Verify CIDR notation is correct (/32 for single IP)
  2. Confirm deployment succeeded in GitHub Actions
  3. Check security group in AWS Console
  4. Verify client is using the correct IP address
  5. Check DNS resolution from client network
  6. Ensure port 443 is not blocked by client firewall
  7. Verify target service is running and healthy
# Debug connectivity
curl -v --connect-timeout 10 https://api.il.unibeam.com

# Check if security group exists
aws ec2 describe-security-groups \
  --filters "Name=tag:Name,Values=api-ext-sg-il-prod" \
  --region eu-central-1

Issue: GitHub Actions Workflow Fails

Error: Error loading state: AccessDenied

Solution: - Check AWS credentials in GitHub Secrets - Verify IAM role has necessary permissions - Contact DevOps team to verify OIDC configuration

Error: Error acquiring the state lock

Solution: - Another deployment is in progress - Wait for it to complete (check other running workflows) - If stuck, contact DevOps to manually unlock state

Error: Invalid CIDR block format

Solution: - Review IP format in ip-list.txt - Ensure proper CIDR notation (e.g., /32, /24) - Check for typos or extra spaces

Issue: Terraform Shows Unexpected Changes

If the plan shows deletions or modifications you didn't expect:

Do Not Apply

Stop and investigate before applying!

Steps:

  1. Review the Terraform plan carefully
  2. Check if someone else made changes
  3. Pull latest changes from the branch
  4. Contact the DevOps team for assistance

🔒 Security Best Practices

Security Guidelines

  • Principle of Least Privilege: Only whitelist necessary IPs
  • Regular Audits: Review and remove unused IPs quarterly
  • Documentation: Always use descriptive names in ip-list.txt
  • Temporary Access: Add expiration comments for short-term access
  • Coordination: Inform the team before adding production IPs

📞 Support and Escalation

If you encounter issues:

  1. Check Logs:
  2. GitHub Actions workflow logs
  3. CloudWatch logs for security group changes

  4. AWS VPC flow logs

  5. Contact DevOps Team with:

  6. IP address being whitelisted
  7. Client/service name
  8. Environment: il-prod
  9. Error messages or screenshots

  10. GitHub Actions run URL

  11. Emergency Contact:

  12. Slack: #devops-support
  13. Email: devops@unibeam.com

Environment: IL Production
Maintained By: DevOps Team