Розгортання Платформи з нуля в публічному хмарному середовищі AWS

ЗМІСТ
🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

Ця інструкція надає детальну інформацію про розгортання платформи з нуля в AWS-середовищі, починаючи зі створення облікового запису AWS і закінчуючи інсталяцією платформи з усіма додатковими налаштуваннями.

1. Передумови

Перед розгортанням і налаштуванням платформи потрібно обов’язково виконати наступні дії.

1.1. Необхідні елементи початкового етапу

Перед початком будь-яких дій потрібно мати в наявності набір ресурсів, які обов’язкові для подальших кроків:

Документація:
Сертифікати цифрового підпису (digital-signature-ops сертифікати):

  • Key-6.dat — приватний ключ організації (лише для файлового ключа);

  • allowed-key.yaml — перелік усіх виданих ключів. Спочатку це лише первинний Key-6.dat. При зміні ключа, туди додається інформація про новий ключ, не видаляючи старий;

  • CAs.json — перелік всіх АЦСК, береться з сайту ІІТ;

  • CACertificates.p7b - публічний ключ, береться з сайту ІІТ.

Файли конфігурації для файлового та апаратного ключів:

  • 3 файли, заповнені значеннями — для файлового носія (див. закріплені приклади):

  • sign.key.device-type — вкажіть тип носія для ключа (файловий);

  • sign.key.file.issuer — вкажіть АЦСК, що видав ключ (замініть у файлі значення на своє);

  • sign.key.file.password — вкажіть пароль до файлового ключа (замініть у файлі значення на своє).

    4 файли із порожніми значеннями — для апаратного носія (створіть 4 порожні файли із відповідними назвами):

  • sign.key.hardware.device — тип носія для ключа (апаратний);

  • sign.key.hardware.password —  пароль апаратного ключа;

  • sign.key.hardware.type — тип ключа;

  • osplm.ini — INI-конфігурація.

Детальніше про особливості завантаження/оновлення ключів та сертифікатів цифрового підпису ви можете переглянути на сторінці Оновлення ключів та сертифікатів цифрового підпису для Платформи.

1.2. Створення облікового запису AWS

Перед встановленням OpenShift Container Platform на Amazon Web Services (AWS), необхідно створити обліковий запис AWS.

Це можна зробити, користуючись офіційною документацією на сайті AWS: How do I create and activate a new AWS account?

1.3. Налаштування облікового запису AWS

Перш ніж встановити OpenShift Container Platform, потрібно налаштувати обліковий запис Amazon Web Services (AWS).

1.3.1. Налаштування Route 53

Щоб встановити OpenShift Container Platform, потрібно зареєструвати домен. Це можна зробити у сервісі Route 53, або ж використати будь-який інший реєстратор доменних імен.

Також обліковий запис Amazon Web Services (AWS), який використовується, повинен мати виділену публічну зону хостингу в сервісі Route 53.

Докладніше описано в офіційній документації на сайті OKD: Configuring Route 53.

1.3.2. Налаштування зовнішнього домену

Якщо для створення домену було використано не AWS Route 53, а зовнішній реєстратор доменних імен, то необхідно виконати делегування домену. Для цього виконайте наступні дії:

  • Перейдіть у створений обліковий запис AWS та створіть публічну зону хостингу у сервісі Route 53 (як було описано у п. Налаштування Route 53). Назвати її необхідно так само як і зовнішній створений домен.

  • Увійдіть до створеної публічної зони хостингу та перегляньте запис із типом NS (Name Servers — це сервери імен, які відповідають на DNS-запити для домену). У значенні будуть вказані сервери імен. Необхідно зберегти назви цих серверів для подальшого використання у наступних кроках.

  • Перейдіть до зовнішнього реєстратора доменних імен, в якому було створено домен.

  • Відкрийте налаштування цього домену та знайдіть налаштування, що стосуються NS-серверів;

  • Відредагуйте NS-сервери відповідно до NS-серверів, які взято із публічної зони хостингу з облікового запису AWS.

1.3.3. Ліміти облікового запису AWS

Кластер OpenShift Container Platform використовує ряд компонентів Amazon Web Services (AWS), і стандартні обмеження послуг впливають на можливість встановлення кластера.

Перелік компонентів AWS, обмеження яких можуть вплинути на можливість встановлення та запуску кластера OpenShift Container Platform, наведено у документації на сайті OKD: AWS account limits.

Також обов’язково потрібно збільшити обмеження CPU для on-demand віртуальних машин в обліковому записі Amazon Web Services (AWS). Необхідні для цього дії описані в офіційній документації на сайті AWS: How do I request an EC2 vCPU limit increase for my On-Demand Instance?

