Skip to content
BranchesTags

Repository files navigation

Kickstart Action

A GitHub Action that automatically generates kickstart.json configuration files for AI Pilot Multi-Service Compositions (MSC) based on deployment configuration and architectural templates.

🎯 Overview

The Kickstart Action combines deployment-specific configuration with predefined architectural templates to generate complete kickstart.json files that can be used for AI Pilot MSC deployment via Ansible Automation Platform (AAP).

✨ Features

  • Automatic Generation: Creates kickstart.json from deployment-config.yml
  • Environment Management: Uses environment-specific configurations for endpoints, orgs, and settings
  • Template-Based: Uses architectural templates for different distributions and sizing
  • PR Integration: Commits generated files back to pull requests
  • Validation: Validates generated configuration before committing
  • Flexible: Supports multiple environments, distributions, and sizing options

🏗️ Architecture

Directory Structure

kickstart-action/
├── action.yml                 # Main action definition
├── scripts/
│   ├── generate_kickstart.py  # Main generation script
│   └── validate_kickstart.py  # Validation script
├── config/
│   └── environments/
│       ├── dev.json           # Development environment config
│       ├── pat.json           # Pre-production environment config
│       └── prod.json          # Production environment config
├── templates/
│   ├── simple/
│   │   ├── minimal.json       # Simple, minimal resources
│   │   └── default.json       # Simple, standard resources
│   ├── ha/
│   │   └── minimal.json       # High availability, minimal
│   └── [other distributions]/
└── examples/
    └── deployment-config.yml  # Example configuration

Template Categories

Geographic Distribution

  • simple: Single-region deployment
  • ha: High availability with redundancy
  • dr: Disaster recovery setup
  • geo: Multi-geographic distribution

Resource Sizing

  • minimal: Minimal resources for development/testing
  • default: Standard sizing for production
  • large: High-performance resources

🚀 Usage

1. Basic Usage

Add this workflow to your repository:

# .github/workflows/kickstart-generator.yml
name: Generate Kickstart Configuration

on:
  pull_request:
    paths:
      - 'infrastructure/deployment-config.yml'
    types: [opened, synchronize]

jobs:
  generate-kickstart:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          token: ${{ github.token }}
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install pyyaml jinja2

      - name: Generate kickstart.json
        run: |
          python scripts/generate_kickstart.py \
            --config infrastructure/deployment-config.yml \
            --templates-dir infrastructure/kickstart-templates \
            --output infrastructure/kickstart.json

      - name: Validate generated kickstart.json
        run: |
          python scripts/validate_kickstart.py \
            --kickstart-file infrastructure/kickstart.json

      - name: Commit kickstart.json to PR
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add infrastructure/kickstart.json
          git commit -m "Auto-generate kickstart.json from deployment config" || exit 0
          git push

2. Create Deployment Configuration

Create infrastructure/deployment-config.yml:

deployment:
  composition_name: "ai-pilot-msc"
  version: "1.0.0"
  description: "AI Pilot Multi-Service Composition for Development"
  deployment_id: "ai-pilot-dev-001"
  
  # Environment configuration (determines which env config to load)
  environment: "dev"
  
  # Resource naming (optional - defaults from environment config)
  resource_prefix: "aipilot"
  resource_group_name: "aipilot-dev-rg"  # Optional - auto-generated if not specified
  
  # Platform configuration
  platform: "torc"
  line_of_business: "ai pilot"
  owner_team: "ai-pilot-dev"
  appcode: "ai-pilot"

architecture:
  distribution: "simple"  # simple, ha, dr, geo
  sizing: "minimal"       # minimal, default, large

tags:
  # Additional tags (merged with environment-specific tags)
  project: "ai-pilot"
  team: "ai-pilot-dev"

Note: Environment-specific values like endpoints, organization IDs, subscription IDs, and default tags are managed centrally in the action's environment configuration files (config/environments/{env}.json).

3. Add Templates Directory

Create infrastructure/kickstart-templates/ with your architectural templates:

infrastructure/kickstart-templates/
├── simple/
│   ├── minimal.json
│   └── default.json
├── ha/
│   ├── minimal.json
│   └── default.json
└── dr/
    └── default.json

📋 Configuration Options

Deployment Configuration (deployment-config.yml)

Required Fields

  • deployment.composition_name: Name of the composition
  • deployment.environment: Environment name (dev, pat, prod)
  • architecture.distribution: Geographic distribution (simple, ha, dr, geo)
  • architecture.sizing: Resource sizing (minimal, default, large)

Optional Fields

  • deployment.resource_prefix: Resource naming prefix (defaults from environment config)
  • deployment.resource_group_name: Resource group name (auto-generated if not specified)
  • tags: Additional tags (merged with environment-specific tags)

Environment-Specific Values (Managed by Action)

The following values are automatically loaded from environment configuration files:

  • AAP workflow settings (workflow_id, organization_id, inventory_id)
  • Azure settings (subscription_id, primary_location)
  • Nexus URL
  • TFE settings (endpoint, organization)
  • Infrastructure settings (discovery_mode, use_stable_infrastructure)
  • Default tags and naming conventions

