.. _cluster-ips-endpoint: Access external resources from Faculty ====================================== It's common practice to limit network traffic to sensitive resources like databases as an added layer of security on top of authentication methods like a username and password. By permitting access only from a set of whitelisted IP addresses, attackers are unable to even attempt to log in unless they have access to one of the approved computers. To enable users to impose this kind of network rule while permitting access from Faculty, we provide an API which returns the list of IP addresses where shared infrastructure Faculty servers run, at https://[domain-name].my.faculty.ai/api/cluster/ip-addresses. Replace ``[domain-name]`` with the URL that you use to access Faculty. .. note:: This endpoint returns IP addresses for 'shared infrastructure' servers, including workspace servers (e.g. Jupyter, RStudio), jobs, apps and APIs. It does **not** return IP addresses for 'dedicated infrastructure' servers, whose IP addresses change frequently. This API returns a JSON object containing the current IP addresses of the cluster, formatted as follows: .. code-block:: javascript { "ipAddresses": [ "101.2.3.4", "105.6.7.8" ] } .. warning:: The list of IP addresses will change as necessary software updates are applied or when the Faculty compute cluster is scaled in size. You should therefore not assume that the IPs do not change, but rather set up a periodic task that updates your relevant network rules. Scripting network rule updates ------------------------------ You can write scripts to automatically update network rules for access from Faculty with Python. For example, you can retrieve the IP addresses from the above API with the *requests* module: .. code-block:: python import requests response = requests.get('https://example.my.faculty.ai/api/cluster/ip-addresses') faculty_ips = response.json()['ipAddresses'] You can then write some code that uses a relevant API to update network rules. For example, on Amazon Web Services (AWS), you can use *boto3* to update AWS security group rules: .. code-block:: python import boto3 EC2 = boto3.resource('ec2') security_group = EC2.SecurityGroup('your-security-group-id') for ip_address in faculty_ips: cidr = '{}/32'.format(ip_address) security_group.authorize_ingress( IpProtocol='tcp', FromPort=5432, # For accessing a PostgreSQL database ToPort=5432, # For accessing a PostgreSQL database CidrIp=cidr ) You should be sure to implement logic to remove access rules from IPs that are no longer in the list retrieved from Faculty. .. toctree:: :hidden: update_faculty_aws_securitygroup .. note:: See :doc:`our example script ` for updating an AWS security group.