1.3.4. Створення користувача IAM

  1. Перед встановленням OpenShift Container Platform, створіть користувача IAM, користуючись офіційною документацією на сайті AWS: Creating an IAM user in your AWS account.

  2. Окрім цього виконайте наступні важливі вимоги:

    • Видаліть будь-які обмеження Service control policies (SCPs) з облікового запису AWS.

      Під час створення кластера, також створюється асоційований постачальник ідентичностей AWS OpenID Connect (OIDC). Ця конфігурація постачальника OIDC базується на відкритому ключі, який знаходиться в регіоні AWS us-east-1. Клієнти з AWS SCP повинні дозволити використання регіону AWS us-east-1 навіть якщо кластер буде розгорнуто в іншому регіоні. Без правильного налаштування цих політик, одразу можуть виникнути помилки з дозволами, оскільки інсталятор OKD перевіряє правильність їх налаштування.
      Детальну інформацію можна отримати в офіційний документації, у пункті 1.1. DEPLOYMENT PREREQUISITES документа Red Hat OpenShift Service on AWS 4. Prepare your environment.

    • Правильно налаштуйте permissions boundary у створеного IAM-користувача.

      Нижче наведено приклад політики permissions boundary. Можна використати її, або зовсім видалити будь-які permissions boundary.

      Приклад. Налаштування політики permissions boundary 
      {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "NotAction": [
                "iam:*"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:Get*",
                "iam:List*",
                "iam:Tag*",
                "iam:Untag*",
                "iam:GenerateServiceLastAccessedDetails",
                "iam:GenerateCredentialReport",
                "iam:SimulateCustomPolicy",
                "iam:SimulatePrincipalPolicy",
                "iam:UploadSSHPublicKey",
                "iam:UpdateServerCertificate",
                "iam:CreateInstanceProfile",
                "iam:CreatePolicy",
                "iam:DeletePolicy",
                "iam:CreatePolicyVersion",
                "iam:DeletePolicyVersion",
                "iam:SetDefaultPolicyVersion",
                "iam:CreateServiceLinkedRole",
                "iam:DeleteServiceLinkedRole",
                "iam:CreateInstanceProfile",
                "iam:AddRoleToInstanceProfile",
                "iam:DeleteInstanceProfile",
                "iam:RemoveRoleFromInstanceProfile",
                "iam:UpdateRole",
                "iam:UpdateRoleDescription",
                "iam:DeleteRole",
                "iam:PassRole",
                "iam:DetachRolePolicy",
                "iam:DeleteRolePolicy",
                "iam:UpdateAssumeRolePolicy",
                "iam:CreateGroup",
                "iam:UpdateGroup",
                "iam:AddUserToGroup",
                "iam:RemoveUserFromGroup",
                "iam:PutGroupPolicy",
                "iam:DetachGroupPolicy",
                "iam:DetachUserPolicy",
                "iam:DeleteGroupPolicy",
                "iam:DeleteGroup",
                "iam:DeleteUserPolicy",
                "iam:AttachUserPolicy",
                "iam:AttachGroupPolicy",
                "iam:PutUserPolicy",
                "iam:DeleteUser",
                "iam:CreateRole",
                "iam:AttachRolePolicy",
                "iam:PutRolePermissionsBoundary",
                "iam:PutRolePolicy"
            ],
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "iam:CreateAccessKey",
                "iam:DeleteAccessKey",
                "iam:UpdateAccessKey",
                "iam:CreateLoginProfile",
                "iam:DeleteLoginProfile",
                "iam:UpdateLoginProfile",
                "iam:ChangePassword",
                "iam:CreateVirtualMFADevice",
                "iam:EnableMFADevice",
                "iam:ResyncMFADevice",
                "iam:DeleteVirtualMFADevice",
                "iam:DeactivateMFADevice",
                "iam:CreateServiceSpecificCredential",
                "iam:UpdateServiceSpecificCredential",
                "iam:ResetServiceSpecificCredential",
                "iam:DeleteServiceSpecificCredential"
            ],
            "Resource": "*"
        }
    ]
}
Докладніше процес створення IAM-користувача описано в офіційній документації на сайті OKD: Creating an IAM user.

1.3.5. Необхідні дозволи AWS для користувача IAM

Для розгортання всіх компонентів кластера OpenShift Container Platform користувачеві IAM потрібні дозволи, які необхідно прикріпити до цього користувача.
Приклад таких дозволів наведено у наступній документації на сайті OKD: Required AWS permissions for the IAM user.

1.4. Створення додаткових облікових записів

Перед встановленням OpenShift Container Platform на Amazon Web Services (AWS), необхідно створити обліковий запис Docker Hub та Red Hat.
Це необхідно зробити для формування docker pull secret, який буде використовуватись пізніше.

1.4.1. Створення облікового запису Docker Hub

  • Деякі сервіси використовують images, які знаходяться у репозиторіях на Docker Hub. Для того, щоб мати можливість їх використовувати, потрібно створити акаунт, користуючись офіційною документацією на сайті Docker: Docker ID accounts.

  • Окрім цього, виникнуть проблеми із лімітом на кількість завантажень images на день. Це призведе до того, що сервіси не зможуть запуститися. Щоб цього уникнути, необхідно оновити підписку до рівня Pro. Це допоможе змінити обмеження на кількість пулів із 200 docker-образів/6 годин до 5000 docker-образів/день. Це можливо зробити користуючись офіційною документацією на сайті Docker: Upgrade your subscription.

1.4.2. Створення облікового запису Red Hat

Для того, щоб завантажити необхідні images для встановлення OpenShift Container Platform, необхідно створити Red Hat Account. Докладніше про те, як це зробити, описано в офіційній документації: Red Hat Login ID and Account.

Це необхідно для того, щоб завантажити сформований pull secret пізніше (докладніше описано у розділі Підготовка до встановлення OKD-кластера в AWS). Він дозволить пройти автентифікацію та завантажити образи контейнерів для компонентів OpenShift Container Platform.

2. Розгортання додаткових ресурсів для інсталяції OKD-кластера в AWS

Для вдалого встановлення кластера та платформи, потрібно підняти наступні ресурси в AWS. На малюнку нижче зображена схема інфраструктури із ними. Це зроблено для спрощення інсталяції платформи та уникнення небажаних помилок, які можуть бути пов’язані з встановленням із локального комп’ютера.

image

2.1. Опис додаткових ресурсів

Більш докладний опис додаткових ресурсів зі схеми подано нижче:

  • S3-кошик — використовується для зберігання стану Terraform;

  • DynamoDB table — використовується для збереження інформації про блокування стану Terraform;

  • NAT Gateway — використовується для забезпечення приватного сервера доступом до інтернету;

  • Bastion — використовується як проміжний сервер для забезпечення безпечного та обмеженого доступу до сервера у приватній мережі. Надалі, через цей bastion буде створено SSH-тунель до deployer-node;

  • Deployer-node — сервер у приватній мережі, через який буде відбуватися інсталяція кластера та Платформи.

Розгорнути ці ресурси можна за допомогою підготовленого Terraform-коду у наступних кроках.

2.1.1. Рекомендовані налаштування bastion

У таблиці нижче наведено рекомендовані налаштування для bastion .

Таблиця 1. Налаштування bastion
№ Опція налаштування Значення

1

Instance type

t2.nano

2

vCPUs

1

3

RAM

0.5 GiB

4

CPU Credits/hr

3

5

Platform

Ubuntu

6

AMI name

