mmv1/products/accesscontextmanager/AccessLevel.yaml

# Copyright 2024 Google Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

---
# This is the singular of `AccessLevels`, any changes here should be made to `AccessLevels` as well
name: 'AccessLevel'
description: |
  An AccessLevel is a label that can be applied to requests to GCP services,
  along with a list of requirements necessary for the label to be applied.
references:
  guides:
    'Access Policy Quickstart': 'https://cloud.google.com/access-context-manager/docs/quickstart'
  api: 'https://cloud.google.com/access-context-manager/docs/reference/rest/v1/accessPolicies.accessLevels'
docs:
  warning: |
    If you are using User ADCs (Application Default Credentials) with this resource,
    you must specify a `billing_project` and set `user_project_override` to true
    in the provider configuration. Otherwise the ACM API will return a 403 error.
    Your account must have the `serviceusage.services.use` permission on the
    `billing_project` you defined.
id_format: '{{name}}'
base_url: ''
self_link: '{{name}}'
# This is an unusual API, so we need to use a few fields to map the methods
# to the right URL.
# create_url is the Create URL
# base_url is the Get and Delete and Patch URL. It is empty on purpose.
# List won't work yet. It should share a URL with Create.
create_url: '{{parent}}/accessLevels'
update_verb: 'PATCH'
update_mask: true
mutex: '{{parent}}'
import_format:
  - '{{name}}'
timeouts:
  insert_minutes: 20
  update_minutes: 20
  delete_minutes: 20
autogen_async: true
async:
  actions: ['create', 'delete', 'update']
  type: 'OpAsync'
  operation:
    base_url: '{{op_id}}'
  result:
    resource_inside_response: true
custom_code:
  encoder: 'templates/terraform/encoders/access_level_never_send_parent.go.tmpl'
  custom_import: 'templates/terraform/custom_import/set_access_policy_parent_from_self_link.go.tmpl'
# Skipping the sweeper due to the non-standard base_url
exclude_sweeper: true
examples:
  - name: 'access_context_manager_access_level_basic'
    primary_resource_id: 'access-level'
    vars:
      access_level_name: 'chromeos_no_lock'
    exclude_test: true
parameters:
  # Parent is a path parameter that _cannot_ be read or sent in the request at all.
  # This must be done at the provider level.
  - name: 'parent'
    type: String
    description: |
      The AccessPolicy this AccessLevel lives in.
      Format: accessPolicies/{policy_id}
    required: true
    immutable: true
    ignore_read: true
  - name: 'name'
    type: String
    description: |
      Resource name for the Access Level. The short_name component must begin
      with a letter and only include alphanumeric and '_'.
      Format: accessPolicies/{policy_id}/accessLevels/{short_name}
    required: true
    immutable: true
