cortexlabs · deliahu · Nov 24, 2020 · Nov 18, 2020 · Nov 18, 2020 · Nov 18, 2020
diff --git a/.gitbook.yaml b/.gitbook.yaml
@@ -8,3 +8,6 @@ redirects:
   tutorial: ../examples/pytorch/text-generator/README.md
   tutorial/realtime: ../examples/pytorch/text-generator/README.md
   tutorial/batch: ../examples/batch/image-classifier/README.md
+  install: ./aws/install.md
+  uninstall: ./aws/uninstall.md
+  update: ./aws/update.md
diff --git a/cli/cluster/errors.go b/cli/cluster/errors.go
@@ -21,6 +21,7 @@ import (
 	"net/url"
 	"strings"
 
+	"github.com/cortexlabs/cortex/pkg/consts"
 	"github.com/cortexlabs/cortex/pkg/lib/errors"
 	"github.com/cortexlabs/cortex/pkg/lib/urls"
 )
@@ -61,8 +62,7 @@ func ErrorFailedToConnectOperator(originalError error, envName string, operatorU
 		msg += fmt.Sprintf("    → otherwise you can ignore this message, and prevent it in the future with `cortex env delete %s`\n", envName)
 		msg += "\nif you have a cluster running:\n"
 		msg += fmt.Sprintf("    → run `cortex cluster info --configure-env %s` to update your environment (include `--config <cluster.yaml>` if you have a cluster configuration file)\n", envName)
-		// CORTEX_VERSION_MINOR
-		msg += "    → if you set `operator_load_balancer_scheme: internal` in your cluster configuration file, your CLI must run from within a VPC that has access to your cluster's VPC (see https://docs.cortex.dev/v/master/guides/vpc-peering)\n"
+		msg += fmt.Sprintf("    → if you set `operator_load_balancer_scheme: internal` in your cluster configuration file, your CLI must run from within a VPC that has access to your cluster's VPC (see https://docs.cortex.dev/v/%s/aws/vpc-peering)\n", consts.CortexVersionMinor)
 	}
 
 	return errors.WithStack(&errors.Error{

diff --git a/cli/cmd/errors.go b/cli/cmd/errors.go
@@ -248,7 +248,7 @@ func ErrorMissingAWSCredentials() error {
 func ErrorCredentialsInClusterConfig(cmd string, path string) error {
 	return errors.WithStack(&errors.Error{
 		Kind:    ErrCredentialsInClusterConfig,
-		Message: fmt.Sprintf("specifying credentials in the cluster configuration is no longer supported, please specify aws credentials using flags (e.g. cortex cluster %s --config %s --aws-key <AWS_ACCESS_KEY_ID> --aws-secret <AWS_SECRET_ACCESS_KEY>) or set environment variables; see https://docs.cortex.dev/v/%s/miscellaneous/security#iam-permissions for more information", cmd, path, consts.CortexVersionMinor),
+		Message: fmt.Sprintf("specifying credentials in the cluster configuration is no longer supported, please specify aws credentials using flags (e.g. cortex cluster %s --config %s --aws-key <AWS_ACCESS_KEY_ID> --aws-secret <AWS_SECRET_ACCESS_KEY>) or set environment variables; see https://docs.cortex.dev/v/%s/aws/security#iam-permissions for more information", cmd, path, consts.CortexVersionMinor),
 	})
 }
 

diff --git a/cli/cmd/lib_aws_creds.go b/cli/cmd/lib_aws_creds.go
@@ -21,6 +21,7 @@ import (
 	"os"
 	"path/filepath"
 
+	"github.com/cortexlabs/cortex/pkg/consts"
 	"github.com/cortexlabs/cortex/pkg/lib/aws"
 	"github.com/cortexlabs/cortex/pkg/lib/errors"
 	libjson "github.com/cortexlabs/cortex/pkg/lib/json"
@@ -68,7 +69,7 @@ func promptIfNotAdmin(awsClient *aws.Client, disallowPrompt bool) {
 	}
 
 	if !awsClient.IsAdmin() {
-		warningStr := fmt.Sprintf("warning: your IAM user%s does not have administrator access. This will likely prevent Cortex from installing correctly, so it is recommended to attach the AdministratorAccess policy to your IAM user (or to a group that your IAM user belongs to) via the AWS IAM console. If you'd like, you may provide separate credentials for your cluster to use after it's running (see https://docs.cortex.dev/miscellaneous/security for instructions).\n\n", accessKeyMsg)
+		warningStr := fmt.Sprintf("warning: your IAM user%s does not have administrator access. This will likely prevent Cortex from installing correctly, so it is recommended to attach the AdministratorAccess policy to your IAM user (or to a group that your IAM user belongs to) via the AWS IAM console. If you'd like, you may provide separate credentials for your cluster to use after it's running (see https://docs.cortex.dev/v/%s/aws/security for instructions).\n\n", accessKeyMsg, consts.CortexVersionMinor)
 		if disallowPrompt {
 			fmt.Print(warningStr)
 		} else {

diff --git a/cli/cmd/lib_cluster_config.go b/cli/cmd/lib_cluster_config.go
@@ -70,7 +70,7 @@ func readCachedClusterConfigFile(clusterConfig *clusterconfig.Config, filePath s
 func readUserClusterConfigFile(clusterConfig *clusterconfig.Config) error {
 	errs := cr.ParseYAMLFile(clusterConfig, clusterconfig.UserValidation, _flagClusterConfig)
 	if errors.HasError(errs) {
-		return errors.Append(errors.FirstError(errs...), fmt.Sprintf("\n\ncluster configuration schema can be found here: https://docs.cortex.dev/v/%s/cluster-management/config", consts.CortexVersionMinor))
+		return errors.Append(errors.FirstError(errs...), fmt.Sprintf("\n\ncluster configuration schema can be found here: https://docs.cortex.dev/v/%s/aws/install", consts.CortexVersionMinor))
 	}
 
 	return nil
@@ -85,7 +85,7 @@ func getNewClusterAccessConfig(disallowPrompt bool) (*clusterconfig.AccessConfig
 	if _flagClusterConfig != "" {
 		errs := cr.ParseYAMLFile(accessConfig, clusterconfig.AccessValidation, _flagClusterConfig)
 		if errors.HasError(errs) {
-			return nil, errors.Append(errors.FirstError(errs...), fmt.Sprintf("\n\ncluster configuration schema can be found here: https://docs.cortex.dev/v/%s/cluster-management/config", consts.CortexVersionMinor))
+			return nil, errors.Append(errors.FirstError(errs...), fmt.Sprintf("\n\ncluster configuration schema can be found here: https://docs.cortex.dev/v/%s/aws/install", consts.CortexVersionMinor))
 		}
 	}
 
@@ -121,7 +121,7 @@ func getClusterAccessConfigWithCache(disallowPrompt bool) (*clusterconfig.Access
 	if _flagClusterConfig != "" {
 		errs := cr.ParseYAMLFile(accessConfig, clusterconfig.AccessValidation, _flagClusterConfig)
 		if errors.HasError(errs) {
-			return nil, errors.Append(errors.FirstError(errs...), fmt.Sprintf("\n\ncluster configuration schema can be found here: https://docs.cortex.dev/v/%s/cluster-management/config", consts.CortexVersionMinor))
+			return nil, errors.Append(errors.FirstError(errs...), fmt.Sprintf("\n\ncluster configuration schema can be found here: https://docs.cortex.dev/v/%s/aws/install", consts.CortexVersionMinor))
 		}
 	}
 
@@ -206,7 +206,7 @@ func getInstallClusterConfig(awsCreds AWSCredentials, accessConfig clusterconfig
 
 	err = clusterConfig.Validate(awsClient)
 	if err != nil {
-		err = errors.Append(err, fmt.Sprintf("\n\ncluster configuration schema can be found here: https://docs.cortex.dev/v/%s/cluster-management/config", consts.CortexVersionMinor))
+		err = errors.Append(err, fmt.Sprintf("\n\ncluster configuration schema can be found here: https://docs.cortex.dev/v/%s/aws/install", consts.CortexVersionMinor))
 		if _flagClusterConfig != "" {
 			err = errors.Wrap(err, _flagClusterConfig)
 		}
@@ -272,7 +272,7 @@ func getConfigureClusterConfig(cachedClusterConfig clusterconfig.Config, awsCred
 
 	err = userClusterConfig.Validate(awsClient)
 	if err != nil {
-		err = errors.Append(err, fmt.Sprintf("\n\ncluster configuration schema can be found here: https://docs.cortex.dev/v/%s/cluster-management/config", consts.CortexVersionMinor))
+		err = errors.Append(err, fmt.Sprintf("\n\ncluster configuration schema can be found here: https://docs.cortex.dev/v/%s/aws/install", consts.CortexVersionMinor))
 		if _flagClusterConfig != "" {
 			err = errors.Wrap(err, _flagClusterConfig)
 		}
@@ -556,23 +556,23 @@ func confirmInstallClusterConfig(clusterConfig *clusterconfig.Config, awsCreds A
 	fmt.Printf("cortex will also create an s3 bucket (%s) and a cloudwatch log group (%s)%s\n\n", clusterConfig.Bucket, clusterConfig.ClusterName, privateSubnetMsg)
 
 	if clusterConfig.APIGatewaySetting == clusterconfig.NoneAPIGatewaySetting {
-		fmt.Print("warning: you've disabled API Gateway cluster-wide, so APIs will not be able to create API Gateway endpoints (they will still be reachable via the API load balancer; see https://docs.cortex.dev/deployments/networking for more information)\n\n")
+		fmt.Print(fmt.Sprintf("warning: you've disabled API Gateway cluster-wide, so APIs will not be able to create API Gateway endpoints (they will still be reachable via the API load balancer; see https://docs.cortex.dev/v/%s/aws/networking for more information)\n\n", consts.CortexVersionMinor))
 	}
 
 	if clusterConfig.OperatorLoadBalancerScheme == clusterconfig.InternalLoadBalancerScheme {
-		fmt.Print("warning: you've configured the operator load balancer to be internal; you must configure VPC Peering to connect your CLI to your cluster operator (see https://docs.cortex.dev/guides/vpc-peering)\n\n")
+		fmt.Print(fmt.Sprintf("warning: you've configured the operator load balancer to be internal; you must configure VPC Peering to connect your CLI to your cluster operator (see https://docs.cortex.dev/v/%s/aws/vpc-peering)\n\n", consts.CortexVersionMinor))
 	}
 
 	if isSpot && clusterConfig.SpotConfig.OnDemandBackup != nil && !*clusterConfig.SpotConfig.OnDemandBackup {
 		if *clusterConfig.SpotConfig.OnDemandBaseCapacity == 0 && *clusterConfig.SpotConfig.OnDemandPercentageAboveBaseCapacity == 0 {
-			fmt.Printf("warning: you've disabled on-demand instances (%s=0 and %s=0); spot instances are not guaranteed to be available so please take that into account for production clusters; see https://docs.cortex.dev/v/%s/cluster-management/spot-instances for more information\n\n", clusterconfig.OnDemandBaseCapacityKey, clusterconfig.OnDemandPercentageAboveBaseCapacityKey, consts.CortexVersionMinor)
+			fmt.Printf("warning: you've disabled on-demand instances (%s=0 and %s=0); spot instances are not guaranteed to be available so please take that into account for production clusters; see https://docs.cortex.dev/v/%s/aws/spot for more information\n\n", clusterconfig.OnDemandBaseCapacityKey, clusterconfig.OnDemandPercentageAboveBaseCapacityKey, consts.CortexVersionMinor)
 		} else {
-			fmt.Printf("warning: you've enabled spot instances; spot instances are not guaranteed to be available so please take that into account for production clusters; see https://docs.cortex.dev/v/%s/cluster-management/spot-instances for more information\n\n", consts.CortexVersionMinor)
+			fmt.Printf("warning: you've enabled spot instances; spot instances are not guaranteed to be available so please take that into account for production clusters; see https://docs.cortex.dev/v/%s/aws/spot for more information\n\n", consts.CortexVersionMinor)
 		}
 	}
 
 	if !disallowPrompt {
-		exitMessage := fmt.Sprintf("cluster configuration can be modified via the cluster config file; see https://docs.cortex.dev/v/%s/cluster-management/config for more information", consts.CortexVersionMinor)
+		exitMessage := fmt.Sprintf("cluster configuration can be modified via the cluster config file; see https://docs.cortex.dev/v/%s/aws/install for more information", consts.CortexVersionMinor)
 		prompt.YesOrExit("would you like to continue?", "", exitMessage)
 	}
 }
@@ -581,7 +581,7 @@ func confirmConfigureClusterConfig(clusterConfig clusterconfig.Config, awsCreds
 	fmt.Println(clusterConfigConfirmationStr(clusterConfig, awsCreds, awsClient))
 
 	if !disallowPrompt {
-		exitMessage := fmt.Sprintf("cluster configuration can be modified via the cluster config file; see https://docs.cortex.dev/v/%s/cluster-management/config for more information", consts.CortexVersionMinor)
+		exitMessage := fmt.Sprintf("cluster configuration can be modified via the cluster config file; see https://docs.cortex.dev/v/%s/aws/install for more information", consts.CortexVersionMinor)
 		prompt.YesOrExit(fmt.Sprintf("your cluster named \"%s\" in %s will be updated according to the configuration above, are you sure you want to continue?", clusterConfig.ClusterName, *clusterConfig.Region), "", exitMessage)
 	}
 }

diff --git a/cli/local/api.go b/cli/local/api.go
@@ -56,9 +56,9 @@ func UpdateAPI(apiConfig *userconfig.API, models []spec.CuratedModelResource, co
 					fmt.Sprintf(
 						"api %s was deployed using CLI version %s but the current CLI version is %s; "+
 							"re-deploying %s with current CLI version %s might yield an unexpected outcome; any cached models won't be deleted\n\n"+
-							"it is recommended to download version %s of the CLI from https://docs.cortex.dev/v/%s/install, delete the API using version %s of the CLI and then re-deploy the API using the latest version of the CLI\n\n"+
+							"it is recommended to install version %s of the CLI (pip install cortex==%s), delete the API using version %s of the CLI, and then re-deploy the API using the latest version of the CLI\n\n"+
 							"do you still want to re-deploy?",
-						apiConfig.Name, incompatibleMinorVersion, consts.CortexVersionMinor, apiConfig.Name, consts.CortexVersionMinor, incompatibleMinorVersion, incompatibleMinorVersion, incompatibleMinorVersion),
+						apiConfig.Name, incompatibleMinorVersion, consts.CortexVersionMinor, apiConfig.Name, consts.CortexVersionMinor, incompatibleMinorVersion, incompatibleVersion, incompatibleMinorVersion),
 					"", "",
 				)
 			}

diff --git a/cli/local/delete.go b/cli/local/delete.go
@@ -48,9 +48,9 @@ func Delete(apiName string, keepCache, deleteForce bool) (schema.DeleteResponse,
 					fmt.Sprintf(
 						"api %s was deployed using CLI version %s but the current CLI version is %s; "+
 							"deleting %s with current CLI version %s might lead to an unexpected state; any cached models won't be deleted\n\n"+
-							"it is recommended to download version %s of the CLI from https://docs.cortex.dev/v/%s/install, delete the API using version %s of the CLI and then re-deploy the API using the latest version of the CLI\n\n"+
+							"it is recommended to download version %s of the CLI (pip install cortex==%s), delete the API using version %s of the CLI, and then re-deploy the API using the latest version of the CLI\n\n"+
 							"do you still want to delete?",
-						apiName, incompatibleMinorVersion, consts.CortexVersionMinor, apiName, consts.CortexVersionMinor, incompatibleMinorVersion, incompatibleMinorVersion, incompatibleMinorVersion),
+						apiName, incompatibleMinorVersion, consts.CortexVersionMinor, apiName, consts.CortexVersionMinor, incompatibleMinorVersion, incompatibleVersion, incompatibleMinorVersion),
 					"", "",
 				)
 			}

diff --git a/cli/local/validations.go b/cli/local/validations.go
@@ -39,7 +39,7 @@ import (
 	"github.com/cortexlabs/cortex/pkg/types/userconfig"
 )
 
-var _startingPort = 8890
+var _startingPort = 8889
 
 type ProjectFiles struct {
 	relFilePaths []string

diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/aws/credentials.md b/docs/aws/credentials.md
@@ -0,0 +1,7 @@
+# Credentials
+
+_WARNING: you are on the master branch, please refer to the docs on the branch that matches your `cortex version`_
+
+1. Follow this [tutorial](https://aws.amazon.com/premiumsupport/knowledge-center/create-access-key) to create an access key.
+1. Enable programmatic access for the IAM user, and attach the built-in `AdministratorAccess` policy to your IAM user.
+1. See [security](security.md) if you'd like to use less privileged credentials after spinning up your cluster.
diff --git a/docs/guides/custom-domain.md → docs/aws/custom-domain.md b/docs/guides/custom-domain.md → docs/aws/custom-domain.md
diff --git a/docs/aws/install.md b/docs/aws/install.md
@@ -0,0 +1,115 @@
+# Install
+
+_WARNING: you are on the master branch, please refer to the docs on the branch that matches your `cortex version`_
+
+## Spin up Cortex on your AWS account
+
+Make sure [Docker](https://docs.docker.com/install) is running on your machine.
+
+If you're using GPUs, subscribe to the [EKS-optimized AMI with GPU Support](https://aws.amazon.com/marketplace/pp/B07GRHFXGM) before creating your cluster.
+
+```bash
+# install the CLI
+pip install cortex
+
+# spin up Cortex on your AWS account
+cortex cluster up  # or: cortex cluster up --config cluster.yaml (see configuration options below)
+
+# set the default environment
+cortex env default aws
+```
+
+<!-- CORTEX_VERSION_MINOR -->
+Try the [tutorial](../../examples/pytorch/text-generator/README.md) or deploy one of our [examples](https://github.com/cortexlabs/cortex/tree/master/examples).
+
+## Configure Cortex
+
+<!-- CORTEX_VERSION_MINOR -->
+```yaml
+# cluster.yaml
+
+# EKS cluster name
+cluster_name: cortex
+
+# AWS region
+region: us-east-1
+
+# list of availability zones for your region
+availability_zones:  # default: 3 random availability zones in your region, e.g. [us-east-1a, us-east-1b, us-east-1c]
+
+# instance type
+instance_type: m5.large
+
+# minimum number of instances
+min_instances: 1
+
+# maximum number of instances
+max_instances: 5
+
+# disk storage size per instance (GB)
+instance_volume_size: 50
+
+# instance volume type [gp2 | io1 | st1 | sc1]
+instance_volume_type: gp2
+
+# instance volume iops (only applicable to io1)
+# instance_volume_iops: 3000
+
+# subnet visibility [public (instances will have public IPs) | private (instances will not have public IPs)]
+subnet_visibility: public
+
+# NAT gateway (required when using private subnets) [none | single | highly_available (a NAT gateway per availability zone)]
+nat_gateway: none
+
+# API load balancer scheme [internet-facing | internal]
+api_load_balancer_scheme: internet-facing
+
+# operator load balancer scheme [internet-facing | internal]
+# note: if using "internal", you must configure VPC Peering to connect your CLI to your cluster operator (https://docs.cortex.dev/v/master/aws/vpc-peering)
+operator_load_balancer_scheme: internet-facing
+
+# API Gateway [public (API Gateway will be used by default, can be disabled per API) | none (API Gateway will be disabled for all APIs)]
+api_gateway: public
+
+# additional tags to assign to AWS resources (all resources will automatically be tagged with cortex.dev/cluster-name: <cluster_name>)
+tags:  # <string>: <string> map of key/value pairs
+
+# enable spot instances
+spot: false
+
+# SSL certificate ARN (only necessary when using a custom domain without API Gateway)
+ssl_certificate_arn:
+
+# primary CIDR block for the cluster's VPC
+vpc_cidr: 192.168.0.0/16
+```
+
+The docker images used by the Cortex cluster can also be overridden, although this is not common. They can be configured by adding any of these keys to your cluster configuration file (default values are shown):
+
+<!-- CORTEX_VERSION_BRANCH_STABLE -->
+```yaml
+image_operator: quay.io/cortexlabs/operator:master
+image_manager: quay.io/cortexlabs/manager:master
+image_downloader: quay.io/cortexlabs/downloader:master
+image_request_monitor: quay.io/cortexlabs/request-monitor:master
+image_cluster_autoscaler: quay.io/cortexlabs/cluster-autoscaler:master
+image_metrics_server: quay.io/cortexlabs/metrics-server:master
+image_inferentia: quay.io/cortexlabs/inferentia:master
+image_neuron_rtd: quay.io/cortexlabs/neuron-rtd:master
+image_nvidia: quay.io/cortexlabs/nvidia:master
+image_fluentd: quay.io/cortexlabs/fluentd:master
+image_statsd: quay.io/cortexlabs/statsd:master
+image_istio_proxy: quay.io/cortexlabs/istio-proxy:master
+image_istio_pilot: quay.io/cortexlabs/istio-pilot:master
+```
+
+The default docker images used for your Predictors are listed in the instructions for [system packages](../deployments/system-packages.md), and can be overridden in your [Realtime API configuration](../deployments/realtime-api/api-configuration.md) and in your [Batch API configuration](../deployments/batch-api/api-configuration.md).
+
+## Advanced
+
+* [Security](security.md)
+* [VPC peering](vpc-peering.md)
+* [Custom domain](custom-domain.md)
+* [REST API Gateway](rest-api-gateway.md)
+* [Spot instances](spot.md)
+* [SSH into instances](ssh.md)