Configuration analysis states

A Connectivity Test configuration analysis goes through a series of test states as it checks the configuration of each Google Cloud resource in a network path from a designated source to a designated destination. Use this reference to interpret these states.

For more information about Connectivity Tests, including details about live data plane analysis, see the overview.

Test states

A Connectivity Test configuration analysis provides data for the following test states in the order listed:

Initial state
Configuration checking state
Forwarding state
Transition state
Special state
Final state
Overall reachability result

Some of these states appear in every trace, while others only appear when testing the configuration of a specific Google Cloud resource or when performing a certain task.

The final state and the overall reachability result provide the most important test output.

In addition, test output can include metadata for Google Cloud resources that are associated with one or more of the states; for example, information about a virtual machine (VM) instance's name and IP address.

How the configuration analysis evaluates reachability

The configuration analysis simulates a test packet through a network path by verifying configurations for Google Cloud resources in that path. Some examples of invalid network configurations are a Cloud Load Balancing forwarding rule that has no backends or a network route that doesn't exist.

During the configuration checking state, Connectivity Tests collects information about network routes such as user-configured routes, dynamic routes based on BGP advertisements, or policy-based routes. The configuration analysis then chooses a network route based on applicability and order.

For the configuration checking state, verified means that Connectivity Tests confirms that a configuration for the Google Cloud resource tested is valid. The configuration allows the simulated test packet to continue through the network path being tested.

For ingress and egress firewall rules, verified means that the configuration analysis confirms that the firewall rule is valid. The firewall rule permits the simulated test packet to pass.

If Connectivity Tests determines that a configuration is invalid, the packet has a final state of Drop.

Overall reachability result

The configuration analysis provides an overall summary of reachability status, also known as a result. Results can have one of four values: Reachable, Unreachable, Ambiguous, and Undetermined.

Values table

The following table describes the value for each type of overall reachability result.

Overall reachability result	Description
`Reachable`	There are two possible scenarios. In both scenarios, Connectivity Tests does not find any configuration issues. Thus, both scenarios are considered `Reachable`. In the first scenario, the packet originating from the source is expected to reach its destination. The final state of one or more traces is `Deliver`. In the second scenario, the analysis is partially complete based on configurations where the user has permission. The final state of one or more traces is `Forward`.
`Unreachable`	The packet originating from the source is expected to be dropped before reaching its destination. The final state of all the traces is `Drop`.
`Ambiguous`	This result is returned if the source and destination endpoints do not uniquely identify the test location in the network, and the overall reachability result contains multiple traces with mixed `Reachable` and `Unreachable` states. In this case, the final states among multiple traces return different final states. The `Ambiguous` result doesn't apply to tests that contain only one trace.
`Undetermined`	Reachability could not be determined. The final state for one trace is `Forward` or `Abort`. For multiple traces, the final state is a combination of either `Forward` or `Abort`. The reachability from the source to the destination cannot be determined for one of the following reasons: The analysis is aborted due to a permission error. The user does not have read permission to the projects listed in the test. The analysis is aborted due to internal errors.

Multiple traces

Each configuration analysis can contain multiple traces, and the final state of these traces might not be the same. For example, a packet to the VIP for a Google Cloud load balancer might have n traces if there are n backend VM instances configured for the load balancer. These n traces might not have the same final states.

Because an analysis can produce multiple possible traces, the following is true:

If there is only one trace result, the overall reachability result is the same as the final state of the trace.
If there are multiple trace results, the overall reachability result is calculated based on the distribution of the final states contained in all of the traces.

Result metadata

In addition to the overall reachability result for traces, every test result contains the following metadata:

The time the test state for the test was verified
Error details of a test failure or cancellation
Trace details for each trace

Error details of a test failure or cancellation are shown as codes and messages displayed in the overall reachability result. For example, a test with a final state of Abort might show an error message such as Failed to pull initial config. An internal error occurred.

Initial state

During the initial state, the configuration analysis simulates starting from a network endpoint.

