Merge pull request crossplane#228 from jbw976/faqs-troubleshoot

docs: troubleshooting and FAQs

docs/faqs.md

@@ -3,4 +3,46 @@ title: FAQs
 toc: true
 weight: 510
 ---
-# Frequently Asked Questions (FAQs)
+# Frequently Asked Questions (FAQs)
+
+### Where did the name Crossplane come from?
+
+Crossplane is the fusing of cross-cloud control plane. We wanted to use a noun that refers to the entity responsible for connecting different cloud providers and acts as control plane across them. Cross implies “cross-cloud” and “plane” brings in “control plane”.
+
+### What's up with popsicle?
+
+We believe in a multi-flavor cloud.
+
+### Why is Upbound open sourcing this project? What are Upbound’s monetization plans?
+
+Upbound’s mission is to create a more open cloud-computing platform, with more choice and less lock-in. We believe the Crossplane as an important step towards this vision and that it’s going to take a village to solve this problem. We believe that multicloud control plane is a new category of open source software, and it will ultimately disrupt closed source and proprietary models. Upbound aspires to be a commercial provider of a more open cloud-computing platform.
+
+### What kind of governance model will be used for Crossplane?
+
+Crossplane will be an independent project and we plan on making a community driven project and not a vendor driven project. It will have an independent brand, github organization, and an open governance model. It will not be tied to single organization or individual.
+
+### Will Crossplane be donated to an open source foundation?
+
+We don’t know yet. We are open to doing so but we’d like to revisit this after the project has gotten some end-user community traction.
+
+### Does using multicloud mean you will use the lowest common denominator across clouds?
+
+Not necessarily. There are numerous best of breed cloud offerings that run on multiple clouds. For example, CockroachDB and ElasticSearch are world class implementations of platform software and run well on cloud providers. They compete with managed services offered by a cloud provider. We believe that by having a open control plane for they to integrate with, and providing a common API, CLI and UI for all of these services, that more of these offerings will exist and get first-class experience in the cloud.
+
+### How are resources and claims related to PersistentVolumes in Kubernetes?
+
+We modeled resource claims and classes after PersistentVolumes and PersistentVolumeClaims in Kubernetes. We believe many of the lessons learned from managing volumes in Kubernetes apply to managing resources within cloud providers. One notable exception is that we avoided creating a plugin model within Crossplane.
+
+### How is workload scheduling related to pod scheduling in Kubernetes?
+
+We modeled workload scheduling after the Pod scheduler in Kubernetes. We believe many of the lessons learned from Pod scheduling apply to scheduling workloads across cloud providers.
+
+### Can I use Crossplane to consistently provision and manage multiple Kubernetes clusters?
+
+Crossplane includes an portable API for Kubernetes clusters that will include common configuration including node pools, auto-scalers, taints, admission controllers, etc. These will be applied to the specific implementations within the cloud providers like EKS, GKE and AKS. We see the Kubernetes Cluster API to be something that will be used by administrators and not developers.
+
+### Other attempts at building a higher level API on-top of a multitude of inconsistent lower level APIs have not been successful, will Crossplane not have the same issues?
+
+We agree that building a consistent higher level API on top of multitudes of inconsistent lower level API's is well known to be fraught with peril (e.g. dumbing down to lowest common denominator, or resulting in so loosely defined an API as to be impossible to practically develop real portable applications on top of it).
+
+Crossplane follows a different approach here. The portable API extracts the pieces that are common across all implementations, and from the perspective of the workload. The rest of the implementation details are captured in full fidelity by the admin in resource classes. The combination of the two is what results in full configuration that can be deployed. We believe this to be a reasonable tradeoff that avoids the dumbing down to lowest common denominator problem, while still enabling portability.

docs/quick-start.md

@@ -5,4 +5,13 @@ weight: 210
 ---
 # Quick Start Guide
 
-## Deploying a Workload
+This quick start will demonstrate using Crossplane to deploy a portable stateful workload in the cloud provider of your choice.
+It will first dynamically provision a Kubernetes cluster within the cloud provider environment, followed by a stateful application and its database to the same environment.
+The database will also be dynamically provisioned using a managed service hosted by the cloud provider.
+The Workload will be deployed into the target Kubernetes cluster, and be configured to consume the database resource in a completely portable way.
+
+The general steps for this example are as follows:
+
+1. Set up a cloud provider and add it to Crossplane: [Adding a Cloud Provider](cloud-providers.md)
+1. Install Crossplane so it is ready to manage resources on your behalf: [Install Crossplane](install-crossplane.md)
+1. Deploy a portable workload to the cloud provider: [Deploying Workloads](deploy.md)

docs/running-resources.md

@@ -4,4 +4,17 @@ toc: true
 weight: 350
 indent: true
 ---
