{"token_count": 2836} # Cloud Client IP Restrictions Client IP Restrictions restrict access to your Teleport Cloud cluster, allowing traffic only from the network ranges (CIDR blocks) you specify. You manage the allowlist with the `client_ip_restriction` resource, using `tctl`, the Teleport Terraform provider, or the Teleport Web UI. Managing the allowlist with `tctl` and the Teleport Terraform provider is available starting with Teleport 18.11.0. The Web UI is available in earlier versions. This guide covers how to: - Configure a Teleport role that can manage Client IP Restrictions. - Set the list of CIDR blocks allowed to connect to your Teleport Cloud cluster. - Check whether the restrictions are enforced. - Disable the restrictions. ## How it works `client_ip_restriction` is a singleton resource: each Teleport Cloud cluster has exactly one, and its name is always `client-ip-restriction`. Its `spec.allowed_cidrs` field holds the list of CIDR blocks permitted to connect to the cluster. An empty list disables restrictions and allows all traffic. When you save an allowlist, Teleport Cloud enforces it at the cluster's ingress layer: only clients whose source IP falls within one of the allowed CIDR blocks can reach the cluster. Changes take 5-20 minutes to propagate and terminate existing connections that no longer match the allowlist. The resource's `status.state` field reflects the current enforcement state: | State | Meaning | | --------- | ------------------------------------------------------------------------------------------------------------ | | `pending` | The allowlist has been saved and is being propagated to the ingress layer. Enforcement is not yet in effect. | | `active` | The allowlist is fully enforced at the ingress layer. Only IPs matching the allowlist can reach the cluster. | Access to read and modify the allowlist is governed by Teleport's RBAC system through the `client_ip_restriction` resource kind, and every change is recorded in the [audit log](https://goteleport.com/docs/reference/audit-events.md). ## Prerequisites --- FEATURE AVAILABILITY Client IP Restrictions are available to Teleport Cloud customers and are opt-in. Contact your account executive or support at [](mailto:support@goteleport.com) to enable the feature for your tenant. --- - A Teleport Cloud cluster. - A Teleport user with a role that can read and write the `client_ip_restriction` resource. The preset `editor` role has this access. To grant it to another role, follow [Step 1](#step-12-configure-rbac). - One of the following client tools for managing the `client_ip_restriction` resource: the `tctl` CLI or the [Teleport Terraform provider](https://goteleport.com/docs/configuration/terraform-provider.md). The Kubernetes Operator does not support the `client_ip_restriction` resource. To confirm that you can run `tctl` against your cluster: Check that you can connect to your Teleport cluster and verify that you can run `tctl` and `tsh` commands using your current credentials. 1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username. 2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not. **In an interactive shell:** Run the following command. By default, this triggers a multi-factor authentication prompt: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 18.10.0 CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` **On non-interactive environments:** If you are running `tsh` and `tctl` as an AI agent, in a CI/CD environment, or similar, make sure the `TELEPORT_IDENTITY_FILE` environment variable is assigned to a valid file path with credentials for your cluster. `tsh` and `tctl` read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you [set up Machine ID](https://goteleport.com/docs/machine-workload-identity/getting-started.md) to provision one automatically. When executing `tctl` commands with an identity file, you must pass the `--auth-server` flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, `tctl` connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to `3025` if you are contacting the Auth Service directly with `tctl`: ``` $ tctl status --auth-server=teleport.example.com:443 ``` For `tsh` commands that read an identity file, you must pass the `--proxy` flag, which points `tsh` to the address of the Teleport Proxy Service: ``` $ tsh status --proxy=teleport.example.com ``` Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file: ``` $ export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}" ``` Add the `--auth-server` or `--proxy` flags to all subsequent `tctl` and `tsh` commands. If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions. ## Step 1/2. Configure RBAC To read and modify Client IP Restrictions, a Teleport user needs permission to manage the `client_ip_restriction` resource. The preset `editor` role already has this access; if the user has the `editor` role, skip this step. Create a file called `client-ip-restriction-editor.yaml`: ``` kind: role version: v8 metadata: name: client-ip-restriction-editor spec: allow: rules: - resources: - client_ip_restriction verbs: - list - read - create - update - delete ``` Use `tctl` to create the role: ``` $ tctl create -f client-ip-restriction-editor.yaml ``` Assign the role to a user. Open the user resource in your editor, replacing `alice` with the Teleport username: ``` $ tctl edit users/alice ``` Add `client-ip-restriction-editor` to `spec.roles`, then save and close the editor to apply the change: ``` spec: roles: - access + - client-ip-restriction-editor ``` ## Step 2/2. Manage the IP allowlist --- AVOID LOCKING YOURSELF OUT A misconfigured allowlist can block all access to your cluster. Before you save changes, make sure the allowlist includes the network you are currently connecting from, as well as any third-party services that need to reach your cluster (CI/CD systems, identity providers, and so on). Teleport does not add these ranges automatically. --- **tctl** Create a file called `client-ip-restriction.yaml`: ``` kind: client_ip_restriction version: v1 metadata: name: client-ip-restriction spec: allowed_cidrs: - "203.0.113.0/24" - "198.51.100.10/32" ``` Replace the entries in `allowed_cidrs` with the CIDR blocks allowed to connect to your cluster. `metadata.name` must be `client-ip-restriction`; the resource is a singleton and no other name is accepted. Apply the allowlist: ``` $ tctl create client-ip-restriction.yaml client_ip_restriction has been created ``` If Client IP Restrictions already exist, `tctl create` reports an error. Use the `-f` flag to overwrite the current allowlist: ``` $ tctl create -f client-ip-restriction.yaml client_ip_restriction has been created ``` You can also edit the allowlist interactively. `tctl edit` opens the current resource in your editor and applies your changes when you save and exit: ``` $ tctl edit client_ip_restriction ``` **Terraform** Before you begin, set up the [Teleport Terraform provider](https://goteleport.com/docs/configuration/terraform-provider.md). Create a file called `client-ip-restriction.tf`: ``` resource "teleport_client_ip_restriction" "main" { version = "v1" metadata = { name = "client-ip-restriction" } spec = { allowed_cidrs = [ "203.0.113.0/24", "198.51.100.10/32", ] } } ``` Replace the entries in `allowed_cidrs` with the CIDR blocks allowed to connect to your cluster. `metadata.name` must be `client-ip-restriction`; the resource is a singleton and no other name is accepted. Apply the configuration: ``` $ terraform plan ... Plan: 1 to add, 0 to change, 0 to destroy. $ terraform apply ``` For the full list of supported fields, see the [`teleport_client_ip_restriction` resource reference](https://goteleport.com/docs/reference/infrastructure-as-code/terraform-provider/resources/client_ip_restriction.md). **Web UI** Log in to your Teleport Cloud account. Open the user dropdown menu on the top right of the navigation bar and select "Help & Support," then scroll down to the IP Allowlist section and add your CIDR blocks. If you do not see the IP Allowlist section, the feature has not been enabled for your account. See the [Prerequisites](#prerequisites) for how to enable it. ## Check the enforcement status Retrieve the resource to view the current allowlist and enforcement state: ``` $ tctl get client_ip_restriction ``` Example output: ``` kind: client_ip_restriction version: v1 metadata: name: client-ip-restriction spec: allowed_cidrs: - 203.0.113.0/24 - 198.51.100.10/32 status: state: active ``` The allowlist is fully enforced when `status.state` is `active`. A `pending` state means the change is still propagating to the ingress layer, which can take up to 20 minutes. ## Disable Client IP Restrictions To allow traffic from all IP ranges again, either apply an allowlist with an empty `allowed_cidrs` list or delete the resource: ``` $ tctl rm client_ip_restriction client_ip_restriction has been deleted ``` With Terraform, remove the `teleport_client_ip_restriction` resource from your configuration and run `terraform apply`. ## Limitations - **Third-party service ranges.** Teleport does not add third-party service ranges automatically. Add allow rules for any third-party service that needs to access your Teleport cluster, such as CI/CD systems and identity providers. - **Network security.** The allowlist applies only to Teleport Cloud access. It does not replace your organization's network or firewall policies. - **Sync time.** Changes to the allowlist take 5-20 minutes to fully sync to the ingress layer. ## FAQ ### How many CIDR blocks can I configure? By default, up to 256 CIDR blocks. Contact your account executive or support to increase the limit. ### Do you support a denylist? Teleport Cloud Client IP Restrictions do not currently support a denylist. ### Can I manage Client IP Restrictions with the Kubernetes Operator? No. The Kubernetes Operator does not support the `client_ip_restriction` resource. Use `tctl`, the Terraform provider, or the Web UI instead. ## Next steps - Review the [role resource reference](https://goteleport.com/docs/reference/access-controls/roles.md) to define more precise RBAC for managing Client IP Restrictions. - Learn how Teleport records changes to the allowlist in the [audit events reference](https://goteleport.com/docs/reference/audit-events.md).