Документация как код: принципы, рабочий процесс и вызовы

В современном мире разработки программного обеспечения концепция «Документация как код» (Documentation as Code, DaC) становится все более популярной. Этот подход использует инструменты и практики разработки программного обеспечения для написания, хранения и управления документацией.

🔹 Основные принципы

1. Хранение в системе контроля версий
Документация хранится в репозитории вместе с кодом, что позволяет отслеживать изменения, откатываться к предыдущим версиям и сотрудничать в команде.

2. Использование текстовых форматов (Markdown, AsciiDoc, reStructuredText и др.)
Вместо сложных редакторов документация пишется в простых текстовых форматах, что облегчает интеграцию с инструментами CI/CD.

3. Автоматизация сборки и публикации
Документация может автоматически обновляться и развертываться при каждом изменении кода.

4. Документирование в процессе разработки
Документация пишется параллельно с кодом, а не после него, что делает её актуальной.

5. Использование инструментов рецензирования
Pull Request'ы, ревью и линтеры помогают поддерживать качество документации.

🔹 Рабочий процесс

1. Создание документации – разработчик или технический писатель пишет документацию в виде кода.
2. Рецензирование – команда проводит код-ревью документации.
3. Автоматическая проверка – линтеры и тесты проверяют синтаксис, ссылки и структуру.
4. Сборка и развертывание – система CI/CD публикует документацию в нужном формате.
5. Обновление и поддержка – документация развивается вместе с кодом.

🔹 Вызовы и сложности

🔸 Сопротивление со стороны команды – не все привыкли писать документацию в таком формате.
🔸 Необходимость в новых инструментах – Markdown или AsciiDoc, системы рендеринга (MkDocs, Docusaurus).
🔸 Поддержание актуальности – требуется дисциплина, чтобы обновлять документацию вместе с кодом.
🔸 Интеграция в CI/CD – настройка автоматического развертывания требует времени.

https://www.tabnine.com/blog/documentation-as-code-principles-workflow-and-challenges/

#devops #девопс

Подпишись 👉@i_DevOps

Выходим за рамки: создание оператора для наблюдения за внешними ресурсами в Kubernetes

В этой статье мы рассмотрим, как создать оператор, который выходит за рамки кластера и взаимодействует с внешним миром. На примере мониторинга HTTP-серверов вы узнаете, как использовать kubebuilder для разработки custom-операторов и как организовать работу с внешними ресурсами. Статья будет полезна разработчикам, желающим расширить возможности своих Kubernetes-кластеров.

https://habr.com/ru/companies/flant/articles/884566/

#devops #девопс

Подпишись 👉@i_DevOps

Какой код сигнала будет выполнен при исполнении команды kill <PID>?

Сигнал SIGTERM (код 15) — это сигнал по-умолчанию отправляемый при вызове команды kill. Это указывает процессу на завершение работы и обычно считается сигналом для использования при чистом завершении работы.

#devops #девопс

Подпишись 👉@i_DevOps

🔥 Как снизить Latency в Kubernetes? 🔥

Высокая задержка (latency) в Kubernetes может стать настоящей головной болью для DevOps-инженера. Давайте разберем, какие ключевые настройки помогут снизить задержку и ускорить ваш кластер!

🚀 1. Настройка Kube-Proxy
Если используете iptables-режим, попробуйте переключиться на IPVS:

kubectl edit configmap -n kube-system kube-proxy

Установите mode: "ipvs". Это значительно улучшает балансировку нагрузки и снижает задержку при обработке запросов.

🚀 2. Подключение eBPF (Cilium)
Классические iptables могут быть узким местом. Попробуйте Cilium с eBPF, который обеспечивает более быструю маршрутизацию:

helm install cilium cilium/cilium --namespace kube-system

🚀 3. Использование NodeLocal DNSCache
DNS-запросы — частая причина высокой задержки. Включите локальный кэш:

kubectl apply -f https://k8s.io/examples/admin/dns/nodelocaldns.yaml

Это уменьшит нагрузку на CoreDNS и ускорит обработку запросов.

