IAC Tools Docker Image

Docker-образ с инструментами для Infrastructure as Code:

• kubectl — CLI для управления Kubernetes-кластерами
• helm — пакетный менеджер для Kubernetes
• helm-diff — плагин Helm для сравнения релизов
• helmfile — декларативное управление Helm-релизами
• terraform — IaC для Proxmox и облачной инфраструктуры (ah-cloud)
• terragrunt — оркестрация Terraform-модулей
• ansible — автоматизация конфигурации серверов

Для Helm charts используйте отдельный образ: ghcr.io/ilyario/ah-helm-charts.

Quick Start

Using the pre-built image

docker run -it --rm ghcr.io/your-username/iac-tools:latest

Building locally

# Build with default versions (linux/amd64)
docker build --platform linux/amd64 -t iac-tools .

# Build with specific versions
docker build \
  --platform linux/amd64 \
  --build-arg KUBECTL_VERSION=v1.34.8 \
  --build-arg HELM_VERSION=v3.21.1 \
  --build-arg HELMFILE_VERSION=v1.5.1 \
  --build-arg TERRAFORM_VERSION=1.15.6 \
  --build-arg TERRAGRUNT_VERSION=v1.0.8 \
  --build-arg ANSIBLE_CORE_VERSION=2.21.0 \
  -t iac-tools .

Usage

Interactive shell

docker run -it --rm iac-tools

Mount current directory

docker run -it --rm -v $(pwd):/workspace iac-tools

Using kubectl

docker run -it --rm -v ~/.kube:/root/.kube iac-tools kubectl get pods

Using helm

docker run -it --rm -v ~/.kube:/root/.kube iac-tools helm list

Using helmfile

docker run -it --rm -v $(pwd):/workspace -v ~/.kube:/root/.kube iac-tools helmfile apply

Using terraform

docker run -it --rm \
  -v $(pwd)/ah-cloud/terraform:/workspace \
  -e PROXMOX_VE_ENDPOINT \
  -e PROXMOX_VE_API_TOKEN \
  iac-tools terraform -chdir=/workspace init

docker run -it --rm \
  -v $(pwd)/ah-cloud/terraform:/workspace \
  -e PROXMOX_VE_ENDPOINT \
  -e PROXMOX_VE_API_TOKEN \
  iac-tools terraform -chdir=/workspace plan

Using terragrunt

docker run -it --rm \
  -v $(pwd):/workspace \
  -e PROXMOX_VE_ENDPOINT \
  -e PROXMOX_VE_API_TOKEN \
  iac-tools terragrunt run-all plan

Using ansible

docker run -it --rm \
  -v $(pwd)/ansible:/workspace \
  -v ~/.ssh:/root/.ssh \
  -e ANSIBLE_HOST_KEY_CHECKING=false \
  iac-tools bash -c "ansible-galaxy install -r requirements.yml && ansible-playbook -i inventories/k3s_pc/hosts k3s_pc.yml"

Verify installed tools

chmod +x scripts/verify-tools.sh
docker build -t iac-tools .
./scripts/verify-tools.sh iac-tools

Or check individually:

docker run --rm iac-tools kubectl version --client
docker run --rm iac-tools helm version
docker run --rm iac-tools helm plugin list
docker run --rm iac-tools helmfile version
docker run --rm iac-tools terraform version
docker run --rm iac-tools terragrunt --version
docker run --rm iac-tools ansible --version

Environment Variables

Kubernetes / Helm

• KUBECONFIG — path to kubectl configuration file
• HELM_KUBECONFIG — path to helm configuration file

Terraform / Terragrunt

• TF_VAR_* — Terraform input variables
• PROXMOX_VE_ENDPOINT — Proxmox API endpoint
• PROXMOX_VE_API_TOKEN — Proxmox API token
• TF_IN_AUTOMATION — set to true in CI pipelines

Ansible

• ANSIBLE_CONFIG — path to ansible.cfg
• ANSIBLE_HOST_KEY_CHECKING — disable SSH host key checks in CI (false)
• ANSIBLE_PRIVATE_KEY_FILE — path to SSH private key

CI/CD Examples

GitHub Actions — helmfile

- name: Deploy with helmfile
  run: |
    docker run --rm \
      -v ${{ github.workspace }}:/workspace \
      -v $HOME/.kube:/root/.kube \
      -e KUBECONFIG=/root/.kube/config \
      ghcr.io/your-username/iac-tools:latest helmfile apply

GitHub Actions — terraform