ubuntu-bionic-18.04-amd64-server-20210224

7

Volume

8 Gb

2.1.2. Рекомендовані налаштування deployer-node

У таблиці нижче наведено рекомендовані налаштування для deployer-node.

Таблиця 2. Налаштування deployer-node
№ Опція налаштування Значення

1

Instance type

t2.medium

2

vCPUs

2

3

RAM

4 GiB

4

CPU Credits/hr

24

5

Platform

Ubuntu

6

AMI name

ubuntu-bionic-18.04-amd64-server-20210224

7

Volume

150 Gb

2.2. Додаткові налаштування

2.2.1. Встановлення необхідних інструментів

Для подальших дій потрібно встановити необхідні інструменти на локальний комп’ютер:

Перевірити правильність встановлення інструментів можна за допомогою наступних команд:

Приклад 1. Перевірка встановлення інструментів
Перевірка unzip
$ unzip -v
Перевірка aws cli
$ aws --version
Перевірка terraform
$ terraform version

2.2.2. Налаштування AWS CLI

За допомогою AWS CLI автентифікуйтесь в обліковому записі AWS. Для цього виконайте наступну команду:

Автентифікація в обліковому записі AWS
$ aws configure
AWS Access Key ID [None]: ********************
AWS Secret Access Key [None]: ***************************************
Default region name [None]: eu-central-1
Default output format [None]: json
Докладніше процес автентифікація в обліковому записі AWS за допомогою AWS CLI описано в офіційній документації на сайті AWS: Configure the AWS CLI.

2.2.3. Налаштування AWS cross account

Перед запуском Terraform-код його необхідно завантажити. Для цього треба отримати доступ до AWS S3 бакету, в якому він знаходиться. Це можливо лише за умови, що створена спеціальна IAM-роль. Це можна зробити, виконавши наступні кроки:

  1. Створіть AWS IAM-роль.

    $ aws iam create-role \
      --role-name UserCrossAccountRole \
      --description "Role for uploading terraform files from AWS S3" \
      --assume-role-policy-document '{
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Action": "sts:AssumeRole",
                    "Effect": "Allow",
                    "Principal": {
                        "AWS": "arn:aws:iam::<YourAccountId>:root"
                    }
                }
            ]
          }'

    • <YourAccountId> — додайте сюди ID від облікового запису AWS.

  2. Створіть AWS IAM-політику.

    $ aws iam create-policy \
      --policy-name UserCrossAccountPolicy \
      --policy-document '{
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Action": "sts:AssumeRole",
                    "Effect": "Allow",
                    "Resource": "arn:aws:iam::764324427262:role/CustomCrossAccountRole"
                }
            ]
          }'

  3. Приєднайте політику до ролі.

    $ aws iam attach-role-policy \
      --role-name UserCrossAccountRole \
      --policy-arn arn:aws:iam::<YourAccountId>:policy/UserCrossAccountPolicy

    • <YourAccountId> — додайте сюди ID від облікового запису AWS.

  4. Додайте до файлу config необхідні значення для ролі.

    $ cat <<EOT >> ~/.aws/config
[profile user-cross-account-role]
role_arn = arn:aws:iam::764324427262:role/CustomCrossAccountRole
source_profile = default
EOT

  5. Для доступу до файлів із зовнішнього облікового запису AWS, зверніться до команди підтримки. Вам потрібно, щоб вони додали ID вашого AWS облікового запису до списку довірених (trust relationship) для ролі CustomCrossAccountRole у їхньому обліковому записі AWS.

2.2.4. Завантаження Terraform-коду

  1. Завантажте архів з Terraform-кодом.

    $ aws s3 cp s3://mdtu-ddm-platform-installer/terraform/terraform.zip terraform.zip  --profile user-cross-account-role

  2. Розпакуйте Terraform-код в окрему директорію.

    $ unzip terraform.zip -d ~/terraform

2.3. Опис Terraform-коду

Як приклад автоматизації процесу було реалізовано Terraform-код, який можна підлаштувати під свої параметри та використати для розгортання інфраструктури.

2.3.1. Початковий Terraform-код

Це Terraform-код, який створить ресурси для подальших кроків. До таких ресурсів відносяться:

  • S3 Bucket

  • DynamoDB Table

Початковий код. Опис Terraform-файлів:

  • main.tf — основний конфігураційний Terraform файл. Він містить модулі для створення:

    • S3-бакета;

    • таблиці DynamoDB.

  • providers.tf — використовується для визначення версії Terraform, необхідних плагінів та параметрів провайдера AWS;

  • variables.tf — використовується для опису всіх змінних, які використовуються в конфігурації Terraform;

  • terraform.tfvars — містить значення для конкретних змінних, які визначені у конфігураційних файлах Terraform. За потреби змініть значення для наступних параметрів на необхідні:

    • region — ця змінна використовується для визначення регіону AWS, в якому будуть створюватися ресурси;

    • tags — ця змінна, використовується для додавання тегів (міток) для ресурсів.

2.3.2. Основний Terraform-код

Основний Terraform-код, розгортає усі необхідні ресурси. Опис шаблонів наведено нижче.

