asmcli 참조

개요

asmcli는 Cloud Service Mesh 설치 또는 업그레이드에 사용할 수 있는 Google 제공 도구입니다. 사용자가 허용하면 asmcli가 프로젝트 및 클러스터를 다음과 같이 구성합니다.

  • Google Cloud 프로젝트에 필요한 Identity and Access Management(IAM) 권한을 부여합니다.
  • Google Cloud 프로젝트에서 필요한 Google API를 사용 설정합니다.
  • 메시를 식별하는 라벨을 클러스터에 설정합니다.
  • 사이드카 프록시와 같은 데이터 영역 구성요소가 프로젝트의 데이터 및 리소스에 안전하게 액세스할 수 있는 서비스 계정을 만듭니다.
  • 아직 등록되지 않은 경우 Fleet에 클러스터를 등록합니다.

asmcli를 실행할 때 --enable_all 플래그를 포함하여 프로젝트와 클러스터를 구성할 수 있습니다. asmcli 옵션 및 플래그에 대한 자세한 내용은 asmcli 참조를 확인하세요.

그런 후 asmcli가 프로젝트 및 클러스터 정보를 사용하여 YAML 파일을 구성합니다. Cloud Service Mesh 컨트롤 플레인을 설치하려면 이러한 구성 파일이 필요합니다.

Cloud Service Mesh 및 Istio를 처음 사용하는 경우에는 지원되는 플랫폼으로 건너뜁니다. 다음 섹션에서는 1.23에 대한 기존 Cloud Service Mesh 업그레이드를 도와줍니다.

asmcli로 전환

asmcli가 istioctl install 및 install_asm을 대체합니다. Cloud Service Mesh 1.11에서는 기존 도구를 계속 사용할 수 있지만, 기존 도구는 지원 중단되어 Cloud Service Mesh 1.12 이상에서는 더 이상 지원되지 않습니다. asmcli를 사용하도록 스크립트와 도구를 업데이트하세요.

클러스터를 Fleet에 등록해야 합니다. 자세한 내용은 Fleet 요구사항을 참조하세요.

install_asm에서 전환

install_asm에 익숙하다면 asmcli는 이와 비슷하지만 다음과 같은 주목할 만한 차이점이 있습니다.

  • 새로운 설치 및 업그레이드에는 asmcli install를 사용하세요. install_asm에서와 같은 --mode 옵션은 없습니다. asmcli install을 실행할 때는 클러스터에 기존 제어 영역이 있는지 확인합니다. 기존 컨트롤 플레인이 없으면 asmcli가 Cloud Service Mesh를 설치합니다. 클러스터에 기존 컨트롤 플레인 (Cloud Service Mesh 컨트롤 플레인 또는 오픈소스 Istio 컨트롤 플레인)이 있는 경우:

  • 대부분의 asmcli 옵션 및 플래그는 install_asm과 동일하게 작동합니다.

istioctl install에서 전환

istioctl install에 익숙한 경우, 일반적으로 제어 영역을 구성하기 위해 -f 명령줄 인수를 통해 IstioOperator YAML 파일을 전달할 때는 --custom_overlay 옵션을 사용해서 파일을 asmcli로 전달할 수 있습니다. Cloud Service Mesh 문서에서는 이러한 파일을 오버레이 파일이라고 합니다.

지원되는 플랫폼

지원되는 플랫폼 목록에 있는 Cloud Service Mesh 설치는 asmcli로 구성하거나 업그레이드할 수 있습니다.

하지만 Google Cloud 외부 플랫폼에서는 일부 기능을 사용할 수 없습니다. 자세한 내용은 클러스터 내 제어 영역 지원 기능을 참조하세요.

asmcli 참조

이 섹션에서는 asmcli에 사용 가능한 인수에 대해 설명합니다.

옵션

클러스터 식별 다음과 같은 클러스터 식별 옵션이 있습니다.

GKE만 해당

-p|--project_id CLUSTER_PROJECT_ID
클러스터가 생성된 프로젝트의 프로젝트 ID입니다.
-n|--cluster_name CLUSTER_NAME
클러스터의 이름입니다.
-l|--cluster_location CLUSTER_LOCATION
클러스터가 생성된 영역(단일 영역 클러스터) 또는 리전(리전 클러스터용)입니다.

모든 플랫폼

