AWS Command Line Interface (AWS CLI)

AWS CLI — это интерфейс командной строки для работы с сервисами AWS. Общий порядок вызова команд смотрите в официальной документации Amazon.

Для работы с Object Storage с помощью AWS CLI вы можете использовать следующие наборы команд:

• s3api — команды, соответствующие операциям в REST API. Перед использованием ознакомьтесь с перечнем поддерживаемых операций.
• s3 — дополнительные команды, упрощающие работу с большим количеством объектов.

Подготовка к работеПодготовка к работе

1. Создайте сервисный аккаунт.

2. Назначьте сервисному аккаунту роли, которые нужны для вашего проекта, например storage.editor на бакет — для работы с конкретным бакетом, или на каталог — для работы со всеми бакетами в каталоге. Подробнее о ролях см. на странице Управление доступом с помощью Yandex Identity and Access Management.

   Чтобы работать с объектами в зашифрованном бакете, у пользователя или сервисного аккаунта вместе с ролью storage.configurer должны быть следующие роли на ключ шифрования:

   • kms.keys.encrypter — для чтения ключа, шифрования и загрузки объектов;
   • kms.keys.decrypter — для чтения ключа, расшифровки и скачивания объектов;
   • kms.keys.encrypterDecrypter — включает разрешения, предоставляемые ролями kms.keys.encrypter и kms.keys.decrypter.

   Подробнее см. Сервисные роли Key Management Service.

3. Создайте статический ключ доступа.

   В результате вы получите данные статического ключа доступа. Для аутентификации в Object Storage вам понадобятся:

   • key_id — идентификатор статического ключа доступа;
   • secret — секретный ключ.

   Сохраните key_id и secret, так как повторное получение значения ключа будет невозможно.

УстановкаУстановка

Для установки AWS CLI воспользуйтесь инструкцией на сайте разработчика.

НастройкаНастройка

Для настройки AWS CLI в терминале введите команду aws configure. Команда запросит значения для следующих параметров:

1. AWS Access Key ID — идентификатор статического ключа, полученный ранее.

2. AWS Secret Access Key — содержимое статического ключа, полученное ранее.

3. Default region name — регион kz1.

   Для работы с Object Storage всегда указывайте регион — kz1. Другие значения региона могут привести к ошибке авторизации.

4. Значения остальных параметров оставьте без изменений.

Конфигурационные файлыКонфигурационные файлы

В результате работы команда aws configure сохранит статический ключ и регион.

• Формат статического ключа в .aws/credentials:

  [default]
  aws_access_key_id = <идентификатор_статического_ключа>
  aws_secret_access_key = <содержимое_статического_ключа>
  

• Формат региона по умолчанию в .aws/config:

  [default]
  region = kz1
  

Статический ключ для доступа к Object Storage можно безопасно хранить в сервисе Yandex Lockbox. Подробнее см. Использование секрета Yandex Lockbox для хранения статического ключа доступа.

Настройка дополнительного профиляНастройка дополнительного профиля

Вы можете создать несколько профилей для AWS CLI с помощью команды:

aws configure --profile <имя_профиля>

Данные профилей будут сохранены в файлах .aws/credentials и .aws/config в следующем виде:

• credentials:

  [default]
  aws_access_key_id = <идентификатор_статического_ключа_1>
  aws_secret_access_key = <содержимое_статического_ключа_1>
  [<имя_профиля_2>]
  aws_access_key_id = <идентификатор_статического_ключа_2>
  aws_secret_access_key = <содержимое_статического_ключа_2>
  ...
  [<имя_профиля_n>]
  aws_access_key_id = <идентификатор_статического_ключа_n>
  aws_secret_access_key = <содержимое_статического_ключа_n>
  

• config:

  [default]
  region = kz1
  [profile <имя_профиля_2>]
  region = kz1
  ...
  [profile <имя_профиля_n>]
  region = us-east-1
  

  Где default — профиль по умолчанию.

Чтобы переключаться между разными профилями в командах AWS CLI используется опция --profile, например:

aws --endpoint-url=https://storage.yandexcloud.kz/ \
  --profile <имя_профиля_2> \
  s3 mb s3://<имя_бакета>

ОсобенностиОсобенности

Учитывайте особенности AWS CLI при работе с Object Storage:

