Skip to main content

Project Peerings

Grant controlled private network access from workloads in one project to resources in another project within the same organization.

By default, projects are fully isolated — workloads in one project cannot reach resources in another. Project peerings let you create precise, auditable exceptions to this isolation.

How it works​

A project peering creates a one-way network policy that allows a source workload (or all workloads in a project) to reach a specific service and port in a target project. Peerings operate at the network level using Kubernetes NetworkPolicy — they do not create database credentials or secrets.

Supported source types: containers, cron jobs.

Supported target types: containers, PostgreSQL databases, PgBouncer connection poolers, MariaDB databases, Valkey instances, NATS clusters, custom services.

When a peering is Pending or Active, SailOps displays the internal endpoint that the source workload must use to reach the target service. When the peering allows a single port, the endpoint includes the port number so you can paste it directly:

<service>.<namespace>:<port>

When the peering allows several ports, the endpoint shows the host only (<service>.<namespace>) because there is no single port to pick.

Endpoint format

Managed pods are configured with a DNS search path that resolves <service>.<namespace> across projects. You do not need the full svc.cluster.local suffix — the short address shown in the peering is all you need.

One-way access

Peerings are directional. If project A needs to reach project B and project B needs to reach project A, you must create two separate peerings.

Prerequisites​

  • At least two projects in your organization
  • Maintainer permission on both the source and target projects
  • The target resource must expose at least one service port

Creating a peering​

  1. Navigate to Project Peerings in the organization sidebar
  2. Click Allow Access
  3. Configure the peering:
FieldDescription
FromThe project containing the workload that needs access
From workloadChoose Specific workload (only the workload you select) or All workloads (every workload in the project, including future ones)
To projectThe project containing the target resource
To resourceThe service to allow access to. For resources that expose several Kubernetes Services (e.g. a PostgreSQL cluster publishes a -rw primary), only eligible Services are listed.
PortThe specific TCP port to open
  1. Review the summary and the Endpoint preview at the bottom of the form — this is the address your source workload will use to reach the target
  2. Click Allow Access
All workloads scope

Choosing All workloads is a broader grant: every current and future managed workload in the source project can reach the selected target resource and port. Use Specific workload when only one workload needs access.

Peering statuses​

StatusDescription
PendingThe peering is being activated. Network policies are being applied.
ActiveThe peering is live. Traffic is allowed.
FailedActivation failed. The peering was safely rolled back.
RevokedThe peering was manually revoked or automatically cleaned up.
InvalidatedThe peering was invalidated because the source or target resource was deleted, or an organization boundary changed.

Revoking a peering​

You can revoke an active peering if you have Maintainer permission on either the source or the target project.

  1. Navigate to Project Peerings
  2. Find the peering in the list
  3. Click Revoke
  4. Confirm the revocation
caution

Revoking a peering immediately closes the private access. Existing connections may be interrupted.

Viewing peerings​

The peering list displays the source and target service names alongside each peering entry, making it easier to identify which workloads and resources are connected without opening individual peering details.

By default, only Pending and Active peerings are shown. Ended peerings (Revoked, Invalidated, Failed) are hidden because they no longer grant access. To see them, enable the Show ended peerings checkbox above the list.

For Pending and Active peerings, the list also shows the Endpoint column with the internal address. Click the copy button next to the endpoint to copy it to your clipboard. Revoked or invalidated peerings do not display an endpoint because the target may no longer exist.

Filtering peerings​

Use the filters at the top of the peering list to narrow results:

  • From — Filter by source project
  • To — Filter by target project
  • Status — Filter by peering status (Pending, Active, Failed, Revoked, Invalidated)
  • Show ended peerings — Include revoked, invalidated, and failed peerings in the list (disabled when a specific status filter is selected)

Limits​

ResourceLimit
Active peerings per organization100

Revocation reasons​

When a peering is revoked or invalidated, the reason is displayed:

ReasonDescription
Manually revokedA user revoked the peering
Creation failed safelyThe peering activation failed and was rolled back
Source deletedThe source workload was deleted
Target deletedThe target resource was deleted
Organization boundary changedA project was moved or organizational structure changed

Best practices​

1. Prefer specific workloads​

Use Specific workload scope to limit the blast radius. Only use All workloads when every workload in the source project genuinely needs access.

2. Use the minimum required port​

Only open the specific port needed. Do not create multiple peerings for ports you do not use.

3. Review peerings regularly​

Periodically audit active peerings and revoke any that are no longer needed.

4. Coordinate with your team​

Creating a peering requires Maintainer access on both projects. Coordinate with project maintainers before creating cross-project access.