terraform-provider-dynamix/wiki/1.0.0/07.01.06-Resource_dynamix_k8s.md

_Resource_ функция **dynamix_k8s** служит для управления кластером.

### Работа с cluster_config

Для использования cluster_config конфигурации, следует:

1. Создать файл с расширением `.json` в рабочей директории.
2. Описать в созданном файле конфигурацию cluster_config в формате JSON:

#### cluster_config.json

```json
{
  "apiServer": {
    "extraArgs": {
      "oidc-issuer-url": "https://dex.decs.local/",
      "oidc-client-id": "dex",
      "oidc-username-claim": "email",
      "oidc-groups-claim": "groups",
      "oidc-ca-file": "/etc/kubernetes/ssl/kc-ca.pem"
    }
  }
}
```

3. Указать путь до файла `cluster_config.json` в качестве значения параметра `cluster_config` в ресурсе `dynamix_k8s`:

```terraform
resource "dynamix_k8s" "cluster1" {
   # ...

   cluster_config = file("cluster_config.json")

   # ...
}
```

4. Выполнить `terraform apply`

### Работа с oidc\_\_cert

Для работы с oidc_cert следует:

1. Создать файл с ssl-сертификатом в формате x509 pem c названием ca.crt в рабочей директории

#### ca.crt

Пример содержания файла ca.crt

```
-----BEGIN CERTIFICATE-----
MIIDzTCCArWgAwIBAgIUUW9bFlExT8f/gVX4OrYXegInXi0wDQYJKoZIhvcNAQEL
BQAwdjELMAkGA1UEBhMCUlUxDzANBgNVBAgMBk1vc2NvdzEPMA0GA1UEBwwGTW9z
Y293MQwwCgYDVQQKDANBQkMxDDAKBgNVBAsMA0FCQzEMMAoGA1UEAwwDQUJDMRsw
GQYJKoZIhvcNAQkBFgxBQkNAbWFpbC5jb20wHhcNMjMwOTI2MTQ0MzM2WhcNMjQw
OTI1MTQ0MzM2WjB2MQswCQYDVQQGEwJSVTEPMA0GA1UECAwGTW9zY293MQ8wDQYD
VQQHDAZNb3Njb3cxDDAKBgNVBAoMA0FCQzEMMAoGA1UECwwDQUJDMQwwCgYDVQQD
DANBQkMxGzAZBgkqhkiG9w0BCQEWDEFCQ0BtYWlsLmNvbTCCASIwDQYJKoZIhvcN
AQEBBQADggEPADCCAQoCggEBAOUGj6B7sBrAYBuAQ4I0f6plcrLG33cNGzcktZrS
SZRWOMwXzBCUNNOBKXZHnapUAoZW23BllpZ/y50Y01JAggdBPbODw864ZROJMt3P
xlZZJQghraFUF8H/ANsmRzfh3nD98fBSr4YUg2VGEwg+Qvzh2peiNBRer4tD6QuV
BqiJZyUNrz0JUKmFZF/uTM4rNRhmF7y95A49GDZeIzwFFARSMkQPtIjMj8h75fs3
PD41wEkQyV5SSM3YMGQeqp/7ay10ec31s6cn/PBB8bF8PTVYc+hJOfNuVrkm8CqG
w1kzKg+7ztgcCMOEL2yftgckg5PSFMQ+5RPgBieEOj3IDHsCAwEAAaNTMFEwHQYD
VR0OBBYEFPLv18WpzpwIGhqlM2EAHl7TXgNnMB8GA1UdIwQYMBaAFPLv18WpzpwI
GhqlM2EAHl7TXgNnMA8GA1UdEwEB/wQFMAMBAf8wDQYJKoZIhvcNAQELBQADggEB
ADbH2Y4ExwEllkKrQ+VcyajjPXV9vcG5Ag+/9DUM0aFCO4H0ZzdBKHVCGMwIx5sS
gLSLx2zoT2F3oTHaJ4T9iVx+sBleKZZbpApO51dLaVSiy69cfkZy/GOMiWuEEZPU
UdGTMAAoM1+gqx8n0EsGf96zJZ+PtjHi6RdNmPBnuRRvRRPXQKNLJF1kYDgYlFdH
KxLl/lm/Y0zhV/VNd7OXsV0LAsyrRiNpuyCaniCOTR1ZRkD4UfWkc/bbNgbLjAfb
8Y0SjvSiYpFPE0DQv0ksSrhySJtyCy71UTGzSHI+tRB9LwhnDiijAoT7LnxQgNq8
5IdaZNyYvyGubkczwBrFddU=
-----END CERTIFICATE-----
```

