3cloud-backend/ansible

xCloudify Ansible Infrastructure as Code

Complete Ansible automation for xCloudify container orchestration platform. This repository provides idempotent infrastructure-as-code capabilities for managing Docker containers, storage volumes, and networking in xCloudify Virtual Data Centers.

🚀 Quick Start

Prerequisites

• Ansible >= 2.9
• Python >= 3.6
• xCloudify account with API access
• Valid Virtual Data Center ID

Installation

# Clone the repository
git clone https://github.com/xcloudify/ansible-infrastructure.git
cd ansible-infrastructure

# Install dependencies
ansible-galaxy install -r requirements.yml

# Set up authentication
export XCLOUDIFY_BEARER_TOKEN="your-bearer-token"
export TEST_VDC_ID="your-vdc-id"

Basic Usage

# Deploy simple web application
ansible-playbook examples/simple-web-app.yml

# Deploy multi-tier application
ansible-playbook examples/multi-tier-app.yml

# Test lifecycle management
ansible-playbook examples/lifecycle-management.yml

# Run integration tests
ansible-playbook tests/test-infrastructure.yml

📦 Roles

xcloudify_infrastructure

Main role for infrastructure management within existing Virtual Data Centers.

Key Features:

• VDC-centric approach (only requires VDC ID)
• Automatic context resolution (Universe/Project/Region)
• Idempotent operations with partial updates for zero-downtime changes
• Container lifecycle management (start/stop/restart)
• Pod management: Create pods or attach to existing pods
• Advanced container features: Healthchecks, restart policies, injected files
• Network and volume management
• Port forwarding with DNS integration
• Robust error handling, validation, and authentication
• Backward compatibility with legacy parameters

Usage:

- include_role:
    name: xcloudify_infrastructure
  vars:
    xcloudify_vdc_id: "{{ my_vdc_id }}"
    xcloudify_bearer_token: "{{ vault_token }}"
    xcloudify_infrastructure:
      containers:
        - name: "web-app"
          image: "nginx:latest"
          ports:
            - internal: 80
              external: 8080
              use_dns: true
            healthcheck:
              test: ["CMD", "curl", "-f", "http://localhost/health"]
              interval: 30
              timeout: 10
              retries: 3
            restart_policy:
              name: always
              maximum_retry_count: 3
            injected_files:
              - filename: /etc/config.json
                content: eyJmb28iOiAiYmFyIn0=  # base64: {"foo": "bar"}
                permissions: "0644"

xcloudify_admin

Administrative role for managing regions and Virtual Data Centers.

Key Features:

• Region creation and management
• VDC creation and management
• Administrative operations
• Requires elevated privileges

Usage:

- include_role:
    name: xcloudify_admin
  vars:
    xcloudify_admin_token: "{{ admin_token }}"
    xcloudify_admin_operations:
      regions:
        - name: "US East 1"
          country: "United States"
          abbreviation: "USE1"

🆕 New Features in v2.0.0

Pod Management

Pods group multiple containers on the same host. Use pod_id to attach containers to an existing pod, or let the role create a new pod automatically.

Example: Attach to Existing Pod

- include_role:
    name: xcloudify_infrastructure
  vars:
    xcloudify_vdc_id: "{{ my_vdc_id }}"
    xcloudify_bearer_token: "{{ vault_token }}"
    xcloudify_infrastructure:
      pod_id: "existing-pod-uuid"  # Attach to existing pod
      containers:
        - name: "sidecar-logger"
          image: "fluentd:latest"
          # ... other config

Example: Create New Pod with Multiple Containers

xcloudify_infrastructure:
  containers:
    - name: "web-app"
      image: "nginx:latest"
      # ... config
    - name: "app-server"
      image: "node:18"
      # ... config
  # Role auto-creates pod grouping these containers

Advanced Container Parameters

Support for healthchecks, restart policies, and runtime file injection.

Healthcheck Example

containers:
  - name: "api-service"
    image: "myapi:latest"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30
      timeout: 10
      retries: 3
      start_period: 40  # Grace period for startup

Restart Policy Example

containers:
  - name: "worker"
    image: "worker:latest"
    restart_policy:
      name: "on-failure"
      maximum_retry_count: 5  # Restart up to 5 times on failure

Injected Files Example

containers:
  - name: "config-driven-app"
    image: "app:latest"
    injected_files:
      - filename: "/app/config.json"
        content: "{{ base64encode(lookup('file', 'config.json')) }}"  # Base64 from Ansible file
        permissions: "0644"
      - filename: "/app/secrets.env"
        content: "{{ base64encode('DB_PASSWORD=secret') }}"
        permissions: "0600"  # Secure permissions

Partial Updates

