On prem 2a and stubs (#3790)

* first draft

* first draft, with stubs for all the documents in the complete on-premises deployment set.

doc/deployment/configuring_k8s_ingress.md

@@ -0,0 +1,4 @@
+# Configuring Kubernetes Ingress for Pachyderm
+
+Coming soon.
+This document, when complete, will detail the Kubernetes ingress configuration you'd need for using `pachctl` and the dashboard outside of the Kubernetes cluster.

doc/deployment/deploy_custom.md

@@ -0,0 +1,74 @@
+# Custom Deployments
+
+This document  details the various options of the `pachctl deploy custom ...` command for an on-premises deployment. 
+
+## Prerequisites
+
+### Software you will need 
+
+1. [kubectl](https://kubernetes.io/docs/user-guide/prereqs/)
+2. [pachctl](http://docs.pachyderm.io/en/latest/pachctl/pachctl.html)
+
+### Preparing your environment
+
+Please see the [introduction to on-premises deployment](./on_premises.html) for steps you need to take prior to creating a Pachydemerm deployment manifest.
+
+## Creating a Pachyderm manifest
+
+Please see the [introduction to on-premises deployment](./on_premises.html) for an explanation of the differences among static persistent volumes, StatefulSets and StatefulSets with StorageClasses, as well as the meanings of the variables, like  `PVC_STORAGE_SIZE` and `OS_ENDPOINT`, used below.
+
+### Configuring with a static persistent volume
+The command you'll want to run is 
+```sh
+$ pachctl deploy custom --persistent-disk aws --object-store s3 
+         ${PVC STORAGE_NAME} ${PVC STORAGE_SIZE} ${OS_BUCKET_NAME} ${OS_ACCESS_KEY_ID} ${OS_SECRET_KEY} ${OS_ENDPOINT} \
+         --static-etcd-volume=${PVC_STORAGE_NAME}  \
+         --dry-run > pachyderm-with-static-volume.json
+```
+### Configuring with StatefulSets
+The command you'll want to run is 
+```sh
+$ pachctl deploy custom --object-store s3 any-string 
+         ${PVC_STORAGE_SIZE} ${OS_BUCKET_NAME} ${OS_ACCESS_KEY_ID} ${OS_SECRET_KEY} ${OS_ENDPOINT} \
+         --dynamic-etcd-nodes=1 \
+         --dry-run > pachyderm-with-statefulset.json
+```
+Note: we use `any-string` as the first argument above because, 
+while the `deploy custom` command expects 6 arguments, 
+it will ignore the first argument when deploying with StatefulSets.
+### Configuring with StatefulSets using StorageClasses
+```sh
+$ pachctl deploy custom --object-store s3 any-string 
+         ${PVC_STORAGE_SIZE} ${OS_BUCKET_NAME} ${OS_ACCESS_KEY_ID} ${OS_SECRET_KEY} ${OS_ENDPOINT} \
+         --dynamic-etcd-nodes=1  --etcd-storage-class $PVC_STORAGECLASS \
+         --dry-run > pachyderm-with-statefulset-using-storageclasses.json
+```
+Note: we use `any-string` as the first argument above because, 
+while the `deploy custom` command expects 6 arguments, 
+it will ignore the first argument when deploying with StatefulSets.
+
+## Next steps
+
+You may either deploy manifests you created above or edit them to customize them further, prior to deploying.
+
+### Editing your manifest to customize it further
+
+This should only be approached if you are an experienced Kubernetes administrator. 
+
+### Deploying
+The command you'll want to run depends on the command you ran, above.
+
+#### Deploying with a static persistent volume
+```sh
+$ kubectl apply -f ./pachyderm-with-static-volume.json
+```
+#### Deploying  with StatefulSets
+```sh
+$ kubectl apply -f ./pachyderm-with-statefulset.json
+```
+#### Deploying  with StatefulSets using StorageClasses
+```sh
+$ kubectl apply -f ./pachyderm-with-statefulset-using-storageclasses.json
+```
+
+

doc/deployment/deploy_troubleshooting.md

@@ -19,6 +19,7 @@ Here are some common issues by symptom related to certain deploys.
 
 - [Pod stuck in `CrashLoopBackoff`](#pod-stuck-in-crashloopbackoff)
 - [Pod stuck in `CrashLoopBackoff` - with error attaching volume](#pod-stuck-in-crashloopbackoff-with-error-attaching-volume)
+- [
 
 ### Pod stuck in `CrashLoopBackoff`
 

doc/deployment/docker_registries.md

@@ -0,0 +1,6 @@
+# Working With Docker Registries
+
+Coming soon.
+This document, when complete, will take you through on-premises, private Docker registry configuration.
+
+

doc/deployment/non-cloud-object-stores.md

@@ -0,0 +1,60 @@
+# Deploying Pachyderm On-Premises With Non-Cloud Object Stores
+
+Coming soon.
+This document, when complete, will discuss common configurations for on-premises objects stores.
+
+## General information on non-cloud object stores
+
+Please see [the on-premises introduction to object stores](./on-premises.html#deploying-an-object-store) for some general information on object stores and how they're used with Pachyderm.
+
+### EMC ECS
+Coming soon.
+
+### MinIO
+Coming soon.
+
+### SwiftStack
+Coming soon.
+
+## Notes
+### S3 API Signature Algorithms and Regions
+
+The S3 protocol has two different ways of authenticating requests through its api.
+`S3v2` has been [officially deprecated by Amazon](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#UsingAWSSDK-sig2-deprecation),
+so it's not likely that you'll run into it.
+You don't need to know the details of how they work
+(though you can follow these links, S3v2 & [S3v4](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html), if you're curious),
+but you may run into issues with either mismatch of the signature method or availability regions.
+
+If you have trouble getting Pachyderm to run, 
+check your Kubernetes logs for the `pachd` pod. 
+Use `kubectl get pods` to find the name of the `pachd` pod and
+`kubectl logs <pachd-pod-name>` to get the logs.
+
+If you see an error beginning with
+```
+INFO error starting grpc server pfs.NewBlockAPIServer
+```
+
+It could have either of two causes.
+
+#### Availability Region Mismatch
+If the error is of the form
+```
+INFO error starting grpc server pfs.NewBlockAPIServer: storage is unable to discern NotExist errors, "The authorization header is malformed; the region 'us-east-1' is wrong; expecting 'z1-a'" should count as NotExist
+```
+It may be [a known issue](https://github.com/pachyderm/pachyderm/issues/3544) with hardcoded region `us-east-1` in the minio libraries.
+You can correct this by either using the `--isS3V2` flag on your the `pachctl deploy custom ...` command 
+or by changing the region of your storage to `us-east-1`.
+
+#### Signature version mismatch
+
+You're not likely to run into this in an on-premises deployment 
+unless your object store has deliberately been set up to use the deprecated `S3v2` signature or 
+you are running your on-premises deployment against Google Cloud Storage, 
+which is not recommended (see the section [Infrastructure in general](./on_premises.html#infrastructure-in-general)).
+
+You'll need to determine what signature algorithm your object store uses in its S3-compatible API:  `S3v2` or `S3v4`.
+If it's `S3V2`, 
+you can solve this by using the `--isS3V2` flag on your the `pachctl deploy custom ...` command.
+