Настройка и использование KOC CLI¶

KOC — клиент командной строки KeyStack для выполнения команд OpenStack. Клиент представляет собой один исполняемый файл и не требует установки Python или python-openstackclient.

В KeyStack 2026.2.1 используется KOC версии 0.10.0. Примеры команд KOC в этой статье соответствуют указанной версии.

Для работы с KOC:

получите исполняемый файл KOC для используемой операционной системы;
подготовьте параметры подключения к OpenStack;
получите CA-сертификат региона;
настройте подключение через clouds.yaml или переменные окружения OS_*.

KOC использует структуру команд, аналогичную OpenStack CLI: сначала указывается объект, затем действие и параметры. Чтобы посмотреть поддерживаемые в поставляемой версии команды, используйте параметр --help.

Получение KOC¶

Отдельная установка KOC не требуется. Клиент поставляется через локальный Nexus инсталляции:

для Windows — архив koc.zip с исполняемым файлом koc.exe;
для Linux — исполняемый файл koc.

В локальном Nexus инсталляции откройте репозиторий k-add.
Скачайте архив koc.zip.
Распакуйте архив в каталог, из которого будете запускать KOC.
Откройте PowerShell в каталоге с файлом koc.exe.
Проверьте запуск клиента и доступные команды:
```
.\koc.exe --help
```

В локальном Nexus инсталляции откройте репозиторий k-add.
Скачайте файл koc.
Перейдите в каталог с загруженным файлом.
Разрешите выполнение файла:
```
$ chmod +x koc
```
Проверьте запуск клиента и доступные команды:
```
$ ./koc --help
```

В примерах ниже запускайте KOC непосредственно из каталога с исполняемым файлом. Для Windows используйте команду .\koc.exe, для Linux — ./koc.

Если каталог с KOC уже добавлен в переменную окружения PATH, запускайте исполняемый файл без указания пути.

Настройка подключения¶

KOC должен получить параметры аутентификации пользователя, параметры проекта и информацию о регионе OpenStack.

Для настройки подключения используйте один из следующих способов:

clouds.yaml — параметры подключения задаются в конфигурационном файле, а пароль вводится интерактивно в терминале и передается через переменную окружения OS_PASSWORD;
переменные окружения OS_* — параметры подключения задаются в текущей сессии терминала, а пароль вводится интерактивно и передается через OS_PASSWORD.

При использовании clouds.yaml ранее заданные переменные окружения OS_* могут переопределить соответствующие параметры подключения из файла. Поэтому перед подключением через clouds.yaml откройте новую сессию терминала или удалите переменные OS_*, оставшиеся от другого пользователя или региона.

Получение CA-сертификата¶

KOC проверяет TLS-сертификат API региона. Для подключения к региону получите его CA-сертификат.

Войдите в GitLab и перейдите в репозиторий project_k / deployments / <имя региона>.
Откройте файл certificates/ca/ca-bundle.crt.
Сохраните ca-bundle.crt на рабочую станцию.

В примерах ниже используйте следующий путь:

C:\Users\<username>\.config\openstack\ca-bundle.crt

~/.config/openstack/ca-bundle.crt

При необходимости сохраните CA-сертификат в другом каталоге. В параметре cacert файла clouds.yaml или в переменной окружения OS_CACERT укажите абсолютный путь к сохраненному CA-сертификату.

Для cacert относительный путь определяется относительно текущего рабочего каталога, а не относительно каталога с clouds.yaml. Используйте абсолютный путь, чтобы подключение не зависело от каталога, из которого запущен KOC.

Если CA-сертификат не найден, содержит некорректные данные или не соответствует сертификату API региона, подключение по TLS завершится ошибкой. В частности, при невозможности проверить цепочку сертификатов может отображаться ошибка:

tls: failed to verify certificate: x509: certificate signed by unknown authority

Подключение через clouds.yaml¶

clouds.yaml содержит именованные конфигурации подключения к OpenStack. Для каждого региона можно создать отдельную конфигурацию и выбирать ее с помощью параметра --os-cloud.

При подключении через clouds.yaml KOC получает параметры подключения из файла, а пароль пользователя — из переменной окружения OS_PASSWORD текущей сессии терминала. Пароль вводится интерактивно перед выполнением команд KOC.

Создайте каталог для конфигурации, если он еще не существует, и создайте в нем файл clouds.yaml:

C:\Users\<username>\.config\openstack\clouds.yaml

~/.config/openstack/clouds.yaml

Добавьте конфигурацию региона:

clouds:
  ks:
    auth:
      auth_url: https://external.<region-fqdn>:5000/v3
      username: <username>
      project_name: <project>
      user_domain_name: <domain>
      project_domain_name: <domain>
    region_name: <region>
    interface: public
    cacert: <path-to-ca-bundle.crt>

Замените значения в угловых скобках фактическими значениями подключения:

<region-fqdn> — внешний FQDN региона;
<username> — имя пользователя OpenStack;
<project> — имя проекта;
<domain> — имя домена пользователя и проекта;
<region> — имя региона;
<path-to-ca-bundle.crt> — абсолютный путь к сохраненному CA-сертификату.

