Crea un'istanza Private Service Connect

Questa pagina descrive come creare un'istanza Private Service Connect per Secure Source Manager.

Le istanze Private Service Connect non espongono endpoint a internet pubblico. Quando crei un'istanza Private Service Connect, vengono creati endpoint per fornire l'accesso SSH (Git) e HTTPS (Git, interfaccia web, API) all'istanza. Agli endpoint devono essere assegnati indirizzi IP sulla tua rete privata. Tutto il traffico verso e dall'istanza Private Service Connect passa attraverso gli endpoint Private Service Connect.

Per ulteriori informazioni sull'utilizzo di Private Service Connect per accedere ai servizi gestiti in privato dall'interno di una rete VPC, consulta Private Service Connect.

Secure Source Manager è un servizio a tenant singolo. Una singola istanza Secure Source Manager deve includere solo utenti di un Google Cloud cliente, a meno che più aziende con un rapporto contrattuale non debbano utilizzare una singola istanza per la collaborazione.

Se lavori con più aziende e vuoi collaborare con loro sul codice sorgente, ti consigliamo di creare un'istanza separata per ogni azienda.

Prima di iniziare

Accedi al tuo Account Google.

Se non ne hai già uno, registrati per creare un nuovo account.

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

Installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo 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

Installa Google Cloud CLI.

Nota: se hai già installato gcloud CLI, assicurati di avere l'ultima versione eseguendo gcloud components update.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare un'istanza Secure Source Manager Private Service Connect, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Ruolo Access Context Manager Admin (roles/accesscontextmanager.policyAdmin) nell'organizzazione
• Ruolo Proprietario dell'istanza (roles/securesourcemanager.instanceOwner) nell'istanza
• Per creare un'identità di servizio e un pool di autorità di certificazione: Gestore operazioni del servizio CA (roles/privateca.caManager) nell'organizzazione

Creare un'identità di servizio e un pool di autorità di certificazione

Questa sezione descrive come utilizzare il tuo certificato CA. Devi utilizzare il tuo certificato CA se intendi utilizzare domini personalizzati con la tua istanza privata. Per utilizzare un certificato gestito senza domini personalizzati, non devi fare altro che eseguire il gcloud source-manager instances create comando senza creare un'identità di servizio e un pool di CA. GooglePer ulteriori informazioni, consulta Creare un'istanza Secure Source Manager Private Service Connect.

Se utilizzi il tuo certificato CA, devi specificare il nome di un pool di autorità di certificazione (CA) quando crei un'istanza Secure Source Manager privata. Al pool di CA viene inviata una richiesta di firma del certificato SSL HTTPS dell'istanza.

1. Esegui questo comando per creare un'identità di servizio per l'API Secure Source Manager all'interno del tuo progetto:

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

   dove PROJECT_ID è l'ID progetto.

   L'output è simile al seguente:

   Service identity created: [e-mail]

   dove [e-mail] è l'agente di servizio Secure Source Manager e PROJECT_NUM è il numero del progetto.

2. Crea un pool di autorità di certificazione (CA) con le richieste di certificati basate su CSR abilitate.

3. Crea una CA. Puoi creare una CA radice o subordinata a seconda delle tue esigenze.

   Nota: quando utilizzi la tua autorità di certificazione, devi utilizzare una dimensione della chiave di 2048 bit.
   • Per creare una CA radice, segui le istruzioni riportate in Creare una CA radice.
   • Per creare una CA subordinata da una CA principale in Google Cloud, segui le istruzioni riportate in Creare una CA subordinata
   • Per creare una CA subordinata da una CA esterna, segui le istruzioni riportate in Creare una CA subordinata da una CA esterna.

   Per ulteriori informazioni sulle differenze tra CA radice e CA subordinate, consulta Determinare le impostazioni dell'autorità di certificazione.

4. Concedi all'identità di servizio dell'API Secure Source Manager le autorizzazioni per richiedere nuovi certificati nel pool di CA:

   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
   

   Sostituisci quanto segue:

   • CA_POOL_NAME con il nome che hai assegnato al pool di CA.
   • CA_LOCATION con la regione o la zona del pool di CA.
   • PROJECT_NUMBER con il numero del progetto in cui è abilitato Secure Source Manager. Per individuare il numero del progetto, consulta Identificare i progetti.
   • CA_PROJECT_ID con l'ID progetto del progetto in cui hai creato il pool di CA.

Creare un'istanza Secure Source Manager Private Service Connect

