[client] update documentation with AWS security_group (ray-project#18905

) * [client] update documentation with AWS security_group * Update doc/source/cluster/ray-client.rst Co-authored-by: Ian Rodney <[email protected]> * lint Co-authored-by: Ian Rodney <[email protected]>
lmco · Sep 28, 2021 · 83a28cc · 83a28cc
1 parent 4d763d3
commit 83a28cc
Show file tree

Hide file tree

Showing 2 changed files with 125 additions and 2 deletions.
diff --git a/doc/source/cluster/config.rst b/doc/source/cluster/config.rst
@@ -109,6 +109,8 @@ Provider
             :ref:`region <cluster-configuration-region>`: str
             :ref:`availability_zone <cluster-configuration-availability-zone>`: str
             :ref:`cache_stopped_nodes <cluster-configuration-cache-stopped-nodes>`: bool
+            :ref:`security_group <cluster-configuration-security-group>`:
+                :ref:`Security Group <cluster-configuration-security-group-type>`
 
     .. group-tab:: Azure
 
@@ -130,6 +132,20 @@ Provider
             :ref:`project_id <cluster-configuration-project-id>`: str
             :ref:`cache_stopped_nodes <cluster-configuration-cache-stopped-nodes>`: bool
 
+.. _cluster-configuration-security-group-type:
+
+Security Group
+~~~~~~~~~~~~~~
+
+.. tabs::
+    .. group-tab:: AWS
+
+        .. parsed-literal::
+
+            :ref:`GroupName <cluster-configuration-group-name>`: str
+            :ref:`IpPermissions <cluster-configuration-ip-permissions>`:
+                - `IpPermission <https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_IpPermission.html>`_
+
 .. _cluster-configuration-node-types-type:
 
 Node types
@@ -923,6 +939,52 @@ If enabled, nodes will be *stopped* when the cluster scales down. If disabled, n
 * **Type:** Boolean
 * **Default:** ``True``
 
+.. _cluster-configuration-security-group:
+
+``provider.security_group``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. tabs::
+    .. group-tab:: AWS
+
+        A security group that can be used to specify custom inbound rules.
+
+        * **Required:** No
+        * **Importance:** Medium
+        * **Type:** :ref:`Security Group <cluster-configuration-security-group-type>`
+
+    .. group-tab:: Azure
+
+        Not available.
+
+    .. group-tab:: GCP
+
+        Not available.
+
+
+.. _cluster-configuration-group-name:
+
+``security_group.GroupName``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The name of the security group. This name must be unique within the VPC.
+
+* **Required:** No
+* **Importance:** Low
+* **Type:** String
+* **Default:** ``"ray-autoscaler-{cluster-name}"``
+
+.. _cluster-configuration-ip-permissions:
+
+``security_group.IpPermissions``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The inbound rules associated with the security group.
+
+* **Required:** No
+* **Importance:** Medium
+* **Type:** `IpPermission <https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_IpPermission.html>`_
+
 .. _cluster-configuration-node-config:
 
 ``available_node_types.<node_type_name>.node_type.node_config``

diff --git a/doc/source/cluster/ray-client.rst b/doc/source/cluster/ray-client.rst
@@ -62,9 +62,9 @@ Step 1: set up your Ray cluster
 
 First, you'll want to create a remote Ray cluster. Follow the directions in :ref:`ref-cluster-quick-start` to do this.
 
-If using the `Ray cluster launcher <cluster-cloud>`_, the remote cluster will be listening on port ``10001`` of the head node. If necessary, you can modify this port by setting ``--ray-client-server-port`` to the ``ray start`` `command <http://127.0.0.1:5500/doc/_build/html/package-ref.html#ray-start>`_.
+If using the :doc:`Ray cluster launcher <cloud>`, the remote cluster will be listening on port ``10001`` of the head node. If necessary, you can modify this port by setting ``--ray-client-server-port`` to the ``ray start`` `command <http://127.0.0.1:5500/doc/_build/html/package-ref.html#ray-start>`_.
 
-If not using the `Ray cluster launcher <cluster-cloud>`_, you can start the "Ray Client Server" manually on the head node of your remote cluster by running the following:
+If not using the :doc:`Ray cluster launcher <cloud>`, you can start the "Ray Client Server" manually on the head node of your remote cluster by running the following:
 
 .. code-block:: bash
 
@@ -77,6 +77,32 @@ Ensure that the Ray Client port on the head node is reachable from your local ma
 This means opening that port up by configuring security groups or other access controls (on  `EC2 <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/authorizing-access-to-an-instance.html>`_)
 or proxying from your local machine to the cluster (on `K8s <https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/#forward-a-local-port-to-a-port-on-the-pod>`_).
 
+.. tabs::
+    .. group-tab:: AWS
+
+        With the Ray cluster launcher, you can configure the security group
+        to allow inbound access by defining :ref:`cluster-configuration-security-group`
+        in your `cluster.yaml`.
+
+        .. code-block:: yaml
+
+            # An unique identifier for the head node and workers of this cluster.
+            cluster_name: minimal_security_group
+
+            # Cloud-provider specific configuration.
+            provider:
+                type: aws
+                region: us-west-2
+                security_group:
+                    GroupName: ray_client_security_group
+                    IpPermissions:
+                          - FromPort: 10001
+                            ToPort: 10001
+                            IpProtocol: TCP
+                            IpRanges:
+                                # This will enable inbound access from ALL IPv4 addresses.
+                                - CidrIp: 0.0.0.0/0
+
 Step 3: Run Ray code
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -99,6 +125,41 @@ Now, connect to the Ray Cluster with the following and then use Ray like you nor
 
    #....
 
+Alternative Approach: SSH Port Forwarding
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As an alternative to configuring inbound traffic rules, you can also set up
+Ray Client via port forwarding. While this approach does require an open SSH
+connection, it can be useful in a test environment where the
+``head_node_host`` often changes.
+
+First, open up an SSH connection with your Ray cluster and forward the
+listening port (``10001``).
+
+.. code-block:: bash
+
+  $ ray up cluster.yaml
+  $ ray attach cluster.yaml -p 10001
+
+Then, you can connect to the Ray cluster using  ``localhost`` as the
+``head_node_host``.
+
+.. code-block:: python
+
+   import ray
+
+   # This will connect to the cluster via the open SSH session.
+   ray.init("ray://localhost:10001")
+
+   # Normal Ray code follows
+   @ray.remote
+   def do_work(x):
+       return x ** x
+
+   do_work.remote(2)
+
+   #....
+
 Connect to multiple ray clusters (Experimental)
 -----------------------------------------------