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

# Service-to-Service Calls

> Configure internal firewall rules for workload-to-workload communication. Covers service endpoint syntax, same-GVC and cross-GVC calls, and latency benefits.

## Overview

The [internal firewall](/reference/workload#internal) rules for a [workload](/reference/workload) can be configured to allow inbound access from other [workloads](/reference/workload) in the same [org](/reference/org).

Allowing this type of access decreases the latency of your [workloads](/reference/workload) by making the request in the most direct path possible and increases security by validating the client certificate of the remote workload. Calling the endpoint of a service follows a specific URL [syntax](#service-endpoint-syntax) that is comprised of the [workload](/reference/workload) name and [GVC](/reference/gvc) name.

## Prerequisites

* [Permissions](/reference/policy#permissions) to edit a [workload](/reference/workload).
* Optional:
  * [CLI](/cli-reference/installation) installed.

## Internal Firewall

The [internal firewall](/reference/workload#internal) settings are part of the firewall options of a [workload](/reference/workload) and can be set to one of the following types:

* `None`
  * No access is allowed to this [workload](/reference/workload) from other [workloads](/reference/workload).
* `Same GVC`
  * [Workloads](/reference/workload) running in the same [GVC](/reference/gvc) are allowed to access this [workload](/reference/workload).
* `Same Org`
  * [Workloads](/reference/workload) running in the same org are allowed to access this [workload](/reference/workload).
* `Specific Workloads`
  * Only specific [workloads](/reference/workload) listed in `inboundAllowWorkload`, including workloads from other GVC's,
    are allowed access to this workload.
  * With this rule selected, the [workload](/reference/workload) can be set to allow replicas of itself to access itself.
    Calling a
    workload using `localhost` doesn't require this setting and will force the request to
    the current workload. By using this setting and sending the request using the [service endpoint syntax](#service-endpoint-syntax),
    the request will be routed to all replicas instead of only the local one.

Only the ports listed in the workload containers array will be made accessible to other workloads.

<Note>Internal workload to workload traffic that spans GVC's may also span locations and will incur egress charges.</Note>

## Service Endpoint Syntax

Once inbound access has been allowed on a [workload](/reference/workload), the following syntax is used when calling the [workload](/reference/workload) from another [workload](/reference/workload):

```text Syntax theme={null}
http://WORKLOAD_NAME.GVC_NAME.cpln.local[:PORT]
```

* The `PORT` is optional, the first port listed in the target workloads container array will be used as the default port for `http` requests.
* Internal communications work with `gRPC`, `HTTP`, `HTTP2`, and `TCP`.
* Requests are initiated using plain text communication. A sidecar service will initiate TLS on behalf of the workload.
* Control Plane enforces Mutual-TLS for all internal workload-to-workload communications.
* Headers may optionally be used on the receiving workload to verify that the communication was encrypted.
* Only the ports listed in the workload containers array will be made accessible to other workloads.

## Setup Internal Firewall using the UI Console

To configure the internal firewall rules using the console:

1. Click `Workloads` in the left menu and click the [workload](/reference/workload) to be configured.
2. Click `Firewall Config` and scroll to the `Internal` section.
3. Click the `Inbound Allow Type` dropdown and select the inbound access for this [workload](/reference/workload).
4. Click the `Save` button at the bottom of the page.

After clicking save, the rule will be enforced within a minute and a new deployment of the [workload](/reference/workload) will be queued.

## Setup Internal Firewall using the CLI

To modify the internal firewall rule with the CLI, use the [workload edit](/cli-reference/commands/workload#workload-edit) command.

1. Running the following command will open the default text editor and show the metadata (in YAML) for the [workload](/reference/workload):

```bash theme={null}
cpln workload edit WORKLOAD_NAME --org ORG_NAME --gvc GVC_NAME
```

2. Scroll down to the section `internal` under the `firewallConfig` section
3. Update the `inboundAllowType` property to one of the following (case sensitive) values:
   * `none`
   * `same-gvc`
   * `same-org`
   * `workload-list`

If `workload-list` is selected, update the `inboundAllowWorkload` property with the names of the allowed workloads using the format:

```text Format theme={null}
/org/ORG_NAME/gvc/GVC_NAME/workload/WORKLOAD_NAME
```

<Note>
  If you want to allow the [workload](/reference/workload) the ability to call itself, the `WORKLOAD_NAME` will be the same as the name of the [workload](/reference/workload).
</Note>

4. Save the file. If the save is successful, the new rules will be applied within a minute and a deployment of the [workload](/reference/workload) will be queued.

## Quick Start

A quick start demonstrating service-to-service calls is available in the [Service-to-Service quickstart](/quickstart/quick-start-4-service-to-service).