🚀 4. Tuning TCP (sysctl)
Настройте TCP-параметры для более быстрой передачи данных:

sysctl -w net.core.somaxconn=1024
sysctl -w net.ipv4.tcp_tw_reuse=1
sysctl -w net.ipv4.tcp_max_syn_backlog=8192

Эти параметры помогут лучше обрабатывать соединения и снижать задержку.

🚀 5. Использование Multi-NIC и CNI-плагинов
Если у вас высокий сетевой трафик, попробуйте Multus CNI для распределения нагрузки между несколькими сетевыми интерфейсами.

#devops #девопс

Подпишись 👉@i_DevOps

Pipeline CI/CD, объясненный простыми словами

Раздел 1 - SDLC с CI/CD
Жизненный цикл разработки программного обеспечения (SDLC) состоит из нескольких ключевых этапов: разработка, тестирование, развертывание и сопровождение. CI/CD автоматизирует и интегрирует эти этапы, чтобы обеспечить более быстрые и надежные релизы.
Когда код размещается в git-репозитории, он запускает автоматизированный процесс сборки и тестирования. Для проверки кода запускаются сквозные (e2e) тесты. Если тесты пройдены, код может быть автоматически развернут на этапе staging/продакшен. Если обнаружены проблемы, код возвращается в разработку для исправления ошибок. Такая автоматизация обеспечивает быструю обратную связь с разработчиками и снижает риск появления ошибок в продакшене.

Раздел 2 - Разница между CI и CD
Непрерывная интеграция (CI) автоматизирует процесс сборки, тестирования и слияния. Она запускает тесты при коммите кода, чтобы обнаружить проблемы интеграции на ранней стадии. Это стимулирует частые коммиты кода и быструю обратную связь.

Continuous Delivery (CD) автоматизирует процессы выпуска, такие как изменение инфраструктуры и развертывание. Она обеспечивает надежный выпуск программного обеспечения в любое время благодаря автоматизированным рабочим процессам. CD также может автоматизировать ручное тестирование и этапы утверждения, необходимые перед развертыванием продакшена.

Раздел 3 - CI/CD Pipeline
Типичный pipeline CI/CD состоит из нескольких взаимосвязанных этапов:
- Разработчик коммитит изменения кода в системе контроля исходного кода
- CI-сервер обнаруживает изменения и запускает сборку
- Код компилируется, тестируется (модульные, интеграционные тесты)
- Результаты тестирования сообщаются разработчику
- При успешном завершении артефакты развертываются в среде staging.
- Дальнейшее тестирование может быть проведено в среде staging перед выпуском.
- Система CD развертывает одобренные изменения в продакшене

#devops #девопс

Подпишись 👉@i_DevOps

10 шагов к созданию оркестратора Terragrunt

1. Определите цели – Четко обозначьте, какие задачи должен решать оркестратор: управление инфраструктурой, стандартизация, масштабируемость.

2. Выберите подходящую структуру каталогов – Используйте рекомендуемые шаблоны Terragrunt (например, live и modules), чтобы упростить поддержку кода.

3. Разделите окружения и компоненты – Используйте отдельные файлы для разных окружений (dev, staging, prod), что обеспечит гибкость и контроль.

4. Оптимизируйте конфигурации – Настройте Terragrunt, чтобы минимизировать дублирование кода с помощью наследования (include).

5. Создайте систему автоматизации – Интегрируйте оркестратор в CI/CD-пайплайны для автоматизированного развертывания.

6. Реализуйте контроль доступа – Используйте IAM-роли и политики, чтобы ограничить доступ к инфраструктуре.

7. Настройте работу с зависимостями – Определите порядок применения модулей и настройте зависимости между ними.

8. Добавьте мониторинг и логи – Внедрите системы логирования (например, AWS CloudWatch) для отслеживания изменений.

9. Проводите тестирование инфраструктуры – Используйте инструменты вроде terraform validate, terragrunt plan и checkov для проверки конфигураций.

10. Документируйте процессы – Поддерживайте актуальную документацию, чтобы упростить онбординг новых членов команды.


https://nordcloud.com/tech-community/10-steps-to-building-terragrunt-orchestrator/

#devops #девопс

Подпишись 👉@i_DevOps

Шпаргалка по Kubernetes

1. Основные понятия
• Pod – наименьшая единица развертывания, содержит один или несколько контейнеров.
• Deployment – контроллер, который управляет репликами Pod’ов и их обновлением.
• Service – абстракция, предоставляющая доступ к Pod’ам (ClusterIP, NodePort, LoadBalancer).
• ConfigMap – хранит конфигурационные данные в виде ключ-значение.
• Secret – безопасное хранилище для конфиденциальных данных (пароли, токены).
• PersistentVolume (PV) – абстракция для хранения данных.
• PersistentVolumeClaim (PVC) – запрос на использование хранилища (PV).
• Namespace – логическое разделение ресурсов в кластере.
• Ingress – объект, предоставляющий доступ к сервисам внутри кластера через HTTP/HTTPS.

2. Основные команды kubectl

Работа с контекстом

kubectl config get-contexts # Список контекстов
kubectl config use-context <name> # Переключение контекста
kubectl config set-context <name> --namespace=<namespace> # Установить namespace по умолчанию

Работа с ресурсами

kubectl get pods # Список Pod'ов
kubectl get deployments # Список Deployment'ов
kubectl get services # Список Service'ов
kubectl get nodes # Список узлов
kubectl get namespaces # Список namespace'ов
kubectl get events # Лог событий
kubectl describe pod <pod-name> # Подробная информация о Pod
kubectl logs <pod-name> # Логи Pod
kubectl exec -it <pod-name> -- /bin/sh # Зайти внутрь контейнера

Создание и удаление объектов

kubectl apply -f <file>.yaml # Применить манифест
kubectl delete -f <file>.yaml # Удалить объект
kubectl delete pod <pod-name> # Удалить Pod
kubectl delete deployment <deploy-name> # Удалить Deployment

3. Пример манифестов

Простой Pod

apiVersion: v1
kind: Pod
metadata:
name: my-pod
spec:
containers:
- name: my-container
image: nginx
ports:
- containerPort: 80

Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
name: my-deployment
spec:
replicas: 3
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: my-container
image: nginx
ports:
- containerPort: 80

Service (NodePort)

apiVersion: v1
kind: Service
metadata:
name: my-service
spec:
selector:
app: my-app
ports:
- protocol: TCP
port: 80
targetPort: 80
nodePort: 30080
type: NodePort

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: my-ingress
spec:
rules:
- host: example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: my-service
port:
number: 80

4. Полезные команды

kubectl top pod # Мониторинг использования CPU/RAM Pod'ов
kubectl top node # Мониторинг узлов
kubectl rollout status deployment <deploy-name> # Статус развертывания
kubectl rollout undo deployment <deploy-name> # Откат изменений
kubectl autoscale deployment <deploy-name> --min=2 --max=10 --cpu-percent=80 # Авто-масштабирование

5. Отладка и устранение проблем

kubectl get pods --all-namespaces # Проверить состояние всех Pod'ов
kubectl describe pod <pod-name> # Подробности о Pod
kubectl logs <pod-name> # Логи контейнера
kubectl logs <pod-name> -p # Логи завершившегося контейнера
kubectl exec -it <pod-name> -- /bin/sh # Подключение внутрь контейнера
kubectl get events --sort-by=.metadata.creationTimestamp # Последние события

#devops #девопс

Подпишись 👉@i_DevOps

📌Docker

Удаление промежуточных образов без тэгов:
docker rmi $(docker images --filter "dangling=true" -q --no-trunc)

Мягко перезапустить контейнер:
docker kill --signal="USR1" <yourcontainer_name>

Список контейнеров:
docker ps -a

Подключиться к контейнеру:
docker exec -it container_name bash

Остановить все контейнеры:
docker stop $(docker ps -a -q)

Удалить все контейнеры, из которых вышли:
docker rm -v $(docker ps -aq -f status=exited)

Удалить образ:
docker rmi image_name

Создать образ:
docker build -t image_name

Удалить все неиспользуемые тома:
docker volume prune

Подключиться под рутом в контейнер Alpine:
docker exec -it --user root alpine-container bash


#devops #девопс

Подпишись 👉@i_DevOps

Практическое руководство по настройке CI/CD для PHP проектов

В этом лонгриде я расскажу немного теории о CI/CD, но в основном это будут практические примеры и советы, в первую очередь полезные для PHP backend разработчиков, однако некоторые инструменты подходят и для других языков, и вы можете уловить общую идею, как писать пайплайны

https://habr.com/ru/articles/889120/

#devops #девопс

Подпишись 👉@i_DevOps

Проект dockur/windows позволяет запускать Windows внутри контейнера Docker.

Он предоставляет такие возможности, как загрузка ISO-образов, ускорение с помощью KVM и веб-интерфейс для просмотра.

Основные особенности:
- Загрузчик ISO-образов
- Аппаратное ускорение через KVM
- Веб-интерфейс для доступа

Пример использования с Docker Compose:

services:
  windows:
    image: dockurr/windows
    container_name: windows
    environment:
      VERSION: "11"
    devices:
      - /dev/kvm
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - 8006:8006
      - 3389:3389/tcp
      - 3389:3389/udp
    restart: always
    stop_grace_period: 2m

Пример использования с Docker CLI:

docker run -it --rm -p 8006:8006 --device=/dev/kvm --device=/dev/net/tun --cap-add NET_ADMIN --stop-timeout 120 dockurr/windows

https://github.com/dockur/windows

#devops #девопс

Подпишись 👉@i_DevOps

Disaster Recovery Plan: Как правильно заваривать чай, когда горит серверная

В жизни любого проекта наступает катастрофа. Мы не можем заранее знать, что именно это будет - короткое замыкание в серверной, инженер, дропнувший центральную БД или нашествие бобров. Тем не менее, оно обязательно случится, причем по предельно идиотской причине.

Насчет бобров, я, кстати, не шутил. В Канаде они перегрызли кабель и оставили целый район Tumbler Ridge без оптоволоконной связи. Причем, животные, как мне кажется, делают все для того, чтобы внезапно лишить вас доступа к вашим ресурсам:

https://habr.com/ru/companies/wiseops/articles/802701/

#devops #девопс

Подпишись 👉@i_DevOps

🚀 Шпаргалка по Docker 🐳

🔹 Сборка (Build)
🔹 Запуск (Run)
🔹 Шаринг (Share)
🔹 Управление (Management)


📌 Сборка образов
📍 Создать образ из Dockerfile и присвоить тег:

docker build -t myimage:1.0 .

📍 Посмотреть локальные образы:

docker image ls

📍 Удалить образ:

docker image rm alpine:3.4

📌 Запуск контейнеров
📍 Запустить контейнер на порту 5000:

docker container run --name web -p 5000:80 alpine:3.9

📍 Остановить контейнер:

docker container stop web

📍 Принудительно завершить контейнер:

docker container kill web

📍 Список запущенных контейнеров:

docker container ls

📍 Удалить все контейнеры:

docker container rm -f $(docker ps -aq)

📌 Работа с образами (Share)
📍 Скачать образ из реестра:

docker pull myimage:1.0

📍 Изменить тег у локального образа:

docker tag myimage:1.0 myrepo/myimage:2.0

📍 Запушить образ в реестр:

docker push myrepo/myimage:2.0

📌 Управление Docker (Management)
⚙️ docker app – Управление приложениями
⚙️ docker image – Управление образами
⚙️ docker container – Управление контейнерами
⚙️ docker network – Управление сетями
⚙️ docker volume – Управление хранилищами
⚙️ docker stack – Управление Docker Stack
⚙️ docker swarm – Управление кластером Swarm
⚙️ docker system – Управление всей системой

📝 Сохраните, поделитесь с друзьями и подписывайтесь на канал! 💙🐳

#devops #девопс

Подпишись 👉@i_DevOps

Руководство от ненавистника Kubernetes: как использовать эту технологию

Пол Батлер, инженер-программист и создатель Jamsocket, уверяет, что Kubernetes — это как сложный, но увлекательный пазл: его можно ненавидеть, но без него не обойтись. Мы перевели его статью, в которой он рассказал, какие ресурсы K8s использует с удовольствием, а от каких предпочитает держаться подальше. В этом руководстве ненавистника вы найдете ценные советы, как извлечь максимум пользы из Kubernetes.

https://habr.com/ru/companies/flant/articles/840998/

original https://paulbutler.org/2024/the-haters-guide-to-kubernetes/

#devops #девопс

Подпишись 👉@i_DevOps

5 советов по эффективному управлению AWS Security Groups с помощью Terraform

1. Используйте модульный подход – Разделение конфигурации Security Groups на модули повышает удобство повторного использования и масштабируемость.
2. Явно указывайте правила вместо использования inline – Это делает код более читаемым и позволяет легко управлять правилами без дублирования.
3. Применяйте terraform import для существующих Security Groups – Это упрощает миграцию и управление уже созданными ресурсами.
4. Используйте динамические блоки в Terraform – Они помогают уменьшить количество кода и повысить гибкость при настройке правил безопасности.
5. Применяйте terraform plan и terraform apply осознанно – Регулярный анализ изменений перед их применением снижает вероятность случайных ошибок.

https://blog.avangards.io/5-tips-to-efficiently-manage-aws-security-groups-using-terraform


#devops #девопс

Подпишись 👉@i_DevOps

Конвейер CI/CD автоматизирует процесс сборки, тестирования и развертывания программного обеспечения.

#devops #девопс

Подпишись 👉@i_DevOps

Подборка Telegram каналов для программистов

https://t.me/bash_srv Bash Советы
https://t.me/win_sysadmin Системный Администратор Windows
https://t.me/lifeproger Жизнь программиста. Авторский канал.
https://t.me/devopslib Библиотека девопса | DevOps, SRE, Sysadmin
https://t.me/rabota1C_rus Вакансии для программистов 1С

Системное администрирование 📌
https://t.me/sysadmin_girl Девочка Сисадмин
https://t.me/srv_admin_linux Админские угодья
https://t.me/linux_srv Типичный Сисадмин

https://t.me/linux_odmin Linux: Системный администратор
https://t.me/devops_star DevOps Star (Звезда Девопса)
https://t.me/i_linux Системный администратор
https://t.me/linuxchmod Linux
https://t.me/sys_adminos Системный Администратор
https://t.me/tipsysdmin Типичный Сисадмин (фото железа, было/стало)
https://t.me/sysadminof Книги для админов, полезные материалы
https://t.me/i_odmin Все для системного администратора
https://t.me/i_odmin_book Библиотека Системного Администратора
https://t.me/i_odmin_chat Чат системных администраторов
https://t.me/i_DevOps DevOps: Пишем о Docker, Kubernetes и др.
https://t.me/sysadminoff Новости Линукс Linux

1C разработка 📌
https://t.me/odin1C_rus Cтатьи, курсы, советы, шаблоны кода 1С
https://t.me/DevLab1C 1С:Предприятие 8

Программирование C++📌
https://t.me/cpp_lib Библиотека C/C++ разработчика
https://t.me/cpp_knigi Книги для программистов C/C++
https://t.me/cpp_geek Учим C/C++ на примерах

Программирование Python 📌
https://t.me/pythonofff Python академия. Учи Python быстро и легко🐍
https://t.me/BookPython Библиотека Python разработчика
https://t.me/python_real Python подборки на русском и английском
https://t.me/python_360 Книги по Python Rus

Java разработка 📌
https://t.me/BookJava Библиотека Java разработчика
https://t.me/java_360 Книги по Java Rus
https://t.me/java_geek Учим Java на примерах

GitHub Сообщество 📌
https://t.me/Githublib Интересное из GitHub

Базы данных (Data Base) 📌
https://t.me/database_info Все про базы данных

Мобильная разработка: iOS, Android 📌
https://t.me/developer_mobila Мобильная разработка
https://t.me/kotlin_lib Подборки полезного материала по Kotlin