Основний код. Опис Terraform файлів

  • main.tf — основний конфігураційний Terraform файл. Він містить модулі для створення:

    • VPC;

    • ec2_bastion;

    • ec2_instance;

    • key_pair.

  • providers.tf — використовується для визначення версії Terraform, необхідних плагінів та параметрів провайдера AWS. Обов’язково змініть значення для наступних параметрів на необхідні:

    • bucket — ця змінна містить ім’я S3-бакета. Змініть <ACCOUNT_ID> на ID від облікового запису AWS.

  • iam-node-role.tf — використовується для створення спеціальної IAM-ролі із необхідними дозволами. Це дасть змогу налаштувати AWS cross account resource access та завантажити Docker-образ для контейнера та Інсталера;

  • elastic-ip.tf – використовується для створення ресурсу AWS Elastic IP (EIP) за допомогою Terraform;

  • security-groups.tf — створюються Security Groups, які дозволяють SSH-з’єднання (TCP порт 22) для bastion та deployer-node;

  • ssh-key.tf — містить код для створення SSH приватного ключа та збереження ключа у файл та налаштування його прав доступу;

  • files/user_data.sh.tpl — шаблон скрипту, який буде виконуватися при створенні або оновленні EC2 інстансу в середовищі AWS. Цей скрипт зробить наступне для deployer-node:

    • встановить Docker;

    • встановить Unzip;

    • встановить AWS CLI v2;

    • додатково налаштує AWS cross account resource access.

  • variables.tf — використовується для опису всіх змінних, які використовуються в конфігурації Terraform;

  • terraform.tfvars — містить значення для конкретних змінних, які визначені у конфігураційних файлах Terraform. За потреби змініть значення для наступних параметрів на необхідні:

    • region — ця змінна використовується для визначення регіону AWS, в якому будуть створюватися ресурси;

    • platform_name — ця змінна використовується для додавання назви для кластера та ресурсів AWS;

    • ingress_cidr_blocks — для підключення через SSH до deployer-node потрібно додати сюди необхідну IP адресу;

    • prefix_list_ids — якщо потрібно відкрити для підключення декілька адрес, то потрібно створити префікс prefix-list та використовувати в цьому параметрі його ID;

    • tags — ця змінна, використовується для додавання тегів (міток) для ресурсів.

2.4. Запуск Terraform-коду

Після зробленних змін в минулих кроках, Terraform-код тепер готовий до запуску.

2.4.1. Запуск початкового Terraform-коду

  1. Послідовно виконуйте наступні команди для того, щоб увійти до директорії з початковим Terraform-кодом та ініціалізувати робочу Terraform-директорію.

    $ cd ~/terraform/initCode

$ terraform init

  2. Використайте наступну команду для застосування змін, визначених у конфігураційних файлах та створення ресурсів.

    $ terraform apply -auto-approve

  3. Дочекайтеся створення ресурсів.

2.4.2. Запуск основного Terraform-коду

  1. Послідовно виконуйте наступні команди для того, щоб увійти до директорії з основним Terraform-кодом та ініціалізувати робочу Terraform-директорію.

    $ cd ~/terraform/mainCode

$ terraform init

  2. Використайте наступну команду для застосування змін, визначених у конфігураційних файлах та створення ресурсів.

    $ terraform apply -auto-approve

  3. Дочекайтеся створення ресурсів.

2.5. Підключення до deployer-node

Щоб під’єднатися з локального комп’ютера до deployer-node, потрібно створити SSH-тунель. Це потрібно зробити наступною командою:

Приклад 2. Створення SSH-тунелю
$ ssh -i <SSH_KEY> -L 1256:<NODE_PRIVATE_IP>:22 -N -f ubuntu@<BASTION_PUBLIC_IP>

Після створення SSH-тунелю, можна підключатися до deployer-node. Це потрібно зробити наступною командою:

Приклад 3. Підключення через SSH
$ ssh -i <SSH_KEY> ubuntu@localhost -p 1256
Мета deployer-node

З deployer-node потрібно виконувати усі подальші кроки, а саме інсталяцію кластера та встановлення платформи.

2.6. Запуск контейнера openshift-install

Щоб використовувати docker image контейнера openshift-install для встановлення кластера, потрібно виконати кроки, подані нижче.

  1. Авторизуйтеся в AWS ECR.

    $ sudo aws ecr get-login-password --profile cross-account-role --region eu-central-1 | docker login --username AWS --password-stdin 764324427262.dkr.ecr.eu-central-1.amazonaws.com

  2. Завантажте docker-образ (docker image).

    $ docker pull 764324427262.dkr.ecr.eu-central-1.amazonaws.com/openshift-install:v3

  3. Додайте тег до завантаженого docker-образу.

    $ docker tag 764324427262.dkr.ecr.eu-central-1.amazonaws.com/openshift-install:v3 openshift-install:v3

  4. Створіть нову директорію, в якій зберігатимуться усі дані кластера:

    $ mkdir ~/openshift-cluster

  5. Перейдіть до створеної директорії.

    $ cd ~/openshift-cluster

  6. Запустіть контейнер openshift-install.

    $ sudo docker run --rm -it --name openshift-install-v3 \
    --user root:$(id -g) \
    --net host \
    -v $(pwd):/tmp/openshift-cluster \
    --env AWS_ACCESS_KEY_ID=<КЛЮЧ_ДОСТУПУ> \
    --env AWS_SECRET_ACCESS_KEY=<СЕКРЕТНИЙ_КЛЮЧ_ДОСТУПУ> \
    openshift-install:v3 bash

3. Підготовка до встановлення OKD-кластера в AWS

У версії 4.11 OpenShift Container Platform можливо встановити кастомізований кластер на інфраструктуру, яка передбачена програмою встановлення на Amazon Web Services (AWS).

Версія OKD

Рекомендована версія OKD — 4.11.0-0.okd-2022-08-20-022919.

Для того, щоб встановити кластер потрібно виконати наступні кроки:

  1. Знаходячись у контейнері, перейдіть до директорії /tmp/openshift-cluster.

    $ cd /tmp/openshift-cluster

  2. Виконайте дії, які описані в офіційній документації на сайті OKD Installing a cluster on AWS with customizations, до кроку Obtaining an AWS Marketplace image: Obtaining an AWS Marketplace image.

  3. Завантажте кастомізований OKD інсталер, що містить виправлення blocker-проблеми, описаної в https://issues.redhat.com/browse/OCPBUGS-11636.

    $ aws s3 cp s3://mdtu-ddm-platform-installer/okd-installer/openshift-install-fix-aws-4.11.0-0.okd-2022-08-20-022-fix-aws.tar.gz openshift-install-fix-aws-4.11.0-0.okd-2022-08-20-022-fix-aws.tar.gz --profile cross-account-role

  4. Розархівуйте програму встановлення із завантаженого архіву.

    $ tar xvfz openshift-install-fix-aws-4.11.0-0.okd-2022-08-20-022-fix-aws.tar.gz
    Щоб налаштувати встановлення, потрібно створити файл install-config.yaml і внести до нього необхідні параметри перед тим, як встановити кластер.

  5. Створіть нову директорію для конфігураційних файлів кластера та файл install-config.yaml. Для цього виконайте послідовно наступні команди:

    $ mkdir /tmp/openshift-cluster/cluster-state

