라벨 인스턴스

MySQL   |  PostgreSQL   |  SQL Server

이 페이지에서는 라벨을 설명합니다. 이 문서는 라벨이 있는 인스턴스를 만들고 라벨을 추가, 업데이트, 제거하는 방법, 라벨을 사용하여 검색하는 방법을 설명합니다.

라벨은 서로 관련이 있거나 연결된 인스턴스를 함께 그룹화하는 간단한 방법입니다. 예를 들어, 인스턴스를 테스트 또는 프로덕션 환경에서 사용하는지, 혹은 인스턴스에 자체 청구 코드를 추가할 수 있는지에 따라 라벨을 지정할 수 있습니다. 라벨을 사용하여 인스턴스를 검색하거나 인스턴스 변경사항을 추적할 수 있습니다.

라벨은 항상 키-값 쌍으로 추가합니다.

{
 "userLabels": {
    "track": "production",
    "location": "western-division"
    "billing-code": "34802",...
 }

라벨 수정은 Cloud SQL 인스턴스 성능에 영향을 미치지 않습니다.

자세한 내용은 라벨이란 무엇인가요?와 라벨 요구사항을 참조하세요.

제한사항

• 각 인스턴스에 최대 64개의 라벨을 할당할 수 있습니다.

• 라벨 키 및 값은 다음 제한사항을 준수해야 합니다.

  • 키 및 값은 각각 63자(영문 기준)보다 길 수 없습니다.
  • 키 및 값은 소문자, 숫자, 밑줄, 대시만 포함할 수 있습니다. 국제 문자는 허용됩니다.
  • 라벨 키는 소문자로 시작해야 합니다.
  • 라벨 키는 비워 둘 수 없습니다.

라벨이 있는 인스턴스 만들기

gcloud CLI 또는 API를 사용하여 새 인스턴스를 만들 때 인스턴스에 라벨을 적용할 수 있습니다.

gcloud

인스턴스를 만들 때 `--labels` 플래그를 포함하고 쉼표로 구분된 키-값 쌍 형식의 라벨 목록을 입력합니다. 베타 버전의 create 명령어를 사용하여 라벨을 포함해야 합니다.

예를 들면 다음과 같습니다.

gcloud beta sql instances create ... --labels track=production,billing-code=34802

Terraform

라벨이 있는 인스턴스를 만들려면 Terraform 리소스를 사용합니다.

resource "google_sql_database_instance" "postgres_instance_labels" {
  name             = "postgres-instance-labels"
  region           = "us-central1"
  database_version = "POSTGRES_14"
  settings {
    tier = "db-custom-2-7680"
    user_labels = {
      track        = "production"
      billing-code = 34802
    }
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

변경사항 적용

Google Cloud 프로젝트에 Terraform 구성을 적용하려면 다음 섹션의 단계를 완료하세요.

Cloud Shell 준비

1. Cloud Shell을 실행합니다.

2. Terraform 구성을 적용할 기본 Google Cloud 프로젝트를 설정합니다.

   이 명령어는 프로젝트당 한 번만 실행하면 되며 어떤 디렉터리에서도 실행할 수 있습니다.

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   Terraform 구성 파일에서 명시적 값을 설정하면 환경 변수가 재정의됩니다.

디렉터리 준비

각 Terraform 구성 파일에는 자체 디렉터리(루트 모듈이라고도 함)가 있어야 합니다.

1. Cloud Shell에서 디렉터리를 만들고 해당 디렉터리 내에 새 파일을 만드세요. 파일 이름에는 .tf 확장자가 있어야 합니다(예: main.tf). 이 튜토리얼에서는 파일을 main.tf라고 합니다.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 튜토리얼을 따라 하는 경우 각 섹션이나 단계에서 샘플 코드를 복사할 수 있습니다.

   샘플 코드를 새로 만든 main.tf에 복사합니다.

   필요한 경우 GitHub에서 코드를 복사합니다. 이는 Terraform 스니펫이 엔드 투 엔드 솔루션의 일부인 경우에 권장됩니다.

3. 환경에 적용할 샘플 매개변수를 검토하고 수정합니다.
4. 변경사항을 저장합니다.
5. Terraform을 초기화합니다. 이 작업은 디렉터리당 한 번만 수행하면 됩니다.

   terraform init

   원하는 경우 최신 Google 공급업체 버전을 사용하려면 -upgrade 옵션을 포함합니다.

   terraform init -upgrade

변경사항 적용

1. 구성을 검토하고 Terraform에서 만들거나 업데이트할 리소스가 예상과 일치하는지 확인합니다.

   terraform plan

   필요에 따라 구성을 수정합니다.

2. 다음 명령어를 실행하고 프롬프트에 yes를 입력하여 Terraform 구성을 적용합니다.

   terraform apply

   Terraform에 '적용 완료' 메시지가 표시될 때까지 기다립니다.

3. 결과를 보려면 Google Cloud 프로젝트를 엽니다. Google Cloud 콘솔에서 UI의 리소스로 이동하여 Terraform이 리소스를 만들었거나 업데이트했는지 확인합니다.

참고: Terraform 샘플은 일반적으로 필요한 API가 Google Cloud 프로젝트에서 사용 설정되었다고 가정합니다.

변경사항 삭제

변경사항을 삭제하려면 다음 단계를 따르세요.

1. Terraform 구성 파일에서 삭제 보호를 사용 중지하려면 deletion_protection 인수를 false로 설정합니다.

   deletion_protection =  "false"

2. 다음 명령어를 실행하고 프롬프트에 yes를 입력하여 업데이트된 Terraform 구성을 적용합니다.

   terraform apply

3. 다음 명령어를 실행하고 프롬프트에 yes를 입력하여 이전에 Terraform 구성에 적용된 리소스를 삭제합니다.

   terraform destroy

curl

API에서 새 인스턴스를 추가하기 위해 `POST` 요청을 수행하는 동안 요청 본문에 `userLabels` 속성을 추가하여 새 인스턴스에 라벨을 적용합니다. 예를 들어 인스턴스를 만들기 위한 요청 본문에는 다음 라벨이 있습니다.

          "settings": {"tier":"db-custom-2-7680",
                       "userLabels": {"track": "production",
                                      "location": "western-division",
                                      "billing-code": "34802"},
          

기존 인스턴스에서 라벨 추가 또는 업데이트

콘솔

1. Google Cloud 콘솔의 Cloud SQL 인스턴스 페이지로 이동합니다.

   Cloud SQL 인스턴스 페이지로 이동

2. 라벨을 지정할 리소스 옆에 있는 체크박스를 선택합니다.

3. 오른쪽 상단에 있는 정보 패널 표시를 클릭하여 라벨 열을 확장합니다.

4. 원하는 대로 라벨을 업데이트하거나 새 라벨을 추가합니다.

5. 변경사항을 저장합니다.

gcloud

patch 하위 명령어(베타 버전)를 사용하여 기존 인스턴스에서 라벨을 업데이트하거나 추가합니다.

gcloud beta sql instances patch [INSTANCE_NAME] --update-labels [KEY1]=[VALUE1]...

예를 들면 다음과 같습니다.

gcloud beta sql instances patch my-instance --update-labels track=production,billing-code=34802

이미 존재하는 라벨 키를 입력하면 도구에서 기존 키를 새 라벨 값으로 업데이트합니다. 새 키를 입력하면 도구에서 라벨 목록에 새 키를 추가합니다. 지정한 라벨만 영향을 받으며 명령어에 포함되지 않은 기존 라벨은 변경되지 않습니다.

rest v1

라벨을 추가하거나 업데이트하려면 PATCH 메서드를 사용합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• project-id: 프로젝트 ID
• instance-id: 인스턴스 ID
• label-name-1: 라벨 이름
• value-1: label-name-1 값
• label-name-2: 라벨 이름
• value-2: label-name-2 값

HTTP 메서드 및 URL:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

JSON 요청 본문:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

이미 존재하는 라벨 키를 입력하면 도구에서 기존 키를 새 라벨 값으로 업데이트합니다. 새 키를 입력하면 도구에서 라벨 목록에 새 키를 추가합니다. 지정한 라벨만 영향을 받으며 요청에 포함되지 않은 기존 라벨은 변경되지 않습니다.

rest v1beta4

라벨을 추가하거나 업데이트하려면 PATCH 메서드를 사용합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• project-id: 프로젝트 ID
• instance-id: 인스턴스 ID
• label-name-1: 라벨 이름
• value-1: label-name-1 값
• label-name-2: 라벨 이름
• value-2: label-name-2 값

HTTP 메서드 및 URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

JSON 요청 본문:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name-1" : "value-1",
            "label-name-2" : "value-2"
         }
    }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

이미 존재하는 라벨 키를 입력하면 도구에서 기존 키를 새 라벨 값으로 업데이트합니다. 새 키를 입력하면 도구에서 라벨 목록에 새 키를 추가합니다. 지정한 라벨만 영향을 받으며 요청에 포함되지 않은 기존 라벨은 변경되지 않습니다.

라벨 삭제

콘솔

1. Google Cloud 콘솔의 Cloud SQL 인스턴스 페이지로 이동합니다.

   Cloud SQL 인스턴스 페이지로 이동

2. 라벨을 제거할 리소스 옆에 있는 체크박스를 선택합니다.

3. 정보 패널 표시를 클릭하여 라벨 열을 확장합니다.

4. 삭제할 모든 라벨 옆에 있는 X를 클릭합니다.

5. 변경사항을 저장합니다.

gcloud

gcloud CLI를 사용하여 --remove-labels 플래그와 함께 patch 하위 명령어(베타 버전)를 실행합니다.

gcloud beta sql instances patch [INSTANCE_NAME] --remove-labels [LABEL1],[LABEL2]

존재하지 않는 라벨 이름을 입력해도 오류가 반환되지 않습니다.

rest v1

API를 사용해 값을 null로 설정하여 라벨을 삭제합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• project-id: 프로젝트 ID
• instance-id: 인스턴스 ID
• label-name: 라벨 이름

HTTP 메서드 및 URL:

PATCH https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id

JSON 요청 본문:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

rest v1beta4

API를 사용해 값을 null로 설정하여 라벨을 삭제합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• project-id: 프로젝트 ID
• instance-id: 인스턴스 ID
• label-name: 라벨 이름

HTTP 메서드 및 URL:

PATCH https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id

JSON 요청 본문:

{
  "settings" :
    {
        "userLabels" :
         {
            "label-name" : null,
         }
    }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/instance-id",
  "status": "PENDING",
  "user": "[e-mail]",
  "insertTime": "2020-01-16T02:32:12.281Z",
  "operationType": "UPDATE",
  "name": "operation-id",
  "targetId": "instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

라벨을 사용하여 인스턴스 검색 필터링

gcloud CLI 또는 API를 사용하여 라벨별로 인스턴스 목록 결과를 필터링할 수 있습니다.

gcloud

gcloud에서 list 요청을 수행하고 --filter 플래그를 사용합니다. 라벨을 필터링하려면 labels.[KEY]:[VALUE] 구문을 사용합니다. 예를 들어 34802 값으로 billing-code 라벨을 필터링하려면 다음 명령어를 실행하면 됩니다.

gcloud beta sql instances list --filter='labels.billing-code:34802'

값에 관계없이 라벨 존재 여부에 따라 필터링하려면 다음 명령어를 실행합니다.

gcloud beta sql instances list --filter='labels:billing-code'

gcloud CLI의 필터 구문에 대한 자세한 내용은 gcloud topic filters 문서를 참조하세요.

curl

API에서 URL이 인코딩된 filter 쿼리 매개변수를 사용하여 목록 요청을 수행합니다.

gcloud auth login
ACCESS_TOKEN="$(gcloud auth print-access-token)"
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.[KEY1_NAME]:[KEY1_VALUE]%20userLabels.[KEY2_NAME]:[KEY2_VALUE]

예를 들면 다음과 같습니다.

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20userLabels.billing-code:34802

두 라벨 값 사이에 인코딩된 공백이 포함된 경우 두 값 모두 참이어야 인스턴스가 반환됩니다(AND 연산). AND, OR, NOT 연산자를 명시적으로 지정할 수도 있습니다. 예를 들면 다음과 같습니다.

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     -X GET \
     https://www.googleapis.com/sql/v1beta4/projects/[PROJECT_ID]/instances/list?filter=userLabels.track:production%20OR%20userLabels.billing-code:34802

다음 단계

• BigQuery로 청구 데이터 내보내기 알아보기
• gcloud 도구를 사용한 필터링 알아보기