Uma conta de serviço é um tipo especial de conta do Google Cloud que permite que os componentes
e os aplicativos de um sistema interajam entre si e com outras APIs. Para mais informações
sobre o Google Cloud, consulte Sobre os serviços do Google Cloud.
O híbrido usa contas de serviço do Google Cloud para realizar várias tarefas, como:
Enviar dados de registros e métricas
Solicitações de rastreamento de pull
Conectar-se ao gateway da API para solicitações administrativas de API
Executar backups
Fazer o download de pacotes proxy
Ainda que uma conta de serviço possa executar todas essas operações para ambientes de produção, a Apigee recomenda que
você crie várias contas de serviço, cada uma atribuída a uma tarefa específica e cada uma com o próprio
conjunto de permissões. Isso reforça a segurança ao compartimentar o acesso e limitar o escopo e
os privilégios de acesso de cada conta de serviço. Assim como
acontece com as contas de usuário, essas permissões são aplicadas
atribuindo um ou mais papéis à conta de serviço.
Contas de serviço e papéis usados por componentes híbridos
Para operar corretamente, a Apigee híbrida exige que você crie várias contas de serviço. Cada
conta de serviço requer um ou mais papéis específicos que permitam que ela execute a respectiva função.
A tabela a seguir descreve as contas de serviço dos componentes híbridos. Os nomes fornecidos para
cada conta de serviço são os nomes padrão. Use os nomes que quiser, mas eles são fáceis de identificar de
acordo com a finalidade de cada conta.
Componente*
Papel
Necessário para instalação básica?
Descrição
apigee-cassandra
Administrador de objetos do Storage roles/storage.objectAdmin
Permite backups do Cassandra para o Cloud Storage, conforme
descrito em Backup e recuperação.
apigee-logger
Gravador de registros roles/logging.logWriter
Permite a coleta de dados de geração de registros, conforme descrito em Geração de registros. Obrigatório apenas para instalações de cluster
que não são do GKE.
apigee-mart
Agente do Apigee Connect roles/apigeeconnect.Agent
Permite a autenticação do serviço MART. O papel de Agente do Apigee Connect permite a comunicação
com segurança com o processo do Apigee Connect, conforme descrito em Como
usar o Apigee Connect.
apigee-metrics
Gravador de métricas do Monitoring roles/monitoring.metricWriter
Permite que o ambiente de execução híbrido da Apigee se conecte a serviços do Google e serviços personalizados no
Google Cloud, como Google Authentication, Google Cloud Trace
e Jaeger.
apigee-synchronizer
Gerenciador de sincronização da Apigee roles/apigee.synchronizerManager
Permite que o sincronizador faça o download de pacotes de proxy e dados de configuração
do ambiente. Ativa também a operação do recurso de rastreamento.
apigee-udca
Agente de análise da Apigee roles/apigee.analyticsAgent
Permite a transferência de dados de status de rastreamento, análise e implantação para o plano de
gerenciamento.
apigee-watcher
Agente do ambiente de execução da Apigee roles/apigee.runtimeAgent
O Apigee Watcher extrai alterações virtuais dos hosts relacionados a uma organização no sincronizador e faz as
alterações necessárias para configurar a entrada istio.
* Esse nome é usado no nome de arquivo da chave da conta
de serviço baixado.
Como alternativa, para ambientes de não produção, teste e demonstração, é possível usar uma única conta de
serviço com todos os papéis atribuídos a ela. Isso não é recomendado para ambientes de produção.
Componente*
Papel
Necessário para instalação básica?
Descrição
apigee-non-prod
Agente de análise da Apigee, agente da Apigee Connect,
administrador da organização da Apigee, agente de ambiente de execução da Apigee,
gerenciador de sincronização da Apigee, agente do Cloud Trace, gravador de registros,
gravador de métricas de monitoramento, administrador de objeto de armazenamento
Além de criar as contas de serviço listadas nesta tabela, você usará chaves privadas
de cada conta para gerar tokens de acesso e acessar as APIs Apigee. A
ferramenta create-service-account faz o download automático dos arquivos de chave para um diretório
na máquina local quando cria ou atualiza as contas de serviço.
Criar contas de serviço
Há várias maneiras de criar contas de serviço, incluindo:
A ferramenta create-service-account fica disponível depois que você
faz o download e expande os gráficos do Helm da Apigee
híbrida.
A ferramenta create-service-account está disponível no seguinte diretório:
create-service-account torna híbridas as contas de serviço específicas de componentes e atribui
os papéis necessários para você. A ferramenta também faz o download automático das chaves da conta de serviço e
as armazena na máquina local.
Por exemplo, o comando a seguir cria todas as contas de serviço individuais separadas de um
ambiente de produção, atribui os papéis apropriados do IAM a cada conta de serviço e faz o download
de cada arquivo de chave privada de contas para o diretório ./service-accounts:
./tools/create-service-account --env prod
O comando a seguir cria uma única conta de serviço chamada apigee-non-prod com todos os papéis
do IAM para todos os componentes
híbridos, adequada para ambientes de demonstração e teste, mas não para ambientes de produção:
No campo Nome da conta de serviço, insira um nome. O
Google Cloud console preenche o campo ID da conta de serviço com base nesse
nome.
A Apigee recomenda que você use um nome que reflita o papel da conta de serviço. É possível
definir o nome da conta de serviço como o mesmo nome do componente que o utiliza.
Por exemplo, defina o nome da conta de serviço do gravador de registros como apigee-logger.
Opcional: preencha o
campo Descrição da conta de serviço. As descrições são úteis para lembrar você sobre como uma conta de
serviço específica é usada.
Por exemplo, para o componente de geração de registros, selecione o papel de gravador de registros.
Se necessário, insira o texto para filtrar a lista de papéis por nome. Por exemplo, para listar somente
os papéis da Apigee, insira Apigee no campo de filtro.
É possível adicionar mais de um papel a uma conta de serviço, mas a Apigee recomenda o uso de apenas
um papel para cada uma das contas de serviço recomendadas. Para alterar os papéis de
uma conta de serviço depois de criá-la, use a página IAM
no Google Cloud console.
Clique em Continuar.
O Google Cloud exibe a visualização Conceder aos usuários acesso a essa conta de serviço:
Em Criar chave (opcional), clique em Criar chave.
O Google Cloud oferece a opção de fazer o download de uma chave JSON ou P12:
Selecione JSON (padrão) e clique em Criar.
O Google Cloud salva o arquivo de chave no formato JSON na sua máquina local e exibe uma confirmação quando
ela é bem-sucedida, como mostra o exemplo a seguir:
Posteriormente, você usará algumas das chaves da conta de serviço para configurar os serviços de ambiente de execução híbrido.
Por exemplo, ao configurar o ambiente de execução híbrido, você especifica o local das chaves
da conta de serviço usando as propriedades SERVICE_NAME.serviceAccountPath.
Essas chaves são usadas pelas contas de serviço para conseguir tokens de acesso, que
serão usados para fazer solicitações nas APIs Apigee em seu nome. Mas isso ainda vai demorar.
Por enquanto, lembre-se de onde você salvou.
Quando terminar, você deverá ter as seguintes contas de serviço (além das padrões,
se houver):
No console Google Cloud , as contas de serviço são indicadas com o
ícone .
Depois de criar uma conta de serviço, se você quiser adicionar ou remover um papel, use
a visualização IAM e administrador. Não é possível gerenciar papéis para contas de serviço na
visualização Contas de serviço.
Usar APIs de criação de conta de serviço da gcloud
É possível criar e gerenciar contas de serviço com a API Cloud Identity and Access Management.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-18 UTC."],[[["\u003cp\u003eGoogle Cloud service accounts are used by Apigee hybrid to perform various tasks, including sending logs and metrics, pulling trace requests, and connecting to the API gateway.\u003c/p\u003e\n"],["\u003cp\u003eFor enhanced security in production environments, Apigee recommends creating multiple service accounts, each dedicated to a specific task with its own set of permissions.\u003c/p\u003e\n"],["\u003cp\u003eApigee hybrid requires several service accounts for proper operation, with each account needing specific roles to perform its designated function, which can be found within the table.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003ecreate-service-account\u003c/code\u003e tool, included with Apigee hybrid Helm Charts, simplifies the process of creating service accounts, assigning roles, and downloading private keys, and is the recommended way to do so.\u003c/p\u003e\n"],["\u003cp\u003eA single service account with all necessary roles can be used for non-production environments, however this is not recommended for production environments.\u003c/p\u003e\n"]]],[],null,["# About service accounts\n\n| You are currently viewing version 1.14 of the Apigee hybrid documentation. For more information, see [Supported versions](/apigee/docs/hybrid/supported-platforms#supported-versions).\n\nA *service account* is a special type of account in Google Cloud that enables components\nand applications of a system to interact with each other and with other APIs. For more information\nabout Google Cloud, see [About Google Cloud services](/apigee/docs/hybrid/v1.14/what-is-hybrid#about-gcp).\n| **SERVICE ACCOUNT FACTOID** \n| Google Cloud projects have a limit of 100 service accounts---including the default service accounts (if any).\n\nApigee hybrid uses Google Cloud service accounts to perform a variety of tasks, including:\n\n- Send log and metrics data\n- Pull trace requests\n- Connect to API gateway for administrative API requests\n- Execute back ups\n- Download proxy bundles\n\nWhile one service account *could* perform all of these operations, for production\nenvironments Apigee recommends that you create multiple service accounts, each assigned to a\nspecific task and each with its own set of permissions. This enhances security by\ncompartmentalizing access and limiting each service account's scope and access privileges. As with\nuser accounts, these permissions are applied by assigning one or more roles to the service\naccount.\n\nService accounts and roles used by hybrid components\n----------------------------------------------------\n\nTo operate properly, Apigee hybrid requires you to create several service accounts. Each\nservice account requires a specific role or roles that enable it to perform its function.\n\nThe following table describes the service accounts for the hybrid components. The names given for\neach service account are the default names. You can use any names you want, but the names should be\neasy to identify with each account's purpose.\n\n\nAs an alternative, for nonproduction, test, and demo environments, you can use a single service\naccount with all the roles assigned to it. This is not recommended for production environments.\n\nIn addition to creating the service accounts listed in this table, you will use each accounts\nprivate keys to generate access tokens so that you can access the Apigee APIs. The\n`create-service-account` tool automatically downloads the key files into a directory\non your local machine when it creates or updates the service accounts.\n\nCreate the service accounts\n---------------------------\n\n| **Deleting and recreating service accounts:** Note that reusing the name of a deleted service account may result in unexpected behavior. If you create a service account and delete it, always recreate it with a unique name. For details, see [Deleting and recreating service accounts](/iam/docs/service-account-overview#deleting-recreating).\n\nThere are several ways to create service accounts, including:\n\n- (*Recommended* ) [`create-service-account` tool](#tool)\n- [Google Cloud console](#gcp)\n- [gcloud SDK](#gcloud)\n\nEach of these is described in the following sections.\n\n### Use the `create-service-account` tool\n\nThe `create-service-account` tool is available after you\ndownload and expand the [Apigee hybrid Helm\nCharts](/apigee/docs/hybrid/v1.14/install-download-charts).\nYou can find the `create-service-account` tool in the following directory: \n\n```\nAPIGEE_HELM_CHARTS_HOME/\n└── apigee-operator/\n └── etc/\n └── tools/\n └── create-service-account\n```\n\n`create-service-account` creates hybrid component-specific service accounts\nand assigns the required roles for you. The tool also automatically downloads the service account\nkeys and stores them on your local machine.\n\nFor example, the following command will create all the separate individual service accounts for a\nproduction environment, assign the appropriate IAM roles to each service account, and download\neach account's private key file to the `./service-accounts` directory: \n\n```\n./tools/create-service-account --env prod\n```\n\n\nThe following command creates a single service account named `apigee-non-prod` with all IAM\nroles for all hybrid components,\nsuitable for demo and test environments, but not for production environments: \n\n```\n./tools/create-service-account --env non-prod\n```\n\nFor more information on using `create-service-account`, see\n[create-service-account reference](/apigee/docs/hybrid/v1.14/create-service-account).\n\n### Use the Google Cloud console\n\nYou can create service accounts with the Google Cloud console.\n| **Note:** To create service accounts in the Google Cloud console, you must have the Google Cloud Service Account Admin role or greater.\n\n**To create a service account with the Google Cloud console and generate a key for the\nservice account, do the following:**\n\n1. Create a service account:\n\n 1. In the Google Cloud console, go to the **Service Accounts** page.\n\n [Go to\n Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)\n 2. Select your project.\n 3. Click add**Create Service Account**.\n 4.\n In the **Service account name** field, enter a name. The\n Google Cloud console fills in the **Service account ID** field based on\n this name.\n\n\n Apigee recommends that you use a name that reflects the service account's role; you\n can set the name of the service account to be the same name as the component that uses it.\n For example, set the name of the Logs Writer service account `apigee-logger`.\n\n\n For more information about the service accounts names and roles, see\n [Service accounts and roles used by hybrid components](#recommended-sas).\n 5. Optional: In the **Service account description** field, enter a description for the service account. Descriptions are helpful at reminding you what a particular service account is used for.\n 6. Click **Create and continue**.\n 7.\n Click the **Select a role** field and select a role, as described in\n [Service accounts and roles used by hybrid components](#recommended-sas). If\n the Apigee roles do not appear in the drop down list, refresh the page.\n\n For example, for the logging component, select the Logs Writer role.\n\n\n If necessary, enter text to filter the list of roles by name. For example, to list only\n the Apigee roles, enter `Apigee` in the filter field.\n\n\n You can add more than one role to a service account, but Apigee recommends using only\n one role for each of the recommended service accounts. To change the roles of\n a service account after you have created it, use the **IAM**\n page in the Google Cloud console.\n | **Note:** If you do not see the roles listed in [Recommended service accounts](#recommended-sas), check with your Apigee account representative to be sure that your account was properly configured and that your organization was provisioned.\n 8. Click **Continue** .\n\n Google Cloud displays the **Grant users access to this service account** view:\n\n 9. Under **Create key (optional)** , click **Create Key** .\n\n Google Cloud gives you the option to download a JSON or P12 key:\n\n 10. Select JSON (the default) and click **Create** .\n\n Google Cloud saves the key file in JSON format to your local machine and displays a confirmation when\n it is successful, as the following example shows:\n\n You will later use some of the service account keys to configure hybrid runtime services.\n For example, when you configure the hybrid runtime, you will specify the location of the service\n account keys using the \u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e`.serviceAccountPath` properties.\n\n These keys are used by the service accounts to get access tokens, which the service account\n then uses to make requests against the Apigee APIs on your behalf. (But that's not for a while\n yet; for now, just remember where you saved it.)\n 11. Repeat steps 4 through 11 for each service account listed in [Service accounts and roles used by hybrid components](#recommended-sas) (except the `apigee-mart` account---which has no role associated with it---so do not assign it a role).\n\n When you're finished, you should have the following service accounts (in addition to the\n defaults, if any):\n\n\n In the Google Cloud console, service accounts are indicated with the\n icon.\n\n After you create a service account, if you want to add or remove a role to it, you must use\n the **IAM \\& Admin** view. You cannot manage roles for service accounts in the\n **Service accounts** view.\n | **Tip:** Apigee hybrid includes a validator that checks your service accounts' key files and permissions when you apply any configuration changes to the Apigee hybrid runtime components to your cluster. This validation is enabled by default. For more information, see [Service account validation](/apigee/docs/hybrid/v1.14/sa-validation).\n\n ### Use the gcloud service account creation APIs\n\n You can create and manage service accounts with the Cloud Identity and Access Management API.\n\n For more information, see\n [Creating\n and managing service accounts](/iam/docs/creating-managing-service-accounts).\n\n Troubleshooting\n ---------------\n\n | **Deleting and recreating service accounts:** Note that reusing the name of a deleted service account, may cause unexpected behavior. If you create a service account and delete it, always recreate it with a unique name. For details, see [Deleting and recreating service accounts](/iam/docs/service-account-overview#deleting-recreating)."]]
.