Criar uma instância do Private Service Connect

Nesta página, descrevemos como criar uma instância do Private Service Connect para o Secure Source Manager.

As instâncias do Private Service Connect não expõem endpoints à Internet pública. Quando você cria uma instância do Private Service Connect, endpoints são criados para fornecer acesso SSH (Git) e HTTPS (Git, interface da Web, API) à instância. Os endpoints precisam ter endereços IP atribuídos na sua rede privada. Todo o tráfego de e para a instância do Private Service Connect passa pelos endpoints do Private Service Connect.

Para mais informações sobre como usar o Private Service Connect para acessar serviços gerenciados de maneira privada em uma rede VPC, consulte Private Service Connect.

O Secure Source Manager é um serviço de locatário único. Uma única instância do Secure Source Manager só deve incluir usuários de um cliente doGoogle Cloud , a menos que várias empresas com uma relação contratual precisem usar uma única instância para colaboração.

Se você trabalha com várias empresas e quer colaborar com elas no código-fonte, recomendamos criar uma instância separada para cada uma.

Antes de começar

Faça login na sua Conta do Google.

Se você ainda não tiver uma, inscreva-se agora.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Secure Source Manager API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud anteriormente, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Enable the Secure Source Manager API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud anteriormente, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Funções exigidas

Para receber as permissões necessárias para criar uma instância do Secure Source Manager do Private Service Connect, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Papel de administrador do Access Context Manager (roles/accesscontextmanager.policyAdmin) na organização
• Papel de proprietário da instância (roles/securesourcemanager.instanceOwner) na instância
• Para criar uma identidade de serviço e um pool de autoridade de certificação: Gerente de operações do serviço de AC (roles/privateca.caManager) na organização

Criar uma identidade de serviço e um pool de autoridade certificadora

Esta seção descreve como usar seu próprio certificado de CA. Você precisa usar seu próprio certificado de CA se quiser usar domínios personalizados com sua instância particular. Para usar um certificado gerenciado por Googlesem domínios personalizados, basta executar o gcloud source-manager instances create comando sem criar uma identidade de serviço e um pool de CA. Para mais informações, consulte Criar uma instância do Secure Source Manager do Private Service Connect.

Se você estiver usando seu próprio certificado de CA, especifique um nome de pool de autoridade de certificação (CA) ao criar uma instância particular do Secure Source Manager. Uma solicitação para assinar o certificado SSL HTTPS da instância é enviada ao pool de ACs.

1. Execute o comando a seguir para criar uma identidade de serviço para a API Secure Source Manager no seu projeto:

   gcloud beta services identity create \
       --service=securesourcemanager.googleapis.com \
       --project=PROJECT_ID
   

   em que PROJECT_ID é o ID do projeto.

   O resultado será o seguinte:

   Service identity created: [e-mail]

   em que [e-mail] é o agente de serviço do Secure Source Manager e PROJECT_NUM é o número do seu projeto.

2. Crie um pool de autoridade certificadora (CA) com solicitações de certificado baseadas em CSR ativadas.

3. Crie uma CA. É possível criar uma AC raiz ou subordinada, dependendo das suas necessidades.

   Observação: ao usar sua própria autoridade certificadora, é necessário usar um tamanho de chave de 2.048 bits.
   • Para criar uma AC raiz, siga as instruções em Criar uma AC raiz.
   • Para criar uma AC subordinada de uma AC principal em Google Cloud, siga as instruções em Criar uma AC subordinada
   • Para criar uma AC subordinada de uma AC externa, siga as instruções em Criar uma AC subordinada de uma AC externa.

   Para mais informações sobre as diferenças entre ACs raiz e subordinadas, consulte Determinar configurações da autoridade certificadora.

