Release Notes

Insight Point

Secure datasource discovery using an Insight Point running in your environment.

What is a Veza Insight Point?

An Insight Point is a lightweight connector running in your environment to enable the secure gathering of authorization metadata for resources that Veza cannot access directly. An Insight Point is typically deployed as a Docker container or VM OVA.

Insight Point Deployment Diagram.

Typically, you will want an Insight Point to enable secure discovery of services (such as Active Directory, Oracle Database, or SQL Server) that require connectivity from within your corporate network. The Insight Point will run within your network to query the internal-only data sources for authorization metadata and push that information to Veza securely.

When do I need an Insight Point?

Deploying an Insight Point for Veza is usually not required, but might be necessary:

  • When the resources to discover are not exposed publicly.

  • To discover databases and other services that do not have cloud-native APIs.

  • If your organization prohibits 3rd-party programmatic access to cloud service providers.

  • To discover on-premise Active Directory and SQL Server.

  • To relay webhooks to internal systems or private network destinations that are not accessible from the public internet.

Installation Options

  • Veza provides an installation script to install an Insight Point for common Linux distributions.

  • The Insight Point is also available as an OVA image suitable for Oracle Virtualbox or VMWare VSphere. This option can be preferable to Docker for Windows-based environments.

  • For AWS environments, see Deploy with AWS EC2 for instructions to start an Insight Point on AWS EC2.

After deploying the Insight Point, you can specify it when configuring an integration. Veza will use the Insight Point for secure collection and transmission of entity metadata.

Communication

The Insight Point establishes a persistent bidirectional tunnel to the Veza Control Plane using gRPC bidirectional streaming through a secure WebSocket. The Insight Point pulls discovery and extraction jobs from Veza's Control Plane, executes them against your internal data sources, and pushes the collected authorization metadata back to Veza's Control Plane. The bidirectional communication also allows Veza's Control Plane to push a limited set of operations to the Insight Point by sending the correct message (eg. Credential validation, Webhook relaying).

Time Synchronization Requirements

Insight Points require accurate time synchronization to communicate properly with the Veza platform. Time drift can cause workflow timeouts and authentication failures. We recommend:

  • Synchronizing the Insight Point host system clock to actual time

  • A configured and running NTP service on the Insight Point Host

  • Reliable NTP servers configured, for example using pool.ntp.org or your organization's NTP servers for redundancy

Verification:

System Requirements

Before deploying an Insight Point, ensure your environment meets the following minimum requirements:

Resource
Minimum Requirement

CPU

2 cores

Memory

4 GB RAM

Storage

20 GB available disk space

Network

Outbound HTTPS (port 443) access to Veza tenant and ECR

Architecture

linux/amd64 or linux/arm64

Note: These are minimum requirements for typical deployments. For large data sources, see Known Issues for additional resource recommendations. If you experience performance issues or timeouts during data collection, consider increasing CPU and memory allocation. Contact Veza support for guidance on resource scaling for your specific environment.

Generating an Insight Point key

Log in to Veza with an administrator account, and create a registration key by browsing to Integrations > Insight Points:

  1. Click Create

  2. Enter a Name

  3. Click Generate Key

  4. Copy the key for use when running the docker image

Save the Insight Point key in a secure location. If lost, there is no way to recover it.

High Availability Mode

Insight Points support high availability by running multiple instances with the same registration key. This configuration ensures continuous operation even if individual instances become unavailable.

How it works

Multiple Insight Point instances using the same registration key form a high-availability cluster. The Veza Control Plane automatically distributes work across available instances and monitors their health through regular heartbeat checks. If an instance becomes unavailable, the Control Plane seamlessly redirects work to healthy instances without interrupting data collection or webhook relay operations.

Configuration

To enable high availability:

  1. Deploy multiple Insight Point instances in your environment

  2. Configure each instance with the same registration key but a unique instance ID

  3. Ensure all instances can communicate with the Veza tenant on port 443

  4. Monitor instance health through the Veza UI under Integrations > Insight Points

For deployment-specific instructions, see:

Best practices

  • Deploy at least two instances for basic high availability

  • Distribute instances across different availability zones or data centers when possible

  • Ensure each instance meets the system requirements

  • Configure event subscriptions to receive alerts when instances become degraded or unavailable

  • Verify all instances have proper time synchronization configured to prevent "Out of Sync" status

Failover behavior

