docs: clean up and update content for adding cloud providers and depl…

…oying workloads Signed-off-by: Jared Watts <jbw976@gmail.com>
arturrez · Dec 4, 2018 · c9b9935 · c9b9935
1 parent 5420711
commit c9b9935
Show file tree

Hide file tree

Showing 9 changed files with 486 additions and 364 deletions.
diff --git a/...s/workloads/wordpress-aws/kubernetes.yaml → ...ples/workloads/wordpress-aws/cluster.yaml b/...s/workloads/wordpress-aws/kubernetes.yaml → ...ples/workloads/wordpress-aws/cluster.yaml
diff --git a/docs/README.md b/docs/README.md
@@ -12,6 +12,8 @@ Crossplane includes a workload scheduler that can factor a number of criteria in
 
 For a deeper dive into Crossplane, see the [architecture](https://docs.google.com/document/d/1whncqdUeU2cATGEJhHvzXWC9xdK29Er45NJeoemxebo/edit?usp=sharing) document.
 
+## Table of Contents
+
 * [Quick Start Guide](quick-start.md)
 * [Getting Started](getting-started.md)
   * [Installing Crossplane](install-crossplane.md)

diff --git a/docs/cloud-providers/aws/aws-provider.md b/docs/cloud-providers/aws/aws-provider.md
@@ -1,113 +1,33 @@
-## Amazon Web Services (AWS)
+# Adding Amazon Web Services (AWS) to Crossplane
 
-The following instructions will help you configure AWS.
+In this guide, we will walk through the steps necessary to configure your AWS account to be ready for integration with Crossplane.
 
-### AWS Credentials
+## AWS Credentials
 
-AWS Credentials file
+### Option 1: aws Command Line Tool
+
+If you have already installed and configured the [`aws` command line tool](https://aws.amazon.com/cli/), you can simply find your AWS credentials file in `~/.aws/credentials`.
+
+### Option 2: AWS Console in Web Browser
+
+If you do not have the `aws` tool installed, you can alternatively log into the [AWS console](https://aws.amazon.com/console/) and export the credentials.
+The steps to follow below are from the [AWS SDK for GO](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/setting-up.html):
 
-Follow the steps in the [AWS SDK for GO](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/setting-up.html) to get your access key ID and secret access key
 1. Open the IAM console.
 1. On the navigation menu, choose Users.
 1. Choose your IAM user name (not the check box).
 1. Open the Security credentials tab, and then choose Create access key.
 1. To see the new access key, choose Show. Your credentials resemble the following:
     - Access key ID: AKIAIOSFODNN7EXAMPLE
     - Secret access key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
-1. To download the key pair, choose Download .csv file. Store the keys
+1. To download the key pair, choose Download .csv file.
+
+Then convert the `*.csv` file to the below format and save it to `~/.aws/credentials`:
 
-Convert *.csv to `.aws/credentials` format
 ```
 [default]
 aws_access_key_id = AKIAIOSFODNN7EXAMPLE
 aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
 ```
 
-**Note** If you have installed and configured `aws cli` you can find your AWS credentials file in  `~/.aws/credentials`
-
-## Setup AWS provider
-
-Next, create a `example` namespace:
-
-```console
-kubectl create namespace example
-```
-
-### Create credentials
-
-1. Get base64 encoded credentials with cat ~/.aws/credentials|base64|tr -d '\n'
-1. Replace BASE64ENCODED_AWS_PROVIDER_CREDS in cluster/examples/workloads/wordpress-aws/provider.yaml with value from previous step.
-
-## Deploy EKS Cluster
-
-### Create a named keypair
-* If you already have an ec2 keypair you can use your existing key pair https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html
-* Replace your keypair name in cluster/examples/workloads/wordpress-aws/provider.yaml in EKS_WORKER_KEY_NAME
-
-### Create your Amazon EKS Service Role
-[Original Source](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html)
-
-1. Open the IAM console at https://console.aws.amazon.com/iam/.
-1. Choose Roles, then Create role.
-1. Choose EKS from the list of services, then Allows Amazon EKS to manage your clusters on your behalf for your use case, then Next: Permissions.
-1. Choose Next: Review.
-1. For Role name, enter a unique name for your role, such as eksServiceRole, then choose Create role.
-1. Replace EKS_ROLE_ARN in cluster/examples/workloads/wordpress-aws/provider.yaml with role arn from previous step.
-
-### Create your Amazon EKS Cluster VPC
-[Original Source](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html)
-
-1. Open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation.
-1. From the navigation bar, select a Region that supports Amazon EKS.
-    ```> Note
-     Amazon EKS is available in the following Regions at this time:
-     * US West (Oregon) (us-west-2)
-     * US East (N. Virginia) (us-east-1)
-     * EU (Ireland) (eu-west-1)
-    ```
-
-1. Choose Create stack.
-1. For Choose a template, select Specify an Amazon S3 template URL.
-1. Paste the following URL into the text area and choose Next:
-    ```
-    https://amazon-eks.s3-us-west-2.amazonaws.com/cloudformation/2018-11-07/amazon-eks-vpc-sample.yaml
-    ```
-1. On the Specify Details page, fill out the parameters accordingly, and then choose Next.
-    ```
-    * Stack name: Choose a stack name for your AWS CloudFormation stack. For example, you can call it eks-vpc.
-    * VpcBlock: Choose a CIDR range for your VPC. You may leave the default value.
-    * Subnet01Block: Choose a CIDR range for subnet 1. You may leave the default value.
-    * Subnet02Block: Choose a CIDR range for subnet 2. You may leave the default value.
-    * Subnet03Block: Choose a CIDR range for subnet 3. You may leave the default value.
-    ```
-1. (Optional) On the Options page, tag your stack resources. Choose Next.
-1. On the Review page, choose Create.
-1. When your stack is created, select it in the console and choose Outputs.
-1. Replace `EKS_VPC`, `EKS_ROLE_ARN`, `EKS_SUBNETS`, `EKS_SECURITY_GROUP` in cluster/examples/workloads/wordpress-aws/provider.yaml with values from previous step (vpcId, subnetIds, securityGroupIds). Note `EKS_SECURITY_GROUP` needs to be replaced twice in file.
-1. Replace `REGION` in cluster/examples/workloads/wordpress-aws/provider.yaml with the region you selected in VPC creation.
-
-### Create an RDS subnet group
-1. Navigate to aws console in same region as eks clsuter
-1. Navigate to `RDS` service
-1. Naviate to `Subnet groups` in left hand pane
-1. Click `Create DB Subnet Group`
-1. Name your subnet i.e. eks-db-subnets
-1. Select the VPC created in the EKS VPC step
-1. Click `Add all subnets related to this VPC`
-1. Click Create
-1. Replace `RDS_SUBNET_GROUP` in cluster/examples/workloads/wordpress-aws/provider.yaml in DBSubnetgroup name you just created.
-
-### Create an RDS Security Group (example only)
-
-**Note**: This will make your RDS instance visible from Anywhere on the internet. This if for **EXAMPLE PURPOSES ONLY**, and
-is **NOT RECOMMENDED** for production system.
-
-1. Navigate to ec2 in the region of the EKS cluster
-1. Navigate to security groups
-1. Select the same VPC from the EKS cluster.
-1. On the Inbound Rules tab, choose Edit.
-    - For Type, choose `MYSQL/Aurora`
-    - For Port Range, type `3306`
-    - For Source, choose `Anywhere` from drop down or type: `0.0.0.0/0`
-1. Choose Add another rule if you need to add more IP addresses or different port ranges.
-1. Replace `RDS_SECURITY_GROUP` in cluster/examples/workloads/wordpress-aws/provider.yaml with the security group we just created.
+After the steps above, you should have your AWS credentials stored in `~/.aws/credentials`.
diff --git a/docs/cloud-providers/azure/azure-provider.md b/docs/cloud-providers/azure/azure-provider.md
@@ -1,8 +1,13 @@
-## Microsoft Azure
+# Adding Microsoft Azure to Crossplane
 
-Azure service principal credentials are needed for an admin account, which must be created before starting this Wordpress Workload example.
+In this guide, we will walk through the steps necessary to configure your Azure account to be ready for integration with Crossplane.
+The general steps we will take are summarized below:
 
-### Preparing your Microsoft Azure Account
+* Create a new service principal (account) that Crossplane will use to create and manage Azure resources
+* Add the required permissions to the account
+* Consent to the permissions using an administrator account
+
+## Preparing your Microsoft Azure Account
 
 In order to manage resources in Azure, you must provide credentials for a Azure service principal that Crossplane can use to authenticate.
 This assumes that you have already [set up the Azure CLI client](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli?view=azure-cli-latest) with your credentials.
@@ -14,13 +19,13 @@ Create a JSON file that contains all the information needed to connect and authe
 az ad sp create-for-rbac --sdk-auth --role Owner > crossplane-azure-provider-key.json
 ```
 
-Save the `clientID` value from the JSON file we just created to an environment variable:
+Take note of the `clientID` value from the JSON file that we just created, and save it to an environment variable:
 
 ```console
 export AZURE_CLIENT_ID=<clientId value from json file>
 ```
 
-Now add the required permissions to the service principal we created that allow us to manage the necessary resources in Azure:
+Now add the required permissions to the service principal that will allow it to manage the necessary resources in Azure:
 
 ```console
 # add required Azure Active Directory permissions
@@ -40,12 +45,17 @@ After these steps are completed, you should have the following file on your loca
 
 * `crossplane-azure-provider-key.json`
 
-## Grant Consent to application
-1. `echo ${AZURE_CLIENT_ID}` and note id
-1. Navigate to azure console: https://portal.azure.com
-1. Click Azure Active Directory
+## Grant Consent to Application Permissions
+
+One more step is required to fully grant the permissions to the new service principal.
+From the Azure Portal, you need to grant consent for the permissions using an admin account.
+The steps to perform this action are listed below:
+
+1. `echo ${AZURE_CLIENT_ID}` and note this ID value
+1. Navigate to the Azure Portal: https://portal.azure.com
+1. Click `Azure Active Directory`, or find it in the `All services` list
 1. Click `App registrations (Preview)`
-1. Click on app item where client id matches step 1
+1. Click on the application from the list where the application (client) ID matches the value from step 1
 1. Click `API permissions`
 1. Click `Grant admin consent for Default Directory`
 1. Click `Yes`
diff --git a/docs/cloud-providers/gcp/gcp-provider.md b/docs/cloud-providers/gcp/gcp-provider.md
@@ -1,49 +1,31 @@
-## Google Cloud Platform (GCP)
+# Adding Google Cloud Platform (GCP) to Crossplane
 
-Create a GCP example project which we will use to host our example GKE cluster, as well as our example CloudSQL instance.
+In this guide, we will walk through the steps necessary to configure your GCP account to be ready for integration with Crossplane.
+The general steps we will take are summarized below:
 
-- Login into [GCP Console](https://console.cloud.google.com)
-- Create a new project (either stand alone or under existing organization)
-- Create Example Service Account
-    - Navigate to: [Create Service Account](https://console.cloud.google.com/iam-admin/serviceaccounts)
-    - `Service Account Name`: type "example"
-    - `Service Account ID`: leave auto assigned
-    - `Service Account Description`: type "Crossplane example"
-    - Hit `Create` button
-        - This should advance to the next section `2 Grant this service account to project (optional)`
-    - We will assign this account 3 roles:
-        - `Service Account User`
-        - `Cloud SQL Admin`
-        - `Kubernetes Engine Admin`  
-    - Hit `Create` button
-        - This should advance to the next section `3 Grant users access to this service account (optinoal)`
-    - We don't need to assign any user or admin roles to this account for the example purposes, so you can leave following two fields blank:
-        - `Service account users role`
-        - `Service account admins role`
-    - Next, we will create and export service account key
-        - Hit `+ Create Key` button. 
-            - This should open a `Create Key` side panel
-        - Select `json` for the Key type (should be selected by default) 
-        - Hit `Create`
-            - This should show `Private key saved to your computer` confirmation dialog
-            - You also should see `crossplane-example-1234-[suffix].json` file in your browser's Download directory
-            - Save (copy or move) this file into example (this) directory, with new name `key.json`
-- Enable `Cloud SQL API`
-    - Navigate to [Cloud SQL Admin API](https://console.developers.google.com/apis/api/sqladmin.googleapis.com/overview)
-    - Hit `Enable`
-- Enable `Kubernetes Engine API`
-    - Navigate to [Kubernetes Engine API](https://console.developers.google.com/apis/api/container.googleapis.com/overview)
-    - Hit `Enable`
+* Create a new example project that all resources will be deployed to
+* Enable required APIs such as Kubernetes and CloudSQL
+* Create a service account that will be used to perform GCP operations from Crossplane
+* Assign necessary roles to the service account
+* Enable billing
+
+For your convenience, the specific steps to accomplish those tasks are provided for you below using either the `gcloud` command line tool, or the GCP console in a web browser.
+You can choose whichever you are more comfortable with.
+
+## Option 1: gcloud Command Line Tool
 
-If you have `gcloud` utility, you can ran following commands from the example directory 
+If you have the `gcloud` tool installed, you can run below commands from the example directory.
+It
+Instructions for installing `gcloud` can be found in the [Google docs](https://cloud.google.com/sdk/install).
 
 ```bash
-# list your organizations (if applicable)
+# list your organizations (if applicable), take note of the specific organization ID you want to use
+# if you have more than one organization (not common)
 gcloud organizations list
-    
+
 # create a new project
 export EXAMPLE_PROJECT_NAME=crossplane-example-123
-gcloud projects create $EXAMPLE_PROJECT_NAME --enable-cloud-apis [--organization ORANIZATION_ID]
+gcloud projects create $EXAMPLE_PROJECT_NAME --enable-cloud-apis [--organization ORGANIZATION_ID]
 
 # record the PROJECT_ID value of the newly created project
 export EXAMPLE_PROJECT_ID=$(gcloud projects list --filter NAME=$EXAMPLE_PROJECT_NAME --format="value(PROJECT_ID)")   
@@ -67,10 +49,51 @@ gcloud projects add-iam-policy-binding $EXAMPLE_PROJECT_ID --member "serviceAcco
 gcloud projects add-iam-policy-binding $EXAMPLE_PROJECT_ID --member "serviceAccount:$EXAMPLE_SA" --role="roles/container.admin"
 ```
 
-### Enable Billing
-In order to create GKE clusters you must enable Billing.
+## Option 2: GCP Console in a Web Browser
+
+If you chose to use the `gcloud` tool, you can skip this section entirely.
+
+Create a GCP example project which we will use to host our example GKE cluster, as well as our example CloudSQL instance.
+
+- Login into [GCP Console](https://console.cloud.google.com)
+- Create a new project (either stand alone or under existing organization)
+- Create Example Service Account
+    - Navigate to: [Create Service Account](https://console.cloud.google.com/iam-admin/serviceaccounts)
+    - `Service Account Name`: type "example"
+    - `Service Account ID`: leave auto assigned
+    - `Service Account Description`: type "Crossplane example"
+    - Click `Create` button
+        - This should advance to the next section `2 Grant this service account to project (optional)`
+    - We will assign this account 3 roles:
+        - `Service Account User`
+        - `Cloud SQL Admin`
+        - `Kubernetes Engine Admin`
+    - Click `Create` button
+        - This should advance to the next section `3 Grant users access to this service account (optional)`
+    - We don't need to assign any user or admin roles to this account for the example purposes, so you can leave following two fields blank:
+        - `Service account users role`
+        - `Service account admins role`
+    - Next, we will create and export service account key
+        - Click `+ Create Key` button.
+            - This should open a `Create Key` side panel
+        - Select `json` for the Key type (should be selected by default)
+        - Click `Create`
+            - This should show `Private key saved to your computer` confirmation dialog
+            - You also should see `crossplane-example-1234-[suffix].json` file in your browser's Download directory
+            - Save (copy or move) this file into example (this) directory, with new name `key.json`
+- Enable `Cloud SQL API`
+    - Navigate to [Cloud SQL Admin API](https://console.developers.google.com/apis/api/sqladmin.googleapis.com/overview)
+    - Click `Enable`
+- Enable `Kubernetes Engine API`
+    - Navigate to [Kubernetes Engine API](https://console.developers.google.com/apis/api/container.googleapis.com/overview)
+    - Click `Enable`
+
+## Enable Billing
+
+No matter what option you chose to configure the previous steps, you will need to enable billing for your account in order to create and use Kubernetes clusters with GKE.
+
 - Go to [GCP Console](https://console.cloud.google.com)
     - Select example project
-    - Hit "Enable Billing"
+    - Click `Enable Billing`
 - Go to [Kubernetes Clusters](https://console.cloud.google.com/kubernetes/list)
-    - Hit "Enable Billing"
+    - Click `Enable Billing`