$ touch /tmp/openshift-cluster/cluster-state/install-config.yaml

    Після створення файлу потрібно заповнити його необхідними параметрами. Створений конфігураційний файл включає тільки необхідні параметри для мінімального розгортання кластера. Для кастомізації налаштувань можна звернутись до офіційної документації.

    Рекомендовані параметри для файлу install-config.yaml:
    install-config.yaml 
    apiVersion: v1
baseDomain: <BASE_DOMAIN>(1)
compute:
  - architecture: amd64
    hyperthreading: Enabled
    name: worker
    platform:
      aws:
        zones:
          - eu-central-1c
        rootVolume:
          size: 80
          type: gp3
        type: r5.2xlarge
        amiID: ami-094fe1584439e91dd
    replicas: 3
controlPlane:
  architecture: amd64
  hyperthreading: Enabled
  name: master
  platform:
    aws:
      zones:
        - eu-central-1c
      rootVolume:
        size: 80
        type: gp3
      type: r5.xlarge
  replicas: 3
metadata:
  name: <CLUSTER_NAME>(2)
networking:
  clusterNetwork:
    - cidr: 10.128.0.0/14
      hostPrefix: 23
  machineNetwork:
    - cidr: 10.0.0.0/16
  networkType: OVNKubernetes
platform:
  aws:
    region: eu-central-1
    userTags:
      'user:tag': <CLUSTER_NAME>(2)
publish: External
pullSecret: <PULL_SECRET>(4)
sshKey: <SSHKEY>(3)

    • (1) <BASE_DOMAIN> — домен, який було створено та налаштовано у підрозділах Налаштування Route 53 та Налаштування зовнішнього домену;

    • (2) <CLUSTER_NAME> — ім’я майбутнього OKD-кластера;

    • (3) <SSHKEY> — ключ або ключі SSH для автентифікації доступу до машин кластера. Можна використати той самий ключ, що був створений під час встановлення OKD-кластера, або будь-який інший;

      Докладніше описано в офіційній документації на сайті OKD: Optional configuration parameters.

    • (4) <PULL_SECRET> — секрет, який було створено у п. Створення додаткових облікових записів. Потрібно отримати цей секрет із Red Hat OpenShift Cluster Manager.

      Докладніше про це описано в п. 5 офіційної документації на сайті OKD: Obtaining the installation program.

      До отриманого секрету також потрібно додати секрет для під’єднання до облікового запису Red Hat, а також секрет від акаунта Docker Hub. Об’єднаний секрет буде виглядати наступним чином:

      Приклад об’єднаного секрету (pull secret) 
      {
   "auths":{
      "cloud.openshift.com":{
         "auth":"b3Blb=",
         "email":"test@example.com"
      },
      "quay.io":{
         "auth":"b3Blb=",
         "email":"test@example.com"
      },
      "registry.connect.redhat.com":{
         "username":"test",
         "password":"test",
         "auth":"b3Blb=",
         "email":"test@example.com"
      },
      "registry.redhat.io":{
         "username":"test",
         "password":"test",
         "auth":"b3Blb=",
         "email":"test@example.com"
      },
      "index.docker.io/v2/":{
         "username":"test",
         "password":"test",
         "auth":"b3Blb=",
         "email":"test@example.com"
      }
   }
}

      Для зручності запису цього секрету в файл install-config.yaml потрібно записати його в один рядок. Фінальний секрет буде виглядати наступним чином:

      Приклад pull secret в один рядок 
      '{"auths":{"cloud.openshift.com":{"auth":"b3Blb=","email":"test@example.com"},"quay.io":{"auth":"b3Blb=","email":"test@example.com"},"registry.connect.redhat.com":{"username":"test","password":"test","auth":"b3Blb=","email":"test@example.com"},"registry.redhat.io":{"username":"test","password":"test","auth":"b3Blb=","email":"test@example.com"},"index.docker.io/v2/":{"username":"test","password":"test","auth":"b3Blb=","email":"test@example.com"}}}'
    Після запуску процесу розгортання кластера, Інсталер видаляє install-config.yaml, тому рекомендовано виконати резервування цього файлу, якщо є потреба розгортання кількох кластерів.

  6. Також виконайте наступну команду для кастомізації встановлення OpenShift кластеру версії 4.11. Ця змінна дозволяє вказати конкретний образ, який буде використовуватися під час інсталяції.

    $ export OPENSHIFT_INSTALL_RELEASE_IMAGE_OVERRIDE="quay.io/openshift/okd:4.11.0-0.okd-2022-08-20-022919"

4. Запуск OKD4-інсталера та розгортання порожнього кластера OKD4

Після створення файлу install-config.yaml, для розгортання OKD-кластера виконайте наступну команду:

Встановлення OKD-кластера
$ ./openshift-install create cluster --dir /tmp/openshift-cluster/cluster-state --log-level=info
Процес розгортання кластера зазвичай займає до 1 години часу.

При успішному розгортанні, в результаті виконання команди будуть представлені наступні параметри доступу до кластера:

  • логін;

  • пароль;

  • посилання до вебконсолі кластера.

image

У директорії, де виконувалася команда, буде створено ряд файлів, що зберігають статус кластера, необхідний для його деінсталяції.

Докладніше про це описано в офіційній документації на сайті OKD, у секції Prerequisites: Uninstalling a cluster on AWS.

Також в цій директорії з’явиться папка /auth, в якій буде збережено два файли для автентифікації: для роботи із кластером через вебконсоль та інтерфейс командного рядка OKD (OKD CLI).

5. Заміна самопідписаних сертифікатів на довірені сертифікати

Для заміни самопідписаних (self-signed) сертифікатів на довірені (trusted), необхідно спочатку отримати ці сертифікати.

