Create a service perimeter

This page describes how to create a service perimeter.

Before you begin

Create a service perimeter

This section describes how to create a service perimeter, add projects or VPC networks to the perimeter, and protect services.

When you create a service perimeter, you can optionally allow access to protected services from outside the perimeter, and specify what services are accessible to other services and users inside the perimeter. If preferred, you can configure these settings after you create a perimeter.

After you create a service perimeter or update an existing service perimeter, it can take up to 30 minutes for the changes to propagate and take effect. During this time, the perimeter might block requests with the following error message: Error 403: Request is prohibited by organization's policy.

Console

  1. In the Google Cloud console navigation menu, click Security, and then click VPC Service Controls.

    Go to VPC Service Controls

  2. If you are prompted, select your organization, folder, or project.

  3. Select an existing access policy or create a new access policy. Make sure that the access policy scope includes all projects and VPC networks that you want to add to the perimeter.

  4. On the VPC Service Controls page, select a perimeter mode. By default, Enforced mode is selected. If you want to create a dry run perimeter, click Dry run mode.

    Enforced perimeters actively prevent access to protected services. Dry run perimeters log violations of the perimeter as though services were protected, but do not prevent access to those services. For more information about the enforced and dry run modes, read about service perimeters.

  5. Click New perimeter.

  6. On the New VPC Service Perimeter page, in the Perimeter Name box, type a name for the perimeter.

    A perimeter name can have a maximum length of 50 characters, must start with a letter, and can contain only ASCII Latin letters (a-z, A-Z), numbers (0-9), or underscores (_). The perimeter name is case sensitive and must be unique within an access policy.

  7. To add projects or VPC networks that you want to secure within the perimeter, do the following:

    1. Click Add Resources.

    2. To add projects to the perimeter, in the Add resources pane, click Add project.

      1. To select a project, in the Add projects dialog, select that project's checkbox.

      2. Click Add selected resources. The added projects appear in the Projects section.

    3. To add VPC networks to the perimeter, in the Add resources pane, click Add VPC network.

      1. From the list of projects, click on the project that contains the VPC networks.
      2. To add a VPC network, in the Add resources dialog, select that VPC network's checkbox.
      3. Click Add selected resources. The added network appears in the VPC networks section.
  8. To select the services that you want to secure within the perimeter, do the following:

    1. Click Restricted Services.

    2. In the Restricted Services pane, click Add services.

    3. To secure services within the perimeter, in the Specify services to restrict dialog, select that service's checkbox.

    4. Click Add n services, where n is the number of services you selected in the previous step.

  9. Optional: If you want to define what services are accessible inside a perimeter, do the following:

    1. Click VPC accessible services.

    2. In the VPC accessible services pane, select Selected services.

      To quickly include all the restricted services that the perimeter protects to the list of accessible services, select Include all restricted services. This option lets you include separate services in addition to restricted services.

    3. Click Add VPC accessible services.

      You can also add accessible services after a perimeter has been created.

    4. In the Specify accessible services page, select the service that you want to make accessible inside your perimeter.

    5. Click Add n services, where n is the number of services you selected in the previous step.

  10. Optional: To allow access to protected resources from outside the perimeter by using access levels, do the following:

    1. Click Access Levels.

    2. In the Ingress Policy: Access Levels pane, click the Choose Access Level box.

      You can also add access levels after a perimeter has been created.

    3. Select the checkboxes corresponding to the access levels that you want to apply to the perimeter.

  11. To allow access to resources within a perimeter from API clients outside the perimeter, do the following:

    1. Click Ingress policy.

    2. In the Ingress rules pane, click Add rule.

    3. Specify the sources from outside the perimeter that require access in From attributes of the API client. You can specify projects, access levels, and VPC networks as sources.

    4. Specify the resources within the perimeter that sources can access in To attributes of Google Cloud resources/services.

      For a list of ingress rule attributes, see Ingress rules reference.

  12. To allow access that involves an API client or resources within the perimeter to resources outside a perimeter, do the following:

    1. Click Egress policy.

    2. In the Egress rules pane, click Add rule.

    3. Designate the required From attributes of the API client and To attributes of Google Cloud resources/services that you want.

      For a list of egress rule attributes, see Egress rules reference.

  13. Click Create perimeter.

gcloud

To create a new perimeter in enforced mode, use the gcloud access-context-manager perimeters create command.

gcloud access-context-manager perimeters create NAME \
  --title=TITLE \
  --resources=RESOURCES \
  --restricted-services=RESTRICTED-SERVICES \
  --ingress-policies=INGRESS-FILENAME.yaml \
  --egress-policies=EGRESS-FILENAME.yaml \
  [--access-levels=LEVELS] \
  [--enable-vpc-accessible-services] \
  [--vpc-allowed-services=ACCESSIBLE-SERVICES] \
  --policy=POLICY_NAME