Environment Configuration

Environment-specific values are managed in config/environments/{environment}.json files:

{
  "environment": "dev",
  "description": "Development environment configuration",
  
  "aap": {
    "workflow_name": "msc_ai_pilot_v1",
    "workflow_id": 41,
    "organization_id": 2,
    "inventory_id": 4
  },
  
  "azure": {
    "subscription_id": "your-subscription-id",
    "primary_location": "eastus",
    "resource_group_suffix": "dev-rg"
  },
  
  "nexus": {
    "url": "http://your-nexus-url:8081"
  },
  
  "tfe": {
    "endpoint": "https://app.terraform.io/api/v2",
    "organization": "your-org"
  },
  
  "infrastructure": {
    "use_stable_infrastructure": false,
    "discovery_mode": false
  },
  
  "naming": {
    "env_suffix": "ai-dev",
    "env_class": "dev",
    "resource_prefix_default": "aipilot"
  },
  
  "tags": {
    "environment": "dev",
    "data_classification": "internal",
    "backup_required": "false"
  }
}

Template Structure

Each template should follow this structure:

{
  "distribution": "simple",
  "sizing": "minimal",
  "description": "Description of this template",
  "services": {
    "service_name": {
      "description": "Service description",
      "variables": {
        "variable_name": "{{ template_variable }}",
        "static_value": "fixed_value"
      }
    }
  }
}

🔧 Scripts

generate_kickstart.py

Main script for generating kickstart.json files.

python scripts/generate_kickstart.py \
  --config infrastructure/deployment-config.yml \
  --templates-dir infrastructure/kickstart-templates \
  --output infrastructure/kickstart.json \
  --validate

Options:

  • --config: Path to deployment configuration file
  • --templates-dir: Directory containing architectural templates
  • --output: Output path for generated kickstart.json
  • --validate: Validate the generated kickstart.json

validate_kickstart.py

Validates generated kickstart.json files.

python scripts/validate_kickstart.py \
  --kickstart-file infrastructure/kickstart.json \
  --verbose

Options:

  • --kickstart-file: Path to kickstart.json file to validate
  • --verbose: Enable verbose output

📁 Generated Files

The action generates a kickstart.json file with this structure:

{
  "metadata": {
    "composition_name": "ai-pilot-msc",
    "version": "1.0.0",
    "description": "AI Pilot Multi-Service Composition",
    "created_at": "2024-01-01T00:00:00Z",
    "composition_type": "ai-pilot",
    "generated_by": "kickstart-action",
    "distribution": "simple",
    "sizing": "minimal"
  },
  "aap_workflow": {
    "workflow_name": "msc_ai_pilot_v1",
    "workflow_id": 41,
    "description": "AI Pilot Provisioning Workflow",
    "organization_id": 2,
    "inventory_id": 4
  },
  "files": {
    "context": {
      "path": "infrastructure/torc/context.json",
      "purpose": "Global context and metadata",
      "content": { ... }
    },
    "env_config": {
      "path": "infrastructure/environments/dev/env_config.json",
      "purpose": "Environment configuration with tfvars mappings",
      "content": { ... }
    },
    "tfvars": {
      "resource_group": {
        "path": "infrastructure/environments/dev/resource_group.terraform.auto.tfvars.json",
        "service_name": "resource_group",
        "content": { ... }
      }
    }
  },
  "generation_rules": {
    "file_naming_convention": "{service_name}.terraform.auto.tfvars.json",
    "path_structure": "infrastructure/environments/dev/",
    "env_config_mapping": { ... },
    "workspace_naming_convention": "{service_name}-dev-ai-dev",
    "common_values": { ... }
  }
}

🔒 Permissions

The action requires these permissions:

permissions:
  contents: write      # To commit back to PR
  pull-requests: write # To comment on PR

🧪 Testing

Local Testing

  1. Clone the action repository
  2. Install dependencies: 
    pip install pyyaml jinja2
  3. Run the generation script: 
    python scripts/generate_kickstart.py \
  --config examples/deployment-config.yml \
  --templates-dir templates \
  --output test-kickstart.json \
  --validate

Manual Workflow Trigger

You can manually trigger the workflow with custom parameters:

on:
  workflow_dispatch:
    inputs:
      config_path:
        description: 'Path to deployment configuration file'
        required: true
        default: 'infrastructure/deployment-config.yml'
      templates_dir:
        description: 'Directory containing architectural templates'
        required: true
        default: 'infrastructure/kickstart-templates'
      output_path:
        description: 'Output path for generated kickstart.json'
        required: true
        default: 'infrastructure/kickstart.json'

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For issues and questions:

  1. Check the Issues page
  2. Create a new issue with detailed information
  3. Include your deployment configuration and error messages

🔄 Version History

  • v1.0.0: Initial release with basic kickstart generation
  • v1.1.0: Added validation and PR integration
  • v1.2.0: Added template system and multiple distributions

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages