1. SSL-сертификаты
Для безопасного доступа к основному домену example.com web-сайта вашего проекта в платформу добавлен сертификат Let`s Encrypt автоматически продлеваемый раз в 3 месяца.
Для безопасного доступа к инфраструктуре мы сгенерировали доменный wildcard сертификат *.example.com и подписали его СА сертификатом, который вы можете найти на хосте в файле tls/certs/tls.crt
Добавьте его в хранилище СА сертификатов удостоверяющих центров вашего браузера. В браузере Mozilla перейдите в меню "Настройки"->"Приватность и защита"-> "Сертификаты"->"Просмотр сертификатов"
Возьмите на хосте ваш CA сертификат в файле tls/certs/tls.crt и добавьте его кнопкой "Импортировать". Теперь у вас есть безопасный доступ по протоколу HTTPs из браузера к инфраструктурным доменам:
web-интерфейс Gitea:
https://gitea.example.com
web-интерфейс Jenkins:
https://jenkins.example.com
web-интерфейс Grafana:
https://grafana.example.com
development контур
review разработчиков:
https://review-dev1.example.com
web-интерфейс управления БД MySQL:
https://phpmyadmin.development.example.com
web-интерфейс управления БД PostgreSQL:
https://pgadmin.development.example.com
staging контур
staing вашего проекта:
https://staging-frontend.example.com
web-интерфейс управления БД MySQL:
https://phpmyadmin.staging.example.com
web-интерфейс управления БД PostgreSQL:
https://pgadmin.staging.example.com
production контур
web-интерфейс управления БД MySQL:
https://phpmyadmin.production.example.com
web-интерфейс управления БД MySQL:
https://pgadmin.production.example.com
Так же сертификат СА нужно добавить в хранилище доверенных сертификатов вашей ОС
для безопасного доступа git-клиента на вашем лаптопе к git-репозиторию Gitea. В ОС Linux выполните команды:
sudo mkdir /usr/local/share/ca-certificates/example.com/
sudo cp certs/tls.crt /usr/local/share/ca-certificates/example.com/example.com_CA.crt
sudo update-ca-certificates
2. Аутентификация пользователей
Аутентификацией пользователей на платформе занимается keycloak. Чтобы добавить нового пользователя, залогиньтесь в Gitea пользователем owneruser наделенным админскими правами. Справа вверху перейдите в меню "Панель управления" и в меню слева выберите пункт "Identity & Access" -> "Пользователи"
Нажмите кнопку "Создать новый аккаунт" и введите данные создаваемого пользователя. Для примера создадим пользователя с логином dev3
Нажмите кнопку "Создать новый аккаунт". Если вы создаете аккаунт администратора проекта, нажмите пиктограму карандаша напротив созданного пользователя спуститесь вниз включите галочку "У этой учетной записи есть права администратора" и нажмите кнопку "Обновить профиль пользователя"
Разлогиньтесь пользователем owneruser и залогиньтесь в Gitea вновь созданным пользователем dev3 и смените пароль.
Откройте web-интерфейс админа keycloak "Administration Console" по ссылке:https://auth.example.com
Войдите пользователем admin
Выберите область master слева в верху. Перейдите в меню Users. Выберите пользователя admin, перейдите на вкладку Credentials и смените пароль
Выберите область вашего проекта слева в верху. Перейдите в меню Users. И создайте пользователя кнопкой "Add user"
Задайте имя пользователя (зададим имя dev3, аналогичное выше созданному в Gitea) и обязательно e-mail (иначе пользователт не войдет в Grafana)
Нажмите кнопку "Join group" и внесите пользователя в группу admins, если вы создаете аккаунт администратора проекта, которому нужно дать админские права в Gitea, Jenkins и Grafana. Если вы создаете аккаунт разработчика, то внесите пользователя в группу devs, чтобы разрешить пользователю только просмотр
Нажмите кнопку Join и следом нажмите кнопку Create. Перейдите на вкладку Credentials и задайте пароль пользователю dev3
Теперь нужно связать выше созданный аккаунт пользователя dev3 в Gitea с аккаунтом пользователя dev3 в Keycloak. Войдите на web-интерфейс Gitea, Нажмите кнопку "войти при помощи keycloak" и залогиньтесь пользователем dev3, только что созданным в keycloak. При первом входе keycloak предложет сменить пароль пользователя в keycloak - смените или продублируйте уже заданный пароль. Далее Gitea предложет связать аккаунт из keycloak с аккаунтов в gitea
Введите логин пользователя dev3 и пароль в Gitea и нажмите кнопку "Привязать учетную запись". Теперь пользователь dev3 логинясь в keycloak, будет попадать в личный кабинет пользователя в Gitea и получит достуа к web-интерфейсам Jenkins, Grafana и баз данных phpmyadmin и pgadmin
3. git-репозиторий вашего проекта в Gitea
По умолчанию мы добавим в Gitea пользователя и keycloak пользователя ownewuser для тимлида проекта.
Войдите в Gitea пользователем owneruser и паролем, который мы вам выдадим и смените пароль.
Это же пароль нужно задать пользователю owneruser в Jenkins для доступа в Gitea п.3.
Затем войдите в консоль администратора keycloak и смените пароль пользователя owneruser.
Настройте доступ по ssh ключам git-клиента вашего лаптопа к git-репозиторию Gitea, чтобы не вводить логин и пароль при каждом обращении в git-репозиторий На своем лаптопе сгенерируйте приватный и публичный ssh-ключи:
mkdir gitea-ssh-keys
cd gitea-ssh-keys
ssh-keygen -t rsa -f ./id_rsa_gitea
Приватный ключ загрузите в ОЗУ вашего лаптопа:
ssh-agent
ssh-add ./id_rsa_gitea
Публичный ключ *.pub задайте в аккаунте пользователя owneruser в меню "Настройки" -> "Ключи SSH/GPG"
Пользователем owneruser мы создадим 3 репозитория базового проекта:
| frontend | фронтент web-сайта вашего проекта |
| backend | бэкенд вашего проекта |
| mysql/postgresql | база данных вашего проекта |
3. Пайплайны вашего проекта в Jenkins
Войдите в web-интерфейс Jenkins https://jenkins.example.com администратором admin, с паролем, который мы вам выдадим. Откройте меню "Dashboard" -> "Настроить Jenkins" -> "Users" и смените пароль администратора admin.
Перейдите в меню "Dashboard"->"Настроить Jenkins"->"Credentials" нажмите на пользователя owneruser перейдите в меню "Update" нажмите кнопку "Change Password" введите в поле "Password" пароль, который вы задали для пользователя owneruser в Gitea в п.2 и нажмите кнопку "Save"
По умолчанию в платформе 6 пайплайнов базового проекта:
| frontend | деплой фронтенда вашего проекта в контуры staging и production | |
| backend | деплой бэкенда вашего проекта в контуры staging и production | |
| frontend-production | промошен фронтенда вашего проекта со staging на production | |
| backend-production | промщшен бэкенда вашего проект со staging на production | |
| mysql или postgresql | деплой БД вашего проекта в контуры development, staging и production | |
| backend-rollback | откат бэкенда в production контуре до предыдущих версий |
Stages и Jobs пайплайнов вы можете найти Jenkinsfile в одноименных репозиториях в Gitea
4. Развертывание базы данных и прочих сервисов
В каждый из контуров development, staging и production развертывается свой экземпляр сервиса
4.1 база данных PostgresSQL
Войдите в web-интерфейс управления базой данных пользователем owneruser через keycloak:
development контур:
https://pgadmin.development.example.com
staging контур:
https://pgadmin.staging.example.com
production контур:
https://pgadmin.production.example.com
Смените master password в pgadmin4. master password pgadmin4 спрашивает при каждом входе и использует его для шифрования паролей
Смените пароль администратора по умолчанию postgres
4.2 база данных MySQL
Вы можете получить доступ к web-интерфейсам phpmyadmin в контурах development, staging и production по ссылкам:
development контур: https://phpmyadmin.development.example.com
staging контур: https://phpmyadmin.staging.example.com
production контур: https://phpmyadmin.production.example.com
Дефолтная форма аутентификации phpmyadmin отключена
Пользователи, которых вы создали в п.2 выше логинятся в phpmyadmin через keycloak. Пользователи из групы admins имеют доступ web-интерфейсам phpmyadmin во всех трех контурах development, staging и production. Пользователи из группы devs имеют доступ только к web-интерфейсу phpmyadmin только в контуре development. Пользователь успешно залогинившийся в keycloak мэпится в пользователя root БД mysql и соответственно получает полный доступ к БД.
Войдите в web-интерфейсы phpmyadmin в контурах development, staging и production пользователем owneruser и смените пароли пользователя root@localhost и root@%
Теперь нужно передать новые пароли root пользователей mysql в модули phpmyadmin клиентам keycloak. Чтобы не скомпрометировать root пароли mysql в репозиториях кода в Gitea, создайте ConfigMap с переменными окружения и подключите их к модулям phpmyadmin. Рассмотрим для примера только для контура production. Для контуров staging и development делаем аналогично. Найдите на хосте файл phpmyadmin-sso-prod.env и задайте в нем логин и пароль root пользователя mysql:
PMA_USER=root
PMA_PASSWORD=password
Пересоздайте ConfigMap и перезапустите модуль phpmyadmin командами:
kubectl delete configmap phpmyadmin-sso-prod -n production
kubectl create configmap phpmyadmin-sso-prod --from-env-file=phpmyadmin-sso-prod.env -n production
kubectl get pod -n production
kubectl delete pod phpmyadmin-656dc86549-zkxnc -n production
4.3 создайте базу данных и пользователей для поступа к ней
Cоздайте БД вашего проекта и пользователя для доступа к ней
Параметры доступа к БД для окружений staging и production передаются в контейнер БД через переменные окружения в ConfigMap, подключаемый к контейнеру БД
Найдите на хосте файл staging.env и пропишите в нем имя БД, пользователя и пароль для доступа к БД staging окружения. Cоздайте ConfigMap с именем env-config:
kubectl create configmap env-config --from-env-file=staging.env -n staging
Найдите на хосте файл production.env и пропишите в нем имя БД, пользователя и пароль для доступа к БД staging окружения, созданной выше. Cоздайте ConfigMap с именем env-config:
kubectl create configmap env-config --from-env-file=production.env -n production
Клонируйте репозиторий бэкенда себе на лаптоп:
git clone git@gitea.example.com:owneruser/backend.git
В Jenkinsfile задайте имя ConfigMap env-config, созданный выше в переменную stagingEnv в секции staging enviromen:
//=====================staging enviroment==========================
def namespace_staging = 'staging'
def stagingReplicaCount = 1
//def stagingEnv = ''
def stagingEnv = 'env-config'
def stagingSharedPvSize = '1Gi'
//=====================staging enviroment==========================
В Jenkinsfile задайте имя ConfigMap env-config, созданный выше в переменную stagingEnv в секции production enviromen:
//=====================production environment======================
def namespace_production = 'production'
def productionReplicaCount = 1
//def productionEnv = ''
def productionEnv = 'env-config'
def productionSharedPvSize = '1Gi'
//=====================production environment======================
При деплое бэкенда, ConfigMap будут подключены к модулю бэкенда. В модуле бэкенда будут созданы одноименные системные переменные окружения из переменных в ConfigMap который вы сможете использовать в коде вашего проекта
Сделайте commit и push в gitea репозиторий:
git add -A && git commit -m "staging commit1" && git push
Gitea запустит веб-хук в Jenkins. По веб-хуку Jenkins автоматически запустит pipeline, соберет Docker образ вашего бэкенда и задеплоит его в staging контур
Клонируйте репозиторий фронтенда к себе на лаптоп:
git clone git@gitea.example.com:owneruser/frontend.git
Сделайте commit и push в gitea репозиторий:
git add -A && git commit -m "staging commit1" && git push
Gitea запустит веб-хук в Jenkins. По веб-хуку Jenkins автоматически запустит pipeline, соберет Docker образ вашего фронтенда и задеплоит его в staging контур
Зайти на staging вашего проекта вы можете по ссылке:
https://staging-owneruser-frontend.example.com/
5. Промоушен вашего проекта со staging на production
Залогиньтесь в Jenkins через keycloak пользователем owneruser, перейдите на вкладку Dashboard, найдите пайплайн c именем backend-production и нажмите зеленый треугольник справа от него и Jenkins задеплоит текущий Docker образ вашего бэкенда со staging на production
Найдите пайплайн c именем frontend-production и нажмите зеленый треугольник справа от него и Jenkins задеплоит текущий Docker образ вашего фронтенда со staging на production
Зайдите на главную страницу вашего сайта чтобы проверить результат
https://example.com
6. rollback на предыдущий релиз
Если Вы задеплоите в production релиз бэкенда вашего проекта с багом, Вы всегда можете опреативно откатить backend на один из предшествующих релизов с помощью пайплайна backend-rollback.
Войдите в Jenkins пользователем owneruser через keycloak, нажмите на пайплайн с именем backend-rollback в Dashboard и нажмите пункт "Собрать с параметрами" нажмите точку "update commit list" и нажмите кнопку "Собрать" - пайплайн отработает и загрузит доступные коммиты в список "commit" ниже
Каждый коммит Gitea в main-ветку, запускает пайплайн, который собирает Docker-образ и деплоит релиз бэкенда на staging. ID этого коммита Gitea поставлен в соответствие релизу бэкенда на staging и впоследствии релизу бэкенда, promote которого вы делаете со staging на production
Найдите коммит в Gitea, до которого вы хотите откатиться, выберите его в спике "commit", включите точку "rollback", нажмите кнопку "Собрать" и пайплайн откатит бэкенд в production, до релиза соответсвующему выбранному вами коммиту
7. Выдаем задание разработчику
Зарегистрируйте ногого разработчика следуя иструкциям в пункте п.2
Сделайте разработчика соавтором репозиториев frontend и backend. Войдите в Gitea пользователем owneruser и в меню репозитория "Настройки" -> "Соавторы" в окне "Поиск пользователя" введите логин разработчика и нажмите кнопку "Добавить соавтора" с правами "Запись"
Войдите в web-интерфейс управления базой данных в development контуре через keycloak пользователем owneruser:
для управления БД PostgreSQL
https://pgadmin.development.example.com
для управления БД MySQL
https://phpmyadmin.development.example.com
Создайте БД вашего проекта в development контуре
Все статические файлы (css, img, javascript) вашего проекта будет отдавать nginx в модуле фронтенда. Организуем доступ nginx из модуля фронтенда к директории со статикой в модуле бэкенда. Для каждого разработчика создайте на хосте Persistent Volume, который при деплое будет подключен одновременно к модулю фронтенда и к модулю бэкенда
Увеличьте номер диска на единицу и создайте директорию под Persistent Volume на хосте:mkdir /usr/local/local-disks/shared-development-disk1
Найдите на хосте файл shared-disk.yaml и задайте в нем параметры Persistent Volume:
имя:
name: shared-development-disk1
размер:
storage: 1Gi
путь к директории, созданной выше:
path: "/usr/local/local-disks/shared-development-disk1"
Создайте Persistent Volume командой:
kubectl apply -f shared-disk.yaml
Выдайте разработчику:
сертификат СА удостоверяющего центра из файла tls/certs/tls.crt на хосте
логин и пароль для доступа к web-интерфейсам сервисов платформы
имя БД в development контуре
cообщите размер Persistent Volume для передачи статики из бэкенда в фронтенд
8. Зашита main-ветки от разработчиков
По умолчанию в main-ветку бэкенда и фронтенда может сделать push любой пользователь, которого вы назначите соавтором и задеплоить изменения на staging. Это неминуемо вызовет путаницу. Мы рекомендуем придерживаться следующей стратегии: разрешить push в main-ветку только владельцу репозитория и запретить всем остальным.
Каждый разработчик будет создать себе ветку для разработки, push-ить в нее и деплоить только в свое динамическое окружение на review. Выполнив задание, разработчик создаст запрос на слияние pull request. Тимлид создаст коммит на слияние merge request, вольет изменения из ветки разработчмка в main-ветку и задеплоит на staging
Залогиньтесь в Gitea владельцем репозиториев. Перейдите в настройках репозитория в меню "Ветки" и нажмите кнопку "Добавить новое правило".
В поле "Шаблоны" -> "Шаблон имени для защищённых веток" введите имя ветки "main". В секции "Отправка" установите точку "Ограничение отправки по белому списку" и перечислите пользователей, которым разрешено делать push в main-ветку. Ниже в разделе "Утверждение запросов на слияние" включите галочку "Ограничить утверждения белым списком пользователей и команд" и перечислите пользователей, которым разрешено вливать изменения в main-ветку. Спуститесь ниже и в секции "Pull Request Merge", установите точку "Ограничить право на слияние белым списком" и перечислите пользователей, которым разрешено вливать изменения в main-ветку. Спуститесь ниже и нажмите кнопку "Сохранить правило"
Разработчик все равно может push-ить изменения в Dockerfile, Jenkinsfile и директорию /helm и тимлид может нечаянно влить эти изменения в main-ветку и "сломать" production. Поэтому запретите разработчику push-ить куда бы то ни было, кроме директории src/ с исходным кодом сайта.
Создайте правило для веток разработчиков. Имена веток разработчиков будут начинаться с префикса dev (например dev-user1, dev-user2). В поле "Шаблоны защищённых файлов (разделённые точкой с запятой ';'):" перечислите файлы и директории, в которые разработчикам запрещено вносить изменения. Ниже в секции "Отправка" установите точку "Включить отправку". Спуститесь ниже и нажмите кнопку "Сохранить правило"
9. Вливаем изменения из ветки разработчика в main-ветку
Выполнив ваше задание, разработчик создаст pull request запрос на слияние (merge) изменений из своей ветки разработчика в main-ветку. Войдите в web-интерфейс владельцем репозиториев проекта owneruser и найдите запрос разработчика на вкладке репозитория "Запросы на слияние". Выберите запрос нажмите на него. В меню "Измененные файлы" проверьте все изменения, который внес пользователь
Если задание выполнено верно,нажмите кнопку "Создать коммит на слияние"
Изменения из ветки разработчика будут влиты в main-ветку, Gitea сгенерирует веб-хук в Jenkins, который соберет и задеплоит новую версию сайта на staging.