--kubeconfig KUBECONFIG_FILE kubeconfig 파일의 전체 경로입니다. 여기서 환경 변수 $PWD는 작동하지 않습니다.

--ctx|--context KUBE_CONTEXT 사용할 kubeconfig 컨텍스트입니다. 지정되지 않은 경우 asmcli에 기본 컨텍스트가 사용됩니다.

-c|--ca {mesh_ca|gcp_cas|citadel}

상호 TLS 인증서 관리를 위해 사용할 인증 기관(CA)입니다. Cloud Service Mesh 인증 기관을 사용하려면 mesh_ca를 지정하고, Certificate Authority Service를 사용하려면 gcp_cas를 지정하고, Istio CA를 사용하려면 citadel을 지정합니다. 관리형 Cloud Service Mesh는 Istio CA를 지원하지 않습니다. 자세한 내용은 다음을 참조하세요.

--channel CLOUD_SERVICE_MESH_CHANNEL

특정 Cloud Service Mesh 출시 채널로 --channel을 사용하여 해당 출시 채널과 연결된 컨트롤 플레인 버전을 프로비저닝합니다. 예를 들면 --channel rapid, --channel regular, --channel stable입니다. 이 플래그는 GKE Autopilot 클러스터에서 특정 Cloud Service Mesh 기능을 구성할 때 필요합니다.

CSM 출시 노트에 언급된 대로 관리형 Cloud Service Mesh에서는 더 이상 --channel 옵션이 지원되지 않습니다. 출시 채널은 GKE 클러스터 출시 채널에 따라 결정됩니다. 자세한 내용은 관리형 Cloud Service Mesh 출시 채널을 참조하세요.

--co|--custom_overlay OVERLAY_FILE
IstioOperator 커스텀 리소스가 포함된 YAML 파일 이름(오버레이 파일)으로 --custom_overly를 사용해서 클러스터내 컨트롤 플레인을 구성합니다. 기본적으로 사용 설정되지 않는 기능을 사용 설정하려면 오버레이 파일을 지정합니다. 관리형 Cloud Service Mesh는 IstioOperator API를 지원하지 않으므로 --custom_overlay를 사용하여 관리형 컨트롤 플레인을 구성할 수 없습니다. asmcli는 오버레이 파일을 찾을 수 있어야 하므로 asmcli와 동일한 디렉터리에 있어야 하거나 상대 경로를 지정할 수 있습니다. 여러 파일을 추가하려면 --co|--custom_overlay 및 파일 이름을 지정합니다(예: --co overlay_file1.yaml --co overlay_file2.yaml --co overlay_file3.yaml).
--hub-registration-extra-flags HUB_REGISTRATION_EXTRA_FLAGS
연결된 Amazon EKS 클러스터를 사용하는 경우 --hub-registration-extra-flags를 사용해서 아직 등록되지 않은 경우 fleet에 클러스터를 등록합니다.
-k|--key_file FILE_PATH
서비스 계정의 키 파일입니다. 서비스 계정을 사용하지 않으면 이 옵션을 생략합니다.
--network_id NETWORK_ID
--network_id를 사용하여 istio-system 네임스페이스에 적용되는 topology.istio.io/network 라벨을 설정합니다. GKE의 경우 --network_id는 기본적으로 클러스터의 네트워크 이름으로 지정됩니다. 다른 환경에서는 default가 사용됩니다.
-o|--option OVERLAY_FILE

asmcli가 선택적인 기능을 사용 설정하기 위해 anthos-service-mesh 저장소에서 다운로드하는 오버레이 파일(.yaml 확장자 제외)의 이름입니다. --option을 사용하려면 인터넷 연결이 필요합니다. --option 및 --custom_overlay 옵션은 비슷하지만 동작이 약간 다릅니다.

  • 오버레이 파일의 설정을 변경해야 하는 경우 --custom_overlay를 사용합니다.

  • --option을 사용하여 오버레이 파일 변경이 필요하지 않은 기능을 사용 설정합니다(예: 서비스의 감사 정책 구성).

여러 파일을 추가하려면 -o|--option 및 파일 이름을 지정합니다(예: -o option_file1 -o option_file2 -o option_file3).

-D|--output_dir DIR_PATH

