Merge pull request #1023 from Bradamant3/docs-misc-issues

add rbac content and a candidate for more versioning information

Author: skriss

docs/quickstart.md docs/get-started.md

@@ -4,9 +4,9 @@ The following example sets up the Ark server and client, then backs up and resto
 
 For simplicity, the example uses Minio, an S3-compatible storage service that runs locally on your cluster.
 
-**NOTE** The example lets you explore basic Ark functionality. In the real world, however, you would back your cluster up to external storage.
+**NOTE** The example lets you explore basic Ark functionality. Configuring Minio for production is out of scope.
 
-See [Set up Ark on your platform][3] for how to configure Ark for a production environment. 
+See [Set up Ark on your platform][3] for how to configure Ark for a production environment.
 
 ### Prerequisites
 
@@ -26,7 +26,9 @@ NOTE: Make sure to check out the appropriate version. We recommend that you chec
 
 ### Set up server
 
-1. Start the server and the local storage service. In the root directory of Ark, run:
+These instructions start the Ark server and a Minio instance that is accessible from within the cluster only. See the following section for information about configuring your cluster for outside access to Minio. Outside access is required to access logs and run `ark describe` commands.
+
+1.  Start the server and the local storage service. In the root directory of Ark, run:
 
     ```bash
     kubectl apply -f examples/common/00-prereqs.yaml
@@ -46,6 +48,53 @@ NOTE: Make sure to check out the appropriate version. We recommend that you chec
     kubectl get deployments --namespace=nginx-example
     ```
 
+### (Optional) Expose Minio outside your cluster
+
+When you run commands to get logs or describe a backup, the Ark server generates a pre-signed URL to download the requested items. To access these URLs from outside the cluster -- that is, from your Ark client -- you need to make Minio available outside the cluster. You can:
+
+- Change the Minio Service type from `ClusterIP` to `NodePort`.
+- Set up Ingress for your cluster, keeping Minio Service type `ClusterIP`.
+
+In Ark 0.10, you can also specify the value of a new `publicUrl` field for the pre-signed URL in your backup storage config.
+
+#### Expose Minio with Service of type NodePort
+
+The Minio deployment by default specifies a Service of type `ClusterIP`. You can change this to `NodePort` to easily expose a cluster service externally if you can reach the node from your Ark client.
+
+You must also get the Minio URL, which you can then specify as the value of the new `publicUrl` field in your backup storage config.
+
+1.  In `examples/minio/00-minio-deployment.yaml`, change the value of Service `spec.type` from `ClusterIP` to `NodePort`.
+
+1.  Get the Minio URL:
+
+    - if you're running Minikube:
+
+      ```shell
+      minikube service minio --namespace=heptio-ark --url
+      ```
+
+    - in any other environment:
+
+      1.  Get the value of an external IP address or DNS name of any node in your cluster. You must be able to reach this address from the Ark client.
+
+      1.  Append the value of the NodePort to get a complete URL. You can get this value by running:
+
+          ```shell
+          kubectl -n heptio-ark get svc/minio -o jsonpath='{.spec.ports[0].nodePort}'
+          ```
+
+1.  In `examples/minio/05-ark-backupstoragelocation.yaml`, uncomment the `publicUrl` line and provide this Minio URL as the value of the `publicUrl` field. You must include the `http://` or `https://` prefix.
+
+#### Work with Ingress
+
+Configuring Ingress for your cluster is out of scope for the Ark documentation. If you have already set up Ingress, however, it makes sense to continue with it while you run the example Ark configuration with Minio.
+
+In this case: 
+
+1.  Keep the Service type as `ClusterIP`.
+
+1.  In `examples/minio/05-ark-backupstoragelocation.yaml`, uncomment the `publicUrl` line and provide the URL and port of your Ingress as the value of the `publicUrl` field.
+
 ### Install client
 
 [Download the client][26].

docs/rbac.md