У цьому пункті розглянуто отримання безплатних сертифікатів Let’s Encrypt та їх встановлення на сервер.

Отримання сертифікатів Let’s Encrypt здійснено за допомогою утиліти acme.sh.

Для отримання деталей використання Let’s Encrypt на базі ACME-протоколу, зверніться до офіційного джерела.
Для заміни сертифікатів потрібно виконати наступні дії:

  1. Задайте змінну середовища. Змінна повинна вказувати на файл kubeconfig.

    $ export KUBECONFIG=cluster-state/auth/kubeconfig

  2. Створіть файл letsencrypt.sh та вставте у нього скрипт, який наведено нижче:

    Скрипт для заміни сертифікатів 
    #!/bin/bash
yum install -y openssl
mkdir -p certificates
export CERT_HOME=./certificates
export CURDIR=$(pwd)
cd $CERT_HOME

# Клонування утиліти acme.sh із репозиторію GitHub
git clone https://github.com/neilpang/acme.sh
sed -i "2i AWS_ACCESS_KEY_ID=\"${AWS_ACCESS_KEY_ID}\"" ./acme.sh/dnsapi/dns_aws.sh
sed -i "3i AWS_SECRET_ACCESS_KEY=\"${AWS_SECRET_ACCESS_KEY}\"" ./acme.sh/dnsapi/dns_aws.sh
cd $CURDIR
# Отримання API Endpoint URL
export LE_API="$(oc whoami --show-server | cut -f 2 -d ':' | cut -f 3 -d '/' | sed 's/-api././')"
#  Отримання Wildcard Domain
export LE_WILDCARD="$(oc get ingresscontroller default -n openshift-ingress-operator -o jsonpath='{.status.domain}')"
${CERT_HOME}/acme.sh/acme.sh --register-account -m user_${RANDOM}@example.com
${CERT_HOME}/acme.sh/acme.sh --issue -d ${LE_API} -d *.${LE_WILDCARD} --dns dns_aws
export CERTDIR=$CERT_HOME/certificates
mkdir -p ${CERTDIR}

# Перенесення сертифікатів із шляху acme.sh за замовчуванням (default path) до більш зручної директорії, за допомогою --install-cert - ключа
${CERT_HOME}/acme.sh/acme.sh --install-cert -d ${LE_API} -d *.${LE_WILDCARD} --cert-file ${CERTDIR}/cert.pem --key-file ${CERTDIR}/key.pem --fullchain-file ${CERTDIR}/fullchain.pem --ca-file ${CERTDIR}/ca.cer
# Створення секрету
oc create secret tls router-certs --cert=${CERTDIR}/fullchain.pem --key=${CERTDIR}/key.pem -n openshift-ingress
# Оновлення Custom Resource для Router
oc patch ingresscontroller default -n openshift-ingress-operator --type=merge --patch='{"spec": { "defaultCertificate": { "name": "router-certs" }}}'

  3. Зробіть цей скрипт таким, що можливо виконати.

    $ chmod +x ./letsencrypt.sh

  4. Виконайте цей скрипт.

    $ bash -x ./letsencrypt.sh

  5. Вийдіть із контейнера після виконання скрипту. Це можна зробити за допомогою команди, яка знаходиться нижче. Контейнер видалиться автоматично.

    Вихід із контейнера
    $ exit

6. Підготовка та запуск Інсталера для розгортання та оновлення Платформи в OKD-кластері

Для запуску Інсталера необхідно виконати ряд умов з підготовки робочої станції, з якої запускатиметься Інсталер.

6.1. Розгортання з нуля

6.1.1. Передумови

Перед запуском скрипту з інсталювання Платформи, необхідно виконати наступні кроки:

  1. Завантажте Інсталер відповідної версії, послідовно виконавши наступні команди.

    $ mkdir ~/installer

$ cd ~/installer

$ sudo aws s3 cp --profile cross-account-role s3://mdtu-ddm-platform-installer/<VERSION>/mdtu-ddm-platform-<VERSION>.zip mdtu-ddm-platform-<VERSION>.zip

  2. Розпакуйте Інсталер в окрему директорію.

    $ unzip mdtu-ddm-platform-(version).zip -d ./installer-<VERSION>

  3. Перенесіть kubeconfig від встановленого кластера.

    $ cp ~/openshift-cluster/cluster-state/auth/kubeconfig ./installer-<VERSION>

  4. Перенесіть kubeconfig від встановленого кластера.

    $ cp ~/openshift-cluster/cluster-state/auth/kubeconfig ./installer-<VERSION>

  5. Перенесіть сертифікати та допоміжні файли сервісу digital-signature-ops в директорію certificates та увійдіть до директорії з Інсталером.

    $ cp -r /path/to/folder/certificates/ ./installer-<VERSION>

$ cd installer-<VERSION>

6.1.2. Налаштування для Minio

Під час запуску Інсталера та розгортання Платформи з нуля додаткові налаштування для Minio не потрібні.

6.1.3. Налаштування для Vault

Під час запуску Інсталера та розгортання Платформи з нуля додаткові налаштування для Vault не потрібні.

6.1.4. Розгортання Платформи з Інсталера

  1. Виконайте наступні команди:

    $ IMAGE_CHECKSUM=$(sudo docker load -i control-plane-installer.img | sed -r "s#.*sha256:(.*)#\1#" \| tr -d '\n')
    $ echo $IMAGE_CHECKSUM
    $ sudo docker tag ${IMAGE_CHECKSUM} control-plane-installer:<VERSION>

  2. Запустіть процес інсталювання нової Платформи з образами (images):

    $ sudo docker run --rm \
    --name control-plane-installer-<VERSION> \
    --user root:$(id -g) \
    --net host \
    -v $(pwd):/tmp/installer \
    --env KUBECONFIG=/tmp/installer/kubeconfig \
    --env idgovuaClientId=f90ab33dc272f047dc330c88e5663b75 \
    --env idgovuaClientSecret=cba49c104faac8c718e6daf3253bc55f2bf11d9e \
    --env CUSTOM_INGRESS_CIDRS='["0.0.0.0/0", "85.223.209.0/24"]' \
    --env deploymentMode=<DEPLOYMENT_MODE> \
    --entrypoint "/bin/sh" control-plane-installer:<VERSION> \
    -c "./install.sh -i"

    • --rm — цей параметр автоматично видалить контейнер після завершення його роботи. Параметр можна прибрати, якщо потрібно дізнатися статус та лог завершеного контейнера або при нестабільному інтернет-з’єднанні.

    • DEPLOYMENT_MODE — може бути development чи production.