Message	Description
`START_FROM_INSTANCE`	The packet originated from a Compute Engine instance. `InstanceInfo` metadata was populated by Connectivity Tests.
`START_FROM_INTERNET`	The packet originated from the internet. `EndpointInfo` metadata was populated by Connectivity Tests.
`START_FROM_PRIVATE_NETWORK`	The packet originated from a VPC network or an on-premises network with an internal source IP address. If the source was a VPC network visible to the user, the `NetworkInfo` metadata was populated with network details by Connectivity Tests.
`START_FROM_CLOUD_FUNCTION`	The packet originated from a Cloud Run function. `CloudFunctionInfo` metadata was populated by Connectivity Tests.
`START_FROM_CLOUD_RUN_REVISION`	The packet originated from a revision of a Cloud Run service. `CloudRunRevisionInfo` metadata was populated by Connectivity Tests.
`START_FROM_APP_ENGINE_VERSION`	The packet originated from a version of an App Engine standard environment service. `AppEngineVersionInfo` metadata was populated by Connectivity Tests.

Final state

There are four final states: Drop, Abort, Forward, and Deliver. Each of the following sections has a table that contains messages and descriptions for each state.

Drop

Connectivity Tests dropped the simulated test packet because the test target was unreachable for the following reasons.

Message	Description
`UNKNOWN_EXTERNAL_ADDRESS`	The destination external address can't be resolved to a known target.
`FOREIGN_IP_DISALLOWED`	The VM instance can only send or receive a packet with a foreign IP address if `ip_forward` is enabled. In other words, the foreign IP address failed a spoof check.
`FIREWALL_RULE`	Dropped due to a firewall rule unless allowed due to connection tracking. Connectivity Tests might deny a test packet because the packet matches a blocking firewall rule. However, the actual data plane might allow the packet through due to connection tracking on the firewall rule. Connection tracking allows packets for an existing connection to return in spite of the firewall rule.
`NO_ROUTE`	Dropped due to no routes.
`ROUTE_BLACKHOLE`	Dropped because the next hop of the matched route doesn't exist.
`ROUTE_WRONG_NETWORK`	The packet was sent to the wrong (unintended) network, as shown in Detect invalid or inconsistent configurations.
`PRIVATE_TRAFFIC_TO_INTERNET`	A packet with an internal destination address was sent to an internet gateway.
`PRIVATE_GOOGLE_ACCESS_DISALLOWED`	A VM instance with only an internal IP address tried to access a Google API or Google service, but Private Google Access was not enabled.
`NO_EXTERNAL_ADDRESS`	A VM instance with only an internal IP address tried to access external hosts through a route whose next hop is the default internet gateway. Expected when Cloud NAT is not enabled in the subnet or when there's no other default route that uses a different type of next hop (such as a proxy VM).
`UNKNOWN_INTERNAL_ADDRESS`	A destination internal address could not be resolved to a known target.
`FORWARDING_RULE_MISMATCH`	A forwarding rule's protocol and ports did not match the packet header, or the packet does not originate from or is not directed to the same region as the regional load balancer.
`FORWARDING_RULE_NO_INSTANCES`	A forwarding rule did not have backends configured.
`FIREWALL_BLOCKING_LOAD_BALANCER_BACKEND_HEALTH_CHECK`	A firewall rule blocked the health check probes to the backends and caused the backends to be unavailable for traffic from the load balancer. As part of its testing sequence for Cloud Load Balancing, the configuration analysis verifies that existing firewall rules have been configured to allow a health check probing packet to be sent to the Cloud Load Balancing backends. This configuration check results in a `healthCheckFirewallState`. For details, see Health check firewall rules.
`INSTANCE_NOT_RUNNING`	A packet was sent from or to a VM instance that was not in a running state.
`TRAFFIC_TYPE_BLOCKED`	The type of traffic was blocked and the user could not configure a firewall rule to enable it. For details, see Always blocked traffic.
`GKE_MASTER_UNAUTHORIZED_ACCESS`	Access to the Google Kubernetes Engine control plane endpoint was not authorized. For details, see Access to the cluster endpoints.
`DROPPED_INSIDE_GKE_SERVICE`	A packet was dropped inside the Google Kubernetes Engine service.
`CLOUD_SQL_INSTANCE_UNAUTHORIZED_ACCESS`	Access to the Cloud SQL instance endpoint is not authorized. For details, see Authorizing with authorized networks.
`DROPPED_INSIDE_CLOUD_SQL_SERVICE`	A packet was dropped inside the Cloud SQL service.
`GOOGLE_MANAGED_SERVICE_NO_PEERING`	A packet was dropped because there is no peering between the originating network and the Google-managed services network.
`CLOUD_SQL_INSTANCE_NO_IP_ADDRESS`	A packet was dropped because the Cloud SQL instance has neither a private nor a public IP address.
`PSC_CONNECTION_NOT_ACCEPTED`	A packet was dropped because the connection to the published service that uses Private Service Connect is not accepted.
`CLOUD_FUNCTION_NOT_ACTIVE`	A packet was dropped because the Cloud Run function is not active.
`VPC_CONNECTOR_NOT_SET`	A packet was dropped because the App Engine standard environment service, the Cloud Run function, or the Cloud Run revision doesn't have a Serverless VPC Access connector configured.
`VPC_CONNECTOR_NOT_RUNNING`	A packet was dropped because the Serverless VPC Access connector is not running.
`CLOUD_RUN_REVISION_NOT_READY`	A packet was dropped because the Cloud Run revision is not ready and cannot serve traffic.