To create a new perimeter in dry run mode, use the gcloud access-context-manager perimeters dry-run create command.

gcloud access-context-manager perimeters dry-run create NAME \
  --perimeter-title=TITLE \
  --perimeter-type=TYPE \
  --perimeter-resources=RESOURCES \
  --perimeter-restricted-services=RESTRICTED-SERVICES \
  --perimeter-ingress-policies=INGRESS-FILENAME.yaml \
  --perimeter-egress-policies=EGRESS-FILENAME.yaml \
  [--perimeter-access-levels=LEVELS] \
  [--perimeter-enable-vpc-accessible-services] \
  [--perimeter-vpc-allowed-services=ACCESSIBLE-SERVICES] \
  --policy=POLICY_NAME

Replace the following:

  • NAME is the name of the perimeter.

    A perimeter name can have a maximum length of 50 characters, must start with a letter, and can contain only ASCII Latin letters (a-z, A-Z), numbers (0-9), or underscores (_). The perimeter name is case sensitive and must be unique within an access policy.

  • TITLE is the human-readable title of the perimeter.

  • TYPE is the type of the perimeter. For example, a "regular" perimeter or a "bridge" perimeter.

  • RESOURCES is a comma-separated list of one or more project numbers or VPC network names. For example: projects/12345 or //compute.googleapis.com/projects/my-project/global/networks/vpc1. Only projects and VPC networks are allowed. Project format: projects/project_number. VPC format: //compute.googleapis.com/projects/project-id/global/networks/network_name. If you specify projects, only project numbers are supported. You cannot use the project name or ID.

  • RESTRICTED-SERVICES is a comma-separated list of one or more services. For example: storage.googleapis.com or storage.googleapis.com,bigquery.googleapis.com.

  • INGRESS-FILENAME is a JSON or YAML file that contains the values of source, identity, project, and service attributes. For a list of ingress rule attributes, see Ingress rules reference.

  • EGRESS-FILENAME is a JSON or YAML file that contains the values of identity, project, and service attributes. For a list of egress rule attributes, see Egress rules reference.

  • POLICY_NAME is the numeric name of your organization's access policy. For example, 330193482019. You only need to include the policy name if you haven't set a default access policy.

Additional options:

  • --access-levels or --perimeter-access-levels is required only if you want to add access levels when you create the perimeter. LEVELS is a comma-separated list of one or more access levels that you want to apply to the service perimeter.

    You can also add access levels after you create the perimeter.

  • --enable-vpc-accessible-services and --vpc-allowed-services, or --perimeter-enable-vpc-accessible-services and --perimeter-vpc-allowed-services are required only if you want to add VPC accessible services when you create the perimeter. ACCESSIBLE-SERVICES is a comma-separated list of one or more services that you want to allow networks inside your perimeter to access. Access to any services that are not included in this list are prevented.

    You can only make a service accessible if you also protect it when configuring the perimeter.

    To quickly include all the services protected by a perimeter, specify RESTRICTED-SERVICES in the list for ACCESSIBLE-SERVICES. For example, --perimeter-vpc-allowed-services=RESTRICTED-SERVICES.

    You can also define VPC accessible services after you create the perimeter.

For example, the following command creates a new dry run mode perimeter named ProdPerimeter that includes projects example-project and example-project2, and restricts the Cloud Storage and BigQuery APIs.

gcloud access-context-manager perimeters \
  dry-run create ProdPerimeter --perimeter-title="Production Perimeter" \
  --perimeter-type="regular" \
  --perimeter-resources=projects/12345,projects/67890 \
  --perimeter-restricted-services=storage.googleapis.com,bigquery.googleapis.com \
  --perimeter-ingress-policies=ingress.yaml \
  --perimeter-egress-policies=egress.yaml \
  --policy=330193482019

API

To create a service perimeter, call accessPolicies.servicePerimeters.create.

 POST https://accesscontextmanager.googleapis.com/v1/accessPolicies/POLICY_NAME/servicePerimeters

Where:

  • POLICY_NAME is the numeric name of your organization's access policy. For example, 330193482019.

Request body

The request body must include a ServicePerimeter resource that defines the service perimeter.

For the ServicePerimeter resource, specify PERIMETER_TYPE_REGULAR for perimeterType.

Dry Run Mode

The proposed perimeter must be included as the spec and useExplicitDryRunSpec set to true.

Response body

If successful, the response body for the call contains an Operation resource that provides details about the POST operation.

What's next