> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revyl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify and Troubleshoot AWS PrivateLink

> Confirm Revyl traffic reaches your service, fix common failures, and revoke access

<Info>
  **AWS PrivateLink is available on Enterprise plans.** Contact your Revyl
  account team or [support@revyl.ai](mailto:support@revyl.ai) to enable it for
  your organization before you start.
</Info>

## Verify the connection

Work through these in order. Each check rules out one layer.

<Steps>
  <Step title="Endpoint connection is Available">
    ```bash theme={null}
    aws ec2 describe-vpc-endpoint-connections \
      --region <service-region> \
      --filters Name=service-id,Values=<your-service-id> \
      --query "VpcEndpointConnections[].[VpcEndpointId,VpcEndpointOwner,VpcEndpointState]" \
      --output table
    ```

    Expect one row with owner `992382537093` (Revyl) and state `available`.
  </Step>

  <Step title="Targets are healthy in every zone">
    ```bash theme={null}
    aws elbv2 describe-target-health \
      --target-group-arn <your-target-group-arn> \
      --query "TargetHealthDescriptions[].[Target.Id,Target.AvailabilityZone,TargetHealth.State]" \
      --output table
    ```

    Every target should be `healthy`. With cross-zone load balancing on, one
    healthy target is enough for all zones.
  </Step>

  <Step title="Traffic is arriving at the NLB">
    In CloudWatch, under the `AWS/NetworkELB` namespace, watch `NewFlowCount` and
    `ActiveFlowCount` for your NLB while Revyl runs a check. On an NLB that only
    serves Revyl, a rise during the check means the PrivateLink leg works. On a
    shared NLB, your other clients keep these metrics busy, so they prove nothing
    about Revyl. Confirm Revyl's request in your target access logs at the time of
    the check instead. If your targets can parse it, proxy protocol v2 on the
    target group also works: its header carries the VPC endpoint ID. Targets that
    cannot parse proxy protocol reject every connection once it is on.

    `TCP_Target_Reset_Count` or `TCP_ELB_Reset_Count` spikes point at your targets
    or listener.
  </Step>

  <Step title="A real job succeeds">
    Ask Revyl to run the connectivity check again, then run a build or test that
    depends on the private service. Successful dependency resolution or API calls
    confirm DNS, routing, and TLS all line up.
  </Step>
</Steps>

## Common problems

<AccordionGroup>
  <Accordion title="Revyl cannot find my endpoint service">
    * Revyl's principal is missing from **Allow principals**, or has a typo.
    * The service is in a region other than `us-west-2` and `us-west-2` is not
      in its **Supported Regions**.
    * The service name you sent has a typo. Copy it from the console or from
      `describe-vpc-endpoint-service-configurations`.
  </Accordion>

  <Accordion title="The connection is stuck in Pending acceptance">
    Acceptance is required and the request has not been accepted yet. Accept
    it from **Endpoint connections**, or with
    `aws ec2 accept-vpc-endpoint-connections`. If you use the Terraform
    accepter resource, make sure it was applied.
  </Accordion>

  <Accordion title="Connections time out">
    The request reaches your side but nothing answers.

    * **AZ mismatch (services in `us-west-2`).** Your NLB has no subnet in
      `usw2-az2`. Compare AZ IDs, not names.
    * **NLB security group.** Turn off **Enforce inbound rules on PrivateLink
      traffic**. With it on, rules match the private IP of Revyl's client, so
      a rule that allows only your VPC CIDR blocks Revyl. The
      `SecurityGroupBlockedFlowCount_Inbound` metric counts these drops.
    * **Target security group or NACL.** Targets must accept traffic from the
      NLB on the target port.
    * **No healthy targets in `usw2-az2`.** With cross-zone load balancing off,
      Revyl's traffic is blackholed even while your other zones are healthy.
      Turn cross-zone on, or restore healthy capacity in `usw2-az2`. See
      [Cross-zone load balancing](/guides/privatelink/overview#cross-zone-load-balancing).
    * **Wrong port.** The listener port must match the port in the hostname
      list you sent Revyl.
  </Accordion>

  <Accordion title="Revyl sees 503s or slow responses, other clients do not">
    Usually an ALB behind your NLB with a zone imbalance. Revyl enters only
    through `usw2-az2`, so it sees that zone's targets, while your other
    clients are spread across every zone.

    * ALB target group with cross-zone off: check that `usw2-az2` has enough
      healthy targets. An empty zone returns `503` for every request.
    * ALB not enabled in `usw2-az2`: enable it there.
    * Long-lived connections stay on their original path after you fix the
      zone. Ask Revyl to rerun the job so it opens new connections.

    See [Fronting an Application Load Balancer](/guides/privatelink/overview#fronting-an-application-load-balancer).
  </Accordion>

  <Accordion title="Connection refused or reset">
    The NLB answered but the target rejected the connection. Confirm the
    service listens on the target group port, and that the target group
    protocol matches the listener (TCP to TCP, or TLS to TCP when the NLB
    terminates TLS).
  </Accordion>

  <Accordion title="Some requests never reach the endpoint">
    The hostname or port is not mapped to your endpoint.
    This often happens with redirects: a registry answers on one host and
    redirects downloads to another, or a Git server redirects to a different
    port. Send Revyl every hostname and port your clients follow.
  </Accordion>

  <Accordion title="TLS certificate errors">
    Clients connect using your real hostname, so your service's certificate
    must be valid for that hostname. If your certificate is issued by a private
    CA, the build or app must trust that CA. For builds, install it in your
    build setup; for apps under test, include it in the build you upload.
  </Accordion>

  <Accordion title="It worked, then stopped">
    * Someone rejected the connection or removed Revyl's principal.
    * The NLB lost a subnet, or the targets were replaced and are unhealthy.
    * A new hostname or port was introduced without being sent to
      Revyl.

    Check the endpoint connection state first, then target health.
  </Accordion>
</AccordionGroup>

## What to send Revyl support

When you contact [support@revyl.ai](mailto:support@revyl.ai) about a
PrivateLink issue, include:

* Your Revyl organization and endpoint service name.
* The hostname and port that fails, and the approximate time of the failure.
* The exact client error, for example the build log line or the app error.
* Output of the endpoint connection and target health checks above.

Do not send credentials, tokens, or certificate private keys.

## Offboarding

You can revoke Revyl's access at any time, without involving Revyl.

<Tabs>
  <Tab title="Immediate cut-off">
    Reject the endpoint connection. Traffic stops right away.

    ```bash theme={null}
    aws ec2 reject-vpc-endpoint-connections \
      --region <service-region> \
      --service-id <your-service-id> \
      --vpc-endpoint-ids <revyl-endpoint-id>
    ```
  </Tab>

  <Tab title="Planned removal">
    1. Tell your Revyl contact the date. Revyl removes your hostname routing and
       deletes the interface endpoint.
    2. Remove Revyl's principal from **Allow principals**.
    3. Delete the endpoint service and the NLB if nothing else uses them.
  </Tab>
</Tabs>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.