Имя ks после clouds: — имя конфигурации. Оно передается KOC в параметре --os-cloud. Если измените это имя, используйте новое имя во всех командах.

Например, для конфигурации с именем ks команда должна содержать:

--os-cloud ks

По умолчанию KOC ищет clouds.yaml последовательно:

в текущем рабочем каталоге;
в пользовательском каталоге .config/openstack;
на Linux — в /etc/openstack.

Если задана переменная OS_CLIENT_CONFIG_FILE, KOC использует указанный в ней путь вместо стандартного поиска.

Чтобы исключить загрузку не того файла, не храните разные clouds.yaml одновременно в текущем каталоге и в пользовательском каталоге конфигурации.

Проверка подключения через clouds.yaml¶

Перед выполнением команд введите пароль пользователя в терминале:

В PowerShell выполните:

$env:OS_PASSWORD = [System.Net.NetworkCredential]::new("", (Read-Host "OpenStack password" -AsSecureString)).Password

В Bash выполните:

read -rsp "OpenStack password: " OS_PASSWORD
export OS_PASSWORD
echo

Введенные символы не отображаются в терминале. Пароль передается KOC через переменную окружения OS_PASSWORD текущей сессии.

Сначала проверьте аутентификацию в Keystone.

.\koc.exe --os-cloud ks token issue

$ ./koc --os-cloud ks token issue

Если команда выполнена успешно, KOC получил токен OpenStack.

Затем проверьте обращение к Compute API:

.\koc.exe --os-cloud ks server list

$ ./koc --os-cloud ks server list

Работа с несколькими регионами через clouds.yaml¶

Чтобы работать с несколькими регионами с одной рабочей станции, добавьте отдельную конфигурацию для каждого региона в один clouds.yaml.

Например:

clouds:
  ks1:
    auth:
      auth_url: https://external.<region-fqdn1>:5000/v3
      username: <username>
      project_name: <project>
      user_domain_name: <domain>
      project_domain_name: <domain>
    region_name: <region1>
    interface: public
    cacert: <path-to-ca-bundle1.crt>

  ks2:
    auth:
      auth_url: https://external.<region-fqdn2>:5000/v3
      username: <username>
      project_name: <project>
      user_domain_name: <domain>
      project_domain_name: <domain>
    region_name: <region2>
    interface: public
    cacert: <path-to-ca-bundle2.crt>

ks1 и ks2 — имена двух независимых конфигураций подключения. Для каждого региона укажите его auth_url, region_name и CA-сертификат.

Перед выполнением команд введите пароль пользователя через OS_PASSWORD, как описано в разделе «Проверка подключения через clouds.yaml». При переключении на другой регион повторите ввод пароля соответствующего пользователя.

Для выполнения команды в первом регионе используйте:

.\koc.exe --os-cloud ks1 server list

$ ./koc --os-cloud ks1 server list

Для выполнения команды во втором регионе используйте:

.\koc.exe --os-cloud ks2 server list

$ ./koc --os-cloud ks2 server list

Параметр --os-cloud определяет, какую секцию clouds.yaml KOC использует для текущей команды.

Подключение через переменные окружения¶

Вместо clouds.yaml параметры подключения можно задать в переменных окружения OS_*.

Пароль пользователя вводится интерактивно в терминале и передается KOC через переменную окружения OS_PASSWORD текущей сессии.

Перед настройкой убедитесь, что в текущей сессии не задана переменная OS_CLOUD, которая указывает KOC использовать clouds.yaml.

В PowerShell удалите OS_CLOUD, если переменная была задана ранее:

Remove-Item Env:\OS_CLOUD -ErrorAction SilentlyContinue

Задайте параметры подключения:

$env:OS_AUTH_URL = "https://external.<region-fqdn>:5000/v3"
$env:OS_USERNAME = "<username>"
$env:OS_PROJECT_NAME = "<project>"
$env:OS_USER_DOMAIN_NAME = "<domain>"
$env:OS_PROJECT_DOMAIN_NAME = "<domain>"
$env:OS_REGION_NAME = "<region>"
$env:OS_INTERFACE = "public"
$env:OS_CACERT = "C:\Users\<username>\.config\openstack\ca-bundle.crt"

Введите пароль пользователя:

$env:OS_PASSWORD = [System.Net.NetworkCredential]::new("", (Read-Host "OpenStack password" -AsSecureString)).Password

PowerShell запросит пароль без отображения введенных символов и сохранит его в OS_PASSWORD текущей сессии.

Проверьте аутентификацию:

.\koc.exe token issue

Затем проверьте обращение к Compute API:

.\koc.exe server list

Откройте Bash и удалите OS_CLOUD, если переменная была задана ранее:

$ unset OS_CLOUD

Задайте параметры подключения:

export OS_AUTH_URL="https://external.<region-fqdn>:5000/v3"
export OS_USERNAME="<username>"
export OS_PROJECT_NAME="<project>"
export OS_USER_DOMAIN_NAME="<domain>"
export OS_PROJECT_DOMAIN_NAME="<domain>"
export OS_REGION_NAME="<region>"
export OS_INTERFACE="public"
export OS_CACERT="$HOME/.config/openstack/ca-bundle.crt"