Abort

The configuration analysis was stopped because of lack of basic information, such as lack of access to the network configuration.

This state usually happens when Connectivity Tests does not have the correct permissions to obtain the configuration from the host project for a service project, as shown in the following table.

Message	Description
`UNKNOWN_NETWORK`	Aborted due to an unknown network. The analysis cannot proceed because, in a Shared VPC network, the user running the test does not have access to the host project's network configurations, including firewall rules and routes. Running a Connectivity Test requires that the user running the test can read configurations for resources such as routes in the host project. This happens because network resources are allocated in the host project, but the actual resources exist in the service project.
`UNKNOWN_IP`	The analysis aborted because the IP addresses required for analysis were unknown. This is due to incorrect user input, or the configuration analysis could not determine a valid endpoint based on the provided input parameters. In a Shared VPC network, the user running the test did not have access to the host project's network configurations. This access is required for testing against IP addresses in the service project.
`UNKNOWN_PROJECT`	The analysis aborted because no project information could be derived from the input to the Connectivity Test. This is due to incorrect user input or, based on the provided input parameters, the analysis could not determine a valid project.
`PERMISSION_DENIED`	The analysis was aborted because the user lacked the permission to access all or part of the network configurations required to run the test.
`NO_SOURCE_LOCATION`	The analysis aborted because no valid source endpoint could be derived from the test input. This is due to incorrect user input or, based on the provided input parameters, the analysis could not determine a valid source endpoint.
`INVALID_ARGUMENT`	The analysis aborted because the source and/or destination endpoint specified in the test input were invalid. The possible reasons for this message include the following: A malformed IP address A non-existent VM instance or network URI An IP address that is not in the range of the specified network URI A VM instance that doesn't own the network interface in the specified network
`NO_EXTERNAL_IP`	The analysis aborted because traffic was sent from a public IP address to a VM instance that did not have an external IP address.
`UNINTENDED_DESTINATION`	The analysis aborted because none of the traces were able to match the destination information specified in the test input.
`TRACE_TOO_LONG`	The analysis aborted because the number of steps in the trace exceeded a certain limit. This issue might be caused by a routing loop.
`INTERNAL_ERROR`	Aborted due to internal server error.
`SOURCE_ENDPOINT_NOT_FOUND`	Aborted because the source endpoint could not be found.
`MISMATCHED_SOURCE_NETWORK`	Aborted because the source network does not match the source endpoint.
`DESTINATION_ENDPOINT_NOT_FOUND`	Aborted because the destination endpoint could not be found.
`MISMATCHED_DESTINATION_NETWORK`	Aborted because the destination network does not match the destination endpoint.

Forward

The analysis stopped at a specific endpoint and could go no further:

The analysis is partially complete based on configurations where the user has permission.
The test packet was forwarded to a network with an unknown configuration.
The test target has not been dropped according to the known configuration, and the test packet has been forwarded to a network where Connectivity Tests has no visibility.

Message	Forwarded
`PEERING_VPC`	To a peer VPC network
`VPN_GATEWAY`	To a Cloud VPN gateway
`INTERCONNECT`	To a Cloud Interconnect connection
`GKE_MASTER`	To a GKE control plane
`IMPORTED_CUSTOM_ROUTE_NEXT_HOP`	To the next hop of a custom route imported from a peered VPC network
`CLOUD_SQL_INSTANCE`	To a Cloud SQL instance

Deliver

The analysis was able to reach the target and deliver the simulated test packet.

A final state of Deliver does not guarantee that traffic can pass through the data plane. The purpose of the analysis is to validate configuration issues that might cause traffic to drop.

