Impostare le variabili di ambiente di compilazione (deployment dell'origine)
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Le variabili di ambiente di build sono coppie chiave-valore che ti consentono di passare le informazioni di configurazione ai buildpack durante il deployment dal codice sorgente. Ad esempio, in fase di compilazione, potresti voler personalizzare le opzioni del compilatore, specificare i certificati di compilazione, configurare i parametri e così via.
Questa pagina mostra come impostare le variabili di ambiente di compilazione disponibili al momento della compilazione ed è pertinente per gli sviluppatori di piattaforme che eseguono il deployment di servizi o funzioni Cloud Run dal codice sorgente. I flag dell'interfaccia a riga di comando gcloud CLI per le variabili dell'ambiente di compilazione sono supportati per i deployment di origine (--source) e non per i deployment di immagini contenitore (--image).
Puoi utilizzare le variabili di ambiente per la configurazione di servizi o funzioni, ma non
le consigliamo come metodo per archiviare secret come credenziali di database o chiavi API.
Memorizza i valori sensibili al di fuori del codice sorgente e delle variabili di ambiente. Per
archiviare i secret, ti consigliamo di utilizzare Secret Manager.
Per configurare i servizi che accedono ai secret archiviati in Secret Manager, consulta Configurare i secret.
Prima di iniziare
Abilita l'API Cloud Run Admin e l'API Cloud Build:
Dopo aver attivato l'API Cloud Run Admin, l'account di servizio predefinito di Compute Engine viene creato automaticamente.
Ruoli obbligatori
Tu o il tuo amministratore dovete concedere all'account di deployment e all'account di servizio Cloud Build i seguenti ruoli IAM.
Fai clic per visualizzare i ruoli richiesti per l'account di deployment
Per ottenere le autorizzazioni necessarie per compilare ed eseguire il deployment dal codice sorgente,
chiedi all'amministratore di concederti i seguenti ruoli IAM:
Fai clic per visualizzare i ruoli richiesti per l'account di servizio Cloud Build
Cloud Build utilizza automaticamente l'account di servizio predefinito di Compute Engine come account di servizio Cloud Build predefinito per compilare il codice sorgente e la risorsa Cloud Run, a meno che tu non sostituisca questo comportamento. Affinché Cloud Build possa compilare le origini, chiedi all'amministratore di concedere il ruolo Cloud Run Builder (roles/run.builder) all'account di servizio predefinito di Compute Engine nel tuo progetto:
Sostituisci PROJECT_NUMBER con il numero Google Cloud
del progetto e PROJECT_ID con l'ID Google Cloud
del progetto. Per istruzioni dettagliate su come trovare l'ID progetto e il numero del progetto, consulta Creazione e gestione dei progetti.
La propagazione del ruolo del compilatore Cloud Run all'account di servizio predefinito di Compute Engine richiede un paio di minuti.
Numero massimo di variabili di ambiente di build e limiti
Puoi definire fino a 100 variabili di ambiente di compilazione, con un limite totale di 64 KiB per chiavi e valori.
Imposta le variabili di ambiente di compilazione
Puoi impostare le variabili di ambiente di compilazione per stabilire nuove variabili o sostituire completamente quelle esistenti.
gcloud
Per impostare le variabili di ambiente di compilazione durante il deployment di un servizio dal codice sorgente, utilizza il flag --set-build-env-vars:
KEY1=VALUE1,KEY2=VALUE2 con l'elenco separato da virgole di nomi di variabili e relativi valori di cui viene eseguito il deployment insieme a una funzione che consente di passare le informazioni di configurazione ai buildpack.
Se stai eseguendo il deployment di una funzione, aggiungi il flag --function con il punto di ingresso della funzione dal codice sorgente.
Aggiorna le variabili di ambiente di build
Puoi aggiornare le variabili di ambiente di compilazione per i servizi esistenti. Si tratta di un approccio non distruttivo che modifica o aggiunge le variabili di ambiente di compilazione, ma non le elimina.
gcloud
Per aggiornare le variabili di ambiente di compilazione per i servizi esistenti, utilizza il flag --update-build-env-vars:
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-04 UTC."],[],[],null,["# Set build environment variables (source deploy)\n\nBuild environment variables are key-value pairs that let you pass configuration\ninformation to [buildpacks](/docs/buildpacks/overview) when deploying\nfrom source code. For example, at build time, you might want to customize\ncompiler options, specify build-time certificates, configure parameters, and so\nforth.\n\nThis page shows how to set build environment variables that are available at\nbuild time, and is relevant for platform developers who are deploying\nCloud Run [services](/run/docs/deploying-source-code) or\n[functions](/run/docs/deploy-functions) from source. The build environment\nvariable gcloud CLI flags are supported for\n[source deployments](/run/docs/deploying-source-code) (`--source`), and not\nsupported for [container image deployments](/run/docs/deploying) (`--image`).\n\nYou can use environment variables for service or function configuration, but we don't\nrecommend them as a way to store secrets such as database credentials or API keys.\nStore sensitive values outside both your source code and environment variables. To\nstore secrets, we recommend using Secret Manager.\nTo configure services that access secrets stored in Secret Manager,\nsee [Configure secrets](/run/docs/configuring/secrets).\n\nBefore you begin\n----------------\n\n- Enable the Cloud Run Admin API and the Cloud Build API:\n\n ```bash\n gcloud services enable run.googleapis.com \\\n cloudbuild.googleapis.com\n ```\n\n After the Cloud Run Admin API is enabled, the Compute Engine default service account is\n automatically created.\n\n### Required roles\n\nYou or your administrator must grant the deployer account and the\nCloud Build service account the following IAM roles. \n\n#### Click to view required roles for the deployer account\n\nTo get the permissions that you need to build and deploy from source,\nask your administrator to grant you the following IAM\nroles:\n\n- [Cloud Run Source Developer](/iam/docs/understanding-roles#run.sourceDeveloper) (`roles/run.sourceDeveloper`) on your project\n- [Service Usage Consumer](/iam/docs/understanding-roles#serviceusage.serviceUsageConsumer) (`roles/serviceusage.serviceUsageConsumer`) on your project\n- [Service Account User](/iam/docs/understanding-roles#iam.serviceAccountUser) (`roles/iam.serviceAccountUser`) on the Cloud Run service identity \n\n#### Click to view required roles for the Cloud Build service account\n\nCloud Build automatically uses the\n[Compute Engine default service\naccount](/build/docs/cloud-build-service-account) as the default Cloud Build service account to build your source code and\nCloud Run resource, unless you override this behavior. For\nCloud Build to build your sources, ask your administrator to grant\n[Cloud Run Builder](/iam/docs/understanding-roles#run.builder)\n(`roles/run.builder`) to the Compute Engine default\nservice account on your project: \n\n```bash\n gcloud projects add-iam-policy-binding PROJECT_ID \\\n --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \\\n --role=roles/run.builder\n \n```\n\nReplace \u003cvar translate=\"no\"\u003ePROJECT_NUMBER\u003c/var\u003e with your Google Cloud\nproject number, and \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e with your Google Cloud\nproject ID. For detailed instructions on how to find your project ID, and project number,\nsee [Creating\nand managing projects](/resource-manager/docs/creating-managing-projects#identifying_projects).\n\nGranting the Cloud Run builder role to the Compute Engine default service account\ntakes a couple of minutes to [propagate](/iam/docs/access-change-propagation).\n| **Note:**\n|\n|\n| The [`iam.automaticIamGrantsForDefaultServiceAccounts` organization policy constraint](/resource-manager/docs/organization-policy/restricting-service-accounts#disable_service_account_default_grants)\n| prevents the Editor role from being automatically granted to default service accounts. If you\n| created your organization after May 3, 2024, this constraint is enforced by\n| default.\n|\n|\n| We strongly recommend that you enforce this constraint to disable the automatic role grant. If you\n| disable the automatic role grant, you must decide which roles to grant to the default service\n| accounts, and then [grant these roles](/iam/docs/granting-changing-revoking-access)\n| yourself.\n|\n|\n| If the default service account already has the Editor role, we recommend that you replace the\n| Editor role with less permissive roles.To safely modify the service account's roles, use [Policy Simulator](/policy-intelligence/docs/simulate-iam-policies) to see the impact of\n| the change, and then [grant and revoke the\n| appropriate roles](/iam/docs/granting-changing-revoking-access).\n\nFor a list of IAM roles and permissions that are associated with\nCloud Run, see\n[Cloud Run IAM roles](/run/docs/reference/iam/roles)\nand [Cloud Run IAM permissions](/run/docs/reference/iam/permissions).\nIf your Cloud Run service interfaces with\nGoogle Cloud APIs, such as Cloud Client Libraries, see the\n[service identity configuration guide](/run/docs/configuring/services/service-identity).\nFor more information about granting roles, see\n[deployment permissions](/run/docs/reference/iam/roles#additional-configuration)\nand [manage access](/iam/docs/granting-changing-revoking-access).\n\nMaximum number of build environment variables and limits\n--------------------------------------------------------\n\nYou can define up to 100 build environment\nvariables, with a total key and value limit of 64 KiB.\n\nSet build environment variables\n-------------------------------\n\nYou can set build environment variables to establish new variables or completely\nreplace existing build variables.\n**Note:** Keys must start with an uppercase ASCII letter, and consist of uppercase ASCII letters, digits, and underscores. You should avoid creating variable keys with a `GOOGLE_*` prefix. [View all supported buildpacks environment variables](/docs/buildpacks/service-specific-configs). \n\n### gcloud\n\nTo set build environment variables when deploying a service from\nsource code, use the `--set-build-env-vars` flag: \n\n```bash\ngcloud run deploy SERVICE \\\n --source . \\\n --set-build-env-vars KEY1=VALUE1,KEY2=VALUE2\n```\n\nReplace:\n\n- \u003cvar translate=\"no\"\u003eSERVICE\u003c/var\u003e with name of your Cloud Run service.\n- \u003cvar translate=\"no\"\u003eKEY1=VALUE1,KEY2=VALUE2\u003c/var\u003e with the comma-separated list of variable names and their values that are deployed alongside a function that let you pass configuration information to buildpacks.\n\nIf you are deploying a function, add the `--function` flag with the function\nentry point from your source code.\n\nUpdate build environment variables\n----------------------------------\n\nYou can update build environment variables for existing services. This is a\nnon-destructive approach that changes or adds build environment variables, but\ndoes not delete the build environment variables. \n\n### gcloud\n\nTo update build environment variables for existing services, use the\n`--update-build-env-vars` flag: \n\n```bash\ngcloud run deploy SERVICE \\\n --source . \\\n --update-build-env-vars KEY1=VALUE1,KEY2=VALUE2\n```\n\nIf you are deploying a function, add the `--function` flag with the function\nentry point from your source code.\n\nDelete build environment variables\n----------------------------------\n\nYou can delete build environment variables for existing services. \n\n### gcloud\n\nTo remove build environment variables for existing services, use the\n`--remove-build-env-vars` flag: \n\n```bash\ngcloud run deploy SERVICE \\\n --source . \\\n --remove-build-env-vars KEY1=VALUE1,KEY2=VALUE2\n```\n\nAlternatively, you can clear build environment variables by using the\n`--clear-build-env-vars` for existing services: \n\n```bash\ngcloud run deploy SERVICE \\\n --source . \\\n --clear-build-env-vars KEY1=VALUE1,KEY2=VALUE2\n```\n\nIf you are deploying a function, add the `--function` flag with the function\nentry point from your source code.\n\nUse a build environment variables file\n--------------------------------------\n\nYou can use a build environment variables file for existing functions. \n\n### gcloud\n\nTo set build environment variables from a file, use the\n`--build-env-vars-file` flag: \n\n```bash\ngcloud run deploy SERVICE \\\n --source . \\\n --build-env-vars-file FILE_NAME.yaml\n```\n\nReplace \u003cvar translate=\"no\"\u003eFILE_NAME\u003c/var\u003e.yaml where the contents of the file, which\nshould look as follows: \n\n KEY1: VALUE1\n KEY2: VALUE2\n\nIf you are deploying a function, add the `--function` flag with the function\nentry point from your source code."]]