4. Conceda à identidade de serviço da API Secure Source Manager permissões para solicitar novos certificados no pool de ACs:

   gcloud privateca pools add-iam-policy-binding CA_POOL_NAME \
       --location=CA_LOCATION \
       --member='serviceAccount:[e-mail]' \
       --role='roles/privateca.certificateRequester' \
       --project=CA_PROJECT_ID
   

   Substitua:

   • CA_POOL_NAME com o nome que você deu ao pool de ACs.
   • CA_LOCATION com a região ou zona do seu pool de CAs.
   • PROJECT_NUMBER com o número do projeto em que o Secure Source Manager está ativado. Para localizar o número do projeto, consulte Identificar projetos.
   • CA_PROJECT_ID com o ID do projeto em que você criou o pool de ACs.

Criar uma instância do Secure Source Manager do Private Service Connect

É possível atribuir domínios personalizados à sua instância particular para os endpoints HTML, API, Git HTTP e Git SSH. Os domínios personalizados exigem seu próprio certificado de CA. Portanto, é necessário fornecer um pool de ACs ao criar uma instância com domínios personalizados. Só é possível configurar domínios personalizados durante a criação da instância usando a API. Não é possível modificá-las depois que a instância é criada.

gcloud

Crie uma instância do Private Service Connect com o seguinte comando:

gcloud source-manager instances create INSTANCE_ID \
  --region=LOCATION \
  --project=PROJECT_ID \
  --is-private \
  --ca-pool=projects/CA_PROJECT/locations/CA_LOCATION/caPools/CA_POOL_NAME

Substitua:

• INSTANCE_ID com o nome que você quer dar à instância.
• LOCATION com a região em que você quer criar a instância. Para locais compatíveis, consulte Locais.
• PROJECT_ID com o nome do projeto em que você quer criar uma instância.
• CA_PROJECT com o nome do projeto do pool de CAs. Obrigatório se você usar seu próprio certificado de CA.
• CA_LOCATION com a região em que você criou o pool de ACs. Obrigatório se você usar seu próprio certificado de CA.
• CA_POOL_NAME com o nome do pool de ACs. Obrigatório se você usar seu próprio certificado de CA.

Observação: é possível omitir a flag --ca-pool se você usar um certificado gerenciado por Googlee não usar domínios personalizados. Só é possível configurar domínios personalizados usando a API.

API

Crie uma instância do Private Service Connect com o seguinte comando:

curl \
    -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://securesourcemanager.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?instance_id=INSTANCE_ID \
    -H "Content-Type: application/json" \
    -d '{"private_config":{"is_private":true,"ca_pool":"projects/CA_PROJECT/locations/CA_LOCATION/caPools/CA_POOL_NAME","custom_host_config":{"api":"API_CUSTOM_DOMAIN", "html":"HTML_CUSTOM_DOMAIN", "git_ssh":"GIT_SSH_CUSTOM_DOMAIN", "git_http":"GIT_HTTP_CUSTOM_DOMAIN"}}}'

Substitua:

• INSTANCE_ID com o nome que você quer dar à instância.
• LOCATION com a região em que você quer criar a instância. Para locais compatíveis, consulte Locais.
• PROJECT_ID com o nome do projeto em que você quer criar uma instância.
• CA_PROJECT com o nome do projeto do pool de CAs. Necessário se você usar seu próprio certificado de CA ou domínios personalizados.
• CA_LOCATION com a região em que você criou o pool de ACs. Necessário se você usar seu próprio certificado de CA ou domínios personalizados.
• CA_POOL_NAME com o nome do pool de ACs. Necessário se você usar seu próprio certificado de CA ou domínios personalizados.
• API_CUSTOM_DOMAIN com seu domínio personalizado para acesso à API, por exemplo, api.source.example.com. Obrigatório apenas se você usar domínios personalizados.
• HTML_CUSTOM_DOMAIN com seu domínio personalizado para acesso UI da Web, por exemplo, source.example.com. Obrigatório apenas se você usa domínios personalizados.
• GIT_SSH_CUSTOM_DOMAIN com seu domínio personalizado para acesso do Git SSH, por exemplo, ssh.source.example.com. Obrigatório apenas se você usa domínios personalizados.
• GIT_HTTP_CUSTOM_DOMAIN com seu domínio personalizado para acesso HTTP do Git, por exemplo, git.source.example.com. Obrigatório apenas se você usa domínios personalizados.