When an Insight Point instance fails to respond to health checks for several minutes, the Control Plane marks it as unavailable and stops routing work to it. Active jobs on the failed instance may time out and will be automatically retried on healthy instances. Once the failed instance recovers and begins responding to health checks, it is automatically reintegrated into the cluster and begins receiving work again.

The overall Insight Point status reflects the health of all instances: OK when all are healthy, Degraded when some are unavailable, and Unavailable when all instances are offline.

Known Issues

Large Data Source Extractions

When connecting to very large data sources—such as Active Directory domains with 100,000+ users or databases with extensive metadata—Insight Points may experience instability during data extraction. In this case, standard minimum resources may be insufficient, leading to performance issues or service interruptions.

If the Insight Point becomes unresponsive during extraction jobs, requires manual restart to resume operation, or extraction jobs timeout before completing, these symptoms typically indicate that the Insight Point is struggling with resource constraints when processing data.

To address these issues, consider increasing resource allocation significantly beyond the minimum requirements. For Active Directory environments with 300,000+ entities, use a minimum of 8 GB RAM, 2 CPU cores, and 40 GB storage. Monitor the Insight Point container logs for memory exhaustion or resource-related errors that can help identify the root cause of stability issues.

  • Ensure the network connection between the Insight Point and target systems is stable throughout long-running extraction processes. Network interruptions can cause extraction failures that require restarting the entire process.

  • For organizations with 9 or more Active Directory domains, consider deploying multiple Insight Points to distribute processing load across instances.

  • For particularly large environments, contact Veza support for specific resource sizing recommendations and potential optimizations tailored to your deployment.

Troubleshooting

Insufficient Resources

Ensure the Insight Point meets the system requirements. The instance must have at least 2 CPU cores and 4 GB RAM allocated.

Refer to specific deployment guides for detailed troubleshooting steps.

Duplicate Instance ID in High Availability Configuration

When running multiple Insight Point instances for high availability, you may encounter a connection error if instances are configured with the same instance ID.

Error message:

Cause: Multiple Insight Point instances are attempting to connect using the same instance ID. Each instance in an HA configuration must have a unique instance ID while sharing the same registration key.

Resolution: Ensure each Insight Point instance is configured with a unique instance ID. Refer to your deployment method's documentation for instructions on setting the instance ID:

After updating the instance ID, restart the affected Insight Point instance.

Checking connectivity

The Insight Point automatically checks for connectivity on container start. This includes steps to resolve the DNS and verify TCP and HTTP communication. If there are connection problems, the container logs will indicate if a connection was refused, a host could not be found, or there is another issue.

Insight Point status

The Veza platform tracks the health of each Insight Point and its instances. An Insight Point can run multiple instances for high availability, and the overall Insight Point status is determined by the health of all its instances.

Insight Point statuses:

Status
Description

OK

All Insight Point instances are online and functioning normally

Degraded

Some instances are online while others are unavailable or out of sync. The Insight Point has partial availability

Unavailable

All Insight Point instances are offline or unreachable

Unknown

Status cannot be determined (typically only seen during initial setup)

Individual instance statuses:

Status
Description

OK

Instance is online and responding to health checks

Unavailable

Instance is offline or not responding to health checks

Out of Sync

Instance is responding but has time drift issues. The system clock is not properly synchronized with the control plane

Unknown

Status cannot be determined

An Insight Point instance is considered unavailable if it fails to respond to health checks for several minutes (determined by the heartbeat interval and offline strike threshold). Time drift is detected when an instance's system clock differs significantly from the control plane time, which can cause authentication failures and workflow issues.

You can view the status of your Insight Points in the Veza UI under Integrations > Insight Points.

Monitoring Insight Point availability

The Veza platform monitors Insight Point status and emits events when connectivity or synchronization issues are detected. To reduce the number of times events trigger, the task manager will not re-emit the same event type for 24 hours. An administrator can configure event subscriptions to get email notifications when issues impact Veza data collection.

Note: If the Insight Point task manager service is restarted, events can be emitted sooner than the 24-hour window.

The platform emits three types of Insight Point monitoring events:

Insight Point Unavailable (Error)

  • Triggered when the entire Insight Point is completely unavailable

  • All instances are offline or unreachable

  • Severity: Error

Insight Point Degraded (Warning)

  • Triggered when some instances are online but others are unavailable or out of sync

  • The Insight Point has partial availability

  • Severity: Warning

Insight Point Instance Out of Sync (Warning)

  • Triggered when an instance has time drift issues

  • The instance is responding but its system time is not synchronized with the control plane

  • Resolution: Ensure NTP is properly configured on the Insight Point host and restart the instance

  • Severity: Warning