Фронтенд разработка 📌
https://t.me/frontend_1 Подборки для frontend разработчиков
https://t.me/frontend_sovet Frontend советы, примеры и практика!
https://t.me/React_lib Подборки по React js и все что с ним связано

Разработка игр 📌
https://t.me/game_devv Все о разработке игр

Библиотеки 📌
https://t.me/book_for_dev Книги для программистов Rus
https://t.me/programmist_of Книги по программированию
https://t.me/proglb Библиотека программиста
https://t.me/bfbook Книги для программистов
https://t.me/books_reserv Книги для программистов

БигДата, машинное обучение 📌
https://t.me/bigdata_1 Data Science, Big Data, Machine Learning, Deep Learning

Программирование 📌
https://t.me/bookflow Лекции, видеоуроки, доклады с IT конференций
https://t.me/coddy_academy Полезные советы по программированию
https://t.me/rust_lib Полезный контент по программированию на Rust
https://t.me/golang_lib Библиотека Go (Golang) разработчика
https://t.me/itmozg Программисты, дизайнеры, новости из мира IT
https://t.me/php_lib Библиотека PHP программиста 👨🏼‍💻👩‍💻
https://t.me/nodejs_lib Подборки по Node js и все что с ним связано
https://t.me/ruby_lib Библиотека Ruby программиста

QA, тестирование 📌
https://t.me/testlab_qa Библиотека тестировщика

Шутки программистов 📌
https://t.me/itumor Шутки программистов

Защита, взлом, безопасность 📌
https://t.me/thehaking Канал о кибербезопасности
https://t.me/xakep_2 Хакер Free

Книги, статьи для дизайнеров 📌
https://t.me/ux_web Статьи, книги для дизайнеров

Математика 📌
https://t.me/Pomatematike Канал по математике
https://t.me/phis_mat Обучающие видео, книги по Физике и Математике

Excel лайфхак📌
https://t.me/Excel_lifehack

https://t.me/tikon_1 Новости высоких технологий, науки и техники💡
https://t.me/mir_teh Мир технологий (Technology World)

Вакансии 📌
https://t.me/sysadmin_rabota Системный Администратор
https://t.me/progjob Вакансии в IT

Принцип работы утилиты ping в Linux

Если вы решили прочесть эту статью, то наверняка вы когда-нибудь работали в ОС Linux. Сегодня я вам расскажу, как работает довольно популярная команда ping и покажу, как реализован ее функционал на языке Си.

Утилита ping стоит в Linux по умолчанию. Пример ее использования (указываем домен или айпи в параметры, например google.com или 173.194.73.138):

https://habr.com/ru/articles/803149/

#devops #девопс

Подпишись 👉@i_DevOps

Курс по Kubernetes

Пакетный менеджер Helm
Мониторинг и логирование в Kubernetes
Постоянные хранилища в Kubernetes
Сеть в Kubernetes
Kubernetes. Управление доступом (RBAC)
КМБ-5 | Вебинар 3. Kubernetes. Архитектура, основные компоненты
КМБ-5 | Вебинар 2. Сети и хранилища в Docker
КМБ-5 | Вебинар 1. Что такое Docker

Все видео доступны на youtube

#devops #девопс

Подпишись 👉@i_DevOps

Teller — универсальный open-source менеджер секретов для разработчиков

Больше не нужно покидать терминал, чтобы использовать секреты при разработке, тестировании и создании приложений.

Вместо использования кастомных скриптов, токенов в файлах .zshrc, видимых команд EXPORT в истории bash, ошибочно размещенных файлов .env.production и других уязвимостей на рабочей станции, просто используйте Teller и подключите его к любому хранилищу секретов, ключевому хранилищу или облачному сервису, который вам нужен (Teller поддерживает HashiCorp Vault, AWS Secrets Manager, Google Secret Manager и многие другие).

Вы можете использовать Teller для упорядочения своего окружения или внедрения его как процесса и лучшей практики для вашей команды.

https://github.com/tellerops/teller

#devops #девопс

Подпишись 👉@i_DevOps