crossplane
/
docs
mirror of https://github.com/crossplane/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs snapshot for crossplane version `master`

This commit is contained in:
Crossplane 2019-06-13 17:41:41 +00:00
parent 796787cb34
commit cd2788bae6
3 changed files with 122 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
docs/master/cloud-providers/gcp/gcp-provider.md
View File

@ -14,29 +14,60 @@ You can choose whichever you are more comfortable with.
## Option 1: gcloud Command Line Tool ## Option 1: gcloud Command Line Tool
If you have the `gcloud` tool installed, you can run below commands from the example directory. If you have the `gcloud` tool installed, you can run the commands below from the crossplane directory.
It
Instructions for installing `gcloud` can be found in the [Google docs](https://cloud.google.com/sdk/install). Instructions for installing `gcloud` can be found in the [Google docs](https://cloud.google.com/sdk/install).
### Using `gcp-credentials.sh`
In the `cluster/examples` directory you will find a helper script, `gcp-credentials.sh`. This script will prompt you for the organization, project, and billing account that will be used by `gcloud` when creating a project, service account, and credentials file (`crossplane-gcp-provider-key.json`). The chosen project and created service account will have access to the services and roles sufficient to run the Crossplane GCP examples.
```console
$ cluster/examples/gcp-credentials.sh
... EXAMPLE OUTPUT ONLY
export ORGANIZATION_ID=987654321
export PROJECT_ID=crossplane-example-1234
export EXAMPLE_SA=example-1234@crossplane-example-1234.iam.gserviceaccount.com
export BASE64ENCODED_GCP_PROVIDER_CREDS=$(base64 -w0 crossplane-gcp-provider-key.json)
```
After running `gcp-credentials.sh`, a series of `export` commands will be shown. Copy and paste the `export` commands that are provided. These variable names will be referenced throughout the Crossplane examples, generally with a `sed` command.
You will also find a `crossplane-gcp-provider-key.json` file in the current working directory. Be sure to remove this file when you are done with the example projects.
### Running `gcloud` by hand
```bash ```bash
# list your organizations (if applicable), take note of the specific organization ID you want to use # 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) # if you have more than one organization (not common)
gcloud organizations list gcloud organizations list
# create a new project # create a new project (project id must be <=30 characters)
export EXAMPLE_PROJECT_NAME=crossplane-example-123 export EXAMPLE_PROJECT_ID=crossplane-example-123
gcloud projects create $EXAMPLE_PROJECT_NAME --enable-cloud-apis [--organization ORGANIZATION_ID] gcloud projects create $EXAMPLE_PROJECT_ID --enable-cloud-apis # [--organization $ORGANIZATION_ID]
# record the PROJECT_ID value of the newly created project # or, record the PROJECT_ID value of an existing project
export EXAMPLE_PROJECT_ID=$(gcloud projects list --filter NAME=$EXAMPLE_PROJECT_NAME --format="value(PROJECT_ID)") # export EXAMPLE_PROJECT_ID=$(gcloud projects list --filter NAME=$EXAMPLE_PROJECT_NAME --format="value(PROJECT_ID)")
# link billing to the new project
gcloud beta billing accounts list
gcloud beta billing projects link $EXAMPLE_PROJECT_ID --billing-account=$ACCOUNT_ID
# enable Kubernetes API # enable Kubernetes API
gcloud --project $EXAMPLE_PROJECT_ID services enable container.googleapis.com gcloud --project $EXAMPLE_PROJECT_ID services enable container.googleapis.com
# enable CloudSQL API # enable CloudSQL API
gcloud --project $EXAMPLE_PROJECT_ID services enable sqladmin.googleapis.com gcloud --project $EXAMPLE_PROJECT_ID services enable sqladmin.googleapis.com
# enable Redis API
gcloud --project $EXAMPLE_PROJECT_ID services enable redis.googleapis.com
# enable Additional APIs needed for the example or project
# See `gcloud services list` for a complete list
# create service account # create service account
gcloud --project $EXAMPLE_PROJECT_ID iam service-accounts create example-123 --display-name "Crossplane Example" gcloud --project $EXAMPLE_PROJECT_ID iam service-accounts create example-123 --display-name "Crossplane Example"
# export service account email # export service account email
export EXAMPLE_SA="example-123@$EXAMPLE_PROJECT_ID.iam.gserviceaccount.com" export EXAMPLE_SA="example-123@$EXAMPLE_PROJECT_ID.iam.gserviceaccount.com"
@ -47,6 +78,7 @@ gcloud --project $EXAMPLE_PROJECT_ID iam service-accounts keys create --iam-acco
gcloud projects add-iam-policy-binding $EXAMPLE_PROJECT_ID --member "serviceAccount:$EXAMPLE_SA" --role="roles/iam.serviceAccountUser" gcloud projects add-iam-policy-binding $EXAMPLE_PROJECT_ID --member "serviceAccount:$EXAMPLE_SA" --role="roles/iam.serviceAccountUser"
gcloud projects add-iam-policy-binding $EXAMPLE_PROJECT_ID --member "serviceAccount:$EXAMPLE_SA" --role="roles/cloudsql.admin" gcloud projects add-iam-policy-binding $EXAMPLE_PROJECT_ID --member "serviceAccount:$EXAMPLE_SA" --role="roles/cloudsql.admin"
gcloud projects add-iam-policy-binding $EXAMPLE_PROJECT_ID --member "serviceAccount:$EXAMPLE_SA" --role="roles/container.admin" gcloud projects add-iam-policy-binding $EXAMPLE_PROJECT_ID --member "serviceAccount:$EXAMPLE_SA" --role="roles/container.admin"
gcloud projects add-iam-policy-binding $EXAMPLE_PROJECT_ID --member "serviceAccount:$EXAMPLE_SA" --role="roles/redis.admin"
``` ```
## Option 2: GCP Console in a Web Browser ## Option 2: GCP Console in a Web Browser
@ -56,7 +88,7 @@ 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. 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) - Login into [GCP Console](https://console.cloud.google.com)
- Create a new project (either stand alone or under existing organization) - Create a [new project](https://console.cloud.google.com/flows/enableapi?apiid=container.googleapis.com,sqladmin.googleapis.com,redis.googleapis.com) (either stand alone or under existing organization)
- Create Example Service Account - Create Example Service Account
- Navigate to: [Create Service Account](https://console.cloud.google.com/iam-admin/serviceaccounts) - Navigate to: [Create Service Account](https://console.cloud.google.com/iam-admin/serviceaccounts)
- `Service Account Name`: type "example" - `Service Account Name`: type "example"
@ -87,10 +119,13 @@ Create a GCP example project which we will use to host our example GKE cluster,
- Enable `Kubernetes Engine API` - Enable `Kubernetes Engine API`
- Navigate to [Kubernetes Engine API](https://console.developers.google.com/apis/api/container.googleapis.com/overview) - Navigate to [Kubernetes Engine API](https://console.developers.google.com/apis/api/container.googleapis.com/overview)
- Click `Enable` - Click `Enable`
- Enable `Cloud Memorystore for Redis`
- Navigate to [Cloud Memorystore for Redis](https://console.developers.google.com/apis/api/redis.googleapis.com/overview)
- Click `Enable`
## Enable Billing ### 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. 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) - Go to [GCP Console](https://console.cloud.google.com)
- Select example project - Select example project

2
docs/master/troubleshoot.md
View File

@ -17,7 +17,7 @@ The first place to look to get more information or investigate a failure would b
To get the current Crossplane logs, run the following: To get the current Crossplane logs, run the following:
```console ```console
kubectl -n crossplane-system logs $(kubectl -n crossplane-system get pod -l app=crossplane -o jsonpath='{.items[0].metadata.name}') kubectl -n crossplane-system logs -lapp=crossplane
``` ```
## Resource Status and Conditions ## Resource Status and Conditions

102
docs/master/workloads/gcp/wordpress-gcp.md
View File

@ -17,81 +17,87 @@ You should have a `crossplane-gcp-provider-key.json` file on your local filesyst
This section covers the tasks performed by the cluster or cloud administrator, which includes: This section covers the tasks performed by the cluster or cloud administrator, which includes:
- Import GCP provider credentials * Import GCP provider credentials
- Define Resource classes for cluster and database resources * Define Resource classes for cluster and database resources
- Create a target Kubernetes cluster (using dynamic provisioning with the cluster resource class) * Create a target Kubernetes cluster (using dynamic provisioning with the cluster resource class)
**Note**: all artifacts created by the administrator are stored/hosted in the `crossplane-system` namespace, which has **Note**: all artifacts created by the administrator are stored/hosted in the `crossplane-system` namespace, which has
restricted access, i.e. `Application Owner(s)` should not have access to them. restricted access, i.e. `Application Owner(s)` should not have access to them.
For the next steps, make sure your `kubectl` context points to the cluster where `Crossplane` was deployed. For the next steps, make sure your `kubectl` context points to the cluster where `Crossplane` was deployed.
- Export Project ID * Export Project ID and GCP Provider Credentials:
**NOTE** you can skip this step if you generated GCP Service Account using `gcloud`
```bash
export DEMO_PROJECT_ID=[your-demo-project-id]
```
- Patch and Apply `provider.yaml`:
```bash ```bash
sed "s/BASE64ENCODED_CREDS/`cat key.json|base64 | tr -d '\n'`/g;s/DEMO_PROJECT_ID/$DEMO_PROJECT_ID/g" cluster/examples/workloads/wordpress-gcp/provider.yaml | kubectl create -f - export PROJECT_ID=[your-demo-project-id]
export BASE64ENCODED_GCP_PROVIDER_CREDS=$(base64 -w0 crossplane-gcp-provider-key.json)
``` ```
- Verify that GCP Provider is in `Ready` state * Patch and Apply `provider.yaml`:
```bash
sed "s/BASE64ENCODED_GCP_PROVIDER_CREDS/$BASE64ENCODED_GCP_PROVIDER_CREDS/g;s/PROJECT_ID/$PROJECT_ID/g" cluster/examples/workloads/kubernetes/wordpress-gcp/provider.yaml | kubectl create -f -
```
* Verify that GCP Provider is in `Ready` state
```bash ```bash
kubectl -n crossplane-system get providers.gcp.crossplane.io -o custom-columns=NAME:.metadata.name,STATUS:'.status.Conditions[?(@.Status=="True")].Type',PROJECT-ID:.spec.projectID kubectl -n crossplane-system get providers.gcp.crossplane.io -o custom-columns=NAME:.metadata.name,STATUS:'.status.Conditions[?(@.Status=="True")].Type',PROJECT-ID:.spec.projectID
``` ```
Your output should look similar to: Your output should look similar to:
```bash ```bash
NAME STATUS PROJECT-ID NAME STATUS PROJECT-ID
gcp-provider Ready [your-project-id] gcp-provider Ready [your-project-id]
``` ```
- Verify that Resource Classes have been created * Verify that Resource Classes have been created
```bash ```bash
kubectl -n crossplane-system get resourceclass -o custom-columns=NAME:metadata.name,PROVISIONER:.provisioner,PROVIDER:.providerRef.name,RECLAIM-POLICY:.reclaimPolicy kubectl -n crossplane-system get resourceclass -o custom-columns=NAME:metadata.name,PROVISIONER:.provisioner,PROVIDER:.providerRef.name,RECLAIM-POLICY:.reclaimPolicy
``` ```
Your output should be: Your output should be:
```bash ```bash
NAME PROVISIONER PROVIDER RECLAIM-POLICY NAME PROVISIONER PROVIDER RECLAIM-POLICY
standard-cluster gkecluster.compute.gcp.crossplane.io/v1alpha1 gcp-provider Delete standard-cluster gkecluster.compute.gcp.crossplane.io/v1alpha1 gcp-provider Delete
standard-mysql cloudsqlinstance.database.gcp.crossplane.io/v1alpha1 gcp-provider Delete standard-mysql cloudsqlinstance.database.gcp.crossplane.io/v1alpha1 gcp-provider Delete
``` ```
- Create a target Kubernetes cluster where `Application Owner(s)` will deploy their `WorkLoad(s)` * Create a target Kubernetes cluster and namespace where `Application Owner(s)` will deploy their `WorkLoad(s)`
As administrator, you will create a Kubernetes cluster leveraging the Kubernetes cluster `ResourceClass` that was created earlier and As administrator, you will create a Kubernetes cluster leveraging the Kubernetes cluster `ResourceClass` that was created earlier and
`Crossplane` Kubernetes cluster dynamic provisioning. `Crossplane` Kubernetes cluster dynamic provisioning.
The `Application Developer(s)` will use the `complex` namespace.
```bash ```bash
kubectl apply -f cluster/examples/workloads/wordpress-gcp/cluster.yaml kubectl apply -f cluster/examples/workloads/kubernetes/wordpress-gcp/cluster.yaml
``` ```
- Verify that Kubernetes Cluster resource was created * Verify that the Kubernetes Cluster resource was created
```bash ```bash
kubectl -n crossplane-system get kubernetescluster -o custom-columns=NAME:.metadata.name,CLUSTERCLASS:.spec.classReference.name,CLUSTERREF:.spec.resourceName.name kubectl -n complex get kubernetescluster -o custom-columns=NAME:.metadata.name,CLUSTERCLASS:.spec.classReference.name,CLUSTERREF:.spec.resourceName.name
``` ```
Your output should look similar to: Your output should look similar to:
```bash ```bash
NAME CLUSTERCLASS CLUSTERREF NAME CLUSTERCLASS CLUSTERREF
demo-gke-cluster standard-cluster gke-67419e79-f5b3-11e8-9cec-9cb6d08bde99 wordpress-demo-cluster standard-cluster gke-67419e79-f5b3-11e8-9cec-9cb6d08bde99
``` ```
- Verify that the target GKE cluster was successfully created * Verify that the target GKE cluster was successfully created
```bash ```bash
kubectl -n crossplane-system get gkecluster -o custom-columns=NAME:.metadata.name,STATE:.status.state,CLUSTERNAME:.status.clusterName,ENDPOINT:.status.endpoint,LOCATION:.spec.zone,CLUSTERCLASS:.spec.classRef.name,RECLAIMPOLICY:.spec.reclaimPolicy kubectl -n crossplane-system get gkecluster -o custom-columns=NAME:.metadata.name,STATE:.status.state,CLUSTERNAME:.status.clusterName,ENDPOINT:.status.endpoint,LOCATION:.spec.zone,CLUSTERCLASS:.spec.classRef.name,RECLAIMPOLICY:.spec.reclaimPolicy
``` ```
Your output should look similar to: Your output should look similar to:
```bash ```bash
NAME STATE CLUSTERNAME ENDPOINT LOCATION CLUSTERCLASS RECLAIMPOLICY NAME STATE CLUSTERNAME ENDPOINT LOCATION CLUSTERCLASS RECLAIMPOLICY
gke-67419e79-f5b3-11e8-9cec-9cb6d08bde99 RUNNING gke-6742fe8d-f5b3-11e8-9cec-9cb6d08bde99 146.148.93.40 us-central1-a standard-cluster Delete gke-67419e79-f5b3-11e8-9cec-9cb6d08bde99 RUNNING gke-6742fe8d-f5b3-11e8-9cec-9cb6d08bde99 146.148.93.40 us-central1-a standard-cluster Delete
@ -99,36 +105,38 @@ For the next steps, make sure your `kubectl` context points to the cluster where
To recap the operations that we just performed as the administrator: To recap the operations that we just performed as the administrator:
- Defined a `Provider` with Google Service Account credentials * Defined a `Provider` with Google Service Account credentials
- Defined `ResourceClasses` for `KubernetesCluster` and `MySQLInstance` * Defined `ResourceClasses` for `KubernetesCluster` and `MySQLInstance`
- Provisioned (dynamically) a GKE Cluster using the `ResourceClass` * Provisioned (dynamically) a GKE Cluster using the `ResourceClass` in a new namespace named `complex`
## Application Developer Tasks ## Application Developer Tasks
This section covers the tasks performed by the application developer, which includes: This section covers the tasks performed by the application developer, which includes:
- Define Workload in terms of Resources and Payload (Deployment/Service) which will be deployed into the target Kubernetes Cluster * Define Workload in terms of Resources and Payload (Deployment/Service) which will be deployed into the target Kubernetes Cluster
- Define the dependency resource requirements, in this case a `MySQL` database * Define the dependency resource requirements, in this case a `MySQL` database
Let's begin deploying the workload as the application developer: Let's begin deploying the workload as the application developer:
- Deploy workload * Deploy workload
```bash ```bash
kubectl apply -f cluster/examples/workloads/wordpress-gcp/workload.yaml kubectl apply -f cluster/examples/workloads/kubernetes/wordpress-gcp/app.yaml
``` ```
- Wait for `MySQLInstance` to be in `Bound` State * Wait for `MySQLInstance` to be in `Bound` State
You can check the status via: You can check the status via:
```bash ```bash
kubectl get mysqlinstance -o custom-columns=NAME:.metadata.name,VERSION:.spec.engineVersion,STATE:.status.bindingPhase,CLASS:.spec.classReference.name kubectl get mysqlinstance -n complex -o custom-columns=NAME:.metadata.name,VERSION:.spec.engineVersion,STATE:.status.bindingPhase,CLASS:.spec.classReference.name
``` ```
Your output should look like: Your output should look like:
```bash ```bash
NAME VERSION STATE CLASS NAME VERSION STATE CLASS
demo 5.7 Bound standard-mysql sql 5.7 Bound standard-mysql
``` ```
**Note**: to check on the concrete resource type status as `Administrator` you can run: **Note**: to check on the concrete resource type status as `Administrator` you can run:
@ -138,26 +146,32 @@ Let's begin deploying the workload as the application developer:
``` ```
Your output should be similar to: Your output should be similar to:
```bash ```bash
NAME STATUS CLASS VERSION NAME STATUS CLASS VERSION
mysql-2fea0d8e-f5bb-11e8-9cec-9cb6d08bde99 RUNNABLE standard-mysql MYSQL_5_7 mysql-2fea0d8e-f5bb-11e8-9cec-9cb6d08bde99 RUNNABLE standard-mysql MYSQL_5_7
``` ```
- Wait for `Workload` External IP Address * Wait for the Wordpress service, a `KubernetesApplicationResource`, to report its External IP Address
```bash ```bash
kubectl get workload -o custom-columns=NAME:.metadata.name,CLUSTER:.spec.targetCluster.name,NAMESPACE:.spec.targetNamespace,DEPLOYMENT:.spec.targetDeployment.metadata.name,SERVICE-EXTERNAL-IP:.status.service.loadBalancer.ingress[0].ip kubectl get kubernetesapplicationresource.workload.crossplane.io -n complex -o custom-columns=NAME:.metadata.name,NAMESPACE:.spec.template.metadata.namespace,KIND:.spec.template.kind,SERVICE-EXTERNAL-IP:.status.remote.loadBalancer.ingress[0].ip
``` ```
**Note** the `Workload` is defined in Application Owner's (`default`) namespace
**Note** the `Workload` is defined in Application Owner's (`complex`) namespace
Your output should look similar to: Your output should look similar to:
```bash ```bash
NAME CLUSTER NAMESPACE DEPLOYMENT SERVICE-EXTERNAL-IP NAME NAMESPACE KIND SERVICE-EXTERNAL-IP
demo demo-gke-cluster demo wordpress 35.193.100.113 wordpress-demo-deployment wordpress Deployment <none>
wordpress-demo-namespace <none> Namespace <none>
wordpress-demo-service wordpress Service 35.232.9.69
``` ```
- Verify that `WordPress` service is accessible via `SERVICE-EXTERNAL-IP` by: * Verify that `WordPress` service is accessible via `SERVICE-EXTERNAL-IP`:
- Navigate in your browser to `SERVICE-EXTERNAL-IP`
* Navigate in your browser to `SERVICE-EXTERNAL-IP`
At this point, you should see the setup page for WordPress in your web browser. At this point, you should see the setup page for WordPress in your web browser.
@ -165,25 +179,25 @@ At this point, you should see the setup page for WordPress in your web browser.
Once you are done with this example, you can clean up all its artifacts with the following commands: Once you are done with this example, you can clean up all its artifacts with the following commands:
- Remove `Workload` * Remove the `App`
```bash ```bash
kubectl delete -f cluster/examples/workloads/wordpress-gcp/workload.yaml kubectl delete -f cluster/examples/workloads/kubernetes/wordpress-gcp/app.yaml
``` ```
- Remove `KubernetesCluster` * Remove the `KubernetesCluster`
```bash ```bash
kubectl delete -f cluster/examples/workloads/wordpress-gcp/cluster.yaml kubectl delete -f cluster/examples/workloads/kubernetes/wordpress-gcp/cluster.yaml
``` ```
- Remove GCP `Provider` and `ResourceClasses` * Remove the GCP `Provider` and Crossplane `ResourceClasses`
```bash ```bash
kubectl delete -f cluster/examples/workloads/wordpress-gcp/provider.yaml kubectl delete -f cluster/examples/workloads/kubernetes/wordpress-gcp/provider.yaml
``` ```
- Delete Google Project * Delete Google Project
```bash ```bash
# list all your projects # list all your projects