Puoi assegnare domini personalizzati alla tua istanza privata per gli endpoint HTML, API, Git HTTP e Git SSH. I domini personalizzati richiedono il tuo certificato CA. Pertanto, devi fornire un pool di CA quando crei un'istanza con domini personalizzati. Puoi configurare i domini personalizzati solo durante la creazione dell'istanza utilizzando l'API. Non puoi modificarli dopo la creazione dell'istanza.

gcloud

Crea un'istanza Private Service Connect con il seguente 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

Sostituisci quanto segue:

• INSTANCE_ID con il nome che vuoi assegnare all'istanza.
• LOCATION con la regione in cui vuoi creare l'istanza. Per le località supportate, consulta Località.
• PROJECT_ID con il nome del progetto in cui vuoi creare un'istanza.
• CA_PROJECT con il nome del progetto del pool di CA. Obbligatorio se utilizzi il tuo certificato CA.
• CA_LOCATION con la regione in cui hai creato il pool di CA. Obbligatorio se utilizzi il tuo certificato CA.
• CA_POOL_NAME con il nome del pool di CA. Obbligatorio se utilizzi il tuo certificato CA.

Nota: puoi omettere il flag --ca-pool se utilizzi un Google-managed certificate e non utilizzi domini personalizzati. Puoi configurare i domini personalizzati solo utilizzando l'API.

API

Crea un'istanza Private Service Connect con il seguente 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"}}}'

Sostituisci quanto segue:

• INSTANCE_ID con il nome che vuoi assegnare all'istanza.
• LOCATION con la regione in cui vuoi creare l'istanza. Per le località supportate, consulta Località.
• PROJECT_ID con il nome del progetto in cui vuoi creare un'istanza.
• CA_PROJECT con il nome del progetto del pool di CA. Obbligatorio se utilizzi il tuo certificato CA o domini personalizzati.
• CA_LOCATION con la regione in cui hai creato il pool di CA. Obbligatorio se utilizzi il tuo certificato CA o domini personalizzati.
• CA_POOL_NAME con il nome del pool di CA. Obbligatorio se utilizzi il tuo certificato CA o domini personalizzati.
• API_CUSTOM_DOMAIN con il tuo dominio personalizzato per l'accesso API, ad esempio api.source.example.com. Obbligatorio solo se utilizzi domini personalizzati.
• HTML_CUSTOM_DOMAIN con il tuo dominio personalizzato per l'accesso all'interfaccia utente web, ad esempio source.example.com. Obbligatorio solo se utilizzi domini personalizzati.
• GIT_SSH_CUSTOM_DOMAIN con il tuo dominio personalizzato per l'accesso Git SSH, ad esempio ssh.source.example.com. Obbligatorio solo se utilizzi domini personalizzati.
• GIT_HTTP_CUSTOM_DOMAIN con il tuo dominio personalizzato per l'accesso Git HTTP, ad esempio git.source.example.com. Obbligatorio solo se utilizzi domini personalizzati.

Nota: se utilizzi un certificato Googlegestito, rimuovi il campo ca_pool da questo comando. Se non utilizzi domini personalizzati, rimuovi il campo custom_host_config.

Terraform

Per creare un'istanza Private Service Connect con Terraform, utilizza la google_secure_source_manager_instance risorsa con il private_config.is_private campo impostato su true.

Viene avviata un'operazione di creazione dell'istanza a lunga esecuzione. La creazione dell'istanza richiede fino a 60 minuti. L'output è simile al seguente:

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

dove projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e è il NOME_OPERAZIONE.

Hai bisogno del NOME_OPERAZIONE per controllare lo stato dell'operazione.

Per controllare lo stato dell'operazione, esegui questo comando:

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

Sostituisci quanto segue:

• NOME_OPERAZIONE con il nome dell'operazione dalla risposta del comando di creazione.
• LOCATION con la regione in cui vuoi creare l'istanza. Per le località supportate, consulta Località.

Dopo la creazione dell'istanza, nell'output vengono elencati gli endpoint Private Service Connect httpServiceAttachment e sshServiceAttachment, insieme ai nomi host per html, api, gitHttp e gitSsh.

Accedere all'istanza privata

Puoi accedere all'istanza Private Service Connect creando endpoint Private Service Connect basati su regole di forwarding o creando backend Private Service Connect basati su bilanciatori del carico.

I backend Private Service Connect basati su bilanciatori del carico sono più flessibili e ti consentono di integrare altri Google Cloud servizi come Cloud Build, ma sono più complessi e comportano una fatturazione aggiuntiva.

