From 083014a9946ddc90b0d655104132ff642236859d Mon Sep 17 00:00:00 2001 From: Modular Magician Date: Tue, 4 Mar 2025 21:50:38 +0000 Subject: [PATCH] Update the description of intercept resources. (#13254) [upstream:50dbf8de1fa0f4a8365bfec502337b8bf2c72047] Signed-off-by: Modular Magician --- .changelog/13254.txt | 3 + ...ecurity_intercept_deployment.html.markdown | 51 +++++++++------ ...y_intercept_deployment_group.html.markdown | 50 +++++++++------ ...ity_intercept_endpoint_group.html.markdown | 45 ++++++++----- ...t_endpoint_group_association.html.markdown | 63 ++++++++++++------- 5 files changed, 135 insertions(+), 77 deletions(-) create mode 100644 .changelog/13254.txt diff --git a/.changelog/13254.txt b/.changelog/13254.txt new file mode 100644 index 00000000000..9c576130b09 --- /dev/null +++ b/.changelog/13254.txt @@ -0,0 +1,3 @@ +```release-note:none +Updated descriptions for Network Security's Intercept resources. +``` \ No newline at end of file diff --git a/website/docs/r/network_security_intercept_deployment.html.markdown b/website/docs/r/network_security_intercept_deployment.html.markdown index e6836dcf45d..9c66fe46a68 100644 --- a/website/docs/r/network_security_intercept_deployment.html.markdown +++ b/website/docs/r/network_security_intercept_deployment.html.markdown @@ -16,12 +16,16 @@ # ---------------------------------------------------------------------------- subcategory: "Network Security" description: |- - InterceptDeployment represents the collectors within a Zone and is associated with a deployment group. + A deployment represents a zonal intercept backend ready to accept + GENEVE-encapsulated traffic, e. --- # google_network_security_intercept_deployment -InterceptDeployment represents the collectors within a Zone and is associated with a deployment group. +A deployment represents a zonal intercept backend ready to accept +GENEVE-encapsulated traffic, e.g. a zonal instance group fronted by an +internal passthrough load balancer. Deployments are always part of a +global deployment group which represents a global intercept service. ~> **Warning:** This resource is in beta, and should be used with the terraform-provider-google-beta provider. See [Provider Versions](https://terraform.io/docs/providers/google/guides/provider_versions.html) for more details on beta resources. @@ -106,24 +110,24 @@ The following arguments are supported: * `forwarding_rule` - (Required) - Immutable. The regional load balancer which the intercepted traffic should be forwarded - to. Format is: - projects/{project}/regions/{region}/forwardingRules/{forwardingRule} + The regional forwarding rule that fronts the interceptors, for example: + `projects/123456789/regions/us-central1/forwardingRules/my-rule`. + See https://google.aip.dev/124. * `intercept_deployment_group` - (Required) - Immutable. The Intercept Deployment Group that this resource is part of. Format is: - `projects/{project}/locations/global/interceptDeploymentGroups/{interceptDeploymentGroup}` + The deployment group that this deployment is a part of, for example: + `projects/123456789/locations/global/interceptDeploymentGroups/my-dg`. + See https://google.aip.dev/124. * `location` - (Required) - Resource ID segment making up resource `name`. It identifies the resource within its parent collection as described in https://google.aip.dev/122. See documentation for resource type `networksecurity.googleapis.com/InterceptDeployment`. + The cloud location of the deployment, e.g. `us-central1-a` or `asia-south1-b`. * `intercept_deployment_id` - (Required) - Id of the requesting object - If auto-generating Id server-side, remove this field and - intercept_deployment_id from the method_signature of Create RPC + The ID to use for the new deployment, which will become the final + component of the deployment's resource name. - - - @@ -131,7 +135,7 @@ The following arguments are supported: * `labels` - (Optional) - Optional. Labels as key value pairs + Labels are key/value pairs that help to organize and filter resources. **Note**: This field is non-authoritative, and will only manage the labels present in your configuration. Please refer to the field `effective_labels` for all of the labels present on the resource. @@ -146,18 +150,23 @@ In addition to the arguments listed above, the following computed attributes are * `id` - an identifier for the resource with format `projects/{{project}}/locations/{{location}}/interceptDeployments/{{intercept_deployment_id}}` * `name` - - Identifier. The name of the InterceptDeployment. + The resource name of this deployment, for example: + `projects/123456789/locations/us-central1-a/interceptDeployments/my-dep`. + See https://google.aip.dev/122 for more details. * `create_time` - - Create time stamp + The timestamp when the resource was created. + See https://google.aip.dev/148#timestamps. * `update_time` - - Update time stamp + The timestamp when the resource was most recently updated. + See https://google.aip.dev/148#timestamps. * `state` - - Current state of the deployment. - Possible values: - STATE_UNSPECIFIED + The current state of the deployment. + See https://google.aip.dev/216. + Possible values: + STATE_UNSPECIFIED ACTIVE CREATING DELETING @@ -165,8 +174,10 @@ In addition to the arguments listed above, the following computed attributes are DELETE_FAILED * `reconciling` - - Whether reconciling is in progress, recommended per - https://google.aip.dev/128. + The current state of the resource does not match the user's intended state, + and the system is working to reconcile them. This part of the normal + operation (e.g. linking a new association to the parent group). + See https://google.aip.dev/128. * `terraform_labels` - The combination of labels configured directly on the resource diff --git a/website/docs/r/network_security_intercept_deployment_group.html.markdown b/website/docs/r/network_security_intercept_deployment_group.html.markdown index 4d593b67380..c2798778e29 100644 --- a/website/docs/r/network_security_intercept_deployment_group.html.markdown +++ b/website/docs/r/network_security_intercept_deployment_group.html.markdown @@ -16,12 +16,15 @@ # ---------------------------------------------------------------------------- subcategory: "Network Security" description: |- - A Deployment Group represents the collector deployments across different zones within an organization. + A deployment group aggregates many zonal intercept backends (deployments) + into a single global intercept service. --- # google_network_security_intercept_deployment_group -A Deployment Group represents the collector deployments across different zones within an organization. +A deployment group aggregates many zonal intercept backends (deployments) +into a single global intercept service. Consumers can connect this service +using an endpoint group. ~> **Warning:** This resource is in beta, and should be used with the terraform-provider-google-beta provider. See [Provider Versions](https://terraform.io/docs/providers/google/guides/provider_versions.html) for more details on beta resources. @@ -60,18 +63,18 @@ The following arguments are supported: * `network` - (Required) - Required. Immutable. The network that is being used for the deployment. Format is: - projects/{project}/global/networks/{network}. + The network that will be used for all child deployments, for example: + `projects/{project}/global/networks/{network}`. + See https://google.aip.dev/124. * `location` - (Required) - Resource ID segment making up resource `name`. It identifies the resource within its parent collection as described in https://google.aip.dev/122. See documentation for resource type `networksecurity.googleapis.com/InterceptDeploymentGroup`. + The cloud location of the deployment group, currently restricted to `global`. * `intercept_deployment_group_id` - (Required) - Required. Id of the requesting object - If auto-generating Id server-side, remove this field and - intercept_deployment_group_id from the method_signature of Create RPC + The ID to use for the new deployment group, which will become the final + component of the deployment group's resource name. - - - @@ -79,7 +82,7 @@ The following arguments are supported: * `labels` - (Optional) - Optional. Labels as key value pairs + Labels are key/value pairs that help to organize and filter resources. **Note**: This field is non-authoritative, and will only manage the labels present in your configuration. Please refer to the field `effective_labels` for all of the labels present on the resource. @@ -94,29 +97,36 @@ In addition to the arguments listed above, the following computed attributes are * `id` - an identifier for the resource with format `projects/{{project}}/locations/{{location}}/interceptDeploymentGroups/{{intercept_deployment_group_id}}` * `name` - - Output only. Identifier. Then name of the InterceptDeploymentGroup. + The resource name of this deployment group, for example: + `projects/123456789/locations/global/interceptDeploymentGroups/my-dg`. + See https://google.aip.dev/122 for more details. * `create_time` - - Output only. [Output only] Create time stamp + The timestamp when the resource was created. + See https://google.aip.dev/148#timestamps. * `update_time` - - Output only. [Output only] Update time stamp + The timestamp when the resource was most recently updated. + See https://google.aip.dev/148#timestamps. * `connected_endpoint_groups` - - Output only. The list of Intercept Endpoint Groups that are connected to this resource. + The list of endpoint groups that are connected to this resource. Structure is [documented below](#nested_connected_endpoint_groups). * `state` - - Output only. Current state of the deployment group. - Possible values: - STATE_UNSPECIFIED + The current state of the deployment group. + See https://google.aip.dev/216. + Possible values: + STATE_UNSPECIFIED ACTIVE CREATING DELETING * `reconciling` - - Output only. Whether reconciling is in progress, recommended per - https://google.aip.dev/128. + The current state of the resource does not match the user's intended state, + and the system is working to reconcile them. This is part of the normal + operation (e.g. adding a new deployment to the group) + See https://google.aip.dev/128. * `terraform_labels` - The combination of labels configured directly on the resource @@ -130,7 +140,9 @@ In addition to the arguments listed above, the following computed attributes are * `name` - (Output) - Output only. A connected intercept endpoint group. + The connected endpoint group's resource name, for example: + `projects/123456789/locations/global/interceptEndpointGroups/my-eg`. + See https://google.aip.dev/124. ## Timeouts diff --git a/website/docs/r/network_security_intercept_endpoint_group.html.markdown b/website/docs/r/network_security_intercept_endpoint_group.html.markdown index be9db7b9002..b1222dc45a6 100644 --- a/website/docs/r/network_security_intercept_endpoint_group.html.markdown +++ b/website/docs/r/network_security_intercept_endpoint_group.html.markdown @@ -16,12 +16,16 @@ # ---------------------------------------------------------------------------- subcategory: "Network Security" description: |- - An intercept endpoint group is a global resource in the consumer account representing the producer’s deployment group. + An endpoint group is a consumer frontend for a deployment group (backend). --- # google_network_security_intercept_endpoint_group -An intercept endpoint group is a global resource in the consumer account representing the producer’s deployment group. +An endpoint group is a consumer frontend for a deployment group (backend). +In order to configure intercept for a network, consumers must create: +- An association between their network and the endpoint group. +- A security profile that points to the endpoint group. +- A firewall rule that references the security profile (group). ~> **Warning:** This resource is in beta, and should be used with the terraform-provider-google-beta provider. See [Provider Versions](https://terraform.io/docs/providers/google/guides/provider_versions.html) for more details on beta resources. @@ -67,17 +71,18 @@ The following arguments are supported: * `intercept_deployment_group` - (Required) - Immutable. The Intercept Deployment Group that this resource is connected to. Format - is: - `projects/{project}/locations/global/interceptDeploymentGroups/{interceptDeploymentGroup}` + The deployment group that this endpoint group is connected to, for example: + `projects/123456789/locations/global/interceptDeploymentGroups/my-dg`. + See https://google.aip.dev/124. * `location` - (Required) - The location of the Intercept Endpoint Group, currently restricted to `global`. + The cloud location of the endpoint group, currently restricted to `global`. * `intercept_endpoint_group_id` - (Required) - ID of the Intercept Endpoint Group. + The ID to use for the endpoint group, which will become the final component + of the endpoint group's resource name. - - - @@ -85,7 +90,7 @@ The following arguments are supported: * `labels` - (Optional) - Optional. Labels as key value pairs + Labels are key/value pairs that help to organize and filter resources. **Note**: This field is non-authoritative, and will only manage the labels present in your configuration. Please refer to the field `effective_labels` for all of the labels present on the resource. @@ -100,27 +105,35 @@ In addition to the arguments listed above, the following computed attributes are * `id` - an identifier for the resource with format `projects/{{project}}/locations/{{location}}/interceptEndpointGroups/{{intercept_endpoint_group_id}}` * `name` - - Identifier. The name of the Intercept Endpoint Group. + The resource name of this endpoint group, for example: + `projects/123456789/locations/global/interceptEndpointGroups/my-eg`. + See https://google.aip.dev/122 for more details. * `create_time` - - Create time stamp. + The timestamp when the resource was created. + See https://google.aip.dev/148#timestamps. * `update_time` - - Update time stamp. + The timestamp when the resource was most recently updated. + See https://google.aip.dev/148#timestamps. * `state` - - Current state of the endpoint group. - Possible values: - STATE_UNSPECIFIED + The current state of the endpoint group. + See https://google.aip.dev/216. + Possible values: + STATE_UNSPECIFIED ACTIVE CLOSED CREATING DELETING OUT_OF_SYNC + DELETE_FAILED * `reconciling` - - Whether reconciling is in progress, recommended per - https://google.aip.dev/128. + The current state of the resource does not match the user's intended state, + and the system is working to reconcile them. This is part of the normal + operation (e.g. adding a new association to the group). + See https://google.aip.dev/128. * `terraform_labels` - The combination of labels configured directly on the resource diff --git a/website/docs/r/network_security_intercept_endpoint_group_association.html.markdown b/website/docs/r/network_security_intercept_endpoint_group_association.html.markdown index 0c127d6dc02..069f0fdf457 100644 --- a/website/docs/r/network_security_intercept_endpoint_group_association.html.markdown +++ b/website/docs/r/network_security_intercept_endpoint_group_association.html.markdown @@ -16,12 +16,19 @@ # ---------------------------------------------------------------------------- subcategory: "Network Security" description: |- - Creates an association between a VPC and an Intercept Endpoint Group in order to intercept traffic in that VPC. + An endpoint group association represents a link between a network and an + endpoint group in the organization. --- # google_network_security_intercept_endpoint_group_association -Creates an association between a VPC and an Intercept Endpoint Group in order to intercept traffic in that VPC. +An endpoint group association represents a link between a network and an +endpoint group in the organization. + +Creating an association creates the networking infrastructure linking the +network to the endpoint group, but does not enable intercept by itself. +To enable intercept, the user must also create a network firewall policy +containing intercept rules and associate it with the network. ~> **Warning:** This resource is in beta, and should be used with the terraform-provider-google-beta provider. See [Provider Versions](https://terraform.io/docs/providers/google/guides/provider_versions.html) for more details on beta resources. @@ -81,18 +88,19 @@ The following arguments are supported: * `intercept_endpoint_group` - (Required) - Immutable. The Intercept Endpoint Group that this resource is connected to. Format - is: - `projects/{project}/locations/global/interceptEndpointGroups/{interceptEndpointGroup}`. + The endpoint group that this association is connected to, for example: + `projects/123456789/locations/global/interceptEndpointGroups/my-eg`. + See https://google.aip.dev/124. * `network` - (Required) - Immutable. The VPC network associated. Format: - `projects/{project}/global/networks/{network}`. + The VPC network that is associated. for example: + `projects/123456789/global/networks/my-network`. + See https://google.aip.dev/124. * `location` - (Required) - The location of the Intercept Endpoint Group Association, currently restricted to `global`. + The cloud location of the association, currently restricted to `global`. - - - @@ -100,13 +108,15 @@ The following arguments are supported: * `labels` - (Optional) - Optional. Labels as key value pairs. + Labels are key/value pairs that help to organize and filter resources. **Note**: This field is non-authoritative, and will only manage the labels present in your configuration. Please refer to the field `effective_labels` for all of the labels present on the resource. * `intercept_endpoint_group_association_id` - (Optional) - ID of the Intercept Endpoint Group Association. + The ID to use for the new association, which will become the final + component of the endpoint group's resource name. If not provided, the + server will generate a unique ID. * `project` - (Optional) The ID of the project in which the resource belongs. If it is not provided, the provider project is used. @@ -119,22 +129,28 @@ In addition to the arguments listed above, the following computed attributes are * `id` - an identifier for the resource with format `projects/{{project}}/locations/{{location}}/interceptEndpointGroupAssociations/{{intercept_endpoint_group_association_id}}` * `name` - - Identifier. The name of the Intercept Endpoint Group Association. + The resource name of this endpoint group association, for example: + `projects/123456789/locations/global/interceptEndpointGroupAssociations/my-eg-association`. + See https://google.aip.dev/122 for more details. * `create_time` - - Create time stamp. + The timestamp when the resource was created. + See https://google.aip.dev/148#timestamps. * `update_time` - - Update time stamp. + The timestamp when the resource was most recently updated. + See https://google.aip.dev/148#timestamps. * `locations_details` - - The list of locations that are currently supported by the associated Intercept Deployment Group and their state. + The list of locations where the association is present. This information + is retrieved from the linked endpoint group, and not configured as part + of the association itself. Structure is [documented below](#nested_locations_details). * `state` - - Current state of the Intercept Endpoint Group Association. - Possible values: - STATE_UNSPECIFIED + Current state of the endpoint group association. + Possible values: + STATE_UNSPECIFIED ACTIVE CREATING DELETING @@ -143,7 +159,10 @@ In addition to the arguments listed above, the following computed attributes are DELETE_FAILED * `reconciling` - - Whether reconciling is in progress. + The current state of the resource does not match the user's intended state, + and the system is working to reconcile them. This part of the normal + operation (e.g. adding a new location to the target deployment group). + See https://google.aip.dev/128. * `terraform_labels` - The combination of labels configured directly on the resource @@ -157,13 +176,13 @@ In addition to the arguments listed above, the following computed attributes are * `location` - (Output) - Location supported by the Intercept Deployment Group, for example `us-central1-a` + The cloud location, e.g. `us-central1-a` or `asia-south1`. * `state` - (Output) - The association state in this location. - Possible values: - STATE_UNSPECIFIED + The current state of the association in this location. + Possible values: + STATE_UNSPECIFIED ACTIVE OUT_OF_SYNC