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-09-18 05:32:51 +00:00
parent 1e504d131d
commit c657560961
8 changed files with 201 additions and 258 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/master/README.md
View File

@ -138,11 +138,6 @@ If you have any questions, please drop us a note on [Crossplane Slack][join-cros
* [Quick Start Guide](quick-start.md)
* [Getting Started](getting-started.md)
* [Installing Crossplane](install-crossplane.md)
* [Adding Your Cloud Providers](cloud-providers.md)
* [Deploying Workloads](deploy.md)
* [Running Resources](running-resources.md)
* [Troubleshooting](troubleshoot.md)
* [Concepts](concepts.md)
* [API Reference](api.md)
* [FAQs](faqs.md)

1
docs/master/cloud-providers.md
View File

@ -11,6 +11,7 @@ In order for Crossplane to be able to manage resources across all your clouds, y
Use the links below for specific instructions to add each of the following cloud providers:
* [Google Cloud Platform (GCP)](cloud-providers/gcp/gcp-provider.md)
* Required for Quick Start
* [Microsoft Azure](cloud-providers/azure/azure-provider.md)
* [Amazon Web Services (AWS)](cloud-providers/aws/aws-provider.md)

142
docs/master/deploy.md
View File

@ -1,142 +0,0 @@
---
title: Deploying Workloads
toc: true
weight: 240
indent: true
---
# Deploying Workloads
## Guides
This section will walk you through how to deploy workloads to various cloud provider environments in a highly portable way.
For detailed instructions on how to deploy workloads to your cloud provider of choice, please visit the following guides:
### GitLab Workload
* [Deploying GitLab on Google Cloud Platform (GCP)](gitlab/gitlab-gcp.md)
* [Deploying GitLab on Amazon Web Services (AWS)](gitlab/gitlab-aws.md)
* Deploying GitLab on Microsoft Azure - coming soon!
### Wordpress Workload
* [Deploying Wordpress on Google Cloud Platform (GCP)](workloads/gcp/wordpress-gcp.md)
* [Deploying Wordpress on Amazon Web Services (AWS)](workloads/aws/wordpress-aws.md)
* [Deploying Wordpress on Microsoft Azure](workloads/azure/wordpress-azure.md)
## Workload Overview
A workload is a schedulable unit of work and contains a payload as well as defines its requirements for how the workload should run and what resources it will consume.
This helps Crossplane setup connectivity between the workload and resources, and make intelligent decisions about where and how to provision and manage the resources in their entirety.
Crossplane's scheduler is responsible for deploying the workload to a target cluster, which in this guide we will also be using Crossplane to deploy within your chosen cloud provider.
This walkthrough also demonstrates Crossplane's concept of a clean "separation of concerns" between developers and administrators.
Developers define workloads without having to worry about implementation details, environment constraints, and policies.
Administrators can define environment specifics, and policies.
The separation of concern leads to a higher degree of reusability and reduces complexity.
During this walkthrough, we will assume two separate identities:
1. Administrator (cluster or cloud) - responsible for setting up credentials and defining resource classes
2. Application Owner (developer) - responsible for defining and deploying the application and its dependencies
## Workload Example
### Dependency Resource
Let's take a closer look at a dependency resource that a workload will declare:
```yaml
## WordPress MySQL Database Instance
apiVersion: storage.crossplane.io/v1alpha1
kind: MySQLInstance
metadata:
name: demo
namespace: default
spec:
classRef:
name: standard-mysql
namespace: crossplane-system
engineVersion: "5.7"
```
This will request to create a `MySQLInstance` version 5.7, which will be fulfilled by the `standard-mysql` `ResourceClass`.
Note that the application developer is not aware of any further specifics when it comes to the `MySQLInstance` beyond their requested engine version.
This enables highly portable workloads, since the environment specific details of the database are defined by the administrator in a `ResourceClass`.
### Workload
Now let's look at the workload itself, which will reference the dependency resource from above, as well as other information such as the target cluster to deploy to.
```yaml
## WordPress Workload
apiVersion: compute.crossplane.io/v1alpha1
kind: Workload
metadata:
name: demo
namespace: default
spec:
resources:
- name: demo
secretName: demo
targetCluster:
name: demo-gke-cluster
namespace: crossplane-system
targetDeployment:
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
name: wordpress
labels:
app: wordpress
spec:
selector:
app: wordpress
strategy:
type: Recreate
template:
metadata:
labels:
app: wordpress
spec:
containers:
- name: wordpress
image: wordpress:4.6.1-apache
env:
- name: WORDPRESS_DB_HOST
valueFrom:
secretKeyRef:
name: demo
key: endpoint
- name: WORDPRESS_DB_USER
valueFrom:
secretKeyRef:
name: demo
key: username
- name: WORDPRESS_DB_PASSWORD
valueFrom:
secretKeyRef:
name: demo
key: password
ports:
- containerPort: 80
name: wordpress
targetNamespace: demo
targetService:
apiVersion: v1
kind: Service
metadata:
name: wordpress
spec:
ports:
- port: 80
selector:
app: wordpress
type: LoadBalancer
```
This `Workload` definition contains multiple components that informs Crossplane on how to deploy the workload and its resources:
- Resources: list of the resources required by the payload application
- TargetCluster: the cluster where the payload application and all its requirements should be deployed
- TargetNamespace: the namespace on the target cluster
- Workload Payload:
- TargetDeployment
- TargetService

185
docs/master/quick-start-gcp.md Normal file
View File

@ -0,0 +1,185 @@
---
title: Provisioning a MySQL Database on GCP
toc: true
weight: 240
indent: true
---
# Provisioning a MySQL Database on GCP
Now that Crossplane and the GCP stack are installed in your Kubernetes cluster,
and your GCP account credentials have been configured in
`crossplane-gcp-provider-key.json`, a MySQL database can easily be provisioned
on GCP.
## Namespaces
Namespaces allow for logical grouping of resources in Kubernetes. For this
example, create one for GCP-specific infrastructure resources, and one for
portable application resources:
```bash
kubectl create namespace gcp-infra-dev
kubectl create namespace app-project1-dev
```
## Provider
The `Provider` and `Secret` resources work together to store your GCP account
credentials in Kubernetes. Because these resources are GCP-specific, create them
in the `gcp-infra-dev` namespace. You will need to set the
`$BASE64ENCODED_GCP_PROVIDER_CREDS` and `$PROJECT_ID` variables before creating:
```bash
export PROJECT_ID=[your-demo-project-id]
export BASE64ENCODED_GCP_PROVIDER_CREDS=$(base64 crossplane-gcp-provider-key.json | tr -d "\n")
```
```bash
cat > provider.yaml <<EOF
apiVersion: v1
kind: Secret
metadata:
name: example-provider-gcp
namespace: gcp-infra-dev
type: Opaque
data:
credentials.json: $BASE64ENCODED_GCP_PROVIDER_CREDS
---
apiVersion: gcp.crossplane.io/v1alpha2
kind: Provider
metadata:
name: example
namespace: gcp-infra-dev
spec:
credentialsSecretRef:
name: example-provider-gcp
key: credentials.json
projectID: $PROJECT_ID
EOF
kubectl apply -f provider.yaml
```
## Cloud-Specific Resource Class
Cloud-specific resource classes define configuration for a specific type of
service that is offered by a cloud provider. GCP provides a managed MySQL
database offering through its CloudSQL service. The GCP stack in Crossplane has
a `CloudsqlInstanceClass` resource that allows us to store configuration details
for a CloudSQL instance. Because this resource is specific to GCP, create it in
the `gcp-infra-dev` namespace:
```bash
cat > cloudsql.yaml <<EOF
apiVersion: database.gcp.crossplane.io/v1alpha2
kind: CloudsqlInstanceClass
metadata:
name: standard-cloudsql
namespace: gcp-infra-dev
specTemplate:
databaseVersion: MYSQL_5_7
tier: db-n1-standard-1
region: us-central1
storageType: PD_SSD
storageGB: 10
ipv4Address: true
providerRef:
name: example
namespace: gcp-infra-dev
reclaimPolicy: Delete
EOF
kubectl apply -f cloudsql.yaml
```
## Portable Resource Class
Portable resource classes define a class of service for an abstract resource
type (e.g. a MySQL database) that could be fulfilled by any number of managed
service providers. They serve to direct any portable claim types (see below) to
a cloud-specific resource class that can satisfy their abstract request. Create
a `MySQLInstanceClass` in the `app-project1-dev` namespace:
```bash
cat > mysql-class.yaml <<EOF
apiVersion: database.crossplane.io/v1alpha1
kind: MySQLInstanceClass
metadata:
name: mysql-standard
namespace: app-project1-dev
classRef:
kind: CloudsqlInstanceClass
apiVersion: database.gcp.crossplane.io/v1alpha2
name: standard-cloudsql
namespace: gcp-infra-dev
EOF
kubectl apply -f mysql-class.yaml
```
## Portable Resource Claim
Portable resource claims serve as abstract requests to provision a service that
can fulfill their specifications. In this example, we have specified that a
request for a `standard-mysql` database will be fulfilled by GCP's CloudSQL
service. Creating a `MySQLInstance` claim for a `standard-mysql` database in the
same namespace as our `MySQLInstanceClass` will provision a `CloudsqlInstance`
on GCP:
```bash
cat > mysql-claim.yaml <<EOF
apiVersion: database.crossplane.io/v1alpha1
kind: MySQLInstance
metadata:
name: app-mysql
namespace: app-project1-dev
spec:
classRef:
name: mysql-standard
writeConnectionSecretToRef:
name: mysqlconn
engineVersion: "5.6"
EOF
kubectl apply -f mysql-claim.yaml
```
## Observe
When the claim is created, Crossplane creates a `CloudSQLInstance` resource in
the `gcp-infra-dev` namespace, which mirrors the CloudSQL MySQL database created
in GCP. You can use the following commands to view your `CloudSQLInstance`:
```bash
$ kubectl -n gcp-infra-dev get cloudsqlinstances
NAME STATUS STATE CLASS VERSION AGE
mysqlinstance-516345d1-d9af-11e9-a1f2-4eae47c3c2d6 PENDING_CREATE standard-cloudsql MYSQL_5_6 3m
```
After some time, GCP will finish creating the CloudSQL database and Crossplane
will inform you that the `STATUS` is `Bound` and the `STATE` is `RUNNABLE`:
```bash
$ kubectl -n gcp-infra-dev get cloudsqlinstances
NAME STATUS STATE CLASS VERSION AGE
mysqlinstance-516345d1-d9af-11e9-a1f2-4eae47c3c2d6 Bound RUNNABLE standard-cloudsql MYSQL_5_6 5m
```
You can also login to the GCP [console] to view your resource!
## Clean Up
The CloudSQL database on GCP and all Crossplane resources in your Kubernetes
cluster can be deleted with the following commands:
```bash
kubectl delete -f mysql-claim.yaml
kubectl delete -f mysql-class.yaml
kubectl delete -f cloudsql.yaml
kubectl delete -f provider.yaml
```
<!-- Named Links -->
[console]: https://console.cloud.google.com

23
docs/master/quick-start.md
View File

@ -5,17 +5,20 @@ weight: 210
---
# Quick Start Guide
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.
This quick start will demonstrate using Crossplane to deploy a portable MySQL
database on a single cloud provider, Google Cloud Platform. It serves as an initial introduction to
Crossplane, but only displays a small portion of its functionality.
The general steps for this example are as follows:
1. [Install Crossplane](install-crossplane.md) into your Kubernetes cluster.
1. [Add a cloud provider](cloud-providers.md) for managed service provisioning.
1. [Deploy a workload](deploy.md) (Wordpress) including the managed services it depends on (MySQL).
1. [Install Crossplane and the GCP stack](install-crossplane.md) into your Kubernetes cluster.
1. [Configure GCP credentials](cloud-providers/gcp/gcp-provider.md) in Crossplane.
1. [Provision a MySQL database](quick-start-gcp.md) on GCP.
Additional info:
* [Running Resources](running-resources.md)
* [Troubleshooting](troubleshoot.md)
## Next Steps
* Add additional [cloud provider stacks](cloud-providers.md) to Crossplane.
* Explore the [Services Guide](services-guide.md) and the [Stacks Guide](stacks-guide.md).
* Learn more about [Crossplane concepts](concepts.md).
* See what services are [currently supported](api.md) for each provider.
* Build [your own stacks](developer-guide.md)!

99
docs/master/running-resources.md
View File

@ -1,99 +0,0 @@
---
title: Running Resources
toc: true
weight: 250
indent: true
---
# 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.
## Guides
The list below contains some direct links to user guides that will walk you through how to deploy specific types of resources into your environments.
* [Workload user guides - WordPress application, MySQL database, Kubernetes cluster](deploy.md#guides)
* [PostgreSQL database](postgresql.md)
## Running Databases
Database managed services can be statically or dynamically provisioned by Crossplane in AWS, GCP, and Azure.
An application developer simply has to specify their general need for a database such as MySQL, without any specific knowledge of what environment that database will run in or even what specific type of database it will be at runtime.
The following sample is all the application developer needs to specify in order to get the correct MySQL database (CloudSQL, RDS, Azure MySQL) provisioned and configured for their application:
```yaml
apiVersion: storage.crossplane.io/v1alpha1
kind: MySQLInstance
metadata:
name: demo-mysql
spec:
classRef:
name: standard-mysql
namespace: crossplane-system
engineVersion: "5.7"
```
The cluster administrator specifies a resource class that acts as a template with the implementation details and policy specific to the environment that the generic MySQL resource is being deployed to.
This enables the database to be dynamically provisioned at deployment time without the application developer needing to know any of the details, which promotes portability and reusability.
An example resource class that will provision a CloudSQL instance in GCP in order to fulfill the applications general MySQL requirement would look like this:
```yaml
apiVersion: core.crossplane.io/v1alpha1
kind: ResourceClass
metadata:
name: standard-mysql
namespace: crossplane-system
parameters:
tier: db-n1-standard-1
region: us-west2
storageType: PD_SSD
provisioner: cloudsqlinstance.database.gcp.crossplane.io/v1alpha1
providerReference:
name: gcp-provider
namespace: crossplane-system
reclaimPolicy: Delete
```
## Running Kubernetes Clusters
Kubernetes clusters are another type of resource that can be dynamically provisioned using a generic resource claim by the application developer and an environment specific resource class by the cluster administrator.
Generic Kubernetes cluster resource claim created by the application developer:
```yaml
apiVersion: compute.crossplane.io/v1alpha1
kind: KubernetesCluster
metadata:
name: demo-cluster
namespace: crossplane-system
spec:
classRef:
name: standard-cluster
namespace: crossplane-system
```
Environment specific GKE cluster resource class created by the admin:
```yaml
apiVersion: core.crossplane.io/v1alpha1
kind: ResourceClass
metadata:
name: standard-cluster
namespace: crossplane-system
parameters:
machineType: n1-standard-1
numNodes: "1"
zone: us-central1-a
provisioner: gkecluster.compute.gcp.crossplane.io/v1alpha1
providerReference:
name: gcp-provider
namespace: crossplane-system
reclaimPolicy: Delete
```
## 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.

2
docs/master/stacks-guide-gcp.md
View File

@ -1,6 +1,6 @@
---
title: "Crossplane Stacks Guide: GCP Setup"
toc: false
toc: true
weight: 421
indent: true
---

2
docs/master/troubleshoot.md
View File

@ -1,6 +1,6 @@
---
title: Troubleshooting
toc: true
toc: false
weight: 260
indent: true
---