• AWS CLI работает с Object Storage как с иерархической файловой системой и ключи объектов имеют вид пути к файлу.
• По умолчанию клиент настроен на работу с серверами Amazon. Поэтому при запуске команды aws для работы с Object Storage обязательно используйте параметр --endpoint-url. Чтобы при каждом запуске не указывать параметр вручную, вы можете использовать файл конфигурации или псевдоним.

  • (поддерживается в AWS CLI версий 1.29.0, 2.13.0 и выше) В файле конфигурации .aws/config добавьте параметр endpoint_url:

    endpoint_url = https://storage.yandexcloud.kz
    

    После этого вы сможете вызывать команды без явного указания эндпоинта. Например, вместо aws --endpoint-url=https://storage.yandexcloud.kz s3 ls можно указывать aws s3 ls. Подробнее смотрите в документации AWS CLI.

  • Создайте псевдоним (alias) с помощью команды:

    alias ycs3='aws s3 --endpoint-url=https://storage.yandexcloud.kz'
    

    Для создания псевдонима при каждом запуске терминала, добавьте команду alias в конфигурационный файл ~/.bashrc или ~/.zshrc, в зависимости от типа оболочки.

    С таким псевдонимом будут равносильны команды:

    aws s3 --endpoint-url=https://storage.yandexcloud.kz ls
    

    ycs3 ls
    

Примеры операцийПримеры операций

Создать бакетСоздать бакет

aws s3 mb s3://bucket-name

Результат:

make_bucket: bucket-name

Загрузить объектыЗагрузить объекты

Можно загрузить все объекты из директории, использовать фильтр или загрузить объекты по одному.

• Загрузить все объекты из локальной директории:

  aws s3 cp --recursive local_files/ s3://bucket-name/path_style_prefix/
  

  Результат:

  upload: ./textfile1.log to s3://bucket-name/path_style_prefix/textfile1.log
  upload: ./textfile2.txt to s3://bucket-name/path_style_prefix/textfile2.txt
  upload: ./prefix/textfile3.txt to s3://bucket-name/path_style_prefix/prefix/textfile3.txt
  

• Загрузить объекты, описанные в фильтре --include, и пропустить объекты, описанные в фильтре --exclude:

  aws s3 cp --recursive --exclude "*" --include "*.log" \
    local_files/ s3://bucket-name/path_style_prefix/
  

  Результат:

  upload: ./textfile1.log to s3://bucket-name/path_style_prefix/textfile1.log
  

• Загрузить объекты по одному, запуская для каждого объекта команду следующего вида:

  aws s3 cp testfile.txt s3://bucket-name/path_style_prefix/textfile.txt
  

  Результат:

  upload: ./testfile.txt to s3://bucket-name/path_style_prefix/textfile.txt
  

Получить список объектовПолучить список объектов

aws s3 ls --recursive s3://bucket-name

Результат:

2022-09-05 17:10:34      10023 other/test1.png
2022-09-05 17:10:34      57898 other/test2.png
2022-09-05 17:10:34     704651 test.png

Удалить объектыУдалить объекты

Можно удалить объекты с заданным префиксом, использовать фильтр или удалить объекты по одному.

• Удалить все объекты с заданным префиксом:

  aws s3 rm s3://bucket-name/path_style_prefix/ --recursive
  

  Результат:

  delete: s3://bucket-name/path_style_prefix/test1.png
  delete: s3://bucket-name/path_style_prefix/subprefix/test2.png
  

• Удалить объекты, описанные в фильтре --include, и пропустить объекты, описанные в фильтре--exclude:

  aws s3 rm s3://bucket-name/path_style_prefix/ --recursive \
      --exclude "*" --include "*.log"
  

  Результат:

  delete: s3://bucket-name/path_style_prefix/test1.log
  delete: s3://bucket-name/path_style_prefix/subprefix/test2.log
  

• Удалить объекты по одному, запуская для каждого объекта команду следующего вида:

  aws s3 rm s3://bucket-name/path_style_prefix/textfile.txt
  

  Результат:

  delete: s3://bucket-name/path_style_prefix/textfile.txt
  

Получить объектПолучить объект

aws s3 cp s3://bucket-name/textfile.txt textfile.txt

Результат:

download: s3://bucket-name/path_style_prefix/textfile.txt to ./textfile.txt

См. такжеСм. также

• Как начать работать с AWS CLI в Yandex Object Storage.