Networking Between Projects

Inside the organization, one project does not reach another over the internal network. A network groups projects that can be authorized to call each other, and a permission — given by whoever receives the call — opens one service to one project. Whatever nobody authorized stays blocked, even between projects in the same network.

How It Works

• The network belongs to the organization. A project joins it with one of its environments. To keep production apart from staging, use one network for each: a project's staging never reaches another project's production service just because both projects are in the same network.
• Being in the network opens nothing. It makes a permission possible and lets the services' internal names resolve.
• A permission is for one service — a web application or an internal service — on the port it announces, over TCP only. It is given in the destination project, and it is not transitive: if project A calls B and B calls C, A does not call C.
• The environment itself does not change. Services in the same environment keep calling each other as before.
• The public address stays public. A service published on the internet stays reachable at its public address, for anyone. For a project to be reachable only through the network, make it internal.
• A preview environment does not join a network.

Who Can Do What

Action	Who
Create or delete a network	The organization's admin or operator
Add an environment to a network	The organization's admin or operator
Take a project's environment out of the network	Whoever can change the project
Authorize a project to call a service	Whoever can change the project of the called service
Revoke a permission	Whoever can change the called project, or the calling one
See the networks and who is in them	Anyone in the organization

Which projects are in each network is visible to the whole organization, so you know whom to ask. Permissions and internal addresses show only for the projects you can see.

The States of a Permission

State	What it means
Not yet allowed	The permission exists; the platform has not applied it yet
Allowed	The source project reaches the service
Revocation in progress — access is still open	The permission was revoked; until the platform applies it, access continues
Revoked — new connections blocked	Applied. A new connection is refused

Revoking applies to new connections

A connection opened before the revocation — a database pool, a gRPC channel, a WebSocket — can stay alive until the destination service restarts. To end those as well, deploy the destination service again after the permission reaches Revoked.

Step by Step

In the Console

1. In Networks, in the organization, click New network. The name has 3 to 40 characters — lowercase letters, digits and hyphens, starting with a letter and not ending with a hyphen — and the description is optional.
2. In each project, on the Project network screen, use Add to network and pick the environment.
3. In the project that will be called, use Authorize project: pick the service and the Calling project. The port is the service's, and the permission follows it if it changes.
4. Follow the permission until Allowed.

With the CLI

zero networks create payments
zero networks attach <checkout-environment> --network payments
zero networks attach <api-environment> --network payments
zero services internal-name <api-service> api      # api.zero.internal
zero networks grant payments --from <checkout-project> --to <api-service> --wait
zero networks grants payments

--wait waits for the rule to be applied and exits with code 1 if the deadline passes (--timeout, 5 minutes by default). The complete commands are in CLI.

Calling the Service

By internal name and the service's port — for example, http://api.zero.internal:8080. The name resolves for any project in the network, but only a project with permission reaches the service: resolving is not reaching.

To give the network paths by prefix, such as /v1 and /v2 leading to different services, use a Gateway internal entry.

Taking an Environment Out of the Network, and Deleting the Network

• Taking an environment out of the network is refused while other projects call its services — by permission or by an internal entry path. Revoke those permissions and remove those paths first.
• A network can only be deleted empty: no attached environments and no internal entries.

Common Errors

Symptom	Cause	What to do
"The source project is not in this network"	The calling project has no environment in the network	Add one of its environments to the network and authorize again
"The destination service is not in this network"	The service's environment is in another network, or in none	Add the service's environment to this network, or use the network it is in
"That port is not the service's"	The port given is not the one the service announces	Omit the port: the permission uses the service's
"This service does not receive connections"	The destination is a continuous process or a scheduled task	Pick a web application or an internal service
"This project is already in this network with another environment"	A project joins a network with one environment only	Take the other environment out, or use one network per environment
"A preview environment does not join a network"	The chosen environment belongs to a pull request	Use a development, staging, or production environment
"Other projects still call services in this environment"	There are permissions or internal entry paths pointing to it	Revoke the permissions and remove the paths before detaching
"This network is still in use"	The network has environments or internal entries	Detach the projects and remove the entries before deleting
"Network rules are delayed"	The platform has not applied a change yet	It retries on its own; if it persists, repeat the operation in a few minutes

Next Steps

• Internal project: no internet address
• Internal name: the address on the network
• Gateway internal entries
• Networking between projects with the CLI