Observação: se você usa um certificado gerenciado pelo Google, remova o campo ca_pool deste comando. Se você não estiver usando domínios personalizados, remova o campo custom_host_config.

Terraform

Para criar uma instância do Private Service Connect com o Terraform, use o recurso google_secure_source_manager_instance com o campo private_config.is_private definido como true.

Uma operação de criação de instância de longa duração é iniciada. A criação da instância leva até 60 minutos. O resultado será o seguinte:

Create request issued for [my-instance].
done: false
metadata:
  '@type': type.googleapis.com/google.cloud.securesourcemanager.v1.OperationMetadata
  apiVersion: v1
  createTime: '2023-02-27T20:57:52.315609549Z'
  requestedCancellation: false
  target: projects/my-project/locations/us-central1/instances/my-instance
  verb: create
name: projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e

em que projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e é o OPERATION_NAME.

Você precisa do OPERATION_NAME para verificar o status da operação.

Para verificar o status da operação, execute o seguinte comando:

gcloud source-manager operations describe OPERATION_NAME \
    --region=LOCATION

Substitua:

• OPERATION_NAME com o nome da operação da resposta do comando create.
• LOCATION com a região em que você quer criar a instância. Para locais compatíveis, consulte Locais.

Depois que a instância for criada, os endpoints do Private Service Connect httpServiceAttachment e sshServiceAttachment, junto com os nomes de host para html, api, gitHttp e gitSsh, serão listados na saída.

Acessar a instância privada

É possível acessar sua instância do Private Service Connect criando endpoints do Private Service Connect com base em regras de encaminhamento ou back-ends do Private Service Connect com base em balanceadores de carga.

Os back-ends do Private Service Connect baseados em balanceadores de carga são mais flexíveis e permitem a integração com outros serviços do Google Cloud , como o Cloud Build, mas são mais complexos e têm faturamento adicional.

Os endpoints do Private Service Connect baseados em regras de encaminhamento são mais simples e custam menos. No entanto, não é possível se conectar ao Cloud Build ou a outros serviços doGoogle Cloud .

Para configurar back-ends do Private Service Connect com base em balanceadores de carga para sua instância do Private Service Connect e conectá-la ao Cloud Build, consulte Conectar o Cloud Build a uma instância do Private Service Connect.

Configurar endpoints do Private Service Connect com base em regras de encaminhamento

1. Para criar endpoints do Private Service Connect, siga as instruções em Acessar serviços publicados por meio de endpoints.

2. Para receber os URIs dos anexos de serviço HTTP e SSH da sua instância do Secure Source Manager, execute o seguinte comando:

   gcloud source-manager instances describe INSTANCE_ID \
       --region=LOCATION
   

   Substitua:

   • INSTANCE_ID com o nome da sua instância. Para listar instâncias em uma determinada região, execute gcloud source-manager instances list --region=LOCATION.
   • LOCATION com o local da sua instância. Para locais compatíveis, consulte Locais.

   A saída inclui:

   createTime: '2023-09-22T18:21:35.729454612Z'
   hostConfig:
     api: my-project-012345678901-api.us-central1.p.sourcemanager.dev
     gitHttp: my-project-012345678901-git.us-central1.p.sourcemanager.dev
     gitSsh: my-project-012345678901-ssh.us-central1.p.sourcemanager.dev
     html: my-project-012345678901.us-central1.p.sourcemanager.dev
   name: projects/my-project/locations/us-central1/instances/my-instance
   privateConfig:
     caPool: projects/my-project/locations/us-central1/caPools/my-ca-pool
     httpServiceAttachment: projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/http-psc
     isPrivate: true
     sshServiceAttachment: projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/ssh-psc
   state: ACTIVE
   updateTime: '2023-09-22T18:39:53.390563549Z'
   

   • projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/http-psc é o URI do anexo de serviço HTTP da sua instância.
   • projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/ssh-psc é o URI do anexo de serviço SSH da sua instância.

