Руководство прикладного разработчика#

Термины и определения#

Термин/аббревиатура	Определение
Платформа	Платформа оркестрации приложений со средствами автоматизации и управления на основе политик, например, Kubernetes
Kubernetes	Платформа оркестрации приложений со средствами автоматизации и управления на основе политик
Deployment / kind: Deployment	Набор инструкций для запуска приложения в Kubernetes
Под / kind: Pod	Набор контейнеров внутри узла кластера Kubernetes
Ansible	Инструмент автоматизации подготовки и конфигурирования инфраструктуры
CRD / kind: CustomResourcesDefinitions	Общее описание конфигурации, которое будет храниться в рамках кластера
Пользовательские конфигурации	Конфигурации (CRD), которые реализуются в namespace командами, в формате `.yaml` (подробное описание будет приведено в разделе «Подключение и конфигурирование» и «Использование программного компонента») Предоставляют возможность командам реализовывать следующие функции: ProviderConfig — задание списка Secrets для монтирования в рабочую директорию AnsibleRun и задание настроек Ansible Controller AnsibleRun — установка внешней инфраструктуры через запуск Ansible Playbook
SYAP	Программный компонент Synapse Ansible Provider (код SYAP)
SSM	Platform V Synapse Service Mesh — Программный продукт на базе Istio SE, обеспечивающий возможность создания сервисной сети поверх Платформенной в Kubernetes
URL	Uniform Resource Locator — стандартизированный способ записи адреса ресурса в сети Интернет
Host	Сервер, на котором будет выполняться задача, описанная в AnsibleRun
Ansible Host	Под, в котором происходит запуск Ansible
Ansible Playbook	Набор инструкций для настройки инфраструктуры
Ansible Collection	Набор сгруппированных инструкций для настройки инфраструктуры
Inventory	Набор сгруппированной информации о Host, на которых будет выполняться Ansible Playbook
Reconcile	Цикл работы контроллера компонента SYAP, в рамках которого происходит обработка CRD и выполнение инструкций, указанных в CRD.
Istio	Настраиваемая сервисная сетка с открытым исходным кодом, служащая для взаимодействия, мониторинга и обеспечения безопасности контейнеров в кластере Kubernetes.
Istio SE	Компонент POLM из состава программного продукта Platform V Synapse Service Mesh (код SSM), предоставляющий и расширяющий функционал Istio
Граничный прокси / IGEG / ingressgateway / egressgateway	Компонент Граничный прокси продукта Platform V Synapse Service Mesh

Системные требования#

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

SYAP работает на уровне Платформы.

Подключение и конфигурирование#

SYAP имеет только один сценарий подключения:

Администратор/команда реализует пользовательскую конфигурацию kind: ProviderConfig, в которой описывается список Secrets для монтирования в контейнер приложения SYAP. Также kind: AnsibleRun, в которой описывается список Host и Ansible Playbook, выполняющийся на этих Hosts.

Общие требования по конфигурированию проекта#

Наличие конфигурации для предоставления прав компоненту SYAP#

В рамках предоставления доступа компоненту «Ansible Controller» к реализации Istio SE конфигураций необходимо реализовать «kind: ClusterRoleBinding» (если в рамках кластера у компонента SYAP установлены ограниченные права).

Пример необходимой конфигурации:

kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: provider-ansible
  namespace: $PROJECT_NAME
subjects:
  - kind: ServiceAccount
    name: provider-ansible-service-account
    namespace:  namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: provider-ansible

Переменная «$PROJECT_NAME» заполняется в рамках используемого вами наименования «Namespace».

Переменная «$PROJECT_SYAP» зависит от «Namespace», в котором реализованы компонент SYAP.

Наличие шлюзов для входящего/исходящего трафика#

Для организации входящего/исходящего трафика в рамках «namespace», подключенного к контрольной панели «Istio SE» необходимо наличие граничных прокси:

egressgateway — прокси «envoy» для организации всего исходящего трафика в рамках проекта

Реализация указанных шлюзов производиться посредством «kind: Deployment».

Как проверить:

Через CLI Kubernetes (kubectl)

Шаг	Действия	Описание
Перейти в нужный namespace	Ввести команду: `kubectl config set-context --current --namespace=<имя вашего проекта>`	–
Запросить список «kind: Deployment»	В консоли выполнить команду: `kubectl get deploy`	Результатом выполнения будет список текущих «kind: Deployment» и количество подов.