지정하지 않으면, asmcli가 Cloud Service Mesh 설치에 필요한 파일 및 구성을 다운로드할 임시 디렉터리를 만듭니다. --output-dir 플래그를 지정하여 대신 사용할 디렉터리의 상대 경로를 지정합니다. 완료되면 지정된 디렉터리에 asm 및 istio-1.23.3-asm.1 하위 디렉터리가 포함됩니다. asm 디렉터리에는 설치 구성이 포함됩니다. istio-1.23.3-asm.1 디렉터리에는 istioctl, 샘플, 매니페스트를 비롯한 설치 파일에서 추출한 콘텐츠가 포함됩니다. --output-dir을 지정하고 디렉터리에 이미 필요한 파일이 포함된 경우 asmcli가 이를 다운로드하는 대신 해당 파일을 사용합니다.

--platform PLATFORM {gcp|multicloud}

Kubernetes 클러스터의 플랫폼 또는 제공업체입니다. 기본값은 gcp(GKE 클러스터용)입니다. 다른 모든 플랫폼에서는 multicloud를 사용합니다.

-r|--revision_name REVISION NAME

버전 라벨은 컨트롤 플레인에 설정된 키-값 쌍입니다. 버전 라벨 키는 항상 istio.io/rev입니다. 기본적으로 asmcli는 Cloud Service Mesh 버전을 기준으로 버전 라벨 값을 설정합니다(예: asm-1233-2). 기본값을 재정의하고 직접 지정하려면 이 옵션을 포함하세요. REVISION NAME 인수가 DNS-1035 라벨이어야 합니다. 즉, 이름이 다음과 같아야 합니다.

  • 63자(영문 기준) 이하여야 합니다.
  • 소문자 영숫자 문자 또는 '-'만 포함해야 합니다.
  • 알파벳 문자로 시작해야 합니다.
  • 영숫자 문자로 끝나야 합니다.

검증에 사용되는 정규식은 '[a-z]([-a-z0-9]*[a-z0-9])?'입니다.

-s|--service_account ACCOUNT
Cloud Service Mesh를 설치하는 데 사용되는 서비스 계정의 이름입니다. 지정하지 않으면 현재 gcloud 구성의 활성 사용자 계정이 사용됩니다. 활성 사용자 계정을 변경해야 하는 경우 gcloud auth login을 실행합니다.

Istio CA 커스텀 인증서 옵션

--ca citadel을 지정했고 커스텀 CA를 사용하는 경우, 다음 옵션을 포함합니다.

  • --ca_cert FILE_PATH: 중간 인증서
  • --ca_key FILE_PATH: 중간 인증서의 키
  • --root_cert FILE_PATH: 루트 인증서
  • --cert_chain FILE_PATH: 인증서 체인

자세한 내용은 기존 CA 인증서 연결을 참조하세요.

사용 설정 플래그

--enable로 시작하는 플래그를 사용하면 asmcli가 필요한 Google API를 사용 설정하고, 필요한 Identity and Access Management(IAM) 권한을 설정하고, 클러스터를 업데이트할 수 있습니다. 원하는 경우 asmcli를 실행하기 전 프로젝트 및 클러스터를 직접 업데이트할 수 있습니다. 모든 사용 설정 플래그는 asmcli validate와 호환되지 않습니다. asmcli validate를 실행할 때 사용 설정 플래그를 지정하면 오류와 함께 명령어가 종료됩니다.

-e|--enable_all
asmcli가 아래 설명된 모든 개별 사용 설정 작업을 수행할 수 있습니다.
--enable_cluster_roles
asmcli를 실행하는 Google Cloud 사용자 또는 서비스 계정을 클러스터의 cluster-admin 역할에 결합하도록 asmcli를 허용합니다. asmcli에서 gcloud config get core/account 명령어를 통해 사용자 계정을 결정합니다. 사용자 계정을 사용해 asmcli를 로컬에서 실행하는 경우 asmcli를 실행하기 전에 gcloud auth login 명령어를 호출해야 합니다. 사용자 계정을 변경해야 하는 경우 gcloud config set core/account GCP_EMAIL_ADDRESS 명령어를 실행합니다. 여기서 GCP_EMAIL_ADDRESS는 Google Cloud에 로그인할 때 사용하는 계정입니다.
--enable_cluster_labels
asmcli가 필수 클러스터 라벨을 설정하도록 허용합니다.
--enable_gcp_components

asmcli가 다음 필수 Google Cloud 관리형 서비스 및 구성요소를 사용 설정하도록 허용합니다.

