이 페이지에서는 Google Distributed Cloud (GDC) 오프라인 프로젝트로 작업할 때 객체 스토리지를 관리하기 위해 gdcloud CLI를 설치하고 구성하는 방법을 안내합니다. 이 가이드에서는 격리된 환경에서 스토리지 버킷과 객체를 효과적으로 사용하는 데 필요한 구성요소와 설정을 다운로드, 설치, 구성하는 방법을 설명합니다.
이 페이지는 GDC 오프라인 환경 내 프로젝트의 객체 스토리지 버킷을 프로비저닝하고 관리하려는 인프라 운영자 그룹의 IT 관리자 또는 애플리케이션 운영자 그룹의 개발자와 같은 사용자를 대상으로 합니다. 자세한 내용은 GDC 오프라인 문서 대상을 참고하세요.
gdcloud CLI 준비
gdcloud CLI를 사용하려면 다음 단계에 따라 패키지를 다운로드, 설치, 구성하세요.
gdcloud config set storage/s3_secret_access_key SECRET_ACCESS_KEY
CA_BUNDLE_FILE를 CA 인증서 경로로 바꿉니다.
gdcloud config set storage/s3_custom_ca_certs_file CA_BUNDLE_FILE
ENDPOINT을 인프라 운영자 (IO)가 제공하는 엔드포인트로 바꿉니다.
gdcloudconfigsetstorage/s3_endpointENDPOINT
이 단계는 이중 영역 버킷의 경우 약간 다릅니다. 각 이중 영역 버킷은 버킷에 액세스하는 데 사용할 수 있는 세 개의 엔드포인트를 제공합니다. 대부분의 경우 자동 장애 조치를 활용하기 위해 전역 엔드포인트가 적합합니다.
Zone1 엔드포인트: 이 엔드포인트는 항상 zone1에서 수신합니다. 이 엔드포인트를 사용하는 경우 zone1에 기록된 객체에 대해 쓰기 후 읽기 일관성이 있습니다. 하지만 zone1이 다운되면 클라이언트는 이 버킷에 계속 읽기/쓰기를 하려면 zone2 또는 전역 엔드포인트를 사용하도록 변경해야 합니다. 클라이언트가 사용자 클러스터에서 오는 경우 이 엔드포인트는 zone1 내에서만 액세스할 수 있습니다.
Zone2 엔드포인트: 이 엔드포인트는 항상 zone2에서 수신합니다. 이 엔드포인트를 사용하면 zone2에 기록된 객체에 대해 쓰기 후 읽기 일관성이 적용됩니다. 하지만 zone2가 다운되면 클라이언트는 이 버킷에 계속 읽기/쓰기를 하려면 zone1 또는 전역 엔드포인트를 사용하도록 변경해야 합니다. 클라이언트가 사용자 클러스터에서 오는 경우 이 엔드포인트는 zone2 내에서만 액세스할 수 있습니다.
전역 엔드포인트: 이 엔드포인트는 요청을 zone1 또는 zone2로 라우팅합니다. 이 옵션은 세션 어피니티를 제공하지 않으므로 동일한 세션을 사용하여 이루어진 요청이 zone1 또는 zone2에 도착할 수 있습니다. 즉, 전역 엔드포인트에 대한 요청에는 쓰기 후 읽기 보장이 없습니다. 전역 엔드포인트는 영역이 다운되는 경우 자동 장애 조치를 제공하므로 사용자는 영역 엔드포인트를 사용하는 경우와 같이 워크로드에서 엔드포인트를 변경할 필요가 없습니다. 또한 이 엔드포인트는 모든 영역의 사용자 클러스터에서 액세스할 수 있습니다.
다음 명령어를 실행하여 버킷의 전역/영역 엔드포인트를 확인하고 사용할 엔드포인트를 선택합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eThe gdcloud CLI tool is used for managing object storage, and this guide provides steps on how to set it up.\u003c/p\u003e\n"],["\u003cp\u003eDownloading the gdcloud CLI is the first step, as detailed in the gdcloud CLI overview document.\u003c/p\u003e\n"],["\u003cp\u003eInstalling the storage dependencies component is required to use the storage command tree, and this can be achieved by running \u003ccode\u003egdcloud components install storage-cli-dependencies\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eConfiguring the gdcloud CLI for object storage involves setting the access key ID, secret access key, CA certificate path, and endpoint using \u003ccode\u003egdcloud config set\u003c/code\u003e commands.\u003c/p\u003e\n"]]],[],null,["# Install and configure storage CLI\n\nThis page guides you through how to install and configure the gdcloud CLI for managing object storage when working with Google Distributed Cloud (GDC) air-gapped projects. It covers how to download, install, and configure the necessary components and settings essential for effectively using storage buckets and objects in this isolated environment.\n\nThis page is for audiences such as IT admins within the infrastructure operator group or developers within the application operator group who are looking to provision and manage object storage buckets for projects within GDC air-gapped environments. For more information, see [Audiences for GDC air-gapped documentation](/distributed-cloud/hosted/docs/latest/gdch/resources/audiences).\n\nPrepare the gdcloud CLI\n-----------------------\n\nTo use the gdcloud CLI, see the following steps to download, install, and configure the package.\n\n### Download the gdcloud CLI\n\nTo download the gdcloud CLI, see the\n[gdcloud CLI overview](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-overview).\n\n### Install the gdcloud CLI\n\nIn order to use the storage command tree, the storage dependencies component must be installed.\n\n1. Follow [Install gdcloud CLI](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-install).\n\n2. To install the storage dependencies component, run the following commands:\n\n gdcloud components install storage-cli-dependencies\n\n For more information on the `components install` command, see [Install gdcloud CLI](/distributed-cloud/hosted/docs/latest/gdch/resources/gdcloud-install).\n\n| **Note:** This command only installs the dependencies onto the client machine. For configuring the gdcloud CLI follow [Configure gdcloud CLI for object storage](#gdcloud-storage-configure).\n\n### Configure the gdcloud CLI for object storage\n\nThe following configurations must be set to use the gdcloud CLI for object storage.\n\n1. Replace `ACCESS_KEY_ID` with the access key ID obtained from the secret in [getting access credentials](/distributed-cloud/hosted/docs/latest/gdch/platform/pa-user/grant-obtain-storage-access#getting_bucket_access_credentials):\n\n gdcloud config set storage/s3_access_key_id ACCESS_KEY_ID\n\n2. Replace `SECRET_ACCESS_KEY` with the secret key obtained from the secret in [getting access credentials](/distributed-cloud/hosted/docs/latest/gdch/platform/pa-user/grant-obtain-storage-access#getting_bucket_access_credentials):\n\n gdcloud config set storage/s3_secret_access_key SECRET_ACCESS_KEY\n\n3. Replace `CA_BUNDLE_FILE` with the path to the CA Certificate:\n\n gdcloud config set storage/s3_custom_ca_certs_file CA_BUNDLE_FILE\n\n | **Note:** If the CA Certs for GDC are already installed on the environment then you can set this to `/etc/ssl/certs/ca-certificates.crt`\n4. Replace `ENDPOINT` with the endpoint your Infrastructure Operator (IO) provides:\n\n gdcloud config set storage/s3_endpoint ENDPOINT\n\n | **Note:** This is the full endpoint beginning with `https://`.\n\n This step differs slightly for dual-zone buckets. Each dual-zone bucket provides three endpoints that you can choose to access the bucket. For most situations, the global endpoint is appropriate in order to take advantage of automatic failovers:\n - Zone1 endpoint: This endpoint is always received by zone1. If using this endpoint, you have read-after-write consistency for any objects written to zone1. However, if zone1 goes down, a client needs to change to using either the zone2 or global endpoint to continue reading/writing to this bucket. If the client is coming from a user cluster, then this endpoint will only be accessible from within zone1.\n - Zone2 endpoint: This endpoint is always received by zone2. If using this endpoint, you have read-after-write consistency for any objects written to zone2. However, if zone2 goes down, a client needs to change to using either the zone1 or global endpoint to continue reading/writing to this bucket. If the client is coming from a user cluster, then this endpoint will only be accessible from within zone2.\n - Global endpoint: This endpoint results in your request being routed to either zone1 or zone2. This option doesn't provide session affinity, meaning that requests made using the same session may arrive in either zone1 or zone2. This means that there is no read-after-write guarantee for requests made to the global endpoint. The global endpoint provides automatic failover in the event that a zone goes down, so users won't have to change endpoints in their workloads the way they would need to if using the zonal endpoint. In addition, this endpoint is accessible from user clusters in all zones.\n\n Run the following commands to view the global/zonal endpoints for your bucket and choose the one you want to use: \n\n kgo get buckets $BUCKET_NAME -n $PROJECT_NAME -o jsonpath=\"{.status.globalEndpoint}\"\n\n kgo get buckets $BUCKET_NAME -n $PROJECT_NAME -o jsonpath=\"{.status.zonalEndpoints}\""]]