Проверка работоспособности «kind: Pod» реализованного по конфигурации «kind: Deployment»

Пример визуализации из запроса «Запросить список «kind: Deployment»»:

NAME	READY	UP-TO-DATE	AVAILABLE	AGE
egressgateway	1/1	1	1	251d

В столбце «READY» визуализируется количество успешно реализованных «kind: Pod», по «kind: Deployment».

При возникновении ошибок проверьте подключение вашего проекта к контрольной панели «Istio SE» (указанное условие также является обязательным).

Алгоритм подключения подробно описан в рамках документации компонента «IGEG».

Конфигурирование Ansible Controller#

Для настройки внешней инфраструктуры через компонент SYAP необходимо реализовать конфигурацию kind: ProviderConfig, через которую происходит монтирование kind: Secret для подключения Ansible Host к удаленным Host и задание параметров для управления поведением SYAP при инициализации Ansible Collection.

kind: ProviderConfig:

apiVersion: ansible.crossplane.io/v1alpha1 # Версия API
kind: ProviderConfig
metadata:
  name: provider-ansible-kafka # наименование конфигурации provider-ansible
  namespace: provider-namespace  #namespace
spec:
  credentials: # монтирование секретов необходимое для подключения к ansible host и его настройки при выполнении ansible script
    - filename: id_rsa_kafka
      secretRef:
        key: id_rsa_kafka
        name: ssh-keys
        namespace: project
      source: Secret
      type: Other
      triggerUponChange: false
    - filename: kafka.truststore.jks
      secretRef:
        key: kafka.truststore.jks
        name: ansible-provider-kafka-ssl
        namespace: project
      source: Secret
      type: Certificate
      triggerUponChange: true
  vars:
    - key: localInstall # параметр, который конфигурирует provider-ansible использовать локальные ansible collections для каждого kind: AnsibleRun, который ссылается на этот kind: ProviderConfig
      value: 'yes'
    - key: ansible-vault # параметр, отвечающий за использование файла из value в качестве ansible-vault для расшифровки данных в inventory
    - value: ansible-vault
    - key: jks-password              # параметр с указанием credential из spec.credentials, который является storepass для всех jks, указанных в spec.credentials
      value: artemis-jks-password
}

ProviderConfig

Поле	Формат	Описание
credentials	array	Описание настроек для загрузки содержимого kind:Secret в файловую систему приложения provider-ansible
requirements	String	Описание ansible collections и ее источник. Формат: внутристрочный yaml
vars	array	Параметры для конфигурирования работы SYAP при выполнении kind: AnsibleRun, ссылающийся на kind: ProviderConfig

vars

Поле	Формат	Описание
key	String	Название параметра
value	String	Значение параметра

credentials

Поле	Формат	Описание
filename	String	Имя файла, в которое будет сохранено содержимое `data` в kind: Secret
secretRef	map	Данные о kind:Secret
source	String	Источник credential (Возможные значения: None, Secret, InjectedIdentity, Environment, Filesystem)
triggerUponChange	bool	Флаг, который управляет запуском работы Ansible при отличии содержимого credential с его содержимым на предыдущем цикле обработки
type	String	тип credential (Значения: Certificate,Other). Определяет, как будет производится сравнение состояний credential между циклами (sha256 всего файла или sha256 конкретно сертификатов внутри jks)

secretRef

Поле	Формат	Описание
key	String	Имя параметр в data в kind: Secret
name	String	Name в metadata.name в kind: Secret
namespace	String	Namespace, в котором находится kind: Secret

Миграция на текущую версию#

Миграция не предусмотрена.

Быстрый старт#

Выполнение Ansible Playbook на удаленном хосте#

Предусловия:

Успешная установка компонента SYAP;
Реализована конфигурация kind: ProviderConfig;
Определение Inventory c Host, на которых будет выполняться Ansible Playbook;
Настройка авторизации Ansible Host к Host: авторизация по логину/паролю, авторизация через private/public ключи.

Шаги:

Реализована пользовательская конфигурация kind: AnsibleRun с указанием списка Host и их параметров, с реализацией Ansible Playbook для выполнения на Host;
Анализ SYAP введенного Inventory и создание Istio конфигураций для доступа SYAP к Host;
Запуск Ansible.

Выполнение Ansible Playbook с предусмотренной возможностью отката изменений на Host#

Предусловия:

Успешная установка компонента SYAP;
Реализована конфигурация kind: ProviderConfig;
Определение Inventory c Host, на которых будет выполняться Ansible Playbook;
Настройка авторизации Ansible Host к Host: авторизация по логину/паролю, авторизация через private/public ключи.

Шаги:

Реализована пользовательская конфигурация kind: AnsibleRun с указанием Inventory, с реализацией полей playbookInline и rollbackPlaybookInline с Ansible Playbook для выполнения на Host. playbookInline - поле для установки внешней инфраструктуры, rollbackPlaybookInline - откат настройки внешней инфраструктуры.
Анализ SYAP введенного Inventory и создание Istio конфигураций для доступа SYAP к Host;
Запуск Ansible.

Использование программного компонента#

Под использованием программного компонента подразумевается реализация kind:ProviderConfig с конфигурацией рабочей области и kind:AnsibleRun с описанием Ansible Playbook, с помощью которого будет происходить настройка внешней по отношению к системе оркестрации инфраструктуры. Настройка происходит через использование Ansible Playbook в Ansible collection, поставляемые компонентом SYAP.

kind:ProviderConfig

apiVersion: ansible.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
  name: artemis
  namespace: namespace
spec:
  files:
     - credFilenames:
          - username
          - password
       filename: artemis.zip
       fullLink: >-
          nexus/repository/repo/repo/ci/artemis/8.0.2-artemis/artemis-8.0.2-artemis-distrib.zip
       host: host
  credentials:
     - filename: username
       secretRef:
          key: username
          name: nexus-userpass
          namespace: проект
       source: Secret
       triggerUponChange: false
       type: Other
     - filename: password
       secretRef:
          key: password
          name: nexus-userpass
          namespace: проект
       source: Secret
       triggerUponChange: false
       type: Other
     - filename: cert
       secretRef:
          key: cert
          name: cert
          namespace: проект
       source: Secret
       triggerUponChange: true
       type: Certificate
  vars:
    - key: ansible-vault
      value: ansible-vault

kind:AnsibleRun:

apiVersion: ansible.crossplane.io/v1alpha1
kind: AnsibleRun
metadata:
  name: ansible-run
  namespace: namespace
spec:
  deletionPolicy: Delete # Настройка, определяющее состояние внешней инфраструктуры при удалении kind: AnsibleRun
  forProvider:
    inventoryInline: | # список hosts с их адресами и зависимыми параметрами
      ---
      all:
        hosts:
          host_1:
            ansible_host: host_adress # адрес host
            ansible_user: juser # пользователь, под которым Ansible Host подключиться к Host
            ansible_connection: ssh # тип подключения к Host
            ansible_private_key_file: id_rsa # путь до файла с private ключом (монтируется ProviderConfig)
    playbookInline: | # ansible playbook 
      --- 
      - name: deploy something
        ansible.builtin.import_playbook: demo.test.test.yaml
    rollbackPlaybookInline: |
      ---
      - name: rollback deployed
        ansible.builtin.import_playbook: demo.test.test_rollback.yaml
    vars:
      ansible_run: ansible-run # metadata.name
  providerConfigRef:
    name: example # ссылка на kind: ProviderConfig
  ansibleRunRef:
    name: example_ansible-run # ссылка на kind: AnsibleRun
    namespace: namespace_ansible-run

AnsibleRun

Поле	Формат	Описание
deletionPolicy	String	Параметр, регулирующий запуск Ansible Playbook по откату настроек внешней инфраструктуры (если предусмотрено Ansible Playbook). Значения: Orphan - Удаление AnsibleRun без отката настроек внешней инфраструктуры; Delete - при удалении AnsibleRun запускается Ansible Playbook в поле rollbackPlaybookInline
forProvider	map	Описание AnsibleRun
providerConfigRef	map	Ссылка на kind: ProviderConfig
ansibleRunRef	map	Ссылка на kind: AnsibleRun, от результата которого зависит запуск текущего AnsibleRun
publishConnectionDetailsTo	map	Ссылка на конфигурацию External Secrets Operator, описывающее подключение к хранилищу секретов, в которое записывать информацию о подключении к удаленным хостам

forProvider