For zero-downtime updates, the role supports partial updates via PATCH API. Legacy full recreation (PUT) remains available but issues warnings.

Example: Update Env Vars Without Recreation

- include_role:
    name: xcloudify_infrastructure
  vars:
    xcloudify_infrastructure:
      containers:
        - name: "web-app"
          env:
            DEBUG: "true"  # Only update this var
    xcloudify_force_recreate: false  # Use partial update (default)

Backward Compatibility

• All v1.x playbooks continue to work unchanged
• New features are optional with defaults matching legacy behavior
• Deprecations: recreate_on_update param now warns in favor of partial updates
• Tests ensure 100% compatibility with existing deployments

🏗️ Architecture

Infrastructure Hierarchy

Universe (Admin)
└── Project (Admin)
    └── Virtual Data Center (User Entry Point)
        ├── Networks (VXLAN with VNI)
        ├── Volumes (Persistent Storage)
        └── Containers (Docker Workloads)
            ├── Port Forwarding
            ├── DNS Records
            └── Volume Mounts

Role Structure

roles/
├── xcloudify_infrastructure/     # Main user role
│   ├── library/                  # Custom Ansible modules
│   │   ├── xcloudify_container.py
│   │   ├── xcloudify_network.py
│   │   └── xcloudify_volume.py
│   ├── module_utils/             # Shared utilities
│   │   └── xcloudify_client.py
│   ├── tasks/                    # Task orchestration
│   └── handlers/                 # Event handlers
│
└── xcloudify_admin/              # Admin operations
    ├── library/
    │   ├── xcloudify_region.py
    │   └── xcloudify_vdc.py
    └── tasks/

🔧 Configuration

Authentication

Multiple authentication methods supported:

# Method 1: Direct token
xcloudify_bearer_token: "your-token"

# Method 2: Ansible Vault
xcloudify_bearer_token: "{{ vault_xcloudify_token }}"

# Method 3: Environment variable
export XCLOUDIFY_BEARER_TOKEN="your-token"

API Configuration

# Default configuration
xcloudify_api_url: "https://api.xcloudify.tech"
xcloudify_api_timeout: 30
xcloudify_validate_ssl: true

# Custom API endpoint
xcloudify_api_url: "https://custom.xcloudify.com"

📋 Infrastructure Specification

Complete Example

xcloudify_infrastructure:
  # Network definitions
  networks:
    - name: "web-tier"
      vni: 1001
      ipv4_cidr: "10.1.0.0/24"
      ipv4_gateway: "10.1.0.1"
      ipv4_dns_servers: "8.8.8.8,8.8.4.4"
    
    - name: "app-tier"
      vni: 1002
      ipv4_cidr: "10.1.1.0/24"
      ipv4_gateway: "10.1.1.1"
    
    - name: "db-tier"
      vni: 1003
      ipv4_cidr: "10.1.2.0/24"
      ipv4_gateway: "10.1.2.1"
  
  # Volume definitions
  volumes:
    - name: "web-content"
      size_gb: 50
      type: "local"
      description: "Web content storage"
    
    - name: "app-data"
      size_gb: 100
      type: "local"
      description: "Application data"
    
    - name: "database-storage"
      size_gb: 500
      type: "local"
      description: "Database storage"
  
  # Container definitions
  containers:
    # Load balancer
    - name: "nginx-lb"
      image: "nginx:alpine"
      cpu_shares: 1
      mem_limit: 256
      ports:
        - internal: 80
          external: 80
          use_dns: true
        - internal: 443
          external: 443
          use_dns: true
      storage:
        - volume: "web-content"
          mount_point: "/usr/share/nginx/html"
          read_only: true
      networks: ["web-tier", "app-tier"]
      env:
        NGINX_WORKER_PROCESSES: "auto"
        NGINX_WORKER_CONNECTIONS: "1024"
    
    # Application servers
    - name: "app-server-1"
      image: "myapp:latest"
      cpu_shares: 2
      mem_limit: 512
      ports:
        - internal: 3000
          external: 3001
      storage:
        - volume: "app-data"
          mount_point: "/app/data"
      networks: ["app-tier", "db-tier"]
      env:
        NODE_ENV: "production"
        DB_HOST: "database"
        REDIS_HOST: "redis"
    
    - name: "app-server-2"
      image: "myapp:latest"
      cpu_shares: 2
      mem_limit: 512
      ports:
        - internal: 3000
          external: 3002
      storage:
        - volume: "app-data"
          mount_point: "/app/data"
      networks: ["app-tier", "db-tier"]
      env:
        NODE_ENV: "production"
        DB_HOST: "database"
        REDIS_HOST: "redis"
    
    # Database
    - name: "database"
      image: "postgres:13"
      cpu_shares: 2
      mem_limit: 1024
      storage:
        - volume: "database-storage"
          mount_point: "/var/lib/postgresql/data"
      networks: ["db-tier"]
      env:
        POSTGRES_DB: "myapp"
        POSTGRES_USER: "appuser"
        POSTGRES_PASSWORD: "{{ vault_db_password }}"
    
    # Cache
    - name: "redis"
      image: "redis:7-alpine"
      cpu_shares: 1
      mem_limit: 256
      networks: ["db-tier"]
      env:
        REDIS_PASSWORD: "{{ vault_redis_password }}"
      healthcheck:
        test: ["CMD", "redis-cli", "ping"]
        interval: 30
        timeout: 5
        retries: 3
      restart_policy:
        name: "unless-stopped"