Введите пароль пользователя:

read -rsp "OpenStack password: " OS_PASSWORD
export OS_PASSWORD
echo

Введенные символы не отображаются в терминале. После выполнения команд пароль находится в переменной OS_PASSWORD текущей сессии.

Проверьте аутентификацию:

$ ./koc token issue

Затем проверьте обращение к Compute API:

$ ./koc server list

Работа с несколькими регионами через переменные окружения¶

При использовании переменных окружения одновременно активен один набор OS_*. Для переключения между регионами подготовьте отдельный скрипт для каждого региона.

Запуск скрипта должен изменять переменные именно в текущей сессии терминала. Поэтому в PowerShell используется dot sourcing, а в Linux — команда source.

Для первого региона создайте файл, например:

C:\Users\<username>\.config\openstack\<region1>.ps1

Добавьте в него:

$env:OS_AUTH_URL = "https://external.<region-fqdn1>:5000/v3"
$env:OS_USERNAME = "<username>"
$env:OS_PROJECT_NAME = "<project>"
$env:OS_USER_DOMAIN_NAME = "<domain>"
$env:OS_PROJECT_DOMAIN_NAME = "<domain>"
$env:OS_REGION_NAME = "<region1>"
$env:OS_INTERFACE = "public"
$env:OS_CACERT = "C:\Users\<username>\.config\openstack\<region1>-ca-bundle.crt"

$env:OS_PASSWORD = [System.Net.NetworkCredential]::new("", (Read-Host "OpenStack password" -AsSecureString)).Password

Аналогичным способом создайте файл <region2>.ps1 и укажите в нем параметры второго региона.

Для подключения к первому региону выполните:

. C:\Users\<username>\.config\openstack\<region1>.ps1

Проверьте выбранный регион:

.\koc.exe token issue
.\koc.exe server list

Для переключения на второй регион в той же сессии выполните:

. C:\Users\<username>\.config\openstack\<region2>.ps1

После выполнения скрипта переменные OS_* текущей сессии будут содержать параметры второго региона.

Для первого региона создайте файл, например:

~/.config/openstack/<region1>.sh

Добавьте в него:

export OS_AUTH_URL="https://external.<region-fqdn1>:5000/v3"
export OS_USERNAME="<username>"
export OS_PROJECT_NAME="<project>"
export OS_USER_DOMAIN_NAME="<domain>"
export OS_PROJECT_DOMAIN_NAME="<domain>"
export OS_REGION_NAME="<region1>"
export OS_INTERFACE="public"
export OS_CACERT="$HOME/.config/openstack/<region1>-ca-bundle.crt"

read -rsp "OpenStack password: " OS_PASSWORD
export OS_PASSWORD
echo

Аналогичным способом создайте файл <region2>.sh и укажите в нем параметры второго региона.

Для подключения к первому региону выполните:

$ source ~/.config/openstack/<region1>.sh

Проверьте выбранный регион:

$ ./koc token issue
$ ./koc server list

Для переключения на второй регион в той же сессии выполните:

$ source ~/.config/openstack/<region2>.sh

После выполнения скрипта переменные OS_* текущей сессии будут содержать параметры второго региона.

Очистка переменных окружения¶

После завершения работы удалите параметры подключения и пароль из текущей сессии.

Выполните:

Remove-Item Env:\OS_AUTH_URL -ErrorAction SilentlyContinue
Remove-Item Env:\OS_USERNAME -ErrorAction SilentlyContinue
Remove-Item Env:\OS_PASSWORD -ErrorAction SilentlyContinue
Remove-Item Env:\OS_PROJECT_NAME -ErrorAction SilentlyContinue
Remove-Item Env:\OS_USER_DOMAIN_NAME -ErrorAction SilentlyContinue
Remove-Item Env:\OS_PROJECT_DOMAIN_NAME -ErrorAction SilentlyContinue
Remove-Item Env:\OS_REGION_NAME -ErrorAction SilentlyContinue
Remove-Item Env:\OS_INTERFACE -ErrorAction SilentlyContinue
Remove-Item Env:\OS_CACERT -ErrorAction SilentlyContinue
Remove-Item Env:\OS_CLOUD -ErrorAction SilentlyContinue
Remove-Item Env:\OS_CLIENT_CONFIG_FILE -ErrorAction SilentlyContinue

Выполните:

$ unset OS_AUTH_URL
$ unset OS_USERNAME
$ unset OS_PASSWORD
$ unset OS_PROJECT_NAME
$ unset OS_USER_DOMAIN_NAME
$ unset OS_PROJECT_DOMAIN_NAME
$ unset OS_REGION_NAME
$ unset OS_INTERFACE
$ unset OS_CACERT
$ unset OS_CLOUD
$ unset OS_CLIENT_CONFIG_FILE

После очистки KOC больше не использует параметры подключения из текущей сессии.