Поле	Формат	Описание
executableInventory	Boolean	Флаг того, что указанные Inventory являются исполняемым
inventories	array	Список используемых Inventory в kind: AnsibleRun
inventoryInline	String	Inventory, реализованное в строчном виде
playbookInline	String	Ansible Playbook, реализованный в строчном виде
rollbackPlaybookInline	String	Ansible Playbook отката, реализованный в строчном виде
roles	array	Список Role для загрузки в под и выполнения (Взаимозаменяемое поле с playbookInline)
vars	map	Конфигурация SYAP на уровне kind: AnsibleRun

inventories

Поле	Формат	Описание
env	String	Ссылка на переменную окружения, которая содержит Inventory
fs	map	Информация об Inventory, который находится в файловой системе приложения
secretRef	map	Информация о kind: Secret
source	String	Источник inventory

providerConfigRef

Поле	Формат	Описание
name	String	Значение `metadata.name` в kind: ProviderConfig
policy	map	Инструкция по обработке `providerConfigRef`

policy

Поле	Формат	Описание
resolution	string	Параметр, описывающий необходимость обрабатывать ссылку на kind: ProviderConfig. Возможные значения: `Required` - наличие kind: ProviderConfig обязательно, `Optional` - наличие kind: ProviderConfig необязательно
resolve	string	Параметр, по которому определяется когда ссылка на kind: ProviderConfig будет обработана. Возможные значения: `Always` - обработка ссылки на kind: ProviderConfig при каждом цикле работы оператора, IfNotPresent - обработка ссылки на kind: ProviderConfig, когда отсутствует поле resolution

roles

Поле	Формат	Описание
name	string	Название роли для скачивания
src	string	Источник репозитория с ролью
version	string	Ветка с ролью

Ansible collections#

В рамках программного компонента поставляются Ansible collections для разворота внешней инфраструктуры.

SMBX#

Установка SMBX с ssl/Удаление SMBX#

Шаблон kind:ProviderConfig для установки с SMBX:

apiVersion: ansible.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
  name: artemis
  namespace: namespace
spec:
  files:
     - credFilenames:
          - username
          - password
       filename: artemis.zip
       fullLink: >-
          nexus/repository/repo/repo/ci/artemis/8.0.2-artemis/artemis-8.0.2-artemis-distrib.zip
       host: host
  credentials:
     - filename: username
       secretRef:
          key: username
          name: nexus-userpass
          namespace: проект
       source: Secret
       triggerUponChange: false
       type: Other
     - filename: password
       secretRef:
          key: password
          name: nexus-userpass
          namespace: проект
       source: Secret
       triggerUponChange: false
       type: Other
     - filename: ansible-vault
       secretRef:
         key: ansible-vault
         name: имя секрета
         namespace: проект, в котором находится kind:Secret с паролем к ansible-vault
       source: Secret
     - filename: id_rsa_artemis
       secretRef:
         key: id_rsa
         name: имя секрета
         namespace: проект, в котором находится kind:Secret с private key
       source: Secret
     - filename: truststore.jks
       secretRef:
         key: truststore.jks
         name: имя секрета
         namespace: проект, в котором находится kind:Secret с содержимым jks
       source: Secret
     - filename: keystore.jks
       secretRef:
         key: keystore.jks
         name: имя секрета
         namespace: проект, в котором находится kind:Secret с содержимым jks
       source: Secret
  vars:
    - key: ansible-vault
      value: ansible-vault

Шаблон kind:AnsibleRun для установки SMBX:

apiVersion: ansible.crossplane.io/v1alpha1
kind: AnsibleRun
metadata:
  name: artemis
  namespace: namespace
spec:
  deletionPolicy: Delete
  forProvider:
    executableInventory: false
    inventoryInline: |
      ---
      all:
        children:
          artemis:
            vars:
              ansible_remote_tmp: ~.ansible/tmp
              password_encoder_cli_path: encryptor-cli-2.4.0-fatjar.jar
              artemis:
                password: пароль для брокера
                keyStorePath: keystore.jks
                trustStorePath: truststore.jks
                # вариант №1 - зашифрованные ansible-vault пароли от jks
                trustStorePassword: пароль от truststore
                keyStorePassword: пароль от keystore
                keyPassword: пароль от private key для ssl
                # вариант №2 - название файла из ProviderConfig из которого взять пароль для jks
                artemis_jks_pass: artemis-jks-password
                admins:
                  - DN пользователя, которому нужно выдать админские права на web ui console
            hosts:
              host_1:
                ansible_host: местоположение хоста
                ansible_user: пользователь
                ansible_become_user: root
                ansible_become: true
                #
                ansible_private_key_file: файл private key
                или
                ansible_password: пароль пользователя к хосту
                #
    playbookInline: |
       ---
       - name: prereq
         import_playbook: synapse.artemis.prerequirements.yml
       - name: create artemis
         import_playbook: synapse.artemis.artemis_create.yml
    rollbackPlaybookInline: |
       ---
       - name: delete artemis
         import_playbook: synapse.artemis.artemis_uninstall.yml
    vars:
       ca_on_egress: /etc/istio/egressgateway-syap/git-0-ca.crt # путь до примонтированного сертификата CA
  providerConfigRef:
    name: artemis

