Skip to content

IP ranges updates #9328

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Apr 29, 2025
Merged

IP ranges updates #9328

Changes from 4 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
dabfc61
update to IP ranges page
rosieyohannan Apr 7, 2025
fd8736d
sort out nav levels
rosieyohannan Apr 7, 2025
ecfa934
remove ip ranges changelog
rosieyohannan Apr 15, 2025
ad813fb
tiny wording change for clarity
rosieyohannan Apr 15, 2025
aa7d21a
changes from review
rosieyohannan Apr 16, 2025
e881c23
Merge branch 'master' into DOCSS-1751-ip-ranges-updates
rosieyohannan Apr 22, 2025
31700fe
update pipeline parameter name
rosieyohannan Apr 28, 2025
9a1dee8
Merge branch 'master' into DOCSS-1751-ip-ranges-updates
rosieyohannan Apr 28, 2025
fc0282d
Merge branch 'master' into DOCSS-1751-ip-ranges-updates
rosieyohannan Apr 29, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
130 changes: 62 additions & 68 deletions jekyll/_cci2/ip-ranges.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ contentTags:
platform:
- Cloud
---
= IP ranges
= Restrict your pipeline traffic to specific IP ranges
:page-description: Enable CircleCI jobs to go through a set of well-defined IP address ranges
:experimental:
:icons: font
Expand All @@ -12,33 +12,37 @@ contentTags:

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
* Accessing a private artifact repository.
* Testing internal systems.
* Interfacing with a system on a cloud service: Google Cloud, AWS, Azure, etc.

