Skip to content

Commit

Permalink
Docs nits (#1853)
Browse files Browse the repository at this point in the history
(cherry picked from commit b39bb0a)
  • Loading branch information
vishalbollu authored and deliahu committed Feb 3, 2021
1 parent 7c22617 commit 44d8d3b
Show file tree
Hide file tree
Showing 8 changed files with 52 additions and 54 deletions.
2 changes: 1 addition & 1 deletion .gitbook.yaml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
root: ./docs/

structure:
readme: ./workloads/realtime/example.md
readme: ./start.md
summary: summary.md
13 changes: 7 additions & 6 deletions charts/templates/NOTES.txt
Original file line number Diff line number Diff line change
@@ -1,24 +1,25 @@
###########################################################################

Cortex {{ .Chart.AppVersion }} is initializing in in your cluster.
Cortex (version {{ .Chart.AppVersion }}) is initializing in your cluster.

Wait for the loadbalancers to be provisioned and connected to your cluster.
It will take 5 to 10 minutes for the load balancers to be provisioned and connected to your cluster.

1. Get the Cortex operator endpoint:
1. Get the Cortex operator endpoint (it might take 1-2 minutes until the endpoint is allocated):

{{ if eq .Values.global.provider "aws" }}
{{- if eq .Values.global.provider "aws" }}
$ kubectl get service --namespace {{ .Release.Namespace }} ingressgateway-operator -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
{{- else if eq .Values.global.provider "gcp" }}
$ kubectl get service --namespace {{ .Release.Namespace }} ingressgateway-operator -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
{{- end }}

2. You can use the curl command below to verify loadbalancer set up. It can take between 5 to 10 minutes for the setup to complete. You can expect to encounter `Could not resolve host` or timeouts when running the verification request below during the loadbalancer initialization.
2. You can use the curl command below to verify that your load balancer is ready. You can expect to encounter `Could not resolve host` or timeouts when running the verification request before the load balancer is initialized.

{{ if eq .Values.global.provider "aws" }}
{{- if eq .Values.global.provider "aws" }}
$ export CORTEX_OPERATOR_ENDPOINT=$(kubectl get service --namespace {{ .Release.Namespace }} ingressgateway-operator -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
{{- else if eq .Values.global.provider "gcp" }}
$ export CORTEX_OPERATOR_ENDPOINT=$(kubectl get service --namespace {{ .Release.Namespace }} ingressgateway-operator -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
{{- end}}
$ echo $CORTEX_OPERATOR_ENDPOINT
$ curl http://$CORTEX_OPERATOR_ENDPOINT/verifycortex --max-time 5

A successful response looks like this:
Expand Down
2 changes: 1 addition & 1 deletion charts/values.yaml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
cortex:
# Please provide the following required fields for a cortex installation on AWS
cluster_name: ""
bucket: ""
bucket: "" # e.g. "my-cortex-bucket" (without s3:// or gs://)

# AWS only
region: ""
Expand Down
2 changes: 1 addition & 1 deletion docs/clusters/aws/networking/vpc-peering.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# VPC peering

If you are using an internal operator load balancer (i.e. you set `operator_load_balancer_scheme: internal` in your cluster configuration file before creating your cluster), you can use VPC Peering to enable your Cortex CLI to connect to your cluster operator from another VPC so that you may run `cortex` commands. Note that because the operator validates that the CLI user is an active IAM user in the same AWS account as the Cortex cluster, it is usually unnecessary to configure the operator's load balancer to be internal.
If you are using an internal operator load balancer (i.e. you set `operator_load_balancer_scheme: internal` in your cluster configuration file before creating your cluster), you can use VPC Peering to enable your Cortex CLI to connect to your cluster operator from another VPC so that you may run `cortex` commands.

If you are using an internal API load balancer (i.e. you set `api_load_balancer_scheme: internal` in your cluster configuration file before creating your cluster), you can use VPC Peering to make prediction requests from another VPC.

Expand Down
8 changes: 2 additions & 6 deletions docs/clusters/aws/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ See [networking](networking/index.md) for a discussion of API visibility.

## Private operator

By default, the Cortex cluster operator's load balancer is internet-facing, and therefore publicly accessible (the operator is what the `cortex` CLI connects to). The operator validates that the CLI user is an active IAM user in the same AWS account as the Cortex cluster (see [below](#cli)). Therefore it is usually unnecessary to configure the operator's load balancer to be private, but this can be done by by setting `operator_load_balancer_scheme: internal` in your [cluster configuration](install.md) file. If you do this, you will need to configure [VPC Peering](networking/vpc-peering.md) to allow your CLI to connect to the Cortex operator (this will be necessary to run any `cortex` commands).
By default, the Cortex cluster operator's load balancer is internet-facing, and therefore publicly accessible (the operator is what the `cortex` CLI connects to). The operator's load balancer can be configured to be private by setting `operator_load_balancer_scheme: internal` in your [cluster configuration](install.md) file. If you do this, you will need to configure [VPC Peering](networking/vpc-peering.md) to allow your CLI to connect to the Cortex operator (this will be necessary to run any `cortex` commands).

## IAM permissions

Expand All @@ -36,7 +36,7 @@ You can specify credentials for spinning up the cluster in four ways (in order o

5. You can specify the AWS credentials `"aws access key id"` and `"aws secret access key"` at the CLI's prompt when requested.

It is recommended to use an IAM user with the `AdministratorAccess` policy to create your cluster, since the CLI requires many permissions for this step, and the list of permissions is evolving as Cortex adds new features. If it is not possible to use `AdministratorAccess` in your existing AWS account, you could create a separate AWS account for your Cortex cluster, or you could ask someone within your organization to create the Cortex cluster for you (since `AdministratorAccess` is not required to deploy APIs to your cluster; see [CLI](#cli) below).
It is recommended to use an IAM user with the `AdministratorAccess` policy to create your cluster, since the CLI requires many permissions for this step, and the list of permissions is evolving as Cortex adds new features. If it is not possible to use `AdministratorAccess` in your existing AWS account, you could create a separate AWS account for your Cortex cluster, or you could ask someone within your organization to create the Cortex cluster for you.

### Operator

Expand Down Expand Up @@ -72,10 +72,6 @@ The operator requires read permissions for any S3 bucket containing exported mod

It is possible to further restrict access by limiting access to particular resources (e.g. allowing access to only the bucket containing your models and the cortex bucket).

### CLI

In order to connect to the operator via the CLI, you must provide valid AWS credentials for any user with access to the account. No special permissions are required. The CLI can be configured using the `cortex env configure ENVIRONMENT_NAME` command (e.g. `cortex env configure aws`).

### Running `cortex cluster` commands from different IAM users

By default, the `cortex cluster *` commands can only be executed by the IAM user who created the Cortex cluster. To grant access to additional IAM users, follow these steps:
Expand Down
57 changes: 28 additions & 29 deletions docs/clusters/kubernetes/install.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# install
# Install

Cortex currently relies on cloud provider specific functionality such as load balancers and storage. Kubernetes clusters in the following cloud providers are supported:

* [AWS](#aws)
* [GCP](#gcp)

Expand All @@ -14,22 +15,23 @@ Cortex uses helm to install the Cortex operator and its dependencies on your Kub
* aws cli
* helm 3
* EKS cluster
* kubernetes version >= 1.17
* at least 3 t3.medium (2 vCPU, 4 GB mem) instances
* at least 3 t3.medium (2 vCPU, 4 GB mem) instances

Note that installing Cortex on your kubernetes cluster will not provide some of the cluster level features such as cluster autoscaling and spot instances with on-demand backup.
You may install Cortex in any namespace in your cluster. In the guide that follows, the "default" namespace is assumed; if you're using a different namespace, replace all occurrences of "default" with the name of your namespace.

### Download cortex charts
Note that installing Cortex on your Kubernetes cluster will not provide some of the cluster-level features such as cluster autoscaling and spot instances with on-demand backup.

<!-- CORTEX_VERSION -->
```
### Download Cortex charts

<!-- CORTEX_VERSION_BRANCH_STABLE x3 -->
```bash
wget https://s3-us-west-2.amazonaws.com/get-cortex/0.28.0/charts/cortex-0.28.0.tar.gz
tar -xzf cortex-0.28.0.tar.gz
```

### Create a bucket in S3

The Cortex operator will use this bucket to store API states and dependencies.
The Cortex operator will use this bucket to store API state and dependencies.

```yaml
aws s3api create-bucket --bucket <CORTEX_S3_BUCKET> --region <CORTEX_REGION>
Expand All @@ -49,7 +51,7 @@ kubectl --namespace default create secret generic 'aws-credentials' \
-o yaml --dry-run=client | kubectl apply -f - >/dev/null
```

### Install Cortex on to your kubernetes cluster
### Install Cortex

Define a `values.yaml` with the following information provided:

Expand All @@ -58,7 +60,7 @@ Define a `values.yaml` with the following information provided:

cortex:
region: <CORTEX_REGION>
bucket: <CORTEX_S3_BUCKET>
bucket: <CORTEX_S3_BUCKET> # e.g. "my-cortex-bucket" (without s3://)
cluster_name: <CORTEX_CLUSTER_NAME>
global:
provider: "aws"
Expand All @@ -78,7 +80,7 @@ Get the Cortex operator endpoint:
kubectl get service --namespace default ingressgateway-operator -o jsonpath='{.status.loadBalancer.ingress[0].hostname}'
```

You can use the curl command below to verify loadbalancer set up. It can take between 5 to 10 minutes for the setup to complete. You can expect to encounter `Could not resolve host` or timeouts when running the verification request below during the loadbalancer initialization.
You can use the curl command below to verify that your load balancer is ready. It can take 5-10 minutes for the setup to complete. You can expect to encounter `Could not resolve host` or timeouts when running the verification request before the load balancer is initialized.

```bash
export CORTEX_OPERATOR_ENDPOINT=$(kubectl get service --namespace default ingressgateway-operator -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
Expand Down Expand Up @@ -120,22 +122,23 @@ The following tolerations are added to Deployments and Jobs orchestrated by Cort
* gsutil
* helm 3
* GKE cluster
* kubernetes version >= 1.17
* at least 2 n1-standard-2 (2 vCPU, 8 GB mem) (with monitoring and logging disabled)
* at least 2 n1-standard-2 (2 vCPU, 8 GB mem) (with monitoring and logging disabled)
Note that installing Cortex on your kubernetes cluster will not provide some of the cluster level features such as cluster autoscaling and spot instances with on-demand backup.
You may install Cortex in any namespace in your cluster. In the guide that follows, the "default" namespace is assumed; if you're using a different namespace, replace all occurrences of "default" with the name of your namespace.
### Download cortex charts
Note that installing Cortex on your Kubernetes cluster will not provide some of the cluster-level features such as cluster autoscaling and preemptible instances.
<!-- CORTEX_VERSION -->
```
### Download Cortex charts
<!-- CORTEX_VERSION_BRANCH_STABLE x3 -->
```bash
wget https://s3-us-west-2.amazonaws.com/get-cortex/0.28.0/charts/cortex-0.28.0.tar.gz
tar -xzf cortex-0.28.0.tar.gz
```

### Create a bucket in GCS

The Cortex operator will use this bucket to store API states and dependencies.
The Cortex operator will use this bucket to store API state and dependencies.

```yaml
gsutil mb gs://CORTEX_GCS_BUCKET
Expand All @@ -146,46 +149,42 @@ gsutil mb gs://CORTEX_GCS_BUCKET
The credentials need to have at least these [permissions](../gcp/credentials.md).

```yaml
export CORTEX_GOOGLE_APPLICATION_CREDENTIALS=
export CORTEX_GOOGLE_APPLICATION_CREDENTIALS=<PATH_TO_CREDENTIALS>

kubectl create secret generic 'gcp-credentials' --namespace default --from-file=key.json=$CORTEX_GOOGLE_APPLICATION_CREDENTIALS
```

Note: make sure to add credentials to the namespace that cortex will be installed into.

### Install cortex
### Install Cortex

Define a `values.yaml` with the following information provided:

```yaml
# values.yaml

cortex:
project: <CORTEX_REGION>
project: <CORTEX_PROJECT>
zone: <CORTEX_ZONE>
bucket: <CORTEX_GCS_BUCKET>
bucket: <CORTEX_GCS_BUCKET> # e.g. "my-cortex-bucket" (without gs://)
cluster_name: <CORTEX_CLUSTER_NAME>
global:
provider: "gcp"
```
### Install with your configuration
```bash
helm install cortex manifests/ --namespace default -f values.yaml
helm install cortex charts/ --namespace default -f values.yaml
```

### Configure Cortex client

Wait for the loadbalancers to be provisioned and connected to your cluster.

Get the Cortex operator endpoint (double check your namespace):
Get the Cortex operator endpoint:

```bash
kubectl get service --namespace default ingressgateway-operator -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
```

You can use the curl command below to verify loadbalancer set up. It can take between 5 to 10 minutes for the setup to complete. You can expect to encounter `Could not resolve host` or timeouts when running the verification request below during the loadbalancer initialization.
You can use the curl command below to verify that your load balancer is ready. It can take 5-10 minutes for the setup to complete. You can expect to encounter `Could not resolve host` or timeouts when running the verification request before the load balancer is initialized.

```bash
export CORTEX_OPERATOR_ENDPOINT=$(kubectl get service --namespace default ingressgateway-operator -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
Expand Down
8 changes: 5 additions & 3 deletions docs/clusters/kubernetes/uninstall.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
# uninstall
# Uninstall

Get the Cortex installation's release name
Identify the Cortex installation's release name:

```bash
helm list
```

Uninstall Cortex:

```bash
helm uninstall <RELEASE_NAME>
```

Resources in your cloud such as the bucket and logging will not be deleted.
Resources in your cloud such as the bucket and logs will not be deleted.
14 changes: 7 additions & 7 deletions docs/start.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,16 @@
$ pip install cortex
```

See the detailed installation instructions [here](clients/install.md).
See [here](clients/install.md) for alternative installation options.

## Connect to a cluster
## Create a cluster

* [Launch a managed Cortex cluster on your AWS account](clusters/aws/install.md)
* [Launch a managed Cortex cluster on your GCP account](clusters/gcp/install.md)
* [Launch a Cortex cluster on your AWS account](clusters/aws/install.md)
* [Launch a Cortex cluster on your GCP account](clusters/gcp/install.md)
* [Install Cortex on your Kubernetes cluster](clusters/kubernetes/install.md)

## Run inference workloads

* [RealtimeAPI](workloads/realtime/example.md)
* [BatchAPI](workloads/batch/example.md)
* [TaskAPI](workloads/task/example.md)
* [Realtime API](workloads/realtime/example.md)
* [Batch API](workloads/batch/example.md)
* [Task API](workloads/task/example.md)

0 comments on commit 44d8d3b

Please sign in to comment.