--enable_gcp_apis

asmcli가 모든 필수 Google API를 사용 설정하도록 허용합니다.

--enable_gcp_iam_roles

asmcli가 필수 IAM 권한을 설정하도록 허용합니다.

--enable_meshconfig_init

스크립트가 사용자 대신 meshconfig 엔드포인트를 초기화하도록 허용합니다. --enable_gcp_components 및 --managed가 묵시적으로 적용됩니다.

--enable_namespace_creation

asmcli에서 루트 istio-system 네임스페이스를 만들도록 허용합니다.

--enable_registration

asmcli가 클러스터가 있는 프로젝트에 클러스터를 등록할 수 있도록 허용합니다. 이 플래그를 포함하지 않는 경우에는 클러스터 등록의 단계에 따라 클러스터를 수동으로 등록합니다. 다른 사용 설정 플래그와 달리 --enable_registration은 클러스터 등록이 필요한 옵션(예: --option hub-meshca)을 지정할 때만 --enable_all에 포함됩니다. 그렇지 않으면 이 플래그를 별도로 지정해야 합니다.

기타 플래그

--dry_run
명령어를 출력하지만 실행하지는 않습니다.
--fleet_id
Fleet의 호스트 프로젝트 ID를 사용하여 Fleet에 클러스터를 등록합니다. 이 플래그는 Google Cloud 외부 클러스터에 필요합니다. Google Cloud 클러스터에 제공되지 않으면 기본값은 클러스터의 프로젝트 ID입니다. asmcli install은 설치 전 --fleet_id와 함께 실행하거나, --enable-registration 및 --fleet-id 플래그를 전달하여 설치의 일부로 실행할 수 있습니다. 이 설정은 구성한 후에는 변경할 수 없습니다.
--managed
지원이 중단되었습니다. 클러스터에 하나씩 설치하는 대신 원격 관리형 컨트롤 플레인을 프로비저닝합니다.
--offline
출력 디렉터리에 사전 다운로드된 패키지를 사용하여 오프라인 설치를 수행합니다. 디렉터리가 지정되지 않았거나 필요한 파일이 없으면 스크립트가 오류와 함께 종료됩니다.
--only_enable
지정된 단계를 수행하여 현재 사용자/클러스터를 설정하지만 아무것도 설치하지 않습니다.
--only_validate
검증을 실행하지만 프로젝트 또는 클러스터를 업데이트하지 않고 Cloud Service Mesh를 설치하지 않습니다. 이 플래그는 사용 설정 플래그와 호환되지 않습니다. 사용 설정 플래그로 --only_validate를 지정하면 asmcli가 오류와 함께 종료됩니다.
--print_config
Cloud Service Mesh를 설치하는 대신 모든 컴파일된 YAML을 표준 출력(stdout)으로 출력합니다. 다른 모든 출력은 일반적으로 stdout으로 이동하더라도 표준 오류(stderr)에 기록됩니다. 이 플래그를 지정하면 asmcli는 모든 검증 및 설정을 건너 뜁니다.
--disable_canonical_service
기본적으로 asmcli는 표준 서비스 컨트롤러를 클러스터에 배포합니다. asmcli에서 컨트롤러를 배포하지 않으려면 --disable_canonical_service를 지정합니다. 자세한 내용은 표준 서비스 컨트롤러 사용 설정 및 중지를 참조하세요.
-h|--help
선택사항과 플래그를 설명하는 도움말 메시지를 표시하고 종료합니다.
--use_managed_cni
관리형 CNI를 사용합니다. 이 플래그가 전달되지 않으면 asmcli가 정적 CNI 매니페스트를 적용합니다.
--use_vpcsc
조직에서 프로젝트에 VPC 서비스 제어를 적용하는 경우 --use_vpcsc 플래그가 있는 관리형 Cloud Service Mesh를 구성해야 합니다. 그렇지 않으면 설치 시 보안 제어에 실패합니다.
-v|--verbose
asmcli가 실행될 때 다음에 실행될 명령어를 인쇄합니다. --verbose 플래그를 사용하면 asmcli가 실행된 후 명령어를 인쇄합니다.
--version
asmcli 버전을 인쇄하고 종료합니다. 최신 버전이 없는 경우 asmcli_1.23의 최신 버전을 다운로드할 수 있습니다.