Skip to main content
Version: 19.x (unreleased)

Cloud Client IP Restrictions

Report an Issue

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 v19. 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:

StateMeaning
pendingThe allowlist has been saved and is being propagated to the ingress layer. Enforcement is not yet in effect.
activeThe 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.

Prerequisites​

Feature availability

Client IP Restrictions are available to Teleport Cloud customers and are opt-in. Contact your account executive or support at [email protected] 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.
  • One of the following client tools for managing the client_ip_restriction resource: the tctl CLI or the Teleport Terraform provider. 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 protected] 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 protected]
    tctl status
    Cluster  teleport.example.com
    Version  19.0.0-dev
    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 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.

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

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​