6.1.5. Статус розгортання

Зображений нижче фінальний лог свідчить про вдале завершення процесу оновлення Платформи:

image

Якщо у п. Розгортання Платформи з Інсталера було прибрано опцію --rm, необхідно:

  1. Виконати наступну команду, щоб впевнитися, що контейнер завершився зі статусом 0 (статус контейнера, що свідчить про те, що він успішно завершив роботу).

    $ docker ps --all --latest

    image

  2. Видалити контейнер наступною командою:

    $ docker rm $(docker ps --latest -q)

6.1.6. Необхідні кроки після розгортання

  1. Після встановлення Платформи потрібно перевірити, що запустився пайплайн cluster-management, та впевнитися, що він пройшов успішно (має зелений статус). Після цього Платформа стане придатною для розгортання реєстрів. Без цієї дії реєстри не розгорнуться.

    Пайплайн cluster-management можна знайти за наступним шляхом:

    OKD Web UI > control-plane NS > Routes > jenkins url > cluster-mgmt > MASTER-Build-cluster-mgmt.

  2. Виконайте запит щодо надання доступу до IIT-віджета, а саме https://eu.iit.com.ua/sign-widget/v20200922/.

Стан додаткових ресурсів

Після виконання усіх дій, bastion та deployer-node можна вимкнути. Вони не будуть потрібні до наступного оновлення Платформи.

6.2. Оновлення

6.2.1. Передумови

Перед запуском скрипту з інсталювання Платформи, необхідно виконати наступні кроки:

  1. Завантажте Інсталер відповідної версії, послідовно виконавши наступні команди.

    $ mkdir ~/installer

$ cd ~/installer

$ sudo aws s3 cp --profile cross-account-role s3://mdtu-ddm-platform-installer/<VERSION>/mdtu-ddm-platform-<VERSION>.zip mdtu-ddm-platform-<VERSION>.zip

  2. Розпакуйте Інсталер в окрему директорію.

    $ unzip mdtu-ddm-platform-(version).zip -d ./installer-<VERSION>

  3. Перенесіть kubeconfig від встановленого кластера.

    $ cp ~/openshift-cluster/cluster-state/auth/kubeconfig ./installer-<VERSION>

  4. Перенесіть kubeconfig від встановленого кластера.

    $ cp ~/openshift-cluster/cluster-state/auth/kubeconfig ./installer-<VERSION>

  5. Перенесіть сертифікати та допоміжні файли сервісу digital-signature-ops в директорію certificates та увійдіть до директорії з Інсталером.

    $ cp -r /path/to/folder/certificates/ ./installer-<VERSION>

$ cd installer-<VERSION>

6.2.2. Налаштування для Minio

  1. Перенесіть terraform state minio з минулого релізу.

    $ cp ~/installer/installer-<VERSION>/terraform/minio/aws/terraform.tfstate ./terraform/minio/aws/

  2. Перенесіть ключ від minio з минулого релізу.

    $ cp ~/installer/installer-<VERSION>/terraform/minio/aws/private_minio.key ./terraform/minio/aws/

6.2.3. Налаштування для Vault

  1. Перенесіть terraform state vault з минулого релізу.

    $ cp ~/installer/installer-<VERSION>/terraform/vault/aws/terraform.tfstate ./terraform/vault/aws/

  2. Перенесіть ключ від vault з минулого релізу.

    $ ~/installer/installer-<VERSION>/terraform/vault/aws/private.key ./terraform/vault/aws/

6.2.4. Оновлення платформи з Інсталера

  1. Виконайте наступні команди:

    $ IMAGE_CHECKSUM=$(sudo docker load -i control-plane-installer.img | sed -r "s#.*sha256:(.*)#\1#" \| tr -d '\n')
    $ echo $IMAGE_CHECKSUM
    $ sudo docker tag ${IMAGE_CHECKSUM} control-plane-installer:<VERSION>

  2. Оновіть версію платформи з образами (images)

    $ sudo docker run --rm \
    --name control-plane-installer-<VERSION> \
    --user root:$(id -g) \
    --net host \
    -v $(pwd):/tmp/installer \
    --env KUBECONFIG=/tmp/installer/kubeconfig \
    --env ID_GOV_UA_CLIENT_ID=mock \
    --env ID_GOV_UA_CLIENT_SECRET=mock \
    --entrypoint "/bin/sh" control-plane-installer:<VERSION> \
    -c "./install.sh -u"

    • --rm — цей параметр автоматично видалить контейнер після завершення його роботи. Параметр можна прибрати, якщо потрібно дізнатися статус та лог завершеного контейнера або при нестабільному інтернет-з’єднанні.

    Запустіть скрипт двічі, якщо отриманий лог НЕ відповідає пункту Статус оновлення.

6.2.5. Статус оновлення

Зображений нижче фінальний лог свідчить про вдале завершення процесу оновлення Платформи.

image

Якщо у п. Оновлення платформи з Інсталера було прибрано опцію --rm, необхідно:

  1. Виконати наступну команду, щоб впевнитися, що контейнер завершився зі статусом 0 (статус контейнера, що свідчить про те, що він успішно завершив роботу).

    $ docker ps --all --latest

    image

  2. Видалити контейнер наступною командою:

    $ docker rm $(docker ps --latest -q)

6.2.6. Необхідні кроки після оновлення

Після оновлення Платформи з Інсталера:

  1. Перейдіть до розділу Оновлення.

  2. Виконайте необхідні спеціальні кроки для оновлення до вашої версії Платформи.

  3. В рамках виконання спеціальних кроків оновіть інфраструктурні компоненти Платформи через інтерфейс Control Plane.