[#overview]
== 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 this feature enabled will have their traffic routed through one of the defined IP address ranges during job execution.
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.

The feature is available to customers on a link:https://circleci.com/pricing/[Performance or Scale Plan]. This feature consumes 450 credits from your account for each GB of data used for jobs with IP ranges enabled.
IP ranges is available to customers on a link:https://circleci.com/pricing/[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.

[#use-cases]
== IP ranges use cases

IP ranges let you limit inbound connections to your infrastructure to IP address ranges that are verifiably associated with CircleCI.
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:

Some example of where IP-based restricted access might be desired include:
* 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.

* 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]
== Example configuration file using IP ranges
=== Example configuration file using IP ranges

[,yaml]
----
Expand All @@ -58,9 +62,9 @@ workflows:
----

[#example-configuration-pipeline-parameters]
== Example configuration file using IP ranges with pipeline parameters.
=== Example configuration file using IP ranges with pipeline parameters.

Use conditional logic to control when IP ranges is enabled with pipeline parameters.
Use conditional logic to control when IP ranges is enabled with pipeline parameters. You can set the pipeline parameter `pipeline.parameters.ip_ranges` to `true` to enable IP ranges for the `build` job. FOr more information on triggering pipelines with pipeline parameters, see the xref:triggers-overview#[Trigger a pipeline] page.

[,yaml]
----
Expand All @@ -73,6 +77,7 @@ parameters:

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
Expand All @@ -85,7 +90,7 @@ workflows:
----

[#list-of-ip-address-ranges]
== List of IP address ranges associated with feature
== List of IP address ranges associated with the IP ranges feature

_Last updated_: 2022-04-06

Expand Down Expand Up @@ -115,43 +120,6 @@ Jobs that have been opted into the IP ranges feature will have one of the follow

NOTE: Jobs can use any of the address ranges above. It is also important to note that the address ranges are shared by all CircleCI customers who have opted into using the feature.

[#list-of-ip-address-ranges-for-core-services]
== List of IP address ranges for core services

These are the IP address ranges for core services (used to trigger jobs, exchange information about users between CircleCI and GitHub etc):

* 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

[#list-of-ip-address-ranges-changelog]
=== List of IP address ranges changelog

==== 2024-11-05

* Added support for parameters.

Use parameters like << pipeline.parameters.ip_ranges >> to determine if IP ranges should be enabled.

==== 2021-08-23

* Added new items to the list of IP address ranges for core services.

The machine-consumable lists have also been updated to reflect the new IP address ranges.

==== 2022-04-06

* Added and removed new IP addresses as part of enabling Docker pulls to go through the list of IP addresses.

The machine-consumable lists have also been updated to reflect the new IP address ranges.

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

* IP address ranges _for jobs_: `jobs.knownips.circleci.com`.
Expand All @@ -168,11 +136,11 @@ 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.

[#pricing]
== Pricing
== 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.

This feature consumes 450 credits from your account for each GB of data used 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:

Expand All @@ -182,18 +150,49 @@ On the *Resources* tab within the *Job Details* UI page, you can view approximat

image::resources-network-transfer.png[Screenshot showing the approximate network transfer]

[#known-limitations]
== Known limitations

* IP ranges is currently available for the xref:configuration-reference#machine[Docker executor], not including `remote_docker`. Jobs that attempt to use the IP ranges feature with a xref:configuration-reference#machine[Machine executor], or with `setup_remote_docker`, will fail with an error. See this link:https://discuss.circleci.com/t/fyi-jobs-that-use-the-ip-ranges-feature-and-remote-docker-will-begin-to-fast-fail-this-week/44639[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 <<list-of-ip-address-ranges,here>>.

[#list-of-ip-address-ranges-for-core-services]
=== 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]
== AWS and GCP IP Addresses
=== 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:

The machines that execute _all jobs_ on CircleCI's platform, not just jobs opted into IP ranges, are hosted on Amazon Web Services (AWS), Google Cloud Platform (GCP), and CircleCI's macOS Cloud (see below). An exhaustive list of IP addresses that CircleCI's traffic may come from on these cloud providers`' platforms can be found by looking up each cloud provider's IP address ranges. AWS & GCP offer endpoints to find this information.
* Amazon Web Services (AWS)
* Google Cloud Platform (GCP)
* CircleCI's macOS cloud

* link:https://ip-ranges.amazonaws.com/ip-ranges.json[AWS]: CircleCI uses the _us-east-1_ and _us-east-2_ regions
* link:https://www.gstatic.com/ipranges/cloud.json[GCP]: CircleCI uses the _us-east1_ and _us-central1_ regions
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:

CircleCI _does not recommend_ configuring an IP-based firewall based on the AWS or GCP IP addresses, as the vast majority are not CircleCI's machines. There is _no guarantee_ that the addresses in the AWS or GCP endpoints persist from day-to-day, as these addresses are reassigned continuously.
* link:https://ip-ranges.amazonaws.com/ip-ranges.json[AWS]: CircleCI uses the _us-east-1_ and _us-east-2_ regions.
* link:https://www.gstatic.com/ipranges/cloud.json[GCP]: CircleCI uses the _us-east1_ and _us-central1_ regions.

CircleCI _does not recommend_ configuring an IP-based firewall using the AWS or GCP IP addresses. The vast majority are not CircleCI's machines. CircleCI can _not guarantee_ that the addresses in the AWS or GCP endpoints persist from day-to-day, as these addresses are reassigned continuously.

[#circleci-macos-cloud]
== CircleCI macOS cloud
=== 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:

Expand Down Expand Up @@ -222,9 +221,4 @@ curl -O https://circleci.com/docs/ip-ranges-list.json

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 IPs. Information about changes to macOS IP ranges will be included in the link:https://circleci.com/changelog/[changelog] and will be sent to the technical contact(s) listed under menu:Organization Settings[Overview].

[#known-limitations]
== Known limitations

* IP ranges is currently available for the xref:configuration-reference#machine[Docker executor], not including `remote_docker`. Jobs that attempt to use the IP ranges feature with a xref:configuration-reference#machine[Machine executor], or with `setup_remote_docker`, will fail with an error. See this link:https://discuss.circleci.com/t/fyi-jobs-that-use-the-ip-ranges-feature-and-remote-docker-will-begin-to-fast-fail-this-week/44639[Discuss post] for details.
*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 link:https://circleci.com/changelog/[changelog] and will be sent to the technical contact(s) listed under menu:Organization Settings[Overview].