properties:
  - name: 'title'
    type: String
    description: |
      Human readable title. Must be unique within the Policy.
    required: true
  - name: 'description'
    type: String
    description: |
      Description of the AccessLevel and its use. Does not affect behavior.
  - name: 'basic'
    type: NestedObject
    description: |
      A set of predefined conditions for the access level and a combining function.
    conflicts:
      - custom
    properties:
      - name: 'combiningFunction'
        type: Enum
        description: |
          How the conditions list should be combined to determine if a request
          is granted this AccessLevel. If AND is used, each Condition in
          conditions must be satisfied for the AccessLevel to be applied. If
          OR is used, at least one Condition in conditions must be satisfied
          for the AccessLevel to be applied.
        custom_flatten: 'templates/terraform/custom_flatten/default_if_empty.tmpl'
        default_value: "AND"
        enum_values:
          - 'AND'
          - 'OR'
      # All of the false defaults below here are omitted on purpose.
      # Let's keep this as simple as possible, since they will all be set by the API.
      - name: 'conditions'
        type: Array
        description: |
          A set of requirements for the AccessLevel to be granted.
        required: true
        item_type:
          type: NestedObject
          properties:
            - name: 'ipSubnetworks'
              type: Array
              description: |
                A list of CIDR block IP subnetwork specification. May be IPv4
                or IPv6.
                Note that for a CIDR IP address block, the specified IP address
                portion must be properly truncated (i.e. all the host bits must
                be zero) or the input is considered malformed. For example,
                "192.0.2.0/24" is accepted but "192.0.2.1/24" is not. Similarly,
                for IPv6, "2001:db8::/32" is accepted whereas "2001:db8::1/32"
                is not. The originating IP of a request must be in one of the
                listed subnets in order for this Condition to be true.
                If empty, all IP addresses are allowed.
              item_type:
                type: String
            - name: 'requiredAccessLevels'
              type: Array
              description: |
                A list of other access levels defined in the same Policy,
                referenced by resource name. Referencing an AccessLevel which
                does not exist is an error. All access levels listed must be
                granted for the Condition to be true.
                Format: accessPolicies/{policy_id}/accessLevels/{short_name}
              item_type:
                type: String
            - name: 'members'
              type: Array
              description: |
                An allowed list of members (users, service accounts).
                Using groups is not supported yet.

                The signed-in user originating the request must be a part of one
                of the provided members. If not specified, a request may come
                from any user (logged in/not logged in, not present in any
                groups, etc.).
                Formats: `user:{emailid}`, `serviceAccount:{emailid}`
              item_type:
                type: String
            - name: 'negate'
              type: Boolean
              description: |
                Whether to negate the Condition. If true, the Condition becomes
                a NAND over its non-empty fields, each field must be false for
                the Condition overall to be satisfied. Defaults to false.
            - name: 'devicePolicy'
              type: NestedObject
              description: |
                Device specific restrictions, all restrictions must hold for
                the Condition to be true. If not specified, all devices are
                allowed.
              properties:
                - name: 'requireScreenLock'
                  type: Boolean
                  description: |
                    Whether or not screenlock is required for the DevicePolicy
                    to be true. Defaults to false.
                  api_name: requireScreenlock
                - name: 'allowedEncryptionStatuses'
                  type: Array
                  description: |
                    A list of allowed encryptions statuses.
                    An empty list allows all statuses.
                  item_type:
                    type: Enum
                    description: |
                      This field only has a name and description because of MM
                      limitations. It should not appear in downstreams.
                    enum_values:
                      - 'ENCRYPTION_UNSPECIFIED'
                      - 'ENCRYPTION_UNSUPPORTED'
                      - 'UNENCRYPTED'
                      - 'ENCRYPTED'
                - name: 'allowedDeviceManagementLevels'
                  type: Array
                  description: |
                    A list of allowed device management levels.
                    An empty list allows all management levels.
                  item_type:
                    type: Enum
                    description: |
                      This field only has a name and description because of MM
                      limitations. It should not appear in downstreams.
                    enum_values:
                      - 'MANAGEMENT_UNSPECIFIED'
                      - 'NONE'
                      - 'BASIC'
                      - 'COMPLETE'
                - name: 'osConstraints'
                  type: Array
                  description: |
                    A list of allowed OS versions.
                    An empty list allows all types and all versions.
                  item_type:
                    type: NestedObject
                    properties:
                      - name: 'minimumVersion'
                        type: String
                        description: |
                          The minimum allowed OS version. If not set, any version
                          of this OS satisfies the constraint.
                          Format: "major.minor.patch" such as "10.5.301", "9.2.1".
                      - name: 'requireVerifiedChromeOs'
                        type: Boolean
                        description:
                          If you specify DESKTOP_CHROME_OS for osType, you can
                          optionally include requireVerifiedChromeOs to require
                          Chrome Verified Access.
                      - name: 'osType'
                        type: Enum
                        description: |
                          The operating system type of the device.
                        required: true
                        enum_values:
                          - 'OS_UNSPECIFIED'
                          - 'DESKTOP_MAC'
                          - 'DESKTOP_WINDOWS'
                          - 'DESKTOP_LINUX'
                          - 'DESKTOP_CHROME_OS'
                          - 'ANDROID'
                          - 'IOS'
                - name: 'requireAdminApproval'
                  type: Boolean
                  description: |
                    Whether the device needs to be approved by the customer admin.
                - name: 'requireCorpOwned'
                  type: Boolean
                  description: |
                    Whether the device needs to be corp owned.
            - name: 'regions'
              type: Array
              description: |
                The request must originate from one of the provided
                countries/regions.
                Format: A valid ISO 3166-1 alpha-2 code.
              item_type:
                type: String
            - name: 'vpcNetworkSources'
              type: Array
              description: 'The request must originate from one of the provided VPC networks in Google Cloud. Cannot specify this field together with `ip_subnetworks`.'
              item_type:
                type: NestedObject
                properties:
                  - name: 'vpcSubnetwork'
                    type: NestedObject
                    description: 'Sub networks within a VPC network.'
                    properties:
                      - name: 'network'
                        type: String
                        description: 'Required. Network name to be allowed by this Access Level. Networks of foreign organizations requires `compute.network.get` permission to be granted to caller.'
                        required: true
                      - name: 'vpcIpSubnetworks'
                        type: Array
                        description: 'A list of CIDR block IP subnetwork specification. Must be IPv4.'
                        item_type:
                          type: String
        min_size: 1
  - name: 'custom'
    type: NestedObject
    description: |
      Custom access level conditions are set using the Cloud Common Expression Language to represent the necessary conditions for the level to apply to a request.
      See CEL spec at: https://github.com/google/cel-spec.
    conflicts:
      - basic
    properties:
      - name: 'expr'
        type: NestedObject
        description: |
          Represents a textual expression in the Common Expression Language (CEL) syntax. CEL is a C-like expression language.
          This page details the objects and attributes that are used to the build the CEL expressions for
          custom access levels - https://cloud.google.com/access-context-manager/docs/custom-access-level-spec.
        required: true
        properties:
          - name: 'expression'
            type: String
            description:
              Textual representation of an expression in Common Expression
              Language syntax.
            required: true
          - name: 'title'
            type: String
            description:
              Title for the expression, i.e. a short string describing its
              purpose.
          - name: 'description'
            type: String
            description: Description of the expression
          - name: 'location'
            type: String
            description:
              String indicating the location of the expression for error
              reporting, e.g. a file name and a position in the file