OpenStackClient 매뉴얼 페이지 편집하기

==개요==
[[분류: OpenStackClient]]
[[분류: Man page]]
;openstack
;OpenStack 커맨드 라인
;OpenStackClient 매뉴얼 페이지
https://docs.openstack.org/python-openstackclient/2024.1/cli/man/openstack.html

==SYNOPSIS==
'''openstack''' [<global-options>] <command> [<command-arguments>]

'''openstack help''' <command>

'''openstack''' --help

==DESCRIPTION==
'''openstack'''은 오픈스택 API에 공통 명령줄 인터페이스를 제공합니다. 이는 오픈스택 프로젝트 클라이언트 라이브러리에서 제공하는 CLI와 거의 동일하지만, 독특하고 일관된 명령어 구조를 가지고 있습니다.

==인증 방법==
'''openstack'''은 OpenStack 프로젝트 CLI와 유사한 인증 체계를 사용하며, 자격증명 정보는 환경변수나 명령줄 옵션으로 제공됩니다. 주요 차이점은 옵션 이름에 'project'가 포함되어 <code>OS_PROJECT_NAME</code>/<code>OS_PROJECT_ID</code>로 제공된다는 점입니다(이전의 테넌트 기반 이름 대신).

<syntaxhighlight lang='bash'>
export OS_AUTH_URL=<url-to-openstack-identity>
export OS_PROJECT_NAME=<project-name>
export OS_USERNAME=<user-name>
export OS_PASSWORD=<password>  # (optional)
</syntaxhighlight>

'''openstack'''은 keystoneclient 라이브러리가 제공하는 다양한 유형의 인증 플러그인을 사용할 수 있습니다. 기본적으로 사용할 수 있는 플러그인은 다음과 같습니다:

* <code>token</code>: 토큰을 사용한 인증
* <code>password</code>: 사용자명과 패스워드를 사용한 인증
* <code>openid</code>: OpenID Connect 프로토콜을 사용한 인증

이 플러그인과 그 옵션에 대한 자세한 내용과 사용가능한 플러그인의 전체 목록은 keystoneclient 라이브러리 문서를 참조하십시오. 일부 플러그인은 '''openstack'''의 모든 기능을 지원하지 않을 수 있습니다. 예를 들어, v3unscopedsaml 플러그인은 범위가 지정되지 않은 토큰만 제공할 수 있으며, 이 인증 방법으로는 일부 명령을 사용할 수 없습니다.

또한, Keystone의 서비스 토큰을 사용하여 인증할 수도 있습니다. 이 경우, <code>--os-token</code>과 <code>--os-endpoint</code> 옵션(또는 환경변수 <code>OS_TOKEN</code>과 <code>OS_ENDPOINT</code>)을 설정해야 합니다. 이 방법은 인증 플러그인보다 우선합니다.

{{NOTE}}
<code>v3unscopedsaml</code> 방법을 사용하려면 lxml 패키지를 설치해야 합니다.
{{/NOTE}}

===페더레이션을 사용한 인증===
페더레이션 인증을 사용하려면, 설정 파일에 다음이 필요합니다:

<syntaxhighlight lang='bash'>
export OS_PROJECT_NAME=<project-name>
export OS_PROJECT_DOMAIN_NAME=<project-domain-name>
export OS_AUTH_URL=<url-to-openstack-identity>
export OS_IDENTITY_API_VERSION=3
export OS_AUTH_PLUGIN=openid
export OS_AUTH_TYPE=v3oidcpassword
export OS_USERNAME=<username-in-idp>
export OS_PASSWORD=<password-in-idp>
export OS_IDENTITY_PROVIDER=<the-desired-idp>
export OS_CLIENT_ID=<the-client-id-configured-in-the-idp>
export OS_CLIENT_SECRET=<the-client-secred-configured-in-the-idp>
export OS_OPENID_SCOPE=<the-scopes-of-desired-attributes-to-claim-from-idp>
export OS_PROTOCOL=<the-protocol-used-in-the-apache2-oidc-proxy>
export OS_ACCESS_TOKEN_TYPE=<the-access-token-type-used-by-your-idp>
export OS_DISCOVERY_ENDPOINT=<the-well-known-endpoint-of-the-idp>
export OS_ACCESS_TOKEN_ENDPOINT=<the-idp-access-token-url>
</syntaxhighlight>

