일부 서드 파티 통합을 구성하려면 운영 에이전트 측정항목 수신기에 비밀번호와 같은 보안 비밀을 제공해야 합니다. 기본적으로 이러한 보안 비밀은 에이전트의 config.yaml 파일에 일반 텍스트로 저장됩니다. 이러한 비밀은 에이전트가 작성한 시스템 로그에 포함되어 Cloud Logging으로 전송되므로 운영 에이전트가 실행 중인 가상 머신(VM) 외부에 보안 비밀이 노출됩니다.
운영 에이전트 버전 2.57.0부터는 OpenTelemetry 공급자 통합 Secret Manager를 사용하여 구성 파일에서 일반 텍스트 보안 비밀을 삭제할 수 있습니다.
제공자는 수신자 및 프로세서 구성요소와 유사한 OpenTelemetry 구성 구성요소입니다. 각 제공자에는 유형이 있으며 각 유형의 제공자는 구성의 특정 식별자를 값에 매핑합니다.
googlesecretmanager 제공자는 Secret Manager 식별자를 Secret Manager에 저장한 비밀번호, 토큰, API 키와 같은 보안 비밀에 매핑합니다. googlesecretmanager 제공자를 사용하면 다음과 같은 이점이 있습니다.
보안 강화: 구성 파일에 비밀번호와 같은 민감한 정보가 포함되지 않습니다. 실제 보안 비밀은 민감한 정보를 안전하게 저장, 액세스, 관리하기 위해 특별히 설계된 서비스인 Secret Manager에 저장됩니다.
노출 위험 감소: 운영 에이전트 초기화 중에 Secret Manager가 보안 비밀을 가져오므로 로그에 일반 텍스트 보안 비밀이 실수로 기록되는 것을 방지할 수 있습니다.
googlesecretmanager는 커스텀 운영 에이전트 구성의 측정항목 수집 구성에서만 사용할 수 있습니다. 로깅 구성에서 보안 비밀을 대체하는 데 공급자를 사용하지 마세요.
시작하기 전에
googlesecretmanager 제공자를 사용하려면 다음 단계에 설명된 대로 Secret Manager API를 사용 설정하고 API에 대한 액세스를 허용해야 합니다.
After installing the Google Cloud CLI,
initialize it by running the following command:
[[["이해하기 쉬움","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-08-01(UTC)"],[],[],null,["# Manage secrets in Ops Agent metric configuration\n\nConfiguring some of the third-party integrations requires you to\nprovide secrets, such as passwords, for the Ops Agent metric\nreceivers. By default, these secrets are stored as plaintext in the agent's\n`config.yaml` file. These secrets are included in system logs\nwritten by the agent and transmitted to Cloud Logging, exposing\nthe secrets beyond the virtual machine (VM) where the Ops Agent is\nrunning.\n\nStarting with Ops Agent version 2.57.0,\nyou can use an OpenTelemetry provider integrated [Secret Manager](/secret-manager/docs/overview) to eliminate\nplaintext secrets in your configuration files.\n\nA *provider* is an OpenTelemetry configuration component,\nanalogous to the receiver and processor components. Each provider has a\ntype, and each type of provider maps a specific identifier in the\nconfiguration to a value.\n\nThe `googlesecretmanager` provider maps Secret Manager\nidentifiers to the secrets, like passwords, tokens, and API keys, that you've\nstored in Secret Manager. Using the\n`googlesecretmanager` provider offers the following benefits:\n\n- **Enhanced security** : Your configuration files don't contain sensitive information like passwords. The actual secrets are stored in [Secret Manager](/secret-manager/docs/overview), a service designed specifically for securely storing, accessing, and managing sensitive data.\n- **Reduced risk of exposure**: Secret Manager fetches secrets during initialization of the Ops Agent, which prevents plaintext secrets from accidentally being recorded in logs.\n\nYou can use the `googlesecretmanager` only in the configuration of\nmetric collection in custom Ops Agent configurations. Don't use the provider to\nreplace secrets in the configuration of log collection.\n\nBefore you begin\n----------------\n\nTo use the `googlesecretmanager` provider, you must enable the\nSecret Manager API and permit access to the API,\nas described in the following steps:\n\n1.\n [Install](/sdk/docs/install) the Google Cloud CLI.\n\n After installation,\n [initialize](/sdk/docs/initializing) the Google Cloud CLI by running the following command:\n\n ```bash\n gcloud init\n ```\n\n\n If you're using an external identity provider (IdP), you must first\n [sign in to the gcloud CLI with your federated identity](/iam/docs/workforce-log-in-gcloud).\n2. Set the default project for Google Cloud CLI:\n\n ```\n gcloud config set project PROJECT_ID\n ```\n\n Before you run the previous command, replace the \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e\n variable with the identifier of your Google Cloud project.\n3.\n\n\n Enable the Secret Manager API:\n\n\n ```bash\n gcloud services enable secretmanager.googleapis.com\n ```\n4. Update the OAuth access scopes for your instance to include the required scope for Secret Manager, `https://www.googleapis.com/auth/cloud-platform`: \n\n ```\n gcloud compute instances set-service-account \"INSTANCE_ID\" \\\n --service-account \"SERVICE_ACCT_EMAIL\" \\\n --scopes \"https://www.googleapis.com/auth/cloud-platform\"\n ```\n\n Before you run the previous command, replace the following variables:\n - \u003cvar translate=\"no\"\u003eINSTANCE_ID\u003c/var\u003e: the identifier of your VM.\n - \u003cvar translate=\"no\"\u003eSERVICE_ACCT_EMAIL\u003c/var\u003e: the address of the service account associated with the VM.\n\n For more information, see\n [Access the Secret Manager API](/stackdriver/docs/solutions/agents/ops-agent/third-party/secret-manager/docs/accessing-the-api).\n5. Grant the user who manages the Ops Agent configurations the permissions needed to create and manage secrets. The Identity and Access Management role `roles/secretManager.secretAdmin` includes the necessary permissions: \n\n ```\n gcloud projects add-iam-policy-binding PROJECT_ID \\\n --member=\"user:USER_EMAIL\" \\\n --role=roles/secretManager.secretAdmin\n ```\n\n Before you run the previous command, replace the following variables:\n - \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the identifier of your Google Cloud project.\n - \u003cvar translate=\"no\"\u003eUSER_EMAIL\u003c/var\u003e: the address of the user being granted the role.\n6. Grant the service account associated with the VM the permissions it needs to access the secrets. The Identity and Access Management role `roles/secretManager.secretAccessor` includes the necessary permissions: \n\n ```\n gcloud projects add-iam-policy-binding PROJECT_ID \\\n --member=\"serviceAccount:SERVICE_ACCT_EMAIL\" \\\n --role=roles/secretManager.secretAccessor\n ```\n\n Before you run the previous command, replace the following variables:\n - \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the identifier of your Google Cloud project.\n - \u003cvar translate=\"no\"\u003eSERVICE_ACCT_EMAIL\u003c/var\u003e: the address of the service account associated with the VM.\n\nReplace plaintext secrets with managed secrets\n----------------------------------------------\n\nTo eliminate the use of plaintext secrets in your configuration files by\nusing Secret Manager and the `googlesecretmanager`\nprovider, do the following:\n\n1. Create a secret in Secret Manager for each plaintext secret in your configuration files.\n2. Replace each plaintext secret in your configuration files with a reference to the corresponding secret in Secret Manager.\n\nFor example, if you are using a `mysql` metric receiver, then\nyour configuration file might include an entry like the following: \n\n```\nreceivers:\n mysql:\n type: mysql\n username: root\n password: plaintext-secret\n```\n\nIn this example, you want to place the \u003cvar translate=\"no\"\u003eplaintext-secret\u003c/var\u003e\nstring into Secret Manager and then replace\nthe plaintext secret with a reference to the managed secret.\n\n### Create Secret Manager secrets\nfor plaintext secrets\n\nTo create a Secret Manager secret containing the plaintext secret `plaintext-secret`, run the following command: \n\n```\necho -n \"plaintext-secret\" | gcloud secrets create SECRET_NAME \\\n --replication-policy=\"automatic\" \\\n --data-file=-\n```\n\nBefore you run the previous command, replace the following variables:\n\n- \u003cvar translate=\"no\"\u003eplaintext-secret\u003c/var\u003e: Replace with your plaintext secret.\n- \u003cvar translate=\"no\"\u003eSECRET_NAME\u003c/var\u003e: Replace with a meaningful name for your secret.\n\nThe fully qualified resource name of your new secret has the following\nformat, with a \u003cvar translate=\"no\"\u003eVERSION\u003c/var\u003e of `1`: \n\n```\nprojects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION\n```\n\nFor more information about storing, versioning, and accessing secrets in\nSecret Manager, see\n[Create a secret](/secret-manager/docs/creating-and-accessing-secrets).\n\n### Replace plaintext secrets\n\nTo update your configuration files, replace each plaintext secret\nwith a reference to the `googlesecretmanager` provider and the resource\nname of the managed secret, as shown in the following example: \n\n```\nreceivers:\n mysql:\n type: mysql\n username: root\n password: ${googlesecretmanager:projects/PROJECT_ID/secrets/SECRET_NAME/versions/VERSION}\n```\n\n### Restart the Ops Agent\n\n### Linux\n\n1. To restart the agent, run the following command on your instance: \n\n ```\n sudo systemctl restart google-cloud-ops-agent\n ```\n2. To confirm that the agent restarted, run the following command and verify that the components \"Metrics Agent\" and \"Logging Agent\" started: \n\n ```\n sudo systemctl status \"google-cloud-ops-agent*\"\n ```\n\n### Windows\n\n1. Connect to your instance using RDP or a similar tool and login to Windows.\n2. Open a PowerShell terminal with administrator privileges by right-clicking the PowerShell icon and selecting **Run as Administrator**\n3. To restart the agent, run the following PowerShell command: \n\n ```\n Restart-Service google-cloud-ops-agent -Force\n ```\n4. To confirm that the agent restarted, run the following command and verify that the components \"Metrics Agent\" and \"Logging Agent\" started: \n\n ```\n Get-Service google-cloud-ops-agent*\n ```"]]
