# Konfiguracja: Terraform i Ansible

Jak przygotować maszynę, z której uruchamiamy Terraform i Ansible: narzędzia, poświadczenia, zmienne środowiskowe i sprawdzenie, że wszystko działa.

> [!WARNING]
>
> **Sekrety**
>
> Żaden klucz nie trafia do repozytorium. Wartości bierzemy z Vault, trzymamy w lokalnym `.envrc` (jest w `.gitignore`) albo w `~/.config/scw/config.yaml`. Jedyny sekret w repo to wartości zaszyfrowane `ansible-vault`.

## 1\. Wymagania

| Narzędzie | Wersja | Po co | Skąd wymóg |
| --- | --- | --- | --- |
| Terraform | **\>= 1.6** | tworzenie zasobów Scaleway | `required_version`; blok `endpoints` backendu s3 |
| provider `scaleway/scaleway` | `~> 2.60` |  | `versions.tf`, zablokowany w `.terraform.lock.hcl` |
| Python | \>= 3.10 | ansible-core, SDK Scaleway |  |
| ansible-core | **\>= 2.15** (testowane 2.21) | konfiguracja hostów | `deb822_repository`, `systemd_service` w rolach |
| `scaleway` (Python SDK) | \>= 2.9.0 | wtyczka inwentarza `scaleway.scaleway.scaleway` | wymóg kolekcji |
| kolekcje Ansible | `community.general`, `ansible.posix`, `scaleway.scaleway` \>= 2.7.2 | moduły, inwentarz | `ansible/collections/requirements.yml` |
| ansible-lint | \>= 24 | kontrola jakości | `.config/ansible-lint.yml` |
| `scw` CLI | dowolna aktualna | sprawdzanie ID projektów i klucza API | opcjonalnie |
| direnv | dowolna | automatyczne ładowanie `.envrc` | opcjonalnie |

Hosty docelowe to Ubuntu, a nowe maszyny z Terraforma dostają 24.04 `ubuntu_noble`.

### Instalacja

```
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager addrepo --from-repofile=https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
sudo dnf install -y terraform python3 direnv
```

```
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install -y terraform python3-venv direnv
```

```
brew install hashicorp/tap/terraform python direnv
```

Ansible i jego zależności instalujemy w wirtualnym środowisku w katalogu repozytorium. Katalog `.venv/` jest w `.gitignore`:

```
cd logintegra-ansible
python3 -m venv .venv
. .venv/bin/activate
pip install -r ansible/requirements.txt
ansible-galaxy collection install -r ansible/collections/requirements.yml
```

## 2\. Poświadczenia Scaleway

Potrzebny jest klucz API aplikacji, tworzony w IAM -\> Applications -\> API keys, z uprawnieniami:

| Zakres | Uprawnienie | Dla |
| --- | --- | --- |
| projekty `apollo-qa`, `apollo-test` | `InstancesFullAccess` | Terraform: instancje, IP, security groups |
| projekt z bucketem na state | `ObjectStorageFullAccess` | backend Terraform |
| projekty, z których Ansible czyta hosty | `InstancesReadOnly` | inwentarz dynamiczny |

Klucz zapisujemy w Vault. Terraform, Ansible i `scw` CLI czytają go z tych samych zmiennych `SCW_*`.

## 3\. Zmienne środowiskowe