Тиражирование сертификатов на SMBX#

Шаблон kind:ProviderConfig для обновления сертификатов на SMBX:

apiVersion: ansible.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
  name: artemis-ssl-update
  namespace: namespace
spec:
  credentials:
    - filename: ansible-vault
      secretRef:
        key: ansible-vault
        name: ansible-vault
        namespace: namespace
      source: Secret
      triggerUponChange: false
    - filename: artemis-jks-password
      secretRef:
        key: artemis-jks-password
        name: artemis-jks-password
        namespace: namespace
      source: Secret
      triggerUponChange: false
    - filename: artemis-keystore-host.jks
      secretRef:
        key: keystore.jks
        name: artemis-host
        namespace: namespace
      source: Secret
      triggerUponChange: true
      type: Certificate
    - filename: artemis-truststore-host.jks
      secretRef:
        key: truststore.jks
        name: artemis-host
        namespace: namespace
      source: Secret
      triggerUponChange: true
      type: Certificate
    - filename: artemis-jks-password
      secretRef:
        key: artemis-jks-password
        name: artemis-jks-password
        namespace: namespace
      source: Secret
      triggerUponChange: true
      type: Other
  vars:
    - key: ansible-vault
      value: ansible-vault
    - key: jks-password
      value: artemis-jks-password

Шаблон kind:AnsibleRun для обновления сертификатов на SMBX:

apiVersion: ansible.crossplane.io/v1alpha1
kind: AnsibleRun
metadata:
  name: artemis-ssl-update
  namespace: namespace
spec:
  ansibleRunRef:
    name: artemis # ссылка на ansibleRun, через который был развернут artemis
    namespace: namespace
  deletionPolicy: Orphan
  forProvider:
    inventoryInline: |
      ---
      all:
        children:
          artemis:
            vars:
              ansible_remote_tmp: ~.ansible/tmp
              password_encoder_cli_path: encryptor-cli-2.4.0-fatjar.jar
            hosts:
              host:
                ansible_host: host
                ansible_port: 22
                ansible_user: user
                ansible_become_user: root
                ansible_become: true
                ansible_connection: ssh
                ansible_password: !vault |
                  password
                artemis:
                  password: Very$trongPassw0rd
                  keyStorePath: artemis-keystore-host.jks
                  trustStorePath: artemis-truststore-host.jks
                  # вариант №1 - зашифрованные ansible-vault пароли от jks
                  trustStorePassword: пароль от truststore
                  keyStorePassword: пароль от keystore
                  keyPassword: пароль от private key для ssl
                  # вариант №2 - название файла из ProviderConfig из которого взять пароль для jks
                  artemis_jks_pass: artemis-jks-password
                  # -
                  admins:
                    - CN=cn
                  super_user: CN=artemis.cn
                  ssl_rolling_update:
                    ignore_dn_mismatch: true
    playbookInline: |
      ---
      - name: create artemis
        import_playbook: synapse.artemis.ssl_rolling_update.yml
  managementPolicies:
    - '*'
  providerConfigRef:
    name: artemis-ssl-update

Создание роли, очередей, адресов/ Удаление роли, очередей, адресов#

apiVersion: ansible.crossplane.io/v1alpha1
kind: AnsibleRun
metadata:
  name: artemis
  namespace: проект