## 🔄 Idempotency

The roles implement comprehensive idempotency:

- **State Detection**: Checks existing resources before operations
- **Change Detection**: Only modifies resources that have changed
- **Container Recreation**: Automatically recreates containers when image/config changes
- **Resource Dependencies**: Handles dependencies between networks, volumes, and containers

### Idempotency Examples

```bash
# First run - creates everything
ansible-playbook deploy.yml
# CHANGED: Networks=3, Volumes=3, Containers=5

# Second run - no changes
ansible-playbook deploy.yml  
# OK: Networks=3, Volumes=3, Containers=5

# Third run with image update - recreates containers
# (after updating image version in vars)
ansible-playbook deploy.yml
# CHANGED: Containers=5 (recreated)

🧪 Testing

Integration Tests

# Set test environment
export TEST_VDC_ID="your-test-vdc-id"
export XCLOUDIFY_BEARER_TOKEN="your-token"

# Run full test suite
ansible-playbook tests/test-infrastructure.yml

# Run with check mode
ansible-playbook tests/test-infrastructure.yml --check

Manual Testing

# Test individual components
ansible-playbook -e "xcloudify_vdc_id=your-vdc" examples/simple-web-app.yml --check
ansible-playbook -e "xcloudify_vdc_id=your-vdc" examples/simple-web-app.yml
ansible-playbook -e "xcloudify_vdc_id=your-vdc" examples/simple-web-app.yml --check  # Should show no changes

📚 Examples

Simple Deployment

# inventory/group_vars/all.yml
xcloudify_vdc_id: "550e8400-e29b-41d4-a716-446655440000"
xcloudify_bearer_token: "{{ vault_xcloudify_token }}"

# playbooks/deploy-web.yml
- hosts: localhost
  roles:
    - role: xcloudify_infrastructure
      vars:
        xcloudify_infrastructure:
          containers:
            - name: "my-web-app"
              image: "nginx:latest"
              ports:
                - internal: 80
                  external: 8080
                  use_dns: true

Advanced Deployment

See examples/multi-tier-app.yml for a complete multi-tier application example.

🔒 Security

Best Practices

• Store bearer tokens in Ansible Vault
• Use environment variables for CI/CD
• Validate SSL certificates in production
• Limit API token permissions
• Use separate tokens for admin operations

Vault Setup

# Create vault file
ansible-vault create group_vars/all/vault.yml

# Add token to vault
vault_xcloudify_token: "your-bearer-token"
vault_db_password: "your-db-password"

🐛 Troubleshooting

Common Issues

1. Authentication Errors

   Error: xCloudify API request failed: 401
   Solution: Check bearer token and permissions
   

2. VDC Not Found

   Error: Virtual Data Center not found
   Solution: Verify VDC ID and access permissions
   

3. Resource Conflicts

   Error: VNI already in use
   Solution: Use unique VNI values for networks
   

Debug Mode

# Enable detailed logging
xcloudify_debug: true
xcloudify_log_api_calls: true

Check Mode

# Preview changes without applying
ansible-playbook deploy.yml --check --diff

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Run linting
ansible-lint roles/

# Run tests
ansible-playbook tests/test-infrastructure.yml

📄 License

MIT License - see LICENSE file for details.

👥 Support

• Documentation: xCloudify Docs
• Issues: GitHub Issues
• Community: xCloudify Community

🏷️ Version History

📄 Changelog

See CHANGELOG.md for detailed release notes.

• v2.0.0: Full API parity with advanced features

  • Pod management and multi-container deployments
  • Healthchecks for container reliability
  • Restart policies (always, on-failure, etc.)
  • Injected files at runtime (base64 content)
  • Partial updates (PATCH) for zero-downtime changes
  • Enhanced validation, errors, and auth (token refresh)
  • Comprehensive tests and backward compatibility
  • Deprecations: Legacy full-recreate warns for partial updates

• v1.0.0: Initial release with core functionality

  • Container management
  • Network management
  • Volume management
  • Port forwarding
  • DNS integration
  • Idempotent operations
  • Check mode support