@@ -0,0 +1,47 @@
+# Run Ark more securely with restrictive RBAC settings
+
+By default Ark runs with an RBAC policy of ClusterRole `cluster-admin`. This is to make sure that Ark can back up or restore anything in your cluster. But `cluster-admin` access is wide open -- it gives Ark components access to everything in your cluster. Depending on your environment and your security needs, you should consider whether to configure additional RBAC policies with more restrictive access. 
+
+**Note:** Roles and RoleBindings are associated with a single namespaces, not with an entire cluster. PersistentVolume backups are associated only with an entire cluster. This means that any backups or restores that use a restrictive Role and RoleBinding pair can manage only the resources that belong to the namespace. You do not need a wide open RBAC policy to manage PersistentVolumes, however. You can configure a ClusterRole and ClusterRoleBinding that allow backups and restores only of PersistentVolumes, not of all objects in the cluster.
+
+For more information about RBAC and access control generally in Kubernetes, see the Kubernetes documentation about [access control][1], [managing service accounts][2], and [RBAC authorization][3].
+
+## Set up Roles and RoleBindings
+
+Here's a sample Role and RoleBinding pair.
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  namespace: YOUR_NAMESPACE_HERE
+  name: ROLE_NAME_HERE
+  labels:
+    component: ark
+rules:
+  - apiGroups:
+      - ark.heptio.com
+    verbs:
+      - "*"
+    resources:
+      - "*"
+```
+
+```yaml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: ROLEBINDING_NAME_HERE
+subjects:
+  - kind: ServiceAccount
+    name: YOUR_SERVICEACCOUNT_HERE
+roleRef:
+  kind: Role
+  name: ROLE_NAME_HERE
+  apiGroup: rbac.authorization.k8s.io
+```
+
+[1]: https://kubernetes.io/docs/reference/access-authn-authz/controlling-access/
+[2]: https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/
+[3]: https://kubernetes.io/docs/reference/access-authn-authz/rbac/
+[4]: namespace.md

docs/troubleshooting.md

@@ -50,7 +50,7 @@ Alternatively, you might be able to use the Service's `spec.loadBalancerIP` fiel
 ### Ark reports `custom resource not found` errors when starting up.
 
 Ark's server will not start if the required Custom Resource Definitions are not found in Kubernetes. Apply
-the `examples/common/00-prereqs.yaml` file to create these defintions, then restart Ark.
+the `examples/common/00-prereqs.yaml` file to create these definitions, then restart Ark.
 
 ### `ark backup logs` returns a `SignatureDoesNotMatch` error
 
@@ -68,4 +68,5 @@ Here are some things to verify if you receive `SignatureDoesNotMatch` errors:
 [2]: debugging-install.md
 [4]: https://github.com/heptio/ark/issues
 [5]: https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html
-[25]: https://kubernetes.slack.com/messages/ark-dr
+[25]: https://kubernetes.slack.com/messages/ark-dr
+[26]: get-started.md#minikube-configuration

docs/versions.md

@@ -14,5 +14,13 @@ Breaking changes are documented in the release notes and in the documentation.
 
 - See [Upgrading to version 0.10.0][2]
 
+## Ark versions and Kubernetes versions
+
+Not all Ark versions support all versions of Kubernetes. You should be aware of the following known limitations:
+
+- Ark version 0.9.0 requires Kubernetes version 1.8 or later. In version 0.9.1, Ark was updated to support earlier versions.
+- Restic support requires Kubernetes version 1.10 or later, or an earlier version with the mount propagation feature enabled. See [Restic Integration][3].
+
 [1]: https://github.com/heptio/ark/releases
 [2]: upgrading-to-v0.10.md
+[3]: restic.md

examples/minio/00-minio-deployment.yaml

@@ -63,6 +63,9 @@ metadata:
   labels:
     component: minio
 spec:
+  # ClusterIP is recommended for production environments.
+  # Change to NodePort if needed per documentation,
+  # but only if you run Minio in a test/trial environment, for example with Minikube.
   type: ClusterIP
   ports:
     - port: 9000

examples/minio/05-ark-backupstoragelocation.yaml

@@ -26,5 +26,8 @@ spec:
     region: minio
     s3ForcePathStyle: "true"
     s3Url: http://minio.heptio-ark.svc:9000
+    # Uncomment the following line and provide the value of an externally
+    # available URL for downloading logs, running Ark describe, and more.
+    # publicUrl: https://minio.mycluster.com