spec:
  deletionPolicy: Delete
  forProvider:
    executableInventory: false
    inventoryInline: |
      ---
      all:
        children:
          artemis:
            vars:
              ansible_remote_tmp: ~.ansible/tmp
              #password_encoder_cli_path: encryptor-cli-1.5.7-fatjar.jar
            hosts:
              host_1:
                ansible_host: местоположение хоста
                ansible_user: пользователь
                ansible_become_user: root
                ansible_become: true
                ansible_private_key_file: id_rsa_artemis
                или
                ansible_password: пароль пользователя к хосту
                artemis_queues:
                  list:
                    - name: имя очереди
                      address: адрес очереди
                      #remove_address_also: True
                artemis_roles:
                   - user: DN пользователя
                     queue: имя очереди
                     address: адрес очереди
                     role: какую роль выдать пользователю
                     userId: id пользователя
                     #delete_user_from_role: True
                     #erase_user_on_delete: True
    playbookInline: |
       ---
       - name: create queue
         ansible.builtin.import_playbook: synapse.artemis.artemis_queues_roles.yml
    rollbackPlaybookInline: |
       ---
       - name: delete kafka topic
         import_playbook: synapse.artemis.artemis_queues_remove.yml
       - name: delete queue
       - name: users remove
         ansible.builtin.import_playbook: synapse.artemis.artemis_users_remove.yml
  providerConfigRef:
    name: artemis

Secret#

Шаблон kind:ProviderConfig для работы с Secret:

apiVersion: ansible.crossplane.io/v1alpha1
kind: ProviderConfig
metadata:
  name: secret
  namespace: namespace
spec:
  credentials:
    - filename: ansible-vault
      secretRef:
        key: ansible-vault
        name: имя секрета
        namespace: проект, в котором находится kind:Secret с паролем к ansible-vault
      source: Secret
    - filename: id_rsa
      secretRef:
         key: id_rsa
         name: имя секрета
         namespace: проект, в котором находится kind:Secret с private key
      source: Secret
  vars:
    - key: localInstall
      value: 'yes'
    - key: ansible-vault
      value: ansible-vault

Шаблон kind:AnsibleRun для работы с Secret:

apiVersion: ansible.crossplane.io/v1alpha1
kind: AnsibleRun
metadata:
  name: artemis.keystore.jks
  namespace: проект
spec:
  deletionPolicy: Orphan
  forProvider:
    executableInventory: false
    inventoryInline: |
      ---
      all:
        vars:
          # флаг добавления ownerReference к создаваемому секрету с ссылкой на AnsibleRun
          createOwnerReference: true
          secrets:
            - host: localhost
              type: Opaque
              namespace: проект куда грузить секрет
              name: artemis.keystore.jks
              values:
                - name: artemis.keystore.jks
                  value: !vault |
                    $ANSIBLE_VAULT;1.1;AES256
    playbookInline: |
      ---
      - name: create secrets
        ansible.builtin.import_playbook: synapse.secrets.secrets_replication.yaml
  providerConfigRef:
    name: secret

Создание секрета в проекте k8s (с удалением секрета через playbook)#

apiVersion: ansible.crossplane.io/v1alpha1
kind: AnsibleRun
metadata:
  name: artemis.keystore.jks
  namespace: проект
spec:
  deletionPolicy: Delete
  forProvider:
    executableInventory: false
    inventoryInline: |
      ---
      all:
        vars:
          secrets:
            - host: localhost
              type: Opaque
              namespace: проект куда грузить секрет
              name: artemis.keystore.jks
              values:
                - name: artemis.keystore.jks
                  value: !vault |
                    $ANSIBLE_VAULT;1.1;AES256
    playbookInline: |
      ---
      - name: create secrets
        ansible.builtin.import_playbook: synapse.secrets.secrets_replication.yaml
    rollbackPlaybookInline: |
       ---
      - name: create secrets
        ansible.builtin.import_playbook: synapse.secrets.secrets_delete.yaml
  providerConfigRef:
    name: secret

Перенос секрета на сервер внешней инфраструктуры (с удалением секрета с сервера при удалении AnsibleRun)#

apiVersion: ansible.crossplane.io/v1alpha1
kind: AnsibleRun
metadata:
  name: distribute-secrets
  namespace: namespace-syap
  finalizers:
    - finalizer.managedresource.crossplane.io