==옵션==
'''openstack'''은 전반적인 동작을 제어하는 전역 옵션과 명령어 실행을 제어하는 명령어별 옵션을 사용합니다. 대부분의 전역 옵션에는 해당 값을 설정하는 데 사용할 수 있는 환경변수가 있습니다. 둘 다 존재하는 경우 명령줄 옵션이 우선합니다. 환경변수 이름은 옵션 이름에서 앞에 붙은 대시(‘--’)를 제거하고, 사이사이의 대시(‘-’)를 밑줄(‘_’)로 변환하고, 대문자로 변환하여 파생됩니다.

'''openstack '''은 다음과 같은 전역 옵션을 인식합니다:

;<code>--os-cloud <cloud-name></code>
:'''openstack'''은 인증에 사용할 클라우드 설정을 포함하는 <code>clouds.yaml</code> 파일을 찾습니다. 자세한 내용은 아래의 클라우드 설정 섹션을 참조하십시오.

;<code>--os-auth-type <auth-type></code>
:Identity 서비스에 연결할 때 사용할 인증 플러그인 유형입니다.
:이 옵션이 설정되지 않은 경우, '''openstack'''은 다른 옵션을 기반으로 사용할 인증 방법을 추측하려고 합니다.
:이 옵션이 설정된 경우, 해당 버전은 <code>--os-identity-api-version</code>과 매치해야 합니다.

;<code>--os-auth-url <auth-url></code>
:인증 URL

;<code>--os-endpoint <service-url></code>
:서비스 토큰을 사용한 인증 시 서비스 엔드포인트

;<code>--os-domain-name <auth-domain-name></code>
:도메인 수준 인가 스코프 (이름으로)

;<code>--os-domain-id <auth-domain-id></code>
:도메인 수준 인가 스코프 (ID로)

;<code>--os-project-name <auth-project-name></code>
:프로젝트 수준 인가 스코프 (이름으로)

;<code>--os-project-id <auth-project-id></code>
:프로젝트 수준 인가 스코프 (ID로)

;<code>--os-project-domain-name <auth-project-domain-name></code>
:프로젝트를 포함하는 도메인 이름

;<code>--os-project-domain-id <auth-project-domain-id></code>
:프로젝트를 포함하는 도메인 ID

;<code>--os-username <auth-username></code>
:인증 사용자명

;<code>--os-password <auth-password></code>
:인증 패스워드

;<code>--os-token <token></code>
:인증된 토큰 또는 서비스 토큰

;<code>--os-user-domain-name <auth-user-domain-name></code>
:사용자를 포함하는 도메인 이름

;<code>--os-user-domain-id <auth-user-domain-id></code>
:사용자를 포함하는 도메인 ID

;<code>--os-trust-id <trust-id></code>
:수탁자 사용자로 사용할 트러스트 ID

;<code>--os-default-domain <auth-domain></code>
:기본 도메인 ID (기본값: ‘default’)

;<code>--os-region-name <auth-region-name></code>
:인증 리전 이름

;<code>--os-cacert <ca-bundle-file></code>
:CA 인증서 번들 파일

;<code>--verify</code> | <code>--insecure</code>
:서버 인증서를 확인하거나 무시 (기본값: 확인)

;<code>--os-cert <certificate-file></code>
:클라이언트 인증서 번들 파일

;<code>--os-key <key-file></code>
:클라이언트 인증서 키 파일

;<code>--os-identity-api-version <identity-api-version></code>
:Identity API 버전 (기본값: 2.0)

