Create a Private Service Connect Secure Source Manager instance

This page describes how to create a Private Service Connect instance.

Private Service Connect instances don't expose any endpoints to the public internet. When you create a Private Service Connect instance, endpoints are created to provide SSH (Git) and HTTPS (Git, web interface, API) access to the instance. The endpoints must be assigned IP addresses on your private network. All traffic to and from the Private Service Connect instance passes through the Private Service Connect endpoints.

For more information on using Private Service Connect to access managed services privately from inside a VPC network, see Private Service Connect.

Secure Source Manager is a single-tenant service. A single Secure Source Manager instance should only include users from one Google Cloud customer unless multiple companies who have a contractual relationship need to use a single instance for collaboration.

If you are working with multiple companies and want to collaborate around source with each of them, we recommend creating a separate instance for each company.

Before you begin

1. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

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

   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

3. Enable the Secure Source Manager API.

   Enable the API

4. Install the Google Cloud CLI.

5. To initialize the gcloud CLI, run the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.

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

   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

7. Enable the Secure Source Manager API.

   Enable the API

8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

   Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
10. Install the beta Google Cloud CLI component:

    gcloud components install beta

Required roles

To get the permissions that you need to create a Private Service Connect Secure Source Manager instance, ask your administrator to grant you the following IAM roles:

• Access Context Manager Admin role (roles/accesscontextmanager.policyAdmin) on the organization
• Instance Owner role (roles/sercuresourcemanager.instanceOwner) on the instance
• To create a service identity and Certificate Authority pool: CA Service Operation Manager (roles/privateca.caManager) on the organization

Create a service identity and Certificate Authority pool

You need to specify a Certificate Authority (CA) pool name when you create a private Secure Source Manager instance. When you create a private Secure Source Manager instance, a request to sign the instance's HTTPS SSL certificate is sent to the CA pool.

1. Run the following command to create a service identity for the Secure Source Manager API within your project:

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

   Where PROJECT_ID is your project ID.

   The output is similar to the following:

   Service identity created: [e-mail]
   

   Where [e-mail] is the Secure Source Manager service agent, and 012345678901 is your project number.

2. Create a Certificate Authority (CA) pool with CSR based certificate requests allowed.

3. Create a CA. You can create a root or subordinate CA depending on your needs.

   • To create a root CA, follow the instructions in Create a root CA.
   • To create a subordinate CA from a parent CA in Google Cloud, follow the instructions in Create a subordinate CA
   • To create a subordinate CA from an external CA, follow the instructions in Create a subordinate CA from an external CA.

   For more information on the differences between root and subordinate CAs, see Determine certificate authority settings.

4. Grant the Secure Source Manager API service identity permissions to request new certificates in the CA pool:

   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
   

   Replace the following:

   • CA_POOL_NAME with the name you gave your CA pool.
   • CA_LOCATION with the region or zone of your CA pool.
   • PROJECT_NUMBER with the project number where Secure Source Manager is enabled. You can locate the project number by following the instructions in Identifying projects.
   • CA_PROJECT_ID with the project ID of the project you created the CA pool in.

Create a Private Service Connect Secure Source Manager instance

gcloud

Create a Private Service Connect instance with the following command:

gcloud beta 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

Replace the following:

• INSTANCE_ID with the name you want to give the instance.
• LOCATION with the region where you want to create the instance. For supported locations, see Locations.
• PROJECT_ID with the name of the project you want to create an instance in.
• CA_PROJECT with the name of the CA pool project.
• CA_LOCATION with the region where you created the CA pool.
• CA_POOL_NAME with the name of the CA pool.

API

Create a Private Service Connect instance with the following command:

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"}}'

Replace the following:

• INSTANCE_ID with the name you want to give the instance.
• LOCATION with the region where you want to create the instance. For supported locations, see Locations.
• PROJECT_ID with the name of the project you want to create an instance in.
• CA_PROJECT with the name of the CA pool project.
• CA_LOCATION with the region where you created the CA pool.
• CA_POOL_NAME with the name of the CA pool.

A long-running create instance operation starts. It takes up to 60 minutes to create the instance. The output is similar to the following:

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

Where projects/my-project/locations/us-central1/operations/operation-1234567894561-5ec69948c0f2b-60dd727f-a9b97a2e is the OPERATION_NAME.

Note the OPERATION_NAME as you will need to use it to check the status of the operation.

To check the status of the operation run the following command:

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

Replace the following:

• OPERATION_NAME with the operation name from your create command response.
• LOCATION with the region where you want to create the instance. For information on supported locations, see Locations.

Once the instance is created, the Private Service Connect endpoints httpServiceAttachment and sshServiceAttachment, along with the hostnames for html, api, gitHttp, and gitSsh, are listed in the output.

Access the private instance

To access your Private Service Connect instance you can either create Private Service Connect endpoints based on forwarding rules, or create Private Service Connect backends based on load balancers.

Private Service Connect backends based on load balancers are more flexible, and allow you to integrate with other Google Cloud services like Cloud Build, but are more complex and have additional billing.

Private Service Connect endpoints based on forwarding rules are simpler, and cost less, but you can't connect to Cloud Build or other Google Cloud services.

To set up Private Service Connect backends based on load balancers for your Private Service Connect instance and connect it to Cloud Build, see Connect Cloud Build to a Private Service Connect instance.

Set up Private Service Connect endpoints based on forwarding rules

1. To create Private Service Connect endpoints, follow the instructions in Access published services through endpoints.

2. To get the URIs for your Secure Source Manager instance's HTTP and SSH service attachments, run the following command:

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

   Replace the following:

   • INSTANCE_ID with the name of your instance. To list instances in a given region, you can run gcloud beta source-manager instances list --region=LOCATION.
   • LOCATION with the location of your instance. For information on supported locations, see Locations.

   The output resembles the following:

   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'
   

   Where:

   • projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/http-psc is your instance's HTTP service attachment URI.
   • projects/abc12345d1a1234a0a-tp/regions/us-central1/serviceAttachments/ssh-psc is your instance's SSH service attachment URI.

3. After you have created the Private Service Connect endpoints, you need to set up private DNS records. For instructions on how to set up private DNS records, see Configure DNS manually.

   1. Map the value of hostConfig.html, hostConfig.api, and hostConfig.gitHttp to the internal IP address of the HTTP service attachment.
   2. Map the value of hostConfig.ssh to the internal IP address of the SSH service attachment.

   For example, in the previous example output, the value of hostConfig.html is my-project-012345678901.us-central1.p.sourcemanager.dev.

   Note: The Google Cloud DNS zone and the Private Service Connect need to be in the same Virtual Private Cloud network.

Use the CA with Secure Source Manager API

Warning: The CA pool maintains a list of trusted CA certificates. Your organization's IT administrators will generally handle distributing CA certificates. The following instructions are for the purpose of this tutorial, and aren't appropriate for a production environment.

Secure Source Manager has a control plane and a data plane. Data plane endpoints are hosted directly by your Secure Source Manager instance, so you must connect to your instance's API hostname to access them.

To use your private Secure Source Manager instance, you need to use the CA you created in the Create a service identity and Certificate Authority pool section.

1. To download your CA, run the following command:

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

2. To perform API calls to your instance, pass the CA certificate to the data plane Secure Source Manager API.

   For example, the following command passes the CA certificate root-cert.pem to the Secure Source Manager API in order to list repositories in the private instance my-instance in location 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
   

What's next

• Connect Cloud Build to a Private Service Connect Secure Source Manager instance.
• Configure Secure Source Manager in a VPC Service Controls perimeter.