GovStack IM Connection - Information Mediator Security Server Automation

This repository provides Ansible automation for deploying and configuring Information Mediator Security Servers in GovStack environments. It simplifies the complex process of setting up Information Mediator Security Servers by automating certificate management, configuration, and registration.

What is This?

This tool automates the deployment of Information Mediator Security Servers - secure data exchange components that enable organizations to securely share data and services. It handles:

• Installation: Deploys IM Security Server to Kubernetes using Helm
• Certificate Management: Creates, signs, and imports certificates automatically
• Configuration: Sets up IM Security Server with proper authentication and signing keys
• Registration: Registers the IM Security Server with the Central Server
• Subsystem Setup: Configures subsystems (services) on the IM Security Server

Quick Start

New users: Start with GETTING_STARTED.md for a quick 5-minute setup.

Want to understand X-Road first? Read X-ROAD_BASICS.md to understand the concepts.

Need detailed instructions? Follow the INSTALLATION_GUIDE.md for step-by-step instructions.

Prerequisites

Before you begin, ensure you have:

1. Ansible 2.9+ installed
2. kubectl configured with access to your Kubernetes cluster
3. helm 3.0+ installed
4. Python kubernetes library: pip install kubernetes
5. Network access to:
   • Central Server (for configuration anchor)
   • Test CA endpoints (for certificate signing)
   • IM Security Server cluster (for deployment)

Repository Structure

govstack-im-connector/
├── README.md                    # This file
├── ansible.cfg                  # Ansible configuration
├── inventory.yml               # Ansible inventory
├── installation.yml             # Installation playbook
├── configure-step1.yml          # Pre-approval configuration playbook
├── configure-step2.yml          # Post-approval configuration playbook
├── teardown.yml                 # Cleanup playbook
├── prepare_anchor.yml            # Repository preparation (maintainers only - DO NOT RUN)
├── group_vars/                  # Configuration variables
│   └── all/
│       ├── all.yml              # Default variables
│       ├── config.yml           # User configuration
│       └── secrets.yml          # Secrets (create this)
├── helm-chart/                  # Helm chart for IM Security Server
├── roles/                       # Ansible roles
│   ├── installation/            # Installation tasks
│   ├── configure_pre_approval/  # Pre-approval configuration
│   ├── configure_post_approval/ # Post-approval configuration
│   ├── prepare_anchor/          # Repository preparation (maintainers only)
│   └── ...
├── certs/                       # Certificate storage (created at runtime)
└── docs/                        # Documentation
    ├── X-ROAD_BASICS.md         # X-Road concepts explained
    ├── INSTALLATION_GUIDE.md    # Step-by-step installation
    ├── CONFIGURATION_GUIDE.md   # Configuration details
    └── TROUBLESHOOTING.md       # Common issues and solutions

Documentation

• X-Road Basics - Learn about X-Road concepts, components, and terminology
• Installation Guide - Step-by-step installation instructions
• Configuration Guide - Detailed configuration options
• Troubleshooting - Common issues and solutions
• Quick Reference - Quick command reference
• Architecture - Architecture and design decisions
• Setup for Maintainers - Repository preparation guide (for maintainers only)

IMPORTANT: Note for End Users: The prepare_anchor.yml playbook and prepare_anchor role are for repository maintainers only. End users should NOT run these - the configuration anchor and certificates are already prepared in the repository.

Typical Workflow

1. Configure Variables: Edit group_vars/all/config.yml and create group_vars/all/secrets.yml (see Configuration Guide)

2. Install IM Security Server (on IM Security Server cluster)

   ansible-playbook installation.yml

3. Configure IM Security Server (pre-approval phase)

   ansible-playbook configure-step1.yml

4. Wait for Certificate Approval: Central Server administrators must approve your authentication certificate

5. Complete Configuration (post-approval phase)

   ansible-playbook configure-step2.yml

Key Features

• Automated Certificate Management: Creates, signs, and imports certificates
• Two-Phase Configuration: Pre-approval and post-approval stages
• Kubernetes Native: Uses Helm for deployment
• Idempotent: Safe to run multiple times
• Standalone Deployment: Works with separate clusters
• Comprehensive Logging: Detailed logs for troubleshooting

Support

For issues, questions, or contributions, please refer to the documentation in the docs/ directory or check the troubleshooting guide.

License

[License information to be added here]