Message	Target
`INSTANCE`	A Compute Engine VM instance
`INTERNET`	The internet
`GOOGLE_API`	A Google API
`GKE_MASTER`	A GKE control plane
`CLOUD_SQL_INSTANCE`	A Cloud SQL instance
`PSC_GOOGLE_API`	All Google APIs and services that use Private Service Connect
`PSC_VPC_SC`	VPC Service Controls that use Private Service Connect
`PSC_PUBLISHED_SERVICE`	A published service that uses Private Service Connect

Metadata

The configuration analysis shows the following metadata for the final state.

Metadata name	Description
`AbortInfo`	Cause of an `Abort` final state and the resource URI that caused that state.
`DropInfo`	Cause of a `Drop` final state and the resource URI that caused that state.
`ForwardInfo`	The target type and target resource URI that a test packet was finally forwarded to (`Forward` final state).

Other states

Before the test packet reaches one of the final states, it goes through the following intermediate states: configuration checking state, forwarding state, transition state, and special state.

Configuration checking state

During the configuration checking state, Connectivity Tests checks the configuration of Google Cloud resources in the simulated network path, verifies that the resource configuration is valid, and verifies that the configuration allows the simulated test packet to continue on through the network path.

If needed, the configuration analysis performs a spoof check.

Message	Description
`APPLY_INGRESS_FIREWALL_RULE`	Verified ingress firewall rule.
`APPLY_EGRESS_FIREWALL_RULE`	Verified egress firewall rule.
`APPLY_ROUTE`	Verified route.
`APPLY_FORWARDING_RULE`	Matched forwarding rule.
`SPOOFING_APPROVED`	The packet was sent or received under a foreign IP address, but allowed. For details, see spoof checking.

Forwarding state

During the forwarding state, Connectivity Tests simulates a packet arriving at an intermediate Google Cloud resource in the testing path (for example, a packet arriving at a Cloud VPN gateway or a Google Cloud load balancer).

Message	Description
`ARRIVE_AT_INSTANCE`	Arrived at a Compute Engine VM instance.
`ARRIVE_AT_INTERNAL_LOAD_BALANCER`	Arrived at a Google Cloud load balancer that uses a private IP address as a VIP.
`ARRIVE_AT_EXTERNAL_LOAD_BALANCER`	Arrived at the public IP address of a Google Cloud load balancer.
`ARRIVE_AT_VPN_GATEWAY`	Arrived at a Cloud VPN gateway.
`ARRIVE_AT_VPN_TUNNEL`	Arrived at a Cloud VPN tunnel.
`ARRIVE_AT_VPC_CONNECTOR`	Arrived at a Serverless VPC Access connector.

Transition state

During the transition state, Connectivity Tests verifies simulated configurations where a packet is changed (for example, where Cloud NAT translates a packet header, or when a Google Cloud load balancing proxy terminates and reinitiates an inbound TCP session to VM instances).

Message	Description
`NAT`	The packet header was translated.
`PROXY_CONNECTION`	The original connection was terminated, and a new proxied connection was initiated.

Special state

In this state, a test viewer does not have permission to view one or more Google Cloud resources. For more information, see Test permissions.

Metadata name	Description
`VIEWER_PERMISSION_MISSING`	The viewer of the test result does not have permission to see the configuration for the Google Cloud resource in this step.

Resource metadata

Connectivity Tests shows the following metadata for the Google Cloud resource configurations that it checks.

Metadata name	Description
`EndpointInfo`	Endpoints used for the test. Connectivity Tests obtains `EndpointInfo` from source and destination endpoints and validates the information by using the model for the data plane.
`FirewallInfo`	Metadata associated with a firewall rule.
`ForwardingRuleInfo`	Metadata associated with a VPC forwarding rule.
`InstanceInfo`	Metadata associated with a Compute Engine VM instance.
`LoadBalancerInfo`	Metadata associated with a Google Cloud load balancer.
`NetworkInfo`	Metadata associated with a VPC network.
`RouteInfo`	Metadata associated with a VPC network route.
`AppEngineVersionInfo`	Metadata associated with a version of an App Engine standard environment service.
`CloudRunRevisionInfo`	Metadata associated with a Cloud Run revision.
`CloudFunctionInfo`	Metadata associated with a Cloud Run function.
`VpcConnectorInfo`	Metadata associated with a Serverless VPC Access connector.