Стан додаткових ресурсів

Після виконання усіх дій, bastion та deployer-node можна вимкнути. Вони не будуть потрібні до наступного оновлення Платформи.

7. Типові помилки під час розгортання платформи

Ця секція надає інформацію про типові помилки, які можуть виникнути під час розгортання платформи з нуля, та методи їх вирішення.

7.1. Помилка із bootstrap-машиною під час розгортання OKD кластера

Опис проблеми

Під час розгортання кластера виникає наступна помилка:

Помилка із bootstrap віртуальною машиною
level=error msg=Attempted to gather ClusterOperator status after installation failure: listing ClusterOperator objects: Get "https://api.<CLUSTER_URL>:6443/apis/config.openshift.io/v1/clusteroperators": dial tcp <CLUSTER_IP>:6443: connect: connection refused
level=error msg=Bootstrap failed to complete: Get "https://api.<CLUSTER_URL>:6443/version": dial tcp <CLUSTER_IP>:6443: connect: connection refused
level=error msg=Failed waiting for Kubernetes API. This error usually happens when there is a problem on the bootstrap host that prevents creating a temporary control plane.

Ця помилка пов’язана із віртуальною машиною bootstrap і зазвичай трапляється, коли на хості bootstrap є проблема, яка перешкоджає створенню тимчасової Control Plane.

Розв’язання проблеми

  1. Запустіть команду для видалення кластера, залишивши той самий параметр --dir.

    Видалення OKD-кластера
    $ ./openshift-install destroy cluster --dir /tmp/openshift-cluster/cluster-state --log-level info

  2. Дочекайтеся видалення кластера та ще раз запустіть команду для його встановлення.

    Повторне встановлення кластера
    $ ./openshift-install create cluster --dir /tmp/openshift-cluster/cluster-state --log-level=info

7.2. Помилка із Vault-токеном під час розгортання Платформи

Опис проблеми

Під час розгортання Платформи, на етапі встановлення Vault, може трапитися помилка, коли змінна vault_root_token повертає порожнє значення:

image

Ця помилка пов’язана із тим, що Vault не запустився успішно, або були пропущенні деякі кроки інсталяції платформи.

Розв’язання

  1. Відкрийте обліковий запис AWS. Знайдіть віртуальну машину platform-vault-<CLUSTER_NAME>.

  2. Перейдіть на віртуальну машину, використовуючи EC2 Instance Connect або SSH.

  3. Перевірте статус Vault. Параметр Initialized має бути у значенні true.

    Отримати статус Vault
    $ vault status

    image

  4. Якщо статус інший, то перезавантажте Vault.

    Рестарт vault
    $ systemctl restart vault

  5. Якщо ця помилка сталася під час оновлення Платформи, то перевірте, чи було перенесено ключ від Vault з минулого релізу, як описано у п. Налаштування для Vault.

  6. Спробуйте ще раз запустити процес оновлення Платформи, як описано у Оновлення платформи з Інсталера.

7.3. Помилка із Minio SSL-сертифікатом під час розгортання Платформи

Опис проблеми

Під час розгортання Платформи, на етапі встановлення Minio, може трапитися наступна помилка:

image

Розв’язання

  1. Увійдіть до директорії з Інсталером та запустіть контейнер для встановлення Платформи наступною командою:

    Запуск контейнера
    $ cd ~/installer/installer-<VERSION>
$ sudo docker run -it --rm \
    --name control-plane-installer-<VERSION> \
    --user root:$(id -g) \
    --net host \
    -v $(pwd):/tmp/installer \
    --env KUBECONFIG=/tmp/installer/kubeconfig \
    --env idgovuaClientId=f90ab33dc272f047dc330c88e5663b75 \
    --env idgovuaClientSecret=cba49c104faac8c718e6daf3253bc55f2bf11d9e \
    --env deploymentMode=<DEPLOYMENT_MODE> control-plane-installer:<VERSION> bash

  2. Перейдіть до необхідної директорії та задайте змінні середовища.

    Вказання змінних середовища
    $ cd /tmp/installer/terraform/minio/aws
$ export AWS_ACCESS_KEY_ID=$(oc get secret/aws-creds -n kube-system -o jsonpath='{.data.aws_access_key_id}' | base64 -d)
$ export AWS_SECRET_ACCESS_KEY=$(oc get secret/aws-creds -n kube-system -o jsonpath='{.data.aws_secret_access_key}' | base64 -d)
$ export CLUSTER_NAME=$(oc get node -l node-role.kubernetes.io/master -o 'jsonpath={.items[0].metadata.annotations.machine\.openshift\.io/machine}' | sed -r 's#.*/(.*)-master.*#\1#')
$ export clusterNameShort="${CLUSTER_NAME::-6}"
$ export baseDomain=$(oc get dns cluster --no-headers -o jsonpath='{.spec.baseDomain}')
$ export route53HostedZone="${baseDomain/${clusterNameShort}./}"

  3. Видаліть Minio за допомогою Terraform.

    Видалення Minio
    $ terraform init
$ terraform destroy -var cluster_name="${clusterNameShort}" -var baseDomain="${route53HostedZone}" -auto-approve

  4. Дочекайтеся видалення Minio. Вийдіть із контейнера та спробуйте ще раз запустити процес встановлення Платформи, як описано у п. Розгортання Платформи з Інсталера, якщо ви розгортаєте платформу з нуля, або п. Оновлення платформи з Інсталера, якщо ви оновлюєте платформу.

7.4. Помилка при відправленні образів до Nexus під час розгортання Платформи

Опис проблеми

Під час розгортання Платформи, на етапі відправлення образів до Nexus, може трапитися наступна помилка:

image

Ця помилка пов’язана зі skopeo. Цей інструмент надсилає образи до Nexus. Якщо образ не зміг завантажитися за 10 хвилин, то skopeo починає повертати помилку через тайм-аут.

Розв’язання

Виконувати встановлення Платформи із deployer-node, як описано в п. Розгортання додаткових ресурсів для інсталяції OKD-кластера в AWS.