Ympäristön hallinta (IaC)¶

Tämä dokumentti kuvaa infrastruktuurin hallintamallin, jonka tavoitteena on varmistaa ympäristön toistettavuus, vikasietoisuus ja hallittu elinkaari määrittelemällä koko kokonaisuus koodina.

graph LR
    %% REPOSITORY
    subgraph GITLAB ["GitLab Cloud"]
        REPO_OPS[("rs-ops.git<br/>(IaC Repository)")]
        PIPELINE["GitLab CI/CD<br/>Pipeline"]
    end

    %% IACO TOOLS
    subgraph IAC_TOOLS ["Infrastructure tools"]
        direction TB
        ANSIBLE[["Ansible<br/>(OS & Config)"]]
        DOCKER_C[["Docker Compose<br/>(Services)"]]
        VAGRANT[["Vagrant<br/>(VM Provisoning)"]]
    end

    %% TARGETS
    subgraph ASUS_HQ ["ASUS HQ (Local)"]
        WIN_HOST["Windows Host"]
        V_BOX["VirtualBox"]
        DEV_VM[("DEV_VM<br/>Ubuntu Server")]
    end

    subgraph HP_PROD ["HP PRODUCTION CLUSTER"]
        HP1[("HP-1<br/>Storage")]
        HP2[("HP-2<br/>Gateway")]
        HP3[("HP-3<br/>Action")]
    end

    %% CONNECTIONS
    REPO_OPS --> PIPELINE
    PIPELINE --> ANSIBLE
    PIPELINE --> DOCKER_C

    %% Deployment flow
    ANSIBLE -.-> |"SSH Config"| HP1
    ANSIBLE -.-> |"SSH Config"| HP2
    ANSIBLE -.-> |"SSH Config"| HP3
    ANSIBLE -.-> |"SSH Config"| DEV_VM

    DOCKER_C -.-> |"Deploy Containers"| HP1
    DOCKER_C -.-> |"Deploy Containers"| HP2
    DOCKER_C -.-> |"Deploy Containers"| HP3

    VAGRANT --> |"Manage"| V_BOX
    V_BOX --> DEV_VM

    %% Developer Interaction
    WIN_HOST -- "Git Push" --> REPO_OPS

    %% Styles
    style REPO_OPS fill:#f9f,stroke:#333,stroke-width:2px
    style PIPELINE fill:#e1f5fe,stroke:#01579b
    style ANSIBLE fill:#ffccbc,stroke:#bf360c
    style DOCKER_C fill:#e1f5fe,stroke:#0277bd
    style HP_PROD fill:none,stroke:#1976d2,stroke-width:3px

1. Strateginen tavoite¶

Infrastruktuurin versionhallinnan tarkoituksena on eliminoida "manuaalinen säätäminen". Kaikki muutokset palvelimiin (HP-1, HP-2, HP-3 ja DEV_VM) tehdään koodin kautta, jolloin ympäristö on palautettavissa nollasta toimintakuntoon alle 30 minuutissa.

Keskeiset hyödyt:¶

Toistettavuus: Identtiset ympäristöt kehitykseen (DEV) ja tuotantoon (PROD).
Dokumentaatio: Koodi itsessään toimii ajantasaisena dokumentaationa infran tilasta.
Turvallisuus: Salaisuudet hallitaan hallitusti (esim. Ansible Vault).

2. Hallinnan arkkitehtuuri¶

Infrastruktuuri hallitaan kolmessa kerroksessa, joista jokaisella on oma vastuualueensa:

Kerros	Työkalu	Kohde	Kuvaus
Provisiointi	Vagrant	DEV_VM	Virtuaalikoneen raudan (RAM, CPU, Verkko) määrittely.
Konfiguraatio	Ansible	OS & Klusteri	Käyttöjärjestelmän asetukset, SSH, paketit ja Dockerin asennus.
Palvelut	Docker Compose	Sovellukset	Tietokannat (Qdrant, Postgres), MCP-serverit ja AI-agentit.

Työnkulun visualisointi¶

graph LR
    subgraph GITLAB ["GitLab Cloud"]
        REPO_OPS[("rs-ops.git<br/>Source of Truth")]
        PIPELINE["GitLab CI/CD<br/>Automation"]
    end

    subgraph TOOLS ["IaC Engine"]
        ANSIBLE[["Ansible<br/>OS Config"]]
        DOCKER[["Docker Compose<br/>Services"]]
    end

    subgraph TARGETS ["Physical & Virtual Nodes"]
        HP1["HP-1 (Storage)"]
        HP2["HP-2 (Gateway)"]
        HP3["HP-3 (Action)"]
        VM["DEV_VM (Ubuntu)"]
    end

    REPO_OPS --> PIPELINE
    PIPELINE --> ANSIBLE
    PIPELINE --> DOCKER
    ANSIBLE -.-> |"SSH"| TARGETS
    DOCKER -.-> |"Runtime"| TARGETS

3. Repositorion rakenne (rs-ops)¶

Suositeltu hakemistorakenne versionhallintaan:

rs-ops/
├── ansible/                # Käyttöjärjestelmäkerros
│   ├── inventory.ini       # Solmujen (HP1-3, VM) osoitteet
│   ├── site.yml            # Pääkonfiguraatio
│   └── roles/              # Modulaariset roolit (docker, ollama, mcp-deps)
├── docker/                 # Sovelluskerros
│   ├── databases/          # Qdrant & PostgreSQL
│   └── mcp-servers/        # MCP-palvelinten kontit
├── vagrant/
│   └── Vagrantfile         # DEV_VM:n määrittely
└── README.md

4. Käytännön esimerkit toteutuksen suunnittelua varten (IaC-koodi)¶