;<code>--os-XXXX-api-version <XXXX-api-version></code>
:설치된 API 라이브러리에 따라 추가적인 API 버전 옵션이 제공됩니다.

;<code>--os-interface <interface></code>
:인터페이스 유형. 유효한 옵션은 public, admin, internal입니다.

{{NOTE}}
novaclient, neutronclient 등 프로젝트 지정 클라이언트에서 openstackclient로 전환하는 경우 --os-endpoint-type 대신 --os-interface를 사용하십시오.
{{/NOTE}}

;<code>--os-profile <hmac-key></code>
:성능 프로파일링 HMAC 키. 컨텍스트 데이터를 암호화하는 데 사용합니다.
:이 키는 추적할 OpenStack 서비스의 설정 파일에 정의된 HMAC 키 값 중 하나여야 합니다.

;<code>--os-beta-command</code>
:변경될 수 있는 베타 명령어 활성화

;<code>--log-file <LOGFILE></code>
:출력 로그 파일 지정. 기본값은 비활성화.

;<code>-v</code>, <code>--verbose</code>
:출력의 상세함(verbosity)을 증가시킵니다. 반복할 수 있습니다.

;<code>-q</code>, <code>--quiet</code>
:경고와 오류를 제외한 출력 억제

;<code>--debug</code>
:오류 발생 시 추적 정보를 표시하고 상세함(verbosity)을 디버그로 설정

;<code>--help</code>
:도움말 메시지를 표시하고 종료

;<code>--timing</code>
:API 호출 타이밍 정보 출력

==명령어==
명령어 목록을 얻으려면:

<syntaxhighlight lang='bash'>
openstack --help
</syntaxhighlight>

특정 명령어에 대한 설명을 얻으려면:

<syntaxhighlight lang='bash'>
openstack help <command>
</syntaxhighlight>

API 버전에 따라 표시되는 명령어 세트가 다를 수 있습니다. 예를 들어, Identity v3 명령어를 강제로 표시하려면:

<syntaxhighlight lang='bash'>
openstack --os-identity-api-version 3 --help
</syntaxhighlight>

;<code>complete</code>
:현재 명령어 세트에 대한 bash 완성 기능을 출력합니다.

;<code>help <command></code>
:개별 명령어에 대한 도움말을 출력합니다.

OpenStackClient 명령어 구조와 인수에 대한 추가 정보는 [[OpenStackClient 명령어 목록]]에서 확인할 수 있습니다.

===명령어 객체===
OpenStack 프로젝트 지원이 추가됨에 따라 명령어 객체 목록이 점점 길어지고 있습니다. 객체 이름은 고유한 이름을 구성하기 위해 여러 단어로 구성될 수 있습니다. 때때로 여러 API가 공통된 이름과 겹치는 목적을 가지고 있을 때, 사용할 객체를 선택할 수 있는 옵션이 있거나, Compute와 Block Storage 할당량을 참조하는 <code>quota</code> 객체와 같이 API 리소스가 병합될 수 있습니다.

===명령어 액션===
OpenStackClient에서 사용되는 액션들은 각 객체에 대해 일관된 액션을 제공하기 위해 특정 의미로 정의됩니다. 일부 액션들은 논리적으로 반대되는 액션이 있으며, 이러한 쌍은 해당 객체에서 항상 매치하게 됩니다.

==클라우드 설정==
여러 클라우드를 다루는 작업은 해당 클라우드의 설정 정보를 로컬 파일에 저장함으로써 간소화할 수 있습니다. '''openstack'''은 <code>clouds.yaml</code> 설정 파일을 사용하는 것을 지원합니다.

===설정 파일===
'''openstack'''은 다음 위치에서 clouds.yaml 파일을 찾습니다:

* 현재 디렉토리
* ~/.config/openstack
* /etc/openstack

가장 먼저 발견된 파일이 사용됩니다.

키는 <code>--os-</code> 접두어 없이 '''openstack''' 전역 옵션과 매치합니다:

