Skip to content

Commit b40640e

Browse files
Added docs for Config and Auth & update doc workflow
1 parent 1677fae commit b40640e

20 files changed

+1163
-308
lines changed

.github/workflows/release.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ jobs:
5353
- name: Run poetry build
5454
run: poetry build
5555
- name: Create new documentation
56-
run: poetry run pdoc --html -o docs src/codeflare_sdk && pushd docs && rm -rf cluster job utils && mv codeflare_sdk/* . && rm -rf codeflare_sdk && popd && find docs -type f -name "*.html" -exec bash -c "echo '' >> {}" \;
56+
run: poetry run pdoc --html -o docs/detailed-documentation src/codeflare_sdk && pushd docs/detailed-documentation && rm -rf cluster job utils && mv codeflare_sdk/* . && rm -rf codeflare_sdk && popd && find docs/detailed-documentation -type f -name "*.html" -exec bash -c "echo '' >> {}" \;
5757

5858
- name: Commit changes in docs
5959
uses: stefanzweifel/git-auto-commit-action@v4

README.md

Lines changed: 0 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -17,31 +17,6 @@ Full documentation can be found [here](https://project-codeflare.github.io/codef
1717

1818
Can be installed via `pip`: `pip install codeflare-sdk`
1919

20-
## CodeFlare SDK in a Kubernetes environment
21-
To create a Ray Cluster using the CodeFlare SDK in a Kubernetes environment an `ingress_domain` must be passed in the Cluster Configuration.
22-
This is used for the creation of the Ray Dashboard and Client ingresses.
23-
24-
`ingress_options` can be passed to create a custom Ray Dashboard ingress, `ingress_domain` is still a required variable for the Client ingress.
25-
An example of `ingress_options` would look like this.
26-
27-
```
28-
ingress_options = {
29-
"ingresses": [
30-
{
31-
"ingressName": "<ingress_name>",
32-
"port": <port_number>,
33-
"pathType": "<path_type>",
34-
"path": "<path>",
35-
"host":"<host>",
36-
"annotations": {
37-
"foo": "bar",
38-
"foo": "bar",
39-
}
40-
}
41-
]
42-
}
43-
```
44-
4520
## Development
4621

4722
### Prerequisites

docs/authentication.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Authentication via the CodeFlare SDK
2+
Currently there are four ways of authenticating to your cluster via the SDK.<br>
3+
Authenticating with your cluster allows you to perform actions such as creating Ray Clusters and Job Submission.
4+
5+
## Method 1 Token Authentication
6+
This is how a typical user would authenticate to their cluster using `TokenAuthentication`.
7+
```
8+
from codeflare_sdk.cluster.auth import TokenAuthentication
9+
10+
auth = TokenAuthentication(
11+
token = "XXXXX",
12+
server = "XXXXX",
13+
skip_tls=False,
14+
# ca_cert_path="/path/to/cert
15+
)
16+
auth.login()
17+
# log out with auth.logout()
18+
```
19+
Setting `skip_tls=True` allows interaction with an HTTPS server bypassing the server certificate checks although this is not secure.<br>
20+
You can pass a custom certificate to `TokenAuthentication` by using `ca_cert_path="/path/to/cert"` when authenticating provided `skip_tls=False`.
21+
22+
## Method 2 Kubernetes Config File Authentication (Default location)
23+
If a user has authenticated to their cluster by alternate means e.g. run a login command like `oc login --token=<token> --server=<server>` their kubernetes config file should have updated.<br>
24+
If the user has not specifically authenticated through the SDK by other means such as `TokenAuthentication` then the SDK will try to use their default Kubernetes config file located at `"/HOME/.kube/config"`.
25+
26+
## Method 3 Specifying a Kubernetes Config File
27+
A user can specify a config file via a different authentication class `KubeConfigFileAuthentication` for authenticating with the SDK.<br>
28+
This is what loading a custom config file would typically look like.
29+
```
30+
from codeflare_sdk.cluster.auth import KubeConfigFileAuthentication
31+
32+
auth = KubeConfigFileAuthentication(
33+
kube_config_path="/path/to/config",
34+
)
35+
auth.load_kube_config()
36+
# log out with auth.logout()
37+
```
38+
39+
## Method 4 In-Cluster Authentication
40+
If a user does not authenticate by any of the means detailed above and does not have a config file at `"/HOME/.kube/config"` the SDK will try to authenticate with the in-cluster configuration file.

docs/cluster-configuration.md

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# Ray Cluster Configuration
2+
3+
To create Ray Clusters using the CodeFlare SDK a cluster configuration needs to be created first.<br>
4+
This is what a typical cluster configuration would look like; Note: The values for CPU and Memory are at the minimum requirements for creating the Ray Cluster.
5+
6+
```
7+
from codeflare_sdk.cluster.cluster import Cluster, ClusterConfiguration
8+
9+
cluster = Cluster(ClusterConfiguration(
10+
name='ray-example', # Mandatory Field
11+
namespace='default', # Default None
12+
head_cpus=1, # Default 2
13+
head_memory=1, # Default 8
14+
head_gpus=0, # Default 0
15+
num_workers=1, # Default 1
16+
min_cpus=1, # Default 1
17+
max_cpus=1, # Default 1
18+
min_memory=2, # Default 2
19+
max_memory=2, # Default 2
20+
num_gpus=0, # Default 0
21+
mcad=True, # Default True
22+
image="quay.io/project-codeflare/ray:latest-py39-cu118", # Mandatory Field
23+
instascale=False, # Default False
24+
machine_types=["m5.xlarge", "g4dn.xlarge"],
25+
ingress_domain="example.com" # Default None, Mandatory for Kubernetes Clusters
26+
))
27+
```
28+
29+
Upon creating a cluster configuration with `mcad=True` an appwrapper will be created featuring the Ray Cluster and any Routes, Ingresses or Secrets that are needed to be created along side it.<br>
30+
From there a user can call `cluster.up()` and `cluster.down()` to create and remove the appwrapper thus creating and removing the Ray Cluster.
31+
32+
In cases where `mcad=False` a yaml file will be created with the individual Ray Cluster, Route/Ingress and Secret included.<br>
33+
The Ray Cluster and service will be created by KubeRay directly and the other components will be individually created.
34+
35+
## Ray Cluster Configuration in a Kubernetes environment
36+
To create a Ray Cluster using the CodeFlare SDK in a Kubernetes environment an `ingress_domain` must be passed in the Cluster Configuration.
37+
This is used for the creation of the Ray Dashboard and Client ingresses.
38+
39+
`ingress_options` can be passed to create a custom Ray Dashboard ingress, `ingress_domain` is still a required variable for the Client ingress.
40+
An example of `ingress_options` would look like this.
41+
42+
```
43+
ingress_options = {
44+
"ingresses": [
45+
{
46+
"ingressName": "<ingress_name>",
47+
"port": <port_number>,
48+
"pathType": "<path_type>",
49+
"path": "<path>",
50+
"host":"<host>",
51+
"annotations": {
52+
"foo": "bar",
53+
"foo": "bar",
54+
}
55+
}
56+
]
57+
}
58+
```

0 commit comments

Comments
 (0)