spec:
  deletionPolicy: Delete
  forProvider:
    executableInventory: false
    inventoryInline: |
      ---
      all:
        hosts:
          kafka:
            ansible_remote_tmp: ~.ansible/tmp
            ansible_host: host
            ansible_user: user
            #
            ansible_private_key_file: id_rsa_kafka_1
            #
            или
            #
            ansible_password: password
            #
            ansible_become_user: root
        vars:
          secrets:
            - host: kafka # совпадает с inventory_hostname
              type: truststore
              file_path: /work/ssl
              values:
                - name: kafka.truststore.jks
                  value: !vault |
                    $ANSIBLE_VAULT;1.1;AES256
    playbookInline: |
      ---
      - name: create secrets
        ansible.builtin.import_playbook: appmesh.secrets.secrets_replication.yaml
    rollbackPlaybookInline: |
      ---
      - name: delete secrets
        ansible.builtin.import_playbook: appmesh.secrets.secrets_delete.yaml
    vars:
      ansible_run: distribute-secrets
  providerConfigRef:
    name: secret

Статусы возвращаемые после цикла Reconcile и работы Ansible#

В программном компоненте SYAP происходит вывод статуса как по работе цикла Reconcile CRD компонента, так и статуса по работе Ansible.
Также происходит вывод пользовательской конфигурации.

Описание статусов в секции Conditions после Reconcile#

В рамках реализации пользовательской конфигурации вы можете столкнуться с ошибками обработки пользовательской конфигурации и ошибками контроллера, которые будут визуализированы в пользовательской конфигурации kind: AnsibleRun в секции status.conditions:

Condition	Текст ошибки	Описание
ReconcilePaused
ReconcileSuccess		Reconcile kind: AnsibleRun прошел успешно
ReconcileError	cannot update managed resource	Ошибка при обновлении kind: AnsibleRun. Необходимо проверить, что kind: ClusterRole в проекте оркестрации совпадает с kind: ClusterRole в разделе «Подготовка окружения» документа «Руководство по установке».
	observe failed: cannot get AnsibleRun: {err}	Ошибка при обработке kind: AnsibleRun: ошибка получения конфигурации kind: AnsibleRun. Необходимо проверить, что kind: ClusterRole в проекте оркестрации совпадает с kind: ClusterRole в разделе «Подготовка окружения» документа «Руководство по установке».
	observe failed: cannot get last applied: cannot unmarshal template: {err}	Ошибка при обработке kind: AnsibleRun: Не удалось в манифесте kind: AnsibleRun обработать `last-applied-configuration`. Возможно предыдущая пользовательская конфигурация была невалидной. Необходимо удалить секцию `last-applied-configuration`
	observe failed: cannot run or process dry-run: {err}	Ошибка при обработке kind: AnsibleRun: ошибки при ansibleRunPolicy: CheckWhenObserve, связанные с dry-run прогоном скриптов Ansible и обработкой результата.
	delete failed: {err}	Ошибка при запуске или ожидании завершения работы скриптов Ansible в режиме удаления внешней инфраструктуры. Необходимо проверить работу контроллера компонента SYAP.
	connect failed: cannot track ProviderConfig usage: cannot apply ProviderConfigUsage	Ошибка при создании kind: ProviderConfigUsage. Необходимо проверить, что kind: ClusterRole в проекте оркестрации совпадает с kind: ClusterRole в разделе «Подготовка окружения» документа «Руководство по установке».
	connect failed: cannot get ProviderConfig: {err}	Ошибка при получении kind: ProviderConfig. Необходимо проверить, что kind: ClusterRole в проекте оркестрации совпадает с kind: ClusterRole в разделе «Подготовка окружения» документа «Руководство по установке».
	connect failed: cannot get Inventory: {err}	Ошибка получения Inventory по ссылке, указанной в секции `Spec.forProvider.inventories`. Проверьте корректность ссылки.
	connect failed: cannot marshal Roles into yaml document: {err}	Ошибка при обработке секции `ForProvider.Roles`. Необходимо проверить корректность секции `Roles`.
	connect failed: cannot get credentials: cannot get credentials secret: {err}	Ошибка при монтировании секретов в контейнер, указанных в kind: ProviderConfig, который привязан с kind: AnsibleRun через `providerConfigRef`. Необходимо проверить, что ссылки на секреты в kind: ProviderConfig указывают на существующие kind: Secret.
	connect failed: cannot initialize Ansible client: at least a Playbook or Role should be provided	Ошибка при начальной обработке kind:AnsibleRun. Отстутствуют секции `Spec.ForProvider.PlaybookInLine` и `Spec.ForProvider.Roles` в kind: AnsibleRun.
	connect failed: cannot initialize Ansible client: cannot execute Playbook(s) and Role(s) at the same time, please respect Mutual Exclusion	Ошибка при начальной обработке kind:AnsibleRun. Присутствуют обе секции `Spec.ForProvider.PlaybookInLine` и `Spec.ForProvider.Roles`. Необходимо оставить одну из них.
	connect failed: cannot initialize Ansible client: cannot marshal ContentVars into yaml document	Ошибка при обработке секции `Spec.ForProvider.Vars` в kind:AnsibleRun
	connect failed: cannot initialize Ansible client: run policy {} not supported	Ошибка при начальной обработке kind:AnsibleRun. Поддерживаемые значения `AnsibleRunPolicy`: `ObserveAndDelete`, `CheckWhenObserve`