3. Depois de criar os endpoints do Private Service Connect, configure registros DNS particulares. Para instruções sobre como configurar registros DNS particulares, consulte Configurar o DNS manualmente. Se você configurou domínios personalizados para sua instância, crie registros DNS que mapeiem seus domínios personalizados para os endereços IP internos dos anexos de serviço. Caso contrário, use os nomes de host no campo hostConfig da instância:

   1. Mapeie o valor de hostConfig.html (ou seu domínio personalizado HTML), hostConfig.api (ou seu domínio personalizado da API) e hostConfig.gitHttp (ou seu domínio personalizado HTTP do Git) para o endereço IP interno da vinculação de serviço HTTP.
   2. Mapeie o valor de hostConfig.ssh (ou seu domínio personalizado do Git SSH) para o endereço IP interno do anexo de serviço SSH.

   Por exemplo, na saída do exemplo anterior, o valor de hostConfig.html é my-project-012345678901.us-central1.p.sourcemanager.dev.

   Observação: a zona de DNS Google Cloud e o Private Service Connect precisam estar na mesma rede de nuvem privada virtual.

Autenticação do Git com domínios personalizados

Se você usa domínios personalizados para sua instância particular, faça a seguinte configuração do lado do cliente em cada máquina para usar o Git por HTTPS. Essa configuração conecta o Git ao auxiliar de credenciais gcloud para autenticar seu domínio personalizado.

1. Configure o Git para usar o auxiliar gcloud no seu domínio HTTP personalizado do Git:

   git config --global credential.'https://GIT_HTTP_CUSTOM_DOMAIN'.helper gcloud.sh
   

   Substitua GIT_HTTP_CUSTOM_DOMAIN pelo domínio personalizado que você configurou para acesso HTTP do Git.

2. Autorize seu domínio personalizado em gcloud:

   gcloud config set core/credentialed_hosted_repo_domains GIT_HTTP_CUSTOM_DOMAIN
   

   Para autorizar vários domínios, forneça-os como uma lista separada por vírgulas.

Usar a CA com a API Secure Source Manager

Aviso: o pool de CA mantém uma lista de certificados de CA confiáveis. Os administradores de TI da sua organização geralmente distribuem certificados de CA. As instruções a seguir são para fins deste tutorial e não são adequadas para um ambiente de produção.

O Secure Source Manager tem um plano de controle e um plano de dados. Os endpoints do plano de dados são hospedados diretamente pela sua instância do Secure Source Manager. Portanto, você precisa se conectar ao nome do host da API da instância para acessá-los.

Para usar sua instância particular do Secure Source Manager, use a CA criada na seção Criar uma identidade de serviço e um pool de autoridades certificadoras.

1. Para fazer o download da CA, execute o seguinte comando:

   gcloud privateca pools get-ca-certs CA_POOL \
       --location LOCATION \
       --output-file=root-cert.pem \
       --project PROJECT
   

2. Para fazer chamadas de API à sua instância, transmita o certificado de CA para a API Secure Source Manager do plano de dados.

   Por exemplo, o comando a seguir transmite o certificado de CA root-cert.pem para a API Secure Source Manager para listar repositórios na instância particular my-instance no local us-central1.

   curl \
       --cacert root-cert.pem \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       https://my-instance-01234567890-api.us-central1.sourcemanager.dev/v1/projects/01234567890/locations/us-central1/repositories
   

A seguir

• Conecte o Cloud Build a uma instância do Secure Source Manager do Private Service Connect.
• Configure o Secure Source Manager em um perímetro do VPC Service Controls.