-# Running Resources
+# Running Resources
+
+Crossplane enables you to run a number of different resources in a portable and cloud agnostic way, allowing you to author an application that runs without modifications on multiple environments and cloud providers.
+A single Crossplane enables the provisioning and full-lifecycle management of infrastructure across a wide range of providers, vendors, regions, and offerings.
+
+## Running Databases
+
+## Running Kubernetes Clusters
+
+## Future support
+
+As the project continues to grow with support from the community, support for more resources will be added.
+This includes all of the essential managed services from cloud providers as well as local or in-cluster services that deploy using the operator pattern.
+Crossplane will provide support for serverless, databases, object storage (buckets), analytics, big data, AI, ML, message queues, key-value stores, and more.

docs/troubleshoot.md

@@ -5,3 +5,94 @@ weight: 360
 indent: true
 ---
 # Troubleshooting
+
+* [Crossplane Logs](#crossplane-logs)
+* [Resource Status and Conditions](#resource-status-and-conditions)
+* [Pausing Crossplane](#pausing-crossplane)
+* [Deleting a Resource Hangs](#deleting-a-resource-hangs)
+
+## Crossplane Logs
+
+The first place to look to get more information or investigate a failure would be in the Crossplane pod logs, which should be running in the `crossplane-system` namespace.
+To get the current Crossplane logs, run the following:
+
+```console
+kubectl -n crossplane-system logs $(kubectl -n crossplane-system get pod -l app=crossplane -o jsonpath='{.items[0].metadata.name}')
+```
+
+## Resource Status and Conditions
+
+All of the objects that represent managed resources such as databases, clusters, etc. have a `status` section that can give good insight into the current state of that particular object.
+In general, simply getting the `yaml` output of a Crossplane object will give insightful information about its condition:
+
+```console
+kubetl get <resource-type> -o yaml
+```
+
+For example, to get complete information about an Azure AKS cluster object, the following command will generate the below sample (truncated) output:
+
+```console
+> kubectl -n crossplane-system get akscluster -o yaml
+...
+  status:
+    Conditions:
+    - LastTransitionTime: 2018-12-04T08:03:01Z
+      Message: 'failed to start create operation for AKS cluster aks-demo-cluster:
+        containerservice.ManagedClustersClient#CreateOrUpdate: Failure sending request:
+        StatusCode=400 -- Please see https://aka.ms/acs-sp-help for more details."'
+      Reason: failed to create cluster
+      Status: "False"
+      Type: Failed
+    - LastTransitionTime: 2018-12-04T08:03:14Z
+      Message: ""
+      Reason: ""
+      Status: "False"
+      Type: Creating
+    - LastTransitionTime: 2018-12-04T09:59:43Z
+      Message: ""
+      Reason: ""
+      Status: "True"
+      Type: Ready
+    bindingPhase: Bound
+    endpoint: crossplane-aks-14af6e93.hcp.centralus.azmk8s.io
+    state: Succeeded
+```
+
+We can see a few conditions in that AKS cluster's history.
+It first encountered a failure, then it moved into the `Creating` state, then it finally became `Ready` later on.
+Conditions that have `Status: "True"` are currently active, while conditions with `Status: "False"` happened in the past, but are no longer happening currently.
+
+## Pausing Crossplane
+
+Sometimes, it can be useful to pause Crossplane if you want to stop it from actively attempting to manage your resources, for instance if you have encountered a bug.
+To pause Crossplane without deleting all of its resources, run the following command to simply scale down its deployment:
+
+```console
+kubectl -n crossplane-system scale --replicas=0 deployment/crossplane
+```
+
+Once you have been able to rectify the problem or smooth things out, you can unpause Crossplane simply by scaling its deployment back up:
+
+```console
+kubectl -n crossplane-system scale --replicas=1 deployment/crossplane
+```
+
+## Deleting a Resource Hangs
+
+The resources that Crossplane manages will automatically be cleaned up so as not to leave anything running behind.
+This is accomplished by using finalizers, but in certain scenarios, the finalizer can prevent the Kubernetes object from getting deleted.
+
+To deal with this, we essentially want to patch the object to remove its finalizer, which will then allow it to be deleted completely.
+Note that this won't necessarily delete the external resource that Crossplane was managing, so you will want to go to your cloud provider's console and look there for any lingering resources to clean up.
+
+In general, a finalizer can be removed from an object with this command:
+
+```console
+kubectl patch <resource-type> <resource-name> -p '{"metadata":{"finalizers": []}}' --type=merge
+```
+
+For example, for a Workload object (`workloads.compute.crossplane.io`) named `test-workload`, you can remove its finalizer with:
+
+```console
+kubectl patch workloads.compute.crossplane.io test-workload -p '{"metadata":{"finalizers": []}}' --type=merge
+```