<syntaxhighlight lang='yaml'>
clouds:
  devstack:
    auth:
      auth_url: http://192.168.122.10:5000/
      project_name: demo
      username: demo
      password: 0penstack
    region_name: RegionOne
  ds-admin:
    auth:
      auth_url: http://192.168.122.10:5000/
      project_name: admin
      username: admin
      password: 0penstack
    region_name: RegionOne
  infra:
    cloud: rackspace
    auth:
      project_id: 275610
      username: openstack
      password: xyzpdq!lazydog
    region_name: DFW,ORD,IAD
</syntaxhighlight>

위 예제에서 <code>rackspace</code> 클라우드의 <code>auth_url</code>은 <code>clouds-public.yaml</code>에서 가져옵니다:

<syntaxhighlight lang='yaml'>
public-clouds:
  rackspace:
    auth:
      auth_url: 'https://identity.api.rackspacecloud.com/v2.0/'
</syntaxhighlight>

===인증 세팅===
OpenStackClient는 Keystone 인증 플러그인을 사용하므로, 필요한 인증 세팅은 인증 유형이 선택될 때까지 항상 알 수 있는 것은 아닙니다. '''openstack'''은 전달된 인수나 설정 파일에서 찾은 내용을 기반으로 몇 가지 일반적인 인증 유형을 감지하려고 시도하지만, 불완전한 경우에는 어떤 인증 유형이 의도된 것인지 알 수 없을 수 있습니다. <code>--os-auth-type</code> 옵션을 사용하여 특정 유형을 강제로 지정할 수 있습니다.

<code>--os-token</code>과 <code>--os-endpoint</code>가 모두 존재할 때는 <code>token_endpoint</code> 인증 유형이 자동으로 선택됩니다. <code>--os-auth-url</code>과 <code>--os-username</code>이 존재할 때는 <code>password</code> 인증 유형이 선택됩니다.

===로깅 세팅===
'''openstack'''은 설정 파일의 로그 세팅을 통해 작업 내역을 기록할 수 있습니다. 사용자 작업을 기록함으로써, 리소스 변경사항을 식별할 수 있으며, 이는 트러블슈팅에 유용한 정보가 됩니다.

로그 세팅에 대한 자세한 내용은 [[OpenStackClient 설정|설정]]을 참조하십시오.

==참고==
도움말 출력에 표시되는 명령어 목록은 선택된 API 버전을 반영합니다. 예를 들어, Identity v3 명령어를 보려면 <code>OS_IDENTITY_API_VERSION</code>이 <code>3</code>으로 세팅되어야 합니다.

==예시==
서버 <code>appweb01</code>에 대한 상세 정보를 표시하는 예시:

<syntaxhighlight lang='bash'>
openstack \
    --os-project-name ExampleCo \
    --os-username demo --os-password secret \
    --os-auth-url http://localhost:5000:/v2.0 \
    server show appweb01
</syntaxhighlight>

keystone에서 openid를 사용하여 인증하는 동일한 명령어:

<syntaxhighlight lang='bash'>
openstack \
    --os-project-name ExampleCo \
    --os-auth-url http://localhost:5000:/v2.0 \
    --os-auth-plugin openid \
    --os-auth-type v3oidcpassword \
    --os-username demo-idp \
    --os-password secret-idp \
    --os-identity-provider google \
    --os-client-id the-id-assigned-to-keystone-in-google \
    --os-client-secret 3315162f-2b28-4809-9369-cb54730ac837 \
    --os-openid-scope 'openid email profile'\
    --os-protocol openid \
    --os-access-token-type access_token \
    --os-discovery-endpoint https://accounts.google.com/.well-known/openid-configuration \
    server show appweb01
</syntaxhighlight>

인증 환경변수(<code>OS_AUTH_URL</code>, <code>OS_PROJECT_NAME</code>, <code>OS_USERNAME</code>, <code>OS_PASSWORD</code>)가 설정된 경우의 동일한 명령어:

<syntaxhighlight lang='bash'>
openstack server show appweb01
</syntaxhighlight>

새 이미지를 생성하는 명령어:

<syntaxhighlight lang='bash'>
openstack image create \
    --disk-format=qcow2 \
    --container-format=bare \
    --public \
    --copy-from http://somewhere.net/foo.img \
    foo
</syntaxhighlight>

==파일==
;<code>~/.config/openstack/clouds.yaml</code>
:<code>--os-cloud</code> 전역 옵션에 의해 사용되는 설정 파일입니다.

;<code>~/.config/openstack/clouds-public.yaml</code>
:인증 URL 및 서비스 정의와 같은 공개 클라우드 제공자 정보를 포함하는 설정 파일입니다. 이 파일의 내용은 공개적이고 공유가능해야 합니다. <code>clouds.yaml</code> 파일은 여기 정의된 클라우드를 참조하여 단축키로 사용할 수 있습니다.

;<code>/.openstack</code>
:미래의 로컬 상태 디렉토리를 위한 플레이스홀더입니다. 이 디렉토리는 여러 OpenStack 관련 애플리케이션 간에 공유되도록 의도되었으며, 내용에는 해당 애플리케이션에서 식별자를 사용하여 네임스페이스가 지정됩니다. 공유된 내용(<code>/.openstack/cache</code>와 같은)에는 접두어가 없으며, 컨텐츠는 포터블이어야 합니다.

==환경변수==
다음 환경변수를 세팅하면 '''openstack'''의 동작을 변경할 수 있습니다. 대부분의 환경변수는 세팅된 경우 우선순위를 갖는 해당 명령줄 옵션이 있습니다.

;<code>OS_CLOUD</code>
:<code>clouds.yaml</code>에 있는 클라우드 설정의 이름입니다.

;<code>OS_AUTH_PLUGIN</code>
:Identity 서비스에 연결할 때 사용할 인증 플러그인입니다. 플러그인의 버전은 Identity API 버전과 일치해야 합니다.

;<code>OS_AUTH_URL</code>
:인증 URL

;<code>OS_AUTH_TYPE</code>
:인증 과정을 처리하는 데 사용될 인증 플러그인을 정의합니다. 다음 중 하나입니다:
:* <code>v2password</code>
:* <code>v2token</code>
:* <code>v3password</code>
:* <code>v3token</code>
:* <code>v3oidcclientcredentials</code>
:* <code>v3oidcpassword</code>
:* <code>v3oidcauthorizationcode</code>
:* <code>v3oidcaccesstoken</code>
:* <code>v3totp</code>
:* <code>v3tokenlessauth</code>
:* <code>v3applicationcredential</code>
:* <code>v3multifactor</code>

;<code>OS_ENDPOINT</code>
:(서비스 토큰을 사용할 때의) 서비스 엔드포인트입니다.

;<code>OS_DOMAIN_NAME</code>
:도메인 수준의 인증 범위 (이름 또는 ID)

;<code>OS_PROJECT_NAME</code>
:프로젝트 수준의 인증 범위 (이름 또는 ID)

;<code>OS_PROJECT_DOMAIN_NAME</code>
:프로젝트가 포함된 도메인 이름 또는 ID

;<code>OS_USERNAME</code>
:인증 사용자명

;<code>OS_TOKEN</code>
:인증된 또는 서비스 토큰

;<code>OS_PASSWORD</code>
:인증 패스워드

;<code>OS_USER_DOMAIN_NAME</code>
:사용자가 포함된 도메인의 이름 또는 ID

;<code>OS_TRUST_ID</code>
:신뢰할 수 있는 사용자로 사용할 트러스트 ID

;<code>OS_DEFAULT_DOMAIN</code>
:기본 도메인 ID (기본값: ‘default’)

;<code>OS_REGION_NAME</code>
:인증 리전 이름

;<code>OS_CACERT</code>
:CA 인증서 번들 파일

