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-11-21 03:38:00 +00:00
parent d2e64e4e75
commit ae6f68e48a
1 changed files with 160 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -5,7 +5,7 @@ weight: 210
--- ---
# Getting Started # Getting Started
This guide will demonstrate using Crossplane to deploy a portable MySQL database This guide will demonstrate using Crossplane to deploy a portable Redis cluster
on the Google Cloud Platform (GCP). It serves as an initial introduction to on the Google Cloud Platform (GCP). It serves as an initial introduction to
Crossplane, but only displays a small set of its features. Crossplane, but only displays a small set of its features.
@ -13,8 +13,10 @@ In this guide we will:
1. [Install Crossplane](#install-crossplane) 1. [Install Crossplane](#install-crossplane)
1. [Add your GCP project to Crossplane](#add-your-gcp-project-to-crossplane) 1. [Add your GCP project to Crossplane](#add-your-gcp-project-to-crossplane)
1. [Provision a MySQL instance using CloudSQL](#provision-a-mysql-instance) 1. [Provision a Redis Cluster using Cloud
1. [Define a class of CloudSQL instance for dynamic provisioning](#define-a-class-of-cloudsql-instance) Memorystore](#provision-a-redis-cluster)
1. [Define a class of Cloud Memorystore for dynamic
provisioning](#define-a-class-of-cloud-memorystore)
## Install Crossplane ## Install Crossplane
@ -80,278 +82,274 @@ Save the above `Provider` as `provider.yaml`, save your Google Application
Credentials as `credentials.json`, then run: Credentials as `credentials.json`, then run:
```bash ```bash
kubectl -n crossplane-system create secret example-gcp-credentials --from-file=credentials.json kubectl -n crossplane-system create secret generic example-gcp-credentials --from-file=credentials.json
kubectl apply -f provider.yaml kubectl apply -f provider.yaml
``` ```
Crossplane can now manage your GCP project! Your service account will need the Crossplane can now manage your GCP project! Your service account will need the
CloudSQL Admin role for this guide. Check out GCP's [Getting Started With Redis Admin role for this guide. Check out GCP's [Getting Started With
Authentication] guide if you need help creating a service account and Authentication] guide if you need help creating a service account and
downloading its `credentials.json` file, and Crossplane's [GCP provider downloading its `credentials.json` file, and Crossplane's [GCP provider
documentation] for detailed instructions on setting up your project and service documentation] for detailed instructions on setting up your project and service
account permissions. account permissions.
## Provision a MySQL Instance ## Provision a Redis Cluster
GCP provides MySQL databases using [CloudSQL] instances. Crossplane uses a GCP provides Redis clusters using [Cloud Memorystore]. Crossplane uses a
resource and claim pattern to provision and manage cloud resources like CloudSQL resource and claim pattern to provision and manage cloud resources like Cloud
instances - if you've ever used [persistent volumes in Kubernetes] you've seen Memorystore - if you've ever used [persistent volumes in Kubernetes] you've seen
this pattern before. The simplest way to start using a new MySQL instance on GCP this pattern before. The simplest way to start using a new Redis cluster on GCP
is to provision a `CloudSQLInstance`, then claim it via a `MySQLInstance`. We is to provision a `CloudMemorystoreInstance`, then claim it via a
call this process _static provisioning_. `RedisCluster`. We call this process _static provisioning_.
```yaml ```yaml
apiVersion: database.gcp.crossplane.io/v1beta1 apiVersion: cache.gcp.crossplane.io/v1beta1
kind: CloudSQLInstance kind: CloudMemorystoreInstance
metadata: metadata:
name: example-cloudsql-instance name: example-cloudmemorystore-instance
spec: spec:
providerRef: providerRef:
name: example-provider name: example-provider
writeConnectionSecretToRef: writeConnectionSecretToRef:
name: example-cloudsql-connection-details name: example-cloudmemorystore-connection-details
namespace: crossplane-system namespace: crossplane-system
reclaimPolicy: Delete
forProvider: forProvider:
databaseVersion: MYSQL_5_6 tier: STANDARD_HA
region: us-west2 region: us-west2
settings: memorySizeGb: 1
tier: db-n1-standard-1
dataDiskType: PD_SSD
dataDiskSizeGb: 10
ipConfiguration:
ipv4Enabled: true
``` ```
First we create a CloudSQL instance. Save the above as `cloudsql.yaml`, then First we create a Cloud Memorystore instance. Save the above as
apply it: `cloudmemorystore.yaml`, then apply it:
```bash ```bash
kubectl apply -f cloudsql.yaml kubectl apply -f cloudmemorystore.yaml
``` ```
Crossplane is now creating the `CloudSQLInstance`! Before we can use it, we need Crossplane is now creating the `CloudMemorystoreInstance`! Before we can use it,
to claim it. we need to claim it.
```yaml ```yaml
apiVersion: database.crossplane.io/v1alpha1 apiVersion: cache.crossplane.io/v1alpha1
kind: MySQLInstance kind: RedisCluster
metadata: metadata:
name: example-mysql-claim name: example-redis-claim
spec: spec:
resourceRef: resourceRef:
apiVersion: database.gcp.crossplane.io/v1beta1 apiVersion: cache.gcp.crossplane.io/v1beta1
kind: CloudSQLInstance kind: CloudMemorystoreInstance
name: example-cloudsql-instance name: example-cloudmemorystore-instance
writeConnectionSecretToRef: writeConnectionSecretToRef:
name: example-mysql-connection-details name: example-redis-connection-details
``` ```
Save the above as `mysql.yaml`, and once again apply it: Save the above as `redis.yaml`, and once again apply it:
```bash ```bash
kubectl --namespace default apply -f mysql.yaml kubectl --namespace default apply -f redis.yaml
``` ```
In Crossplane cloud provider specific resources like the `CloudSQLInstance` we In Crossplane cloud provider specific resources like the
created above are called _managed resources_. They're considered infrastructure, `CloudMemorystoreInstance` we created above are called _managed resources_.
like a Kubernetes `Node` or `PersistentVolume`. Managed resources exist at the They're considered infrastructure, like a Kubernetes `Node` or
cluster scope (they're not namespaced) and let you specify nitty-gritty provider `PersistentVolume`. Managed resources exist at the cluster scope (they're not
specific configuration details. Managed resources that have reached `v1beta1` namespaced) and let you specify nitty-gritty provider specific configuration
are a high fidelity representation of their underlying cloud provider resource, details. Managed resources that have reached `v1beta1` are a high fidelity
and can be updated to change their configuration after provisioning. We _claim_ representation of their underlying cloud provider resource, and can be updated
these resources by submitting a _resource claim_ like the `MySQLInstance` above. to change their configuration after provisioning. We _claim_ these resources by
Resource claims are namespaced, and indicate that the managed resource they submitting a _resource claim_ like the `RedisCluster` above. Resource claims are
claim is in use by _binding_ to it. You can also use resource claims to namespaced, and indicate that the managed resource they claim is in use by
_dynamically provision_ managed resources on-demand - we'll discuss that in the _binding_ to it. You can also use resource claims to _dynamically provision_
next section of this guide. managed resources on-demand - we'll discuss that in the next section of this
guide.
Soon your new `MySQLInstance` should be online. You can use `kubectl` to Soon your new `RedisCluster` should be online. You can use `kubectl` to inspect
inspect its status. If you see `Bound` under the `STATUS` column, it's ready to its status. If you see `Bound` under the `STATUS` column, it's ready to use!
use!
```bash ```bash
$ kubectl --namespace default get mysqlinstance example-mysql-claim $ kubectl --namespace default get rediscluster example-redis-claim
NAME STATUS CLASS-KIND CLASS-NAME RESOURCE-KIND RESOURCE-NAME AGE NAME STATUS CLASS-KIND CLASS-NAME RESOURCE-KIND RESOURCE-NAME AGE
example-mysql-claim Bound CloudSQLInstance example-cloudsql-instance 4m example-redis-claim Bound CloudMemorystoreInstance example-cloudmemorystore-instance 8m39s
``` ```
You'll find all the details you need to connect to your new MySQL instance saved You'll find all the details you need to connect to your new Redis cluster
in the Kubernetes `Secret` you specified via `writeConnectionSecretToRef`, ready instance saved in the Kubernetes `Secret` you specified via
to [use with your Kubernetes pods]. `writeConnectionSecretToRef`, ready to [use with your Kubernetes pods].
```bash ```bash
$ kubectl --namespace default describe secret example-mysql-connection-details $ kubectl --namespace default describe secret example-redis-connection-details
Name: example-mysql-connection-details Name: example-redis-connection-details
Namespace: default Namespace: default
Labels: <none>
Annotations: crossplane.io/propagate-from-name: example-cloudmemorystore-connection-details
crossplane.io/propagate-from-namespace: crossplane-system
crossplane.io/propagate-from-uid: 7cd8666f-0bb9-11ea-8195-42010a800088
Type: Opaque Type: Opaque
Data Data
==== ====
serverCACertificateCommonName: 98 bytes endpoint: 12 bytes
serverCACertificateInstance: 25 bytes port: 4 bytes
username: 4 bytes
password: 27 bytes
publicIP: 13 bytes
serverCACertificateCertSerialNumber: 1 bytes
serverCACertificateCreateTime: 24 bytes
serverCACertificateExpirationTime: 24 bytes
serverCACertificateSha1Fingerprint: 40 bytes
endpoint: 13 bytes
serverCACertificateCert: 1272 bytes
``` ```
That's all there is to static provisioning with Crossplane! We've created a That's all there is to static provisioning with Crossplane! We've created a
`CloudSQLInstance` as cluster scoped infrastructure, then claimed it as a `CloudMemorystoreInstance` as cluster scoped infrastructure, then claimed it as
`MySQLInstance`. You can use `kubectl describe` to view the detailed a `RedisCluster`. You can use `kubectl describe` to view the detailed
configuration and status of your `CloudSqlInstance`. configuration and status of your `CloudMemorystoreInstance`.
```bash ```bash
$ kubectl describe example-cloudsql-instance $ kubectl describe cloudmemorystoreinstance example-cloudmemorystore-instance
Name: example-cloudsql-instance Name: example-cloudmemorystore-instance
Annotations: crossplane.io/external-name: example-cloudsql-instance Namespace:
API Version: database.gcp.crossplane.io/v1beta1 Labels: <none>
Kind: CloudSQLInstance Annotations: crossplane.io/external-name: example-cloudmemorystore-instance
kubectl.kubernetes.io/last-applied-configuration:
{"apiVersion":"cache.gcp.crossplane.io/v1beta1","kind":"CloudMemorystoreInstance","metadata":{"annotations":{},"name":"example-cloudmemory...
API Version: cache.gcp.crossplane.io/v1beta1
Kind: CloudMemorystoreInstance
Metadata:
Creation Timestamp: 2019-11-20T17:16:27Z
Finalizers:
finalizer.managedresource.crossplane.io
Generation: 4
Resource Version: 284706
Self Link: /apis/cache.gcp.crossplane.io/v1beta1/cloudmemorystoreinstances/example-cloudmemorystore-instance
UID: 7c9cb407-0bb9-11ea-8195-42010a800088
Spec: Spec:
Claim Ref:
API Version: cache.crossplane.io/v1alpha1
Kind: RedisCluster
Name: example-redis-claim
Namespace: default
UID: 9cd9105b-0bb9-11ea-8195-42010a800088
For Provider: For Provider:
Database Version: MYSQL_5_6 Alternative Location Id: us-west2-b
Gce Zone: us-west2-b Authorized Network: projects/my-project/global/networks/default
Instance Type: CLOUD_SQL_INSTANCE Location Id: us-west2-a
Region: us-west2 Memory Size Gb: 1
Settings: Redis Version: REDIS_4_0
Activation Policy: ALWAYS Region: us-west2
Backup Configuration: Reserved Ip Range: 10.77.247.64/29
Start Time: 17:00 Tier: STANDARD_HA
Data Disk Size Gb: 10
Data Disk Type: PD_SSD
Ip Configuration:
ipv4Enabled: true
Location Preference:
Zone: us-west2-b
Pricing Plan: PER_USE
Replication Type: SYNCHRONOUS
Storage Auto Resize: true
Tier: db-n1-standard-1
Provider Ref: Provider Ref:
Name: example-provider Name: example-provider
Write Connection Secret To Ref: Write Connection Secret To Ref:
Name: example-cloudsql-connection-details Name: example-cloudmemorystore-connection-details
Namespace: crossplane-system Namespace: crossplane-system
Status: Status:
At Provider: At Provider:
Backend Type: SECOND_GEN Create Time: 2019-11-20T17:16:29Z
Connection Name: my-cool-gcp-project:us-west2:example-cloudsql-instance Current Location Id: us-west2-a
Gce Zone: us-west2-b Host: 10.77.247.68
Ip Addresses: Name: projects/my-project/locations/us-west2/instances/example-cloudmemorystore-instance
Ip Address: 8.8.8.8 Persistence Iam Identity: serviceAccount:651413264395-compute@developer.gserviceaccount.com
Type: PRIMARY Port: 6379
Project: my-cool-gcp-project State: READY
Self Link: https://www.googleapis.com/sql/v1beta4/projects/my-cool-gcp-project/instances/example-cloudsql-instance Binding Phase: Bound
Service Account Email Address: REDACTED@gcp-sa-cloud-sql.iam.gserviceaccount.com
State: RUNNABLE
Binding Phase: Bound
Conditions: Conditions:
Last Transition Time: 2019-10-25T08:09:16Z Last Transition Time: 2019-11-20T17:16:27Z
Reason: Successfully reconciled managed resource
Status: True
Type: Synced
Last Transition Time: 2019-10-25T08:09:12Z
Reason: Successfully resolved managed resource references to other resources Reason: Successfully resolved managed resource references to other resources
Status: True Status: True
Type: ReferencesResolved Type: ReferencesResolved
Last Transition Time: 2019-10-25T08:09:16Z Last Transition Time: 2019-11-20T17:20:00Z
Reason: Managed resource is available for use Reason: Managed resource is available for use
Status: True Status: True
Type: Ready Type: Ready
Last Transition Time: 2019-11-20T17:16:29Z
Reason: Successfully reconciled managed resource
Status: True
Type: Synced
``` ```
Pay attention to the `Ready` and `Synced` conditions above. `Ready` represents Pay attention to the `Ready` and `Synced` conditions above. `Ready` represents
the availability of the CloudSQL instance while `Synced` reflects whether the availability of the Cloud Memorystore instance while `Synced` reflects
Crossplane is successfully applying your specified CloudSQL configuration. whether Crossplane is successfully applying your specified Cloud Memorystore
configuration.
## Define a Class of CloudSQL Instance ## Define a Class of Cloud Memorystore
Now that we've learned how to statically provision and claim managed resources Now that we've learned how to statically provision and claim managed resources
it's time to try out _dynamic provisioning_. Dynamic provisioning allows us to it's time to try out _dynamic provisioning_. Dynamic provisioning allows us to
define a class of managed resource - a _resource class_ - that will be used to define a class of managed resource - a _resource class_ - that will be used to
automatically satisfy resource claims when they are created. automatically satisfy resource claims when they are created.
Here's a resource class that will dynamically provision Cloud SQL instances with Here's a resource class that will dynamically provision Cloud Memorystore with
the same settings as the `CloudSqlInstance` we provisioned earlier in the guide: the same settings as the `CloudMemorystoreInstance` we provisioned earlier in
the guide:
```yaml ```yaml
apiVersion: database.gcp.crossplane.io/v1beta1 apiVersion: cache.gcp.crossplane.io/v1beta1
kind: CloudSQLInstanceClass kind: CloudMemorystoreInstanceClass
metadata: metadata:
name: example-cloudsql-class name: example-cloudmemorystore-class
annotations: annotations:
resourceclass.crossplane.io/is-default-class: "true" resourceclass.crossplane.io/is-default-class: "true"
labels: labels:
guide: getting-started guide: getting-started
specTemplate: specTemplate:
providerRef: providerRef:
name: example name: example-provider
writeConnectionSecretsToNamespace: crossplane-system writeConnectionSecretsToNamespace: crossplane-system
reclaimPolicy: Delete
forProvider: forProvider:
databaseVersion: MYSQL_5_6 tier: STANDARD_HA
region: us-west2 region: us-west2
settings: memorySizeGb: 1
tier: db-n1-standard-1
dataDiskType: PD_SSD
dataDiskSizeGb: 10
ipConfiguration:
ipv4Enabled: true
``` ```
Save the above as `cloudsql-class.yaml` and apply it to enable dynamic Save the above as `cloudmemorystore-class.yaml` and apply it to enable dynamic
provisioning of `CloudSqlInstance` managed resources: provisioning of `CloudMemorystoreInstance` managed resources:
```bash ```bash
kubectl apply -f cloudsql-class.yaml kubectl apply -f cloudmemorystore-class.yaml
``` ```
Now you can omit the `resourceRef` when you create resource claims. Save the Now you can omit the `resourceRef` when you create resource claims. Save the
below resource claim as `mysql-dynamic-claim.yaml`: below resource claim as `redis-dynamic-claim.yaml`:
```yaml ```yaml
apiVersion: database.crossplane.io/v1alpha1 apiVersion: cache.crossplane.io/v1alpha1
kind: MySQLInstance kind: RedisCluster
metadata: metadata:
name: example-mysql-dynamic-claim name: redis-dynamic-claim
spec: spec:
classSelector: classSelector:
matchLabels: matchLabels:
guide: getting-started guide: getting-started
writeConnectionSecretToRef: writeConnectionSecretToRef:
name: example-mysql-dynamic-connection-details name: example-redis-dynamic-connection-details
``` ```
When you apply this `MySQLInstance` claim you'll see that it dynamically When you apply this `RedisCluster` claim you'll see that it dynamically
provisions a new `CloudSQLInstance` to satisfy the resource claim: provisions a new `CloudMemorystoreInstance` to satisfy the resource claim:
```bash ```bash
$ kubectl --namespace default apply -f mysql-dynamic-claim.yaml $ kubectl --namespace default apply -f redis-dynamic-claim.yaml
mysqlinstance.database.crossplane.io/example-mysql-dynamic-claim created rediscluster.cache.crossplane.io/redis-dynamic-claim created
$ kubectl get rediscluster redis-dynamic-claim
NAME STATUS CLASS-KIND CLASS-NAME RESOURCE-KIND RESOURCE-NAME AGE
redis-dynamic-claim CloudMemorystoreInstanceClass example-cloudmemorystore-class CloudMemorystoreInstance default-redis-dynamic-claim-hvwwd 33s
$ kubectl get mysqlinstance example-mysql-dynamic-claim
NAME STATUS CLASS-KIND CLASS-NAME RESOURCE-KIND RESOURCE-NAME AGE
example-mysql-dynamic-claim CloudSQLInstanceClass example-cloudsql-class CloudSQLInstance default-example-mysql-dynamic-claim-bwpzd 47s
``` ```
You just dynamically provisioned a `CloudSQLInstance`! You can find the name of You just dynamically provisioned a `CloudMemorystoreInstance`! You can find the
your new `CloudSQLInstance` under the `RESOURCE-NAME` column when you run name of your new `CloudMemorystoreInstance` under the `RESOURCE-NAME` column
`kubectl describe mysqlinstance`. Reuse the resource class as many times as you when you run `kubectl describe rediscluster`. Reuse the resource class as many
like; simply submit more `MySQLInstance` resource claims to create more CloudSQL times as you like; simply submit more `RedisCluster` resource claims to create
instances. more Cloud Memorystore instances.
You may have noticed that your resource claim included a `classSelector`. The You may have noticed that your resource claim included a `classSelector`. The
class selector lets you select which resource class to use by [matching its class selector lets you select which resource class to use by [matching its
labels]. Resource claims like `MySQLInstance` can match different kinds of labels]. Resource claims like `RedisCluster` can match different kinds of
resource class using label selectors, so you could just as easily use the resource class using label selectors, so you could just as easily use the exact
exact same `MySQLInstance` to create an Amazon Relational Database Service (RDS) same `RedisCluster` to create an Amazon Replication Group instance by creating a
instance by creating an `RDSInstanceClass` labelled as `guide: getting-started`. `ReplicationGroupClass` labelled as `guide: getting-started`. When multiple
When multiple resource classes match the class selector, a matching class is resource classes match the class selector, a matching class is chosen at random.
chosen at random. Claims can be matched to classes by either: Claims can be matched to classes by either:
* Specifying a `classRef` to a specific resource class. * Specifying a `classRef` to a specific resource class.
* Specifying a `classSelector` that matches one or more resource classes. * Specifying a `classSelector` that matches one or more resource classes.
@ -361,9 +359,11 @@ chosen at random. Claims can be matched to classes by either:
## Next Steps ## Next Steps
* Add additional [cloud provider stacks](cloud-providers.md) to Crossplane. * Add additional [cloud provider stacks](cloud-providers.md) to Crossplane.
* Explore the [Services Guide](services-guide.md) and the [Stacks Guide](stacks-guide.md). * Explore the [Services Guide](services-guide.md) and the [Stacks
Guide](stacks-guide.md).
* Learn more about [Crossplane concepts](concepts.md). * Learn more about [Crossplane concepts](concepts.md).
* See what managed resources are [currently supported](api.md) for each provider. * See what managed resources are [currently supported](api.md) for each
provider.
* Build [your own stacks](developer-guide.md)! * Build [your own stacks](developer-guide.md)!
<!-- Named Links --> <!-- Named Links -->
@ -375,7 +375,7 @@ chosen at random. Claims can be matched to classes by either:
[Crossplane installation guide]: install-crossplane.md [Crossplane installation guide]: install-crossplane.md
[Getting Started With Authentication]: https://cloud.google.com/docs/authentication/getting-started [Getting Started With Authentication]: https://cloud.google.com/docs/authentication/getting-started
[GCP provider documentation]: gcp-provider.md [GCP provider documentation]: gcp-provider.md
[CloudSQL]: https://cloud.google.com/sql/docs/mysql/ [Cloud Memorystore]: https://cloud.google.com/memorystore/
[Persistent volumes in Kubernetes]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/ [Persistent volumes in Kubernetes]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/
[use with your Kubernetes pods]: https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets [use with your Kubernetes pods]: https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets
[matching its labels]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ [matching its labels]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/