Tässä osiossa kuvataan konkreettiset koodiesimerkit siitä, miten infrastruktuuria hallitaan ohjelmallisesti. Kaikki alla olevat tiedostot säilytetään rs-ops-repositoriossa.

A. Konfiguraatio (Ansible)¶

Ansible varmistaa, että kaikissa solmuissa (HP-1, HP-2, HP-3 ja DEV_VM) on identtiset perusasetukset. Tämä poistaa tarpeen asentaa paketteja manuaalisesti SSH:n kautta.

Tiedosto: ansible/playbook_base_config.yml

---
- name: RS Infra - Perusominaisuuksien varmistaminen
  hosts: rs_nodes
  become: yes
  tasks:
    - name: Päivitä pakettivarastot (apt update)
      apt:
        update_cache: yes
        cache_valid_time: 3600

    - name: Asenna tarvittavat järjestelmätyökalut
      apt:
        name:
          - curl
          - git
          - python3-pip
          - htop
          - ufw  # Palomuuri
        state: present

    - name: Varmista että Docker on asennettu ja käynnissä
      apt:
        name: 
          - docker.io
          - docker-compose
        state: present

    - name: Salli SSH-liikenne palomuurissa
      ufw:
        rule: allow
        name: OpenSSH
        state: enabled

B. Palvelun määrittely (Docker Compose)¶

Docker Composea käytetään sovelluskerroksen (tietokannat ja AI-palvelut) hallintaan. Se takaa, että palvelut käynnistyvät aina samoilla parametreilla.

Tiedosto: docker/databases/docker-compose.yml

version: '3.8'

services:
  # Qdrant: Vektoritietokanta AI-kontekstia varten
  qdrant:
    image: qdrant/qdrant:latest
    container_name: rs_qdrant
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - ./qdrant_storage:/qdrant/storage
    restart: unless-stopped

  # PostgreSQL: Rakenteellinen data ja tilanhallinta
  postgres:
    image: postgres:15-alpine
    container_name: rs_db
    environment:
      POSTGRES_DB: repostage
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: ${DB_PASSWORD} # Haetaan ympäristömuuttujasta
    ports:
      - "5432:5432"
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

C. Virtuaaliympäristön hallinta (Vagrant)¶

ASUS-isäntäkoneella pyörivä DEV_VM määritellään yhdellä tiedostolla, joka varaa tarvittavat resurssit VirtualBoxista.

Tiedosto: vagrant/Vagrantfile

Vagrant.configure("2") do |config|
  config.vm.box = "ubuntu/focal64"
  config.vm.network "forwarded_port", guest: 80, host: 8080

  config.vm.provider "virtualbox" do |vb|
    vb.memory = "4096"
    vb.cpus = 2
    vb.name = "RepoStage-DEV-VM"
  end

  # Automaattinen asennus käynnistyksen yhteydessä
  config.vm.provision "shell", inline: <<-SHELL
    apt-get update
    apt-get install -y docker.io
  SHELL
end

5. Operatiivinen prosessi¶

Tämä osio kuvaa standardoidun työnkulun, jota noudatetaan aina, kun infrastruktuuriin tehdään muutoksia. Tavoitteena on välttää manuaalisia virheitä ja varmistaa, että Git-repositorio on aina "Source of Truth" (ajantasaisin tieto).

Muutoksen elinkaari:¶

Muutos (Change): Kehittäjä muokkaa IaC-tiedostoja (esim. ansible/site.yml tai docker-compose.yml) paikallisessa DEV_VM-ympäristössä.
- Esimerkki: Lisätään uusi MCP-palvelin (Filesystem) solmuun HP-3.
Tallennus (Commit): Muutokset tallennetaan versionhallintaan selkeällä viestillä.
```
git add .
git commit -m "Add MCP-filesystem server to HP-3"
```
Synkronointi (Push): Muutokset lähetetään GitLab-palvelimelle.
```
git push origin main
```
Käyttöönotto (Deploy): GitLab CI/CD -pipeline käynnistyy.
- GitLab Runner (HP-2) lukee uudet konfiguraatiot.
- Runner ajaa Ansible-playbookin: ansible-playbook -i inventory.ini site.yml.
- Kohdepalvelin (esim. HP-3) päivittyy automaattisesti vastaamaan uutta määrittelyä.

6. Disaster Recovery (Vikasietoisuus)¶

RS Infran suurin vahvuus on sen kyky toipua täydellisestä laiterikosta erittäin nopeasti. Koska konfiguraatiota ei säilytetä vain palvelimen muistissa, vaan koodina, palautus on suoraviivaista.

Skenaario: Fyysinen HP-palvelin rikkoutuu¶

Jos esimerkiksi HP-1 (Storage) rikkoutuu pysyvästi, palautusprosessi on seuraava:

Uusi rauta: Hankitaan uusi fyysinen laite (tai asennetaan käyttöjärjestelmä uudelleen vanhalle).
Perusyhteys: Varmistetaan, että uudessa laitteessa on SSH-yhteys ja sama IP-osoite (tai päivitetään uusi IP inventory.ini-tiedostoon).
Automaattinen palautus: Ajetaan Ansible-ajo omalta koneelta tai GitLabista:
```
ansible-playbook -i inventory.ini site.yml --limit hp_1
```
Tulos: * Ansible asentaa Dockerin, Pythonin ja tarvittavat kirjastot.
- Docker Compose pystyttää PostgreSQL- ja Qdrant-kontit.
- Infra palautuu automaattisesti viimeisimpään tunnettuun toimivaan tilaan.

[!IMPORTANT] Huomio datasta: IaC palauttaa palvelut ja konfiguraatiot. Varsinainen data (tietokantojen sisältö) tulee palauttaa erillisistä varmuuskopioista (Backups), jotka on tallennettu HP-klusterin ulkopuolelle.