;<code>OS_CERT</code>
:클라이언트 인증서 번들 파일

;<code>OS_KEY</code>
:클라이언트 인증서 키 파일

;<code>OS_IDENTITY_API_VERSION</code>
:Identity API 버전 (기본값: 2.0)

;<code>OS_XXXX_API_VERSION</code>
:설치된 API 라이브러리에 따라 추가 API 버전 옵션을 사용할 수 있습니다.

;<code>OS_INTERFACE</code>
:인터페이스 유형입니다. 유효한 옵션은 public, admin, internal입니다.

;<code>OS_PROTOCOL</code>
:연합 인증 프로세스를 실행하는 데 사용되는 프로토콜을 정의합니다. Keystone 인증 URL 생성 과정에 사용됩니다.

;<code>OS_IDENTITY_PROVIDER</code>
:사용할 페더레이션의 신원 제공자를 정의합니다. Keystone 인증 URL 생성 과정에 사용됩니다. 사용할 수 있는 신원 제공자는 '''openstack identity provider list''' 명령어를 사용하여 나열할 수 있습니다.

;<code>OS_CLIENT_ID</code>
:Identity Provider에서 애플리케이션(OpenStack)을 인증하는 데 CLI가 사용할 <code>CLIENT_ID</code>를 설정합니다. 이 값은 Identity Provider 측에서 정의됩니다. 사용자 ID와 혼동하지 마십시오.

;<code>OS_CLIENT_SECRET</code>
:CLI(신원 제공자에 있는 OpenStack 시크릿)를 인증하는 데 CLI가 사용할 OS_CLIENT_SECRET을 설정합니다.

;<code>OS_OPENID_SCOPE</code>
:서비스 제공자(SP)인 OpenStack이 신원 제공자에게 요청할 속성 스코프를 구성합니다. 이 스코프와 각 스코프가 포함하는 속성은 신원 제공자 측에서 정의됩니다. 이 매개변수는 공백으로 구분된 여러 값을 받을 수 있습니다.

;<code>OS_ACCESS_TOKEN_TYPE</code>
:토큰 검사 과정에서 사용되는 액세스 토큰 유형을 정의합니다. 이 변수는 “access_token” 또는 “id_token” 상태 중 하나를 가질 수 있습니다.

;<code>OS_DISCOVERY_ENDPOINT</code>
:신원 제공자의 발견 URL을 설정합니다. 이 URL은 신원 제공자 엔드포인트를 설명하는 메타데이터가 포함된 발견 문서를 제공합니다. 이 변수는 <code>OS_ACCESS_TOKEN_ENDPOINT</code>가 정의된 경우 선택사항입니다.

;<code>OS_ACCESS_TOKEN_ENDPOINT</code>
:<code>OS_DISCOVERY_ENDPOINT</code> URL 요청에서 조회된 문서에 표시된 값을 재정의합니다. 이 변수는 <code>OS_DISCOVERY_ENDPOINT</code>가 설정된 경우 선택사항입니다.

{{NOTE}}
novaclient, neutronclient 등 프로젝트별 클라이언트에서 openstackclient로 전환하는 경우 OS_ENDPOINT_TYPE 대신 OS_INTERFACE를 사용하십시오.
{{/NOTE}}

==버그==
버그 리포트는 python-openstackclient Launchpad 프로젝트 https://bugs.launchpad.net/python-openstackclient 에서 접수됩니다.

==저자==
OpenStackClient와 함께 배포된 AUTHORS 파일을 참조하십시오.

==저작권==
Copyright 2011-2014 OpenStack 재단 및 AUTHORS 파일에 나열된 저자들.

==라이선스==
http://www.apache.org/licenses/LICENSE-2.0

==같이 보기==
[[OpenStack Docs]]의 [[OpenStackClient 페이지]]에 추가 문서가 포함되어 있습니다.

개별 OpenStack 프로젝트 CLI, OpenStack API 참고자료.