Пример поля conditions при успешном Reconcile:

conditions:
    - lastTransitionTime: '2024-04-23T06:53:06Z'
      reason: ReconcileSuccess
      status: 'True'
      type: Synced

Пример поля conditions при ошибочном Reconcile:

conditions:
    - lastTransitionTime: '2024-04-23T06:33:04Z'
      message: >-
        connect failed: cannot get credentials: cannot get credentials secret:
        Secret "ansible-vault-1" not found
      reason: ReconcileError
      status: 'False'
      type: Synced

Описание статусов в секции Conditions после работы скриптов Ansible#

После работы скриптов Ansible, в пользовательскую конфигурацию kind: AnsibleRun в секцию status.conditions будет визуалирован результат их работы.

reason	status	type	Описание
Available	„True“	Ready	Работа Ansible завершилась успешно
Unavailable	„False“		Работа Ansible завершилась неуспешно
Creating	„False“		Выполнение Ansible для установки инфраструктуры
Deleting	„False“		Удаление внешней инфраструктуры
ReconcileSuccess	„True“	Synced	Работа AnsibleController прошла штатно
ReconcileError	„False“		Работа AnsibleController прошла не штатно
ReconcilePaused	„False“		Работа AnsibleController приостановлена

Пример поля conditions при успешном выполнении скриптов Ansible:

  conditions:
  - lastTransitionTime: '2024-07-31T11:56:09Z'
    reason: Available
    status: 'True'
    type: Ready
  - lastTransitionTime: '2024-07-31T11:56:09Z'
    reason: ReconcileSuccess
    status: 'True'
    type: Synced

Пример поля conditions при ошибочном выполнении скриптов Ansible:

   conditions:
   - lastTransitionTime: '2024-07-31T11:56:09Z'
     reason: Unavailable
     status: 'False'
     type: Ready
     message: 'error'
   - lastTransitionTime: '2024-07-31T11:56:09Z'
     reason: ReconcileSuccess
     status: 'True'
     type: Synced

Описание поля сonfiguration#

Поле configuration формируется при Reconcile, перед запуском Ansible и хранит в себе данные поля spec.forProvider пользовательской конфигурации kind: AnsibleRun. Пример поля configuration:

 configuration: >-
    {"inventoryInline":null,"inventories":null,"executableInventory":false,"playbookInline":"---\n-
    hosts: localhost\n  tasks:\n    - name: \"test-1\"\n      debug:\n      
    msg: \"test-debug-1\"\n- hosts: localhost\n  tasks:\n    - name:
    \"test-2\"\n      debug:\n       msg:
    \"test-debug--2\"\n","roles":null,"vars":null}

Алгоритм использования данных поля `configuration` в рамках цикла Reconcile и работы Ansible:#

Получение данных текущей конфигурации из поля spec.forProvider;
Получение данных последней конфигурации из поля configuration;
Сравнение данных полученных конфигураций;
На основе различий данных в текущей и последней конфигурациях принимается решение о запуске работы Ansible.

Часто встречающиеся проблемы и пути их устранения#

Проблема	Причина	Решение
Не стартует под приложения	Недостаточно ресурсов	Увеличить limits/requests для приложения
Не стартует под приложения	Нет доступной node для запуска	Зарегистрировать обращение в поддержку инфраструктуры
Не стартует под приложения	Ошибка в конфигурации	Выгрузить лог, провести анализ, скорректировать конфигурацию
Частый перезапуск контейнера приложения	Медленная загрузка приложения	Увеличить задержку и/или интервал опроса Liveness пробы
Частый перезапуск контейнера приложения	Недостаточно ресурсов	Увеличить limits/requests для приложения
Под приложения перезапускается с ошибкой OOM Killed	Недостаточно ресурсов	Увеличить limits/requests для приложения