To enable email alerts for Insight Point issues:

  1. Use the Veza navigation menu to open Administration > Event Subscriptions

  2. Click Create Subscription

  3. On the Details tab, enter a descriptive name to communicate the alert purpose.

  4. On the Conditions tab:

    • Set Event Type to "Insight Point Unavailable", "Insight Point Degraded", or "Insight Point Instance Out of Sync" depending on which issues you want to monitor

    • Set Severity to "Error" (for Unavailable) or "Warning" (for Degraded/Out of Sync)

    • Set Category to "Integrations"

  5. On the Action → Send Alert tab, select or create an email Veza Action

  6. Click Create to save the subscription

You can create multiple subscriptions to monitor different severity levels or event types.

Example of Insight Point monitoring subscription

Changing an Insight Point

When modifying the Insight Point associated with an integration — for example, if the registration key is lost — you will need to re-enter the credentials and secrets for that integration configuration.

  • Follow the instructions to start another Insight Point with a new deployment key

  • On the Integrations page, edit the integration configuration to re-enter the credentials for each affected integration.

Ports and connectivity

The Insight Point will communicate out from the container VM to the Veza Tenant and targeted systems. Your implementation must enable traffic to and from the host on the required ports.

Also, the host must be able to communicate out to the ECR repository hosting the insight point image.

Required
Destination
Protocol
Port

yes

Veza Tenant

TCP

443

yes

public.ecr.aws

TCP

443

for AD

AD Domain Controller

TCP/UDP

636

for SQL

SQL Server

TCP

1433

  • The Insight Point must be able to communicate with https://<your-org>.vezacloud.com on outbound port 443. Ensure that firewalls allow outbound traffic to the Veza tenant domain.

  • For Active Directory and SQL Server: The Insight Point must be allowed to communicate with Active Directory Domain Controllers on port 636, and SQL Servers on port 1433.

  • For AWS RDS and Trino: To discover AWS RDS or Trino instances, you will need to add the Insight Point egress IP to the Security Groups Inbound rules. Do this for each of the instances to discover.

To add an entry for AWS RDS:

  1. Log in to the AWS account containing the resources to discover, and go to RDS > Databases

  2. Click the DB identifier and go to Connectivity & security > Security > VPC security groups

  3. Click Inbound rules > Edit inbound rules to set the IP address entry

  4. Click Add rule > Type (MySQL, Aurora or PostgreSQL) > Source (Custom)

  5. Enter the Insight Point egress IP

  6. Optionally enter a description and click Save rules

To add an entry for Trino:

  1. Log in to the AWS account containing the resources to discover, and go to EC2 > Security Groups

  2. Click the Security Group associated with your Trino instances and go to 'Inbound rules' > 'Edit inbound rules' to set the IP address entry

  3. Click 'Add rule' > Type (Custom TCP) > Port Range (8080 or your custom port) > Source (Custom) > enter the Insight Point egress IP

  4. Optionally enter a description, and save the rules

Webhook Relay

Insight Points can forward webhook requests from the Veza platform to destinations that are only accessible from the Insight Point's private network. This capability enables webhooks to reach internal systems, on-premises services, or private test endpoints that are not accessible from the public internet.

When to use Webhook Relay

Use webhook relay if you need to:

  • Send webhooks to internal systems not accessible from the public internet

  • Route webhook traffic through your private network for security or compliance requirements

  • Test webhook integrations using private endpoints during development

Security considerations

Important: Webhook relay is disabled by default for security reasons. When enabled:

  • Only explicitly allowed destinations can receive webhook requests

  • All webhook destinations must be added to the allowed hosts list

  • Invalid or unallowed destinations will be rejected

  • Invalid host patterns are logged and ignored (they don't prevent startup)

Allowed host formats

You can specify webhook destinations in multiple formats:

  • Exact domains: webhook.site, example.com

  • Wildcard domains: *.example.com, *.internal.company.com

  • IPv4 addresses: 172.17.0.100

  • IPv6 addresses: 2001:db8::1

  • CIDR ranges: 172.17.0.0/24, 10.0.0.0/8

  • IP wildcards: 172.17.0.*, 10.*

Multiple destinations can be specified as a comma-separated list:

Configuration

Webhook relay configuration varies by deployment method:

For detailed configuration instructions, consult the deployment-specific guide for your installation method.

PreviousPrerequisites and ConnectivityNextDeploying an Insight Point using the install script

Last updated

Was this helpful?