2. Указать путь до файла `ca.crt` в качестве значениея параметра `oidc_cert` в ресурсе `dynamix_k8s`

```terraform
resource "dynamix_k8s" "cluster1" {
   # ...

   oidc_cert = file("ca.crt")

   # ...
}
```

3. Выполнить `terraform apply`

### Работа с cloud_init

Cloud Init позволяет запустить ВМ с предустановленными настройками пользователя, группами и доступами. Подробнее про настройку cloud_init можно прочесть по [ссылке](https://cloudinit.readthedocs.io/en/latest/reference/examples.html).

**Пароли, указанные в cloud_init не сохраняются на платформе и не отображаются в API!**

Для использования cloud_init конфигурации, следует:

1. Создать файл с расширением `.tftpl` в рабочей директории.
2. Описать в созданном файле конфигурацию cloud_init в формате YAML:

### initconfig.tftpl

```
---
users:
- groups: users, wheel
  name: user
  plain_text_passwd: examplePassword
  primary_group: user
  ssh_authorized_keys:
  - ssh-rsa EXAMPLE%id_rsa.pub
  sudo: ALL=(ALL) NOPASSWD:ALL

```

3. Указать путь до файла `initconfig.tftpl` в качестве значения параметра `cloud_init` в ресурсе `dynamix_k8s`:

```terraform
resource "dynamix_k8s" "cluster1" {
   # ...

   cloud_init = file("initconfig.tftpl")

   # ...
}
```

4. Выполнить `terraform apply`

**Конфигурация cloud_init применяется только при создании кластера, во всех остальных случаях - игнорируется**

## Работа в параллельном режиме

Рекомендуется создавать одновременно не более одного экземпляра ресурса.
В случае необходимости создания нескольких ресурсов одновременно, необходимо запускать `terraform apply/plan` в режиме `-parallelism=1`.

## Аргументы

_Resource_ функция **dynamix_k8s** для создания кластера принимает следующие аргументы:

| Аргумент | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| name | string | :heavy_check_mark: | Наименование кластера, <br/>при изменении - изменяет наименование кластера |
| rg_id | int | :heavy_check_mark: | ID ресурсной группы |
| k8sci_id | int | :heavy_check_mark: | ID catalogue item |
| wg_name | string | :heavy_check_mark: | Имя для первой worker group, <br/> созданной в кластере |
| network_plugin | string | :heavy_check_mark: | Плагин сети для кластера. Допустимые значения: flannel, calico, weavenet |
| labels | []string | :x: | Список меток для дефолтной worker-группы k8s |
| taints | []string | :x: | Список taints для дефолтной worker-группы k8s |
| annotations | []string | :x: | Список аннотаций дефолтной worker-группы k8s |
| masters | Struct{} [см. ниже](#описание-структуры-masters) | :x: | Настройка мастер-группы |
| workers | Struct{} [см. ниже](#описание-структуры-workers) | :x: | Настройка worker-групп |
| extnet_id | int | :x: | ID внешней сети для соединения workers.<br/>Если не задано,<br/>то сеть будет выбрана платформой. |
| vins_id | int | :x: | ID виртуальной  сети для соединения workers.<br/>Если не задано,<br/>то сеть будет выбрана платформой. |
| cloud_init | string | :x: | Используется на этапе создания вм.<br/>Параметры для утилиты _cloud_init_, которая используется в платформе DYNAMIX для первичного конфигурирования виртуальной машины после её создания |
| init_config | string | :x: | Используется для определения настроек и действий, которые должны быть выполнены перед запуском любого другого компонента в кластере, это позволяет вам настраивать такие вещи, как регистрация node, настройка network и другие задачи инициализации |
| kubelet_config | string | :x: | Используется для настройки поведения и параметров Kubelet, который является агентом primary node, запускаемым на каждом node кластера он включает в себя такие параметры, как IP-адрес node, распределение ресурсов, политики удаления модулей и другие конфигурации, специфичные для Kubelet |
| kube_proxy_config | string | :x: | Используется для настройки поведения и параметров присоединения node к кластеру, он включает в себя такие параметры, как режим прокси-сервера, диапазоны IP-адресов кластера и другие конфигурации, специфичные для Kube-proxy |
| cluster_config | string | :x: | Используется для определения глобальных настроек и конфигураций для всего кластера. Она включает в себя такие параметры, как имя кластера, настройки DNS, методы аутентификации и другие конфигурации в масштабах кластера. вставьте допустимую строку JSON со всеми уровнями вложенности |
| join_config | string | :x: | Используется для настройки поведения и параметров присоединения node к кластеру, он включает в себя такие параметры, как cluster's control plane endpoint, токен и ключ сертификата |
| oidc_cert | string | :x: | ssl-сертификат в формате x509 pem |
| with_lb | bool | :x: | Создать кластер с балансировщиком нагрузки |
| additional_sans | []string | :x: | Дополнительные SAN (Subject Alternative Names) для использования в процессе автоматического выписывания сертификата Кластера Kubernetes, возможность взаимодействовать с кластером по FQDN параметр получает список строк – IP-адреса и/или DNS (по формату RFC 1123 c поддержкой wildcard) |
| lb_sysctl_params | []map[string]interface{} | :x: | Пользовательские значения sysctl для балансировщика нагрузки |
| extnet_only | bool | :x: | Использовать только extnet для работы кластера |
| desc | string | :x: | Описание кластера |
| oidc_cert | string | :x: | ssl-сертификат в формате x509 pem |
| ha_mode | bool | :x: | Режим высокой доступностью балансировщика нагрузки |
| start | bool | :x: | Старт/Стоп кластера |
| permanently | bool | :x: | Мгновенное удаление виртуальной машины, минуя корзину. Параметр считывается только при использовании команды `terraform destroy`, то есть только при удалении ресурса |

### Описание структуры masters

| Аргумент | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| num | int | :heavy_check_mark: | Количество nodes |
| cpu | int | :heavy_check_mark: | Количество cpu |
| ram | int | :heavy_check_mark: | Количество RAM в Mбайтах |
| disk | int | :heavy_check_mark: | Объем boot диска в ГБ |
| sep_id | int | :x: | Идентификатор SEP |
| sep_pool | string | :x: | Название SEP pool'а |

### Описание структуры workers

| Аргумент | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| name | string | :heavy_check_mark: | Наименование воркер-группы |
| num | int | :heavy_check_mark: | Количество nodes |
| cpu | int | :heavy_check_mark: | Количество cpu |
| ram | int | :heavy_check_mark: | Количество RAM в Mбайтах |
| disk | int | :heavy_check_mark: | Объем boot диска в ГБ |
| sep_id | int | :x: | Идентификатор SEP |
| sep_pool | string | :x: | Название SEP pool'а |
| labels | []string | :x: | Список labels |
| annotations | []string | :x: | Список annotations |
| taints | []string | :x: | Список taints |

## Возвращаемые значения

В случае успешного выполнения _resource_ функция **dynamix_k8s** возвращает в указанную при вызове переменную следующие значения:

| Параметр | Тип | Описание |
| --- | --- | --- |
| acl | Struct{} [см. ниже](#описание-структуры-acl) | acl |
| account_id | int | ID аккаунта |
| account_name | string | Имя аккаунта |
| bservice_id | int | ID bservice |
| k8sci_id | int | ID образа кластера |
| created_by | string | Кем был создан ресурс |
| created_time | int | Время создания ресурса |
| deleted_by | string | Кем был удален ресурс |
| deleted_time | int | Время удаления ресурса |
| extnet_id | int | ID внешней сети |
| k8s_ci_name | string | Имя образа кластера |
| masters | []Struct{} [см. ниже](#описание-структуры-masters) | Структура компьютов мастеров |
| workers | []Struct{} [см. ниже](#описание-структуры-workers) | Структура компьютов воркеров |
| lb_id | int | ID балансировщика нагрзуки |
| lb_ip | string | IP балансировщика нагрзуки |
| name | string | Имя ресурса |
| network_plugin | string | Сетевой плагин |
| rg_id | int | ID ресурсной группы |
| rg_name | string | Имя ресурсной группы |
| status | string | Статус ресурса |
| tech_status | string | Технический статус ресурса |
| updated_by | string | Кем был обновлен ресурс |
| updated_time | int | Время последнего обновления ресурса |
| kubeconfig | string | Конфиг |
| vins_id | int | ID виртуальной сети |

### Описание структуры acl

| Параметр | Тип | Описание |
| --- | --- | --- |
| account_acl | []Struct{} [см. ниже](#описание-структуры-списка-acl) | account_acl |
| k8s_acl | []Struct{} [см. ниже](#описание-структуры-списка-acl) | k8s_acl |
| rg_acl | []Struct{} [см. ниже](#описание-структуры-списка-acl) | rg_acl |

### Описание структуры списка acl

| Параметр | Тип | Описание |
| --- | --- | --- |
| explicit | bool | explicit |
| guid | string | ID ресурса |
| right | string | right |
| status | string | Статус ресурса |
| type | string | Тип ресурса |
| user_group_id | string | ID группы |

### Описание структуры masters

| Параметр | Тип | Описание |
| --- | --- | --- |
| cpu | int | Кол-во cpu на компьютах master |
| detailed_info | []Struct{} [см. ниже](#описание-структуры-списка-detailed_info) | Детальная информация masters |
| disk | int | ID диска |
| master_id | int | ID группы master |
| name | string | Имя группы master |
| num | int | Кол-во компьютов в группе master |
| ram | int | Кол-во Ram на компьютах группы master |

### Описание структуры workers

| Параметр | Тип | Описание |
| --- | --- | --- |
| annotations | []string | Аннотации группы workers |
| cpu | int | Кол-во cpu на компьютах workers |
| detailed_info | []Struct{} [см. ниже](#описание-структуры-списка-detailed_info) | Детальная информация masters |
| disk | int | ID диска |
| guid | string | ID ресурса |
| id | int | ID группы workers |
| labels | []string | Лейблы группы workers |
| name | string | Имя ресурса |
| num | int | Кол-во компьютов в группе workers |
| ram | int | Кол-во Ram на компьютах группы workers |
| taints | []string | огранечители группы workers |

### Описание структуры списка detailed_info

| Параметр | Тип | Описание |
| --- | --- | --- |
| compute_id | int | ID компьюта в составе группы |
| name | string | Имя компьюта в составе группы |
| status | string | Статус компьюта в составе группы |
| tech_status | string | Статус компьюта в составе группы |
| interfaces | []Struct{} [см. ниже](#описание-структуры-списка-interfaces) | Список интерфейсов группы |
| natable_vins_ip | string | IP NAT |
| natable_vins_network | string | IP виртуальной сети |

### Описание структуры списка interfaces

| Параметр | Тип | Описание |
| --- | --- | --- |
| def_gw | string | Шлюз по умолчанию |
| ip_address | string | IP интерфейса |

## Пример использования

Пример вызова _resource_ функции **dynamix_k8s**:

```terraform
resource "dynamix_k8s" "cluster" {
  #имя кластера
  #обязательный параметр
  #при изменении - обновляет имя кластера
  #тип - строка
  name = "tftest"

  #id resource group
  #обязательный параметр
  #тип - целое число
  rg_id = 776

  #id catalogue item 
  #обязательный параметр
  #тип - целое число
  k8sci_id = 9

  #сетевой плагин
  #обязательный параметр
  #тип - строка
  network_plugin = "flannel"

  #имя для первой worker group, созданной в кластере
  #обязательный параметр
  #тип - строка
  wg_name = "workers"

  # список labels для дефолтной worker группы
  # опциональный параметр
  # тип - массив строк 
  labels = ["key1=val1", "key2=val2"]

  # список annotations для дефолтной worker группы
  # опциональный параметр
  # В скором времени параметры labels, annotations, taints будут полностью перенесены в структуру workers
  # тип - массив строк 
  annotations = ["key1=val1", "key2=val2"]

  # список taints для дефолтной worker группы
  # опциональный параметр
  # В скором времени параметры labels, annotations, taints будут полностью перенесены в структуру workers
  # тип - массив строк 
  taints = ["key1=value1:NoSchedule", "key2=value2:NoExecute"]

  #настройка мастер node или nodes
  #опциональный параметр
  #максимальное кол-во элементов - 1
  #тип - список нод
  masters {
    #кол-во node (1, 3 или 5)
    #обязательный параметр
    #тип - целое число
    num = 1

    #кол-во cpu
    #обязательный параметр
    #тип - целое число
    cpu = 2

    #кол-во RAM в Мбайтах
    #обязательный параметр
    #тип - целое число
    ram = 2048

    #размер диска в Гбайтах
    #обязательный параметр
    #тип - целое число
    disk = 10

    #идентификатор SEP для создания загрузочных дисков для master узлов
    #опциональный параметр
    #тип - целое число
    sep_id = 3

    #наименование MasterSEPPool используется если установлен master sepId, также может быть пустым
    #опциональный параметр
    #тип - строка
    sep_pool = "data_01"
  }

  #настройка worker группы
  #опциональный параметр
  #Первая указанная воркер-группа должна соответствовать изначально созданной вместе с кластером.
  #labels, annotations, taints для дефолтной worker группы указываются в корне ресурса при создании кластера.
  workers {
    #имя группы
    #обязательный параметр
    #тип - строка
    name = "test"

    #кол-во node
    #обязательный параметр
    #тип - целое число
    num = 1

    #кол-во cpu
    #обязательный параметр
    #тип - целое число
    cpu = 2

    #кол-во RAM в Мбайтах
    #обязательный параметр
    #тип - целое число
    ram = 2048

    #размер диска в Гбайтах
    #обязательный параметр
    #тип - целое число
    disk = 10

    #Идентификатор SEP
    #опциональный параметр
    #тип - целое число
    sep_id = 1010

    #Имя SEP pool'a
    #опциональный параметр
    #тип - строка
    sep_pool = "data01"
  }

  #...Далее можно создавать произвольное кол-во дополнительных worker групп
  #labels, annotations и taints для последующих групп указываются непосредственно в структуре workers
  workers {
    #наименование worker группы
    #обязательный параметр
    #тип - строка
    name = "additional_wg"

    #кол-во node
    #обязательный параметр
    #тип - целое число
    num = 2

    #кол-во cpu
    #обязательный параметр
    #тип - целое число
    cpu = 2

    #кол-во RAM в Мбайтах
    #обязательный параметр
    #тип - целое число
    ram = 4096

    #размер диска в Гбайтах
    #обязательный параметр
    #тип - целое число
    disk = 10

    #идентификатор SEP
    #опциональный параметр
    #тип - целое число
    sep_id = 1010

    #имя SEP pool'a
    #опциональный параметр
    #тип - строка
    sep_pool = "data01"

    #список лейблов
    #опциональный параметр
    #тип - массив строк
    labels = ["label1=value1", "label2=value2"]

    #список аннотаций
    #опциональный параметр
    #тип - массив строк
    annotations = ["key1=value1", "key2=value2"]

    #список taints
    #опциональный параметр
    #тип - массив строк
    taints = ["key1=value1:NoSchedule", "key2=value2:NoExecute"]
  }

  #id extnet
  #опциональный параметр
  #тип - целое число
  extnet_id = 0

  #id vins
  #опциональный параметр
  #тип - целое число
  vins_id = 1234

  #создать Kubernetes cluster с masters nodes с подключенным LB
  #опциональный параметр
  #тип - булев 
  with_lb = true

  #пользовательские значения sysctl для LB
  #опциональный параметр
  #тип - список мап
  lb_sysctl_params = [{ text = "1", text = "some" }]

  #позволяет создать схему отказоустройчивой LB
  #опциональный параметр
  #тип - булев
  ha_mode = true

  #дополнительные SAN (Subject Alternative Names) для использования в процессе автоматического выписывания сертификата Кластера Kubernetes;
  #возможность взаимодействовать с кластером по FQDN
  #параметр получает список строк – IP-адреса и/или DNS (по формату RFC 1123 c поддержкой wildcard)
  #опциональный параметр
  #тип - массив строк
  additional_sans = ["192.168.201.0", "192.168.201.1"]

  #используется для определения настроек и действий, которые должны быть выполнены перед запуском любого другого компонента в кластере
  #это позволяет вам настраивать такие вещи, как регистрация node, настройка network и другие задачи инициализации
  #опциональный параметр
  #тип - строка
  init_config = "{JSON string}"

  #используется для определения глобальных настроек и конфигураций для всего кластера
  #он включает в себя такие параметры, как имя кластера, настройки DNS, методы аутентификации и другие конфигурации в масштабах кластера
  #опциональный параметр
  #тип - строка
  cluster_config = "{JSON string}"

  #используется для настройки поведения и параметров Kubelet, который является агентом primary node, запускаемым на каждом node кластера
  #он включает в себя такие параметры, как IP-адрес node, распределение ресурсов, политики удаления модулей и другие конфигурации, специфичные для Kubelet
  #опциональный параметр
  #тип - строка
  kubelet_config = "{JSON string}"

  #используется для настройки поведения и параметров присоединения node к кластеру
  #он включает в себя такие параметры, как режим прокси-сервера, диапазоны IP-адресов кластера и другие конфигурации, специфичные для Kube-proxy
  #опциональный параметр
  #тип - строка
  kube_proxy_config = "{JSON string}"

  #используется для настройки поведения и параметров присоединения node к кластеру
  #он включает в себя такие параметры, как cluster's control plane endpoint, токен и ключ сертификата
  #опциональный параметр
  #тип - строка
  join_config = "{JSON string}"

  #описание кластера
  #опциональный параметр
  #тип - строка
  desc = "description"

  #перечень аргументов для cloud-init создаваемым группам узлов Worker
  #необязательный параметр
  #тип - файл с форматом в виде yaml
  cloud_init = file("initconfig.tftpl")

  #при создании кластре использовать подключение только к сети ExtNet
  #опциональный параметр
  #тип - булев
  extnet_only = true

  #добавить ssl-сертификат в формате x509 pem
  #необязательный параметр
  #тип - файл с форматом в виде x509 pem
  oidc_cert = file("ca.crt")

  #запуск,остановка кластера
  #опциональный параметр
  #тип - булев
  start = true

  #команда destroy удаляет кластер без возможности восстановления
  #опциональный параметр
  #тип - булев
  permanently = true

}
```

После успешного завершения такого вызова **dynamix_k8s** в переменной `dynamix_k8s.cluster` будут сохранены возвращаемые значения.