Restrict your pipeline traffic to specific IP ranges

3 days ago4 min read
Last updated • Read time
Cloud
This document is applicable to CircleCI Cloud

Enable CircleCI jobs to go through a set of well-defined IP address ranges. This can be useful if you are interacting with systems that are not public, for example:

  • Accessing a private artifact repository.

  • Testing internal systems.

  • Interfacing with a system on a cloud service: Google Cloud, AWS, Azure, etc.

Introduction

IP ranges is a feature for CircleCI customers who need to configure IP-based access to their restricted environments using existing workflows and platforms. As part of this feature, CircleCI provides a list of well-defined IP address ranges associated with the CircleCI service. CircleCI jobs that have the IP ranges feature enabled will have their traffic routed through one of the defined IP address ranges during job execution.

IP ranges is available to customers on a Performance or Scale Plan.

Use of the IP ranges feature consumes 450 credits from your account for each 1 GB of data used for jobs with IP ranges enabled.

IP ranges use cases

Enabling IP ranges for a job limits inbound connections to your infrastructure to IP address ranges that are verifiably associated with CircleCI.

Some examples of when IP-based restricted access might be desired include the following:

  • Accessing private artifact repositories.

  • Pulling dependencies from a CocoaPods proxy hosted behind a firewall.

  • Running test cases on an internal environment.

  • Performing integration testing against private AWS resources.

  • Deploying an internal app with sensitive data.

  • Granting access to a production network.

Examples of enabling IP ranges for a job

Example configuration file using IP ranges

version: 2.1

jobs:
  build:
    circleci_ip_ranges: true # opts the job into the IP ranges feature
    docker:
      - image: cimg/ruby:3.2.2
    steps:
      - run: echo “Hello World”
workflows:
  build-workflow:
    jobs:
      - build

Example configuration file using IP ranges with pipeline parameters.

Use conditional logic to control when IP ranges is enabled with pipeline parameters. You can set the pipeline parameter ip_ranges to true to enable IP ranges for the build job. For more information on triggering pipelines with pipeline parameters, see the Trigger a pipeline page.

version: 2.1

parameters:
  ip_ranges:
    type: boolean
    default: false

jobs:
  build:
    # opts the job into the IP ranges feature when the pipeline parameter pipeline.parameters.ip_ranges is true
    circleci_ip_ranges: << pipeline.parameters.ip_ranges >>
    docker:
      - image: cimg/ruby:3.2.2
    steps:
      - run: echo “Hello World”
workflows:
  build-workflow:
    jobs:
      - build

List of IP address ranges associated with the IP ranges feature

Last updated: 2022-04-06

Jobs that have been opted into the IP ranges feature will have one of the following IP address ranges associated with them:

  • 3.228.39.90

  • 18.213.67.41

  • 34.194.94.201

  • 34.194.144.202

  • 34.197.6.234

  • 35.169.17.173

  • 35.174.253.146

  • 52.3.128.216

  • 52.4.195.249

  • 52.5.58.121

  • 52.21.153.129

  • 52.72.72.233

  • 54.92.235.88

  • 54.161.182.76

  • 54.164.161.41

  • 54.166.105.113

  • 54.167.72.230

  • 54.172.26.132

  • 54.205.138.102

  • 54.208.72.234

  • 54.209.115.53

Machine-consumable lists can be found by querying the DNS A records below:

  • IP address ranges for jobs: jobs.knownips.circleci.com.

  • IP address ranges for core services: core.knownips.circleci.com.

  • All IP address ranges: all.knownips.circleci.com.

To query these, you can use any DNS resolver. Here is an example using dig with the default resolver:

dig all.knownips.circleci.com A +short

Notifications of a change to this list will be sent out by email to all customers who have at least one job opted into the IP ranges feature. 30 days notice will be given before changes are made to the existing set of IP address ranges. This page and the machine-consumable list will also be updated when there are upcoming changes.

IP ranges feature pricing

Pricing is calculated based on the data usage of jobs opted into the IP ranges feature. It is possible to mix jobs with and without the IP ranges feature within the same workflow or pipeline. Data used to pull in the Docker image to the container before the job starts executing does not incur usage costs for jobs with IP ranges enabled.

Enabling IP ranges consumes 450 credits from your account for each GB of data used for jobs with IP ranges enabled.

IP ranges usage is visible in the Plan Usage section of the CircleCI app:

Screenshot showing the location of the IP ranges feature

On the Resources tab within the Job Details UI page, you can view approximations of network transfer for any Docker job, even those without the IP ranges feature enabled. This approximation can be used to predict the cost of enabling the IP ranges feature on a job without having to turn the feature on. See more details on the CircleCI blog. You can also view whether or not the job has IP ranges enabled by viewing the IP Ranges badge.

Screenshot showing the approximate network transfer

Known limitations

  • IP ranges is currently available for the Docker executor, not including remote_docker. Jobs that attempt to use the IP ranges feature with a Machine executor, or with setup_remote_docker, will fail with an error. See this Discuss post for details.

IP ranges for core CircleCI services

This section covers the IP ranges used by CircleCI core services. Core service IP ranges are separate from the IP ranges feature list, which is available here.

List of IP address ranges for core CircleCI services

The following list shows the IP address ranges for core CircleCI cloud services (used to trigger jobs, exchange information about users between CircleCI and GitHub/GitLab/Bitbucket):

  • 18.214.70.5

  • 52.20.166.242

  • 18.214.156.84

  • 54.236.156.101

  • 52.22.215.219

  • 52.206.105.184

  • 52.6.77.249

  • 34.197.216.176

  • 35.174.249.131

  • 3.210.128.175

AWS and GCP IP Addresses

The machines that execute all jobs on CircleCI’s platform, not just jobs opted into IP ranges, are hosted on the following platforms:

  • Amazon Web Services (AWS)

  • Google Cloud Platform (GCP)

  • CircleCI’s macOS cloud

An exhaustive list of IP addresses that CircleCI’s traffic may come can be found by looking up each cloud provider’s IP address ranges. AWS and GCP offer endpoints to find this information:

  • AWS: CircleCI uses the us-east-1 and us-east-2 regions.

  • GCP: CircleCI uses the us-east1 and us-central1 regions.

CircleCI macOS cloud

In addition to AWS and GCP (see above), CircleCI’s macOS cloud hosts jobs executed by machines. The following IP address ranges are used by CircleCI macOS Cloud:

  • 100.27.248.128/25

  • 100.29.139.128/25

  • 98.80.165.0/24

  • 38.23.41.0/24

  • 38.23.42.0/24

  • 38.23.43.0/24

  • 207.254.116.0/24

  • 207.254.118.0/24

  • 18.97.4.0/24

  • 18.97.6.0/24

  • 18.97.7.0/24

This list of IP Ranges can also be downloaded and saved using the following curl command:

curl -O https://circleci.com/docs/ip-ranges-list.json

IP ranges is the recommended method for configuring an IP-based firewall to allow traffic from CircleCI’s platform.

macOS builds are automatically restricted within the IP ranges listed here. In other words, you do not have to explicitly set circleci_ip_ranges: true for macOS builds.

macOS IP ranges are not included in the machine-consumable lists maintained in DNS. Refer to the list above for the most up-to-date macOS IP addresses. Information about changes to macOS IP ranges will be included in the changelog and will be sent to the technical contact(s) listed under Organization Settings  Overview.