chore: import upstream snapshot with attribution

doc/source/ray-core/runtime_env_auth.md

@@ -0,0 +1,185 @@
+(runtime-env-auth)=
+# Authenticating Remote URIs in runtime_env
+
+This section helps you:
+
+* Avoid leaking remote URI credentials in your `runtime_env`
+* Provide credentials safely in KubeRay
+* Understand best practices for authenticating your remote URI
+
+## Authenticating Remote URIs
+
+You can add dependencies to your `runtime_env` with [remote URIs](remote-uris). This is straightforward for files hosted publicly, because you simply paste the public URI into your `runtime_env`:
+
+```python
+runtime_env = {"working_dir": (
+        "https://github.com/"
+        "username/repo/archive/refs/heads/master.zip"
+    )
+}
+```
+
+However, dependencies hosted privately, in a private GitHub repo for example, require authentication. One common way to authenticate is to insert credentials into the URI itself:
+
+```python
+runtime_env = {"working_dir": (
+        "https://username:personal_access_token@github.com/"
+        "username/repo/archive/refs/heads/master.zip"
+    )
+}
+```
+
+In this example, `personal_access_token` is a secret credential that authenticates this URI. While Ray can successfully access your dependencies using authenticated URIs, **you should not include secret credentials in your URIs** for two reasons:
+
+1. Ray may log the URIs used in your `runtime_env`, which means the Ray logs could contain your credentials.
+2. Ray stores your remote dependency package in a local directory, and it uses a parsed version of the remote URI–including your credential–as the directory's name.
+
+In short, your remote URI is not treated as a secret, so it should not contain secret info. Instead, use a `netrc` file.
+
+## Running on VMs: the netrc File
+
+The [netrc file](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html) contains credentials that Ray uses to automatically log into remote servers. Set your credentials in this file instead of in the remote URI:
+
+```bash
+# "$HOME/.netrc"
+
+machine github.com
+login username
+password personal_access_token
+```
+
+In this example, the `machine github.com` line specifies that any access to `github.com` should be authenticated using the provided `login` and `password`.
+
+:::{note}
+On Unix, name the `netrc` file as `.netrc`. On Windows, name the file as `_netrc`.
+:::
+
+The `netrc` file requires owner read/write access, so make sure to run the `chmod` command after creating the file:
+
+```bash
+chmod 600 "$HOME/.netrc"
+```
+
+Add the `netrc` file to your VM container's home directory, so Ray can access the `runtime_env`'s private remote URIs, even when they don't contain credentials.
+
+## Running on KubeRay: Secrets with netrc
+
+[KubeRay](kuberay-index) can also obtain credentials from a `netrc` file for remote URIs. Supply your `netrc` file using a Kubernetes secret and a Kubernetes volume with these steps:
+
+1\. Launch your Kubernetes cluster.
+
+2\. Create the `netrc` file locally in your home directory.
+
+3\. Store the `netrc` file's contents as a Kubernetes secret on your cluster:
+
+```bash
+kubectl create secret generic netrc-secret --from-file=.netrc="$HOME/.netrc"
+```
+
+4\. Expose the secret to your KubeRay application using a mounted volume, and update the `NETRC` environment variable to point to the `netrc` file. Include the following YAML in your KubeRay config.
+
+```yaml
+headGroupSpec:
+    ...
+    containers:
+        - name: ...
+          image: rayproject/ray:latest
+          ...
+          volumeMounts:
+            - mountPath: "/home/ray/netrcvolume/"
+              name: netrc-kuberay
+              readOnly: true
+          env:
+            - name: NETRC
+              value: "/home/ray/netrcvolume/.netrc"
+    volumes:
+        - name: netrc-kuberay
+          secret:
+            secretName: netrc-secret
+
+workerGroupSpecs:
+    ...
+    containers:
+        - name: ...
+          image: rayproject/ray:latest
+          ...
+          volumeMounts:
+            - mountPath: "/home/ray/netrcvolume/"
+              name: netrc-kuberay
+              readOnly: true
+          env:
+            - name: NETRC
+              value: "/home/ray/netrcvolume/.netrc"
+    volumes:
+        - name: netrc-kuberay
+          secret:
+            secretName: netrc-secret
+```
+
+5\. Apply your KubeRay config.
+
+Your KubeRay application can use the `netrc` file to access private remote URIs, even when they don't contain credentials.
+
+## Using Bearer Tokens for HTTPS Authentication
+
+As an alternative to using a `netrc` file, you can authenticate HTTPS remote URIs using bearer tokens. This is particularly useful when working with APIs that require OAuth2 or similar token-based authentication.
+
+Set the `RAY_RUNTIME_ENV_BEARER_TOKEN` environment variable with your bearer token:
+
+```bash
+export RAY_RUNTIME_ENV_BEARER_TOKEN="your_bearer_token_here"
+```
+
+Ray will automatically include this token in the `Authorization` header when downloading HTTPS URIs in your `runtime_env`:
+
+```python
+runtime_env = {"working_dir": "https://example.com/private/repo.zip"}
+```
+
+The bearer token will be sent as an `Authorization: Bearer your_bearer_token_here` header with the HTTPS request.
+
+### Running on KubeRay: Bearer Tokens with Secrets
+
+For KubeRay deployments, you can securely provide the bearer token using Kubernetes secrets:
+
+1\. Create a Kubernetes secret containing your bearer token:
+
+```bash
+kubectl create secret generic bearer-token-secret \
+  --from-literal=RAY_RUNTIME_ENV_BEARER_TOKEN="your_bearer_token_here"
+```
+
+2\. Expose the secret to your KubeRay application using environment variables. Include the following YAML in your KubeRay config:
+
+```yaml
+headGroupSpec:
+    ...
+    containers:
+        - name: ...
+          image: rayproject/ray:latest
+          ...
+          env:
+            - name: RAY_RUNTIME_ENV_BEARER_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: bearer-token-secret
+                  key: RAY_RUNTIME_ENV_BEARER_TOKEN
+
+workerGroupSpecs:
+    ...
+    containers:
+        - name: ...
+          image: rayproject/ray:latest
+          ...
+          env:
+            - name: RAY_RUNTIME_ENV_BEARER_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: bearer-token-secret
+                  key: RAY_RUNTIME_ENV_BEARER_TOKEN
+```
+
+3\. Apply your KubeRay config.
+
+Your KubeRay application will use the bearer token to authenticate HTTPS requests when downloading remote URIs in the `runtime_env`.
+