- name: Terraform plan
  run: |
    docker run --rm \
      -v ${{ github.workspace }}/ah-cloud/terraform:/workspace \
      -e PROXMOX_VE_ENDPOINT \
      -e PROXMOX_VE_API_TOKEN \
      -e TF_IN_AUTOMATION=true \
      ghcr.io/your-username/iac-tools:latest terraform -chdir=/workspace plan -input=false

GitHub Actions — ansible

- name: Run ansible playbook
  run: |
    docker run --rm \
      -v ${{ github.workspace }}/ansible:/workspace \
      -v $HOME/.ssh:/root/.ssh \
      -e ANSIBLE_HOST_KEY_CHECKING=false \
      ghcr.io/your-username/iac-tools:latest \
      bash -c "ansible-galaxy install -r requirements.yml && ansible-playbook -i inventories/k3s_pc/hosts k3s_pc.yml"

GitLab CI

deploy:
  image: ghcr.io/your-username/iac-tools:latest
  script:
    - helmfile apply
  before_script:
    - echo "$KUBECONFIG" | base64 -d > /root/.kube/config

terraform:
  image: ghcr.io/your-username/iac-tools:latest
  script:
    - cd ah-cloud/terraform
    - terraform init -backend=false
    - terraform validate

ansible:
  image: ghcr.io/your-username/iac-tools:latest
  script:
    - cd ansible
    - ansible-galaxy install -r requirements.yml
    - ansible-playbook -i inventories/k3s_pc/hosts k3s_pc.yml

Included Tools

Tool	Version	Description
kubectl	Configurable (default: v1.34.8)	Kubernetes command-line tool
helm	Configurable (default: v3.21.1)	Kubernetes package manager
helm-diff	Configurable (default: v3.15.7)	Helm plugin for diffing releases
helmfile	Configurable (default: v1.5.1)	Declarative Helm deployments
terraform	Configurable (default: 1.15.6)	Infrastructure as Code (from hashicorp/terraform image)
terragrunt	Configurable (default: v1.0.8)	Terraform orchestration
ansible-core	Configurable (default: 2.21.0)	Server configuration automation

Releases (Semver)

Проект использует автоматическое версионирование по Semantic Versioning на основе Conventional Commits.

Как это работает

1. При push в main запускается workflow Release (Semver)
2. semantic-release анализирует коммиты с последнего тега
3. По типу коммитов определяется следующая версия:
   • fix: → patch (v1.3.5 → v1.3.6)
   • feat: → minor (v1.3.5 → v1.4.0)
   • BREAKING CHANGE: в footer или ! после типа → major (v1.3.5 → v2.0.0)
4. Обновляется CHANGELOG.md, создаётся git-тег vX.Y.Z и GitHub Release
5. Workflow собирает и публикует Docker-образ с тегами vX.Y.Z, X.Y.Z и latest

Формат коммитов

<type>(<scope>): <description>

[optional body]

[optional footer]

Примеры:

feat: add yq to image
fix(dockerfile): correct helmfile download URL
build(kubectl): bump kubectl to v1.35.0

Breaking change:

feat(api)!: remove deprecated tool

BREAKING CHANGE: terragrunt binary path has changed

Docker image tags

docker pull ghcr.io/ilyario/iac-tools:v1.3.5
docker pull ghcr.io/ilyario/iac-tools:latest

История изменений: CHANGELOG.md и GitHub Releases.

Конфигурация

• .github/workflows/release.yml — release workflow
• .github/workflows/ci.yml — CI для PR и push в main (build + smoke test)
• .releaserc.json — конфигурация semantic-release

Tool Versions

You can specify tool versions using build arguments:

• KUBECTL_VERSION — kubectl version (default: v1.34.8)
• HELM_VERSION — Helm version (default: v3.21.1)
• HELM_DIFF_VERSION — helm-diff plugin version (default: v3.15.7)
• HELMFILE_VERSION — helmfile version (default: v1.5.1)
• TERRAFORM_VERSION — Terraform version (default: 1.15.6)
• TERRAGRUNT_VERSION — Terragrunt version (default: v1.0.8)
• ANSIBLE_CORE_VERSION — ansible-core version (default: 2.21.0)

The image is built for linux/amd64. Terraform is copied from the official hashicorp/terraform image (more reliable than direct downloads from releases.hashicorp.com in restricted networks).

Ansible collections from requirements.yml are not baked into the image. Install them at runtime with ansible-galaxy install -r requirements.yml.

Security

This image is automatically scanned for vulnerabilities using:

• Trivy vulnerability scanner
• Hadolint for Dockerfile best practices

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

This project is licensed under the MIT License.