Gli endpoint Private Service Connect basati su regole di forwarding sono più semplici e costano meno. Tuttavia, non puoi connetterti a Cloud Build o ad altri Google Cloud servizi.

Per configurare i backend Private Service Connect basati su bilanciatori del carico per l'istanza Private Service Connect e connetterla a Cloud Build, consulta Connettere Cloud Build a un'istanza Private Service Connect.

Configurare gli endpoint Private Service Connect basati su regole di forwarding

1. Per creare endpoint Private Service Connect, segui le istruzioni riportate in Accedere ai servizi pubblicati tramite endpoint.

2. Per ottenere gli URI degli allegati del servizio HTTP e SSH dell'istanza Secure Source Manager, esegui questo comando:

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

   Sostituisci quanto segue:

   • INSTANCE_ID con il nome dell'istanza. Per elencare le istanze in una determinata regione, esegui gcloud source-manager instances list --region=LOCATION.
   • LOCATION con la località dell'istanza. Per le località supportate, consulta Località.

   L'output include:

   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 è l'URI dell'allegato del servizio HTTP dell'istanza.
   • projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/ssh-psc è l'URI dell'allegato del servizio SSH dell'istanza.

3. Dopo aver creato gli endpoint Private Service Connect, devi configurare i record DNS privati. Per istruzioni su come configurare i record DNS privati, consulta Configurare manualmente il DNS. Se hai configurato domini personalizzati per l'istanza, crea record DNS che mappano i domini personalizzati agli indirizzi IP interni degli allegati del servizio. In caso contrario, utilizza i nomi host nel campo hostConfig dell'istanza:

   1. Mappa il valore di hostConfig.html (o il dominio personalizzato HTML), hostConfig.api (o il dominio personalizzato API) e hostConfig.gitHttp (o il dominio personalizzato Git HTTP) all'indirizzo IP interno dell'allegato del servizio HTTP.
   2. Mappa il valore di hostConfig.ssh (o il dominio personalizzato Git SSH) a l'indirizzo IP interno dell'allegato del servizio SSH.

   Ad esempio, nell'output dell'esempio precedente, il valore di hostConfig.html è my-project-012345678901.us-central1.p.sourcemanager.dev.

   Nota: la Google Cloud zona DNS e Private Service Connect devono trovarsi nella stessa rete Virtual Private Cloud.

Autenticazione Git con domini personalizzati

Se utilizzi domini personalizzati per la tua istanza privata, esegui la seguente configurazione lato client su ogni macchina per utilizzare Git su HTTPS. Questa configurazione connette Git all'helper delle credenziali gcloud per l'autenticazione rispetto al tuo dominio personalizzato.

1. Configura Git in modo che utilizzi l'helper gcloud per il tuo dominio Git HTTP personalizzato:

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

   Sostituisci GIT_HTTP_CUSTOM_DOMAIN con il dominio personalizzato che hai configurato per l'accesso Git HTTP.

2. Autorizza il tuo dominio personalizzato in gcloud:

   gcloud config set core/credentialed_hosted_repo_domains GIT_HTTP_CUSTOM_DOMAIN
   

   Per autorizzare più domini, fornisci un elenco separato da virgole.

Utilizzare la CA con l'API Secure Source Manager

Avviso: il pool di CA gestisce un elenco di certificati CA attendibili. In genere, gli amministratori IT della tua organizzazione gestiscono la distribuzione dei certificati CA. Le seguenti istruzioni sono fornite ai fini di questo tutorial e non sono appropriate per un ambiente di produzione.

Secure Source Manager ha un piano di controllo e un piano dati. Gli endpoint del piano dati sono ospitati direttamente dall'istanza Secure Source Manager, quindi devi connetterti al nome host dell'API dell'istanza per accedervi.

Per utilizzare l'istanza Secure Source Manager privata, utilizza la CA che hai creato nella sezione Creare un'identità di servizio e un pool di autorità di certificazione.

1. Per scaricare la CA, esegui questo comando:

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

2. Per effettuare chiamate API all'istanza, trasmetti il certificato CA all'API Secure Source Manager del piano dati.

   Ad esempio, il seguente comando trasmette il certificato CA root-cert.pem all'API Secure Source Manager per elencare i repository nell'istanza privata my-instance nella località 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
   

Passaggi successivi

• Connettere Cloud Build a un'istanza Secure Source Manager Private Service Connect.
• Configurare Secure Source Manager in un perimetro dei Controlli di servizio VPC.