Wzór wszystkich zmiennych: [`.envrc.example`](<https://bitbucket.org/logintegraspzoo/logintegra-ansible/src/master/.envrc.example>).

```
cp .envrc.example .envrc     # uzupełnij wartości z Vault
direnv allow                 # albo: source .envrc
```

### Scaleway - Terraform, Ansible, `scw`

| Zmienna | Wymagana | Kto czyta | Znaczenie |
| --- | --- | --- | --- |
| `SCW_ACCESS_KEY` | tak | provider Terraform, inwentarz Ansible, `scw` | identyfikator klucza API (`SCW...`) |
| `SCW_SECRET_KEY` | tak | jw. | sekret klucza API (UUID) |
| `SCW_DEFAULT_ORGANIZATION_ID` | zalecana | jw. | organizacja Logintegra |
| `SCW_DEFAULT_PROJECT_ID` | nie | `scw` | **Terraform jej nie używa** - projekt bierze z `project_id` w `<env>.tfvars` |
| `SCW_DEFAULT_REGION` | nie | `scw` | `pl-waw` |
| `SCW_TOKEN` | dla playbooków start/stop | `perform-server-action-and-wait.yml` (i nakładki `start-`/`stop-`/`reboot-server-and-wait.yml`) | \= `SCW_SECRET_KEY`; playbook woła API Scaleway bezpośrednio i czyta klucz pod tą nazwą |
| `SCW_PROFILE`, `SCW_CONFIG_FILE` | nie | inwentarz Ansible, `scw` | alternatywa dla zmiennych: profil z `~/.config/scw/config.yaml` (`scw init`) |

### State Terraform - backend s3 na Object Storage

| Zmienna | Wymagana | Znaczenie |
| --- | --- | --- |
| `AWS_ACCESS_KEY_ID` | tak (przy `init`/`plan`/`apply`) | \= `SCW_ACCESS_KEY` - backend s3 czyta klucze pod nazwami AWS |
| `AWS_SECRET_ACCESS_KEY` | tak | \= `SCW_SECRET_KEY` |

### Ansible

| Zmienna | Wymagana | Znaczenie |
| --- | --- | --- |
| `ANSIBLE_PRIVATE_KEY_FILE` | tak | klucz prywatny pary `ansible/playbooks/ansible_key.pub`, czyli konta `ansible` na hostach |
| `ANSIBLE_REMOTE_USER` | zalecana | `ansible` - to konto zakłada cloud-init na nowych maszynach i `create-ansible-user.yaml` na starych |
| `ANSIBLE_VAULT_PASSWORD_FILE` | gdy używamy vault | plik z hasłem do `ansible-vault`, poza repozytorium |
| `ANSIBLE_CONFIG` | nie | tylko gdy uruchamiamy spoza `ansible/` - wskazuje `ansible/ansible.cfg` |

## 4\. Terraform

Wartości środowiska są w repo, w `terraform/environments/<env>/<env>.tfvars`, i nie ma wśród nich sekretów. Środowisko `qa` to mirror produkcji na hostach Tomcata w projekcie `apollo-qa`. Środowisko `test` to hosty apollo-docker testerów w projekcie `apollo-test`.

### Jednorazowo, per środowisko

1. Wpisz `project_id` w `<env>.tfvars`. Dopóki jest `"TODO"`, `plan` zatrzyma się na walidacji - celowo, żeby zasoby nie powstały w projekcie ustawionym akurat w shellu.

   ```
   scw account project list          # ID projektów apollo-qa i apollo-test
   ```
2. Bucket na state to `apollo-terraform-state` w Object Storage (region `pl-waw`), wpisany w `backend.tf` - jeden na wszystkie środowiska, klucze `qa/terraform.tfstate`, `test/terraform.tfstate`. Bucket ma włączone **wersjonowanie i Object Lock** - historia state jest chroniona ([FAQ Terraform](<https://docs.logintegra.com/logintegra-ansible/terraform-faq/index.md#1-gdzie-jest-state-i-jak-to-dziaa>)).

### Praca

```
cd terraform/environments/test                     # albo qa
terraform init
terraform fmt -check -recursive ../..
terraform validate
terraform plan -var-file=test.tfvars -out=test.tfplan
terraform apply test.tfplan                        # po akceptacji planu przez drugą osobę
```

Lokalnie, bez dostępu do state, np. przy sprawdzaniu składni w PR:

```
terraform init -backend=false && terraform validate
```

`.terraform.lock.hcl` jest w repo - wersję providera podnosimy świadomie (`terraform init -upgrade`) osobnym commitem.

## 5\. Ansible

Wszystkie polecenia **z katalogu `ansible/`** - stamtąd wczytuje się `ansible.cfg` (ścieżka ról, `force_valid_group_names`).

> [!WARNING]
>
> **Środowisko `test` tylko przez VPN**
>
> Security groups w `test` przepuszczają SSH wyłącznie z `logintegra-vpn` (151.115.59.12). Bez VPN Ansible zakończy się timeoutem połączenia.

```
cd ansible

# kogo widzi inwentarz i w jakich grupach (tag `apollo-docker` -> grupa tag_apollo_docker)
ansible-inventory -i inventory/test_scw.yml --graph

# połączenie
ansible -i inventory/test_scw.yml tag_docker -m ansible.builtin.ping

# stan docelowy: najpierw podgląd, potem zmiana
ansible-playbook -i inventory/test_scw.yml playbooks/state/site.yml --check --diff
ansible-playbook -i inventory/test_scw.yml playbooks/state/site.yml

# jedna maszyna
ansible-playbook -i inventory/test_scw.yml -l test-apollo-wombaty-docker-01 playbooks/state/site.yml

# lint
ansible-lint
```

### Dane, które trzeba uzupełnić przed pierwszym uruchomieniem

| Co | Gdzie | Skąd |
| --- | --- | --- |
| klucze publiczne agentów TeamCity | `inventory/group_vars/all.yml` -\> `teamcity_access_authorized_keys` | Vault: `Public key: SSH Access to servers from TeamCity Apollo` |
| klucz Bitbucket dla apollo-docker | `inventory/group_vars/tag_apollo_docker.yml` -\> `vault_apollo_docker_deploy_key` | Vault; zaszyfrować (niżej) |

```
ansible-vault encrypt_string --name vault_apollo_docker_deploy_key < klucz_bitbucket
# wynik wkleić do tag_apollo_docker.yml i odkomentować apollo_docker_deploy_key
```

## 6\. Sprawdzenie konfiguracji

```
terraform version                                   # >= 1.6
ansible --version | head -1                         # core >= 2.15
python -c "import scaleway; print(scaleway.__version__)"   # >= 2.9, w Pythonie Ansible'a
ansible-galaxy collection list | grep -E "scaleway|posix|community.general"
env | grep -E "^(SCW|AWS|ANSIBLE)_" | sed 's/=.*/=***/'  # czy zmienne są ustawione
scw account project list                            # czy klucz działa
cd ansible && ansible-inventory -i inventory/test_scw.yml --graph
```

## 7\. Problemy

| Objaw | Przyczyna | Rozwiązanie |
| --- | --- | --- |
| `Invalid secrets, access_key & secret_key must be defined` | brak `SCW_ACCESS_KEY` / `SCW_SECRET_KEY` w środowisku i brak profilu `scw` | `source .envrc` / `direnv allow` |
| `authentication is denied ... "reason":"not_found"` | klucz API nie istnieje albo jest z innej organizacji | sprawdzić klucz w Vault / IAM |
| `Failed to import the required Python library (scaleway)` | SDK w innym Pythonie niż Ansible | `pip install -r ansible/requirements.txt` w venv Ansible'a |
| inwentarz pusty, bez błędu | żaden host nie ma taga środowiska. `qa_scw.yml` jest pusty do czasu pierwszego `apply` w `qa`. | tagi hostów w konsoli / w Terraformie |
| `-l tag_apollo-docker` nic nie wybiera | myślnik w tagu -\> podkreślenie w grupie | `-l tag_apollo_docker` |
| `the role 'users' was not found` / lint zgłasza `syntax-check` | uruchomienie spoza `ansible/` | `cd ansible` albo `ANSIBLE_CONFIG=ansible/ansible.cfg` |
| `project_id: ID projektu ... (UUID)` przy `plan` | `project_id = "TODO"` w `<env>.tfvars` | wpisać ID projektu (sekcja 4) |
| `Backend initialization required` | brak `terraform init` w katalogu środowiska | `terraform init` |
| `No valid credential sources found` przy `init` | brak `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | ustawić = klucze Scaleway |
| `--check`: `Either user must exist or you must provide full path to key file` | konto jeszcze nie istnieje, a `authorized_key` w trybie próbnym tego nie przewidzi | normalne